Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 2 additions & 0 deletions AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -14,6 +14,8 @@

**Competing-PR coverage is not established by existence or passing tests.** For every VSM-derived/informed Upgrade hypothesis, use [the function-ownership/overlap receipt](PROTOCOL.md#existing-work-functional-overlap-and-vsm-ownership-gate): pin historical assessment plus current original source and competing PR head/diff, identify the decisive VSM decision owner and closure, compare matched native cases, and explicitly assess the remaining user task. An S2 tab router, static limit, or health check is not S3; current-task retry or accumulated helpers is not S4. Evaluate continuation/dependent work before opening a duplicate, but never mutate another author's PR branch or post to an external repo without the separate exact public consent. A partial/uncertain overlap does not close the single-harness search; preserve `EVIDENCE_INSUFFICIENT` where functional proof is absent.

**Architecture-first `upstream roadmap OWNER/REPO` — read-only plan:** Use one named original, current source/issue/PR heads and accepted historical Index assessment separately. Create a [Capability Roadmap Receipt](docs/CAPABILITY_ROADMAP.md), map actual VSM decision owner/closure and competing work before proposing useful composable `C` constructors. Optional `C(P)`/`A(P)` applies only when separately proved for S3/S4/S5; autonomy is never mandated. Offer source-native code, Profile/Skills specification feedback, or a separately permitted domain fork. VSM and cost-saving claims are hypotheses, not proof. No default fork record/Index regrade/public issue/PR. The template is `DRAFT — NOT PUBLISHED` until the owner approves exact third-party destination and text; a code task must follow normal full Upgrade and consent gates. [Route](PROTOCOL.md#architecture-first-upstream-roadmap-ownerrepo-plan-only) · [template](templates/EXTERNAL_ARCHITECTURE_ISSUE.md).

**Capability-first `upstream upgrade` — one original harness, full engineering cycle:** if unspecified, run bounded eligibility/preselection and select **one** source. Lock the whole invocation to that original; after an unsuccessful capability hypothesis, test other source-backed possibilities **in the same harness**, never switch to another original. Do not request routine `continue`. Qualify need/mechanism/counterfactual/scope; when authorized implement on its matching `opensiro-contributions` product branch and independently run baseline/after, negative and native CI. Preserve `.opensiro/` only on `opensiro/meta`. Stage the exact source-template external PR title/body, AI disclosure and code diff **as a review PR inside the same `opensiro-contributions` fork**; show the real fork-local PR URL to the human after obtaining the separate current exact consent to create that public fork PR. Never merge fork PR to fork default branch. If that public stage is not yet approved, provide read-only compare/diff and complete draft, not a fictitious URL. External PR creation/editing requires **separate exact current-conversation consent**. A source-local CLA/maintenance, DORMANT/PAUSE/STOP, **unavailable authority to initialize missing meta**/runner, no valid functional improvement or exhausted safe hypotheses is a valid final blocker **for the selected source**: do not bypass it by changing harness. See [single-harness end-to-end Upgrade](PROTOCOL.md#end-to-end-single-source-upgrade--finish-at-human-pr-approval), [fork-local PR review and AI disclosure](docs/UPGRADE_PR_REVIEW.md). `upstream upgrade batch N` and `upstream batch [N]` remain distinct **chat-scoped multi-source screening** commands with no mandatory PR/public write.

**Required `.opensiro/` provisioning for full-cycle Upgrade:** after source-native qualification and an **independent verified effectful fork-write permission**, check the original-matching `opensiro-contributions/*` fork for `opensiro/meta`. If the ref is **confirmed missing**, initialize it from a pinned current fork default HEAD and commit `.opensiro/state.json` plus the **one stable intervention record** on that branch only; do not abandon a qualified, authorized source just because meta is missing. If the ref exists, re-read and reuse it; if unreadable, colliding, paused/stopped, unlicensed or unauthorized, fail closed **inside the selected original harness** and investigate only safe in-source alternatives; never switch harnesses. No implicit `ALLOW/ACTIVE`, owner `RESUME`, historical events, independent test results or original PR statuses. Read back the exact metadata HEAD and contribution and verify the fork with [`scripts/aggregate.py`](scripts/aggregate.py) before claiming `READY_FOR_HUMAN_PR_APPROVAL`. If an external PR is already live, reconcile its verified URL into **one existing/missing record** without creating another PR. This obligation applies to single-source `upstream upgrade`, **not** chat-only batches or read-only scans; never put `.opensiro/` in product branches. [Provisioning procedure](PROTOCOL.md#upgrade-metadata-materialization--missing-opensirometa).
Expand Down
2 changes: 2 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,6 +5,8 @@
**Release status:** a protocol version merged to `main` is **not** automatically a published GitHub Release. Check [published Releases](https://github.com/opensiro/upstream/releases). At the 2026-11-16 review, v0.13.0 was the latest published release, and the [v0.16.0 consolidated candidate](docs/RELEASE_CANDIDATE_v0.16.0.md) awaits final owner approval. Individual v0.14–v0.16 history entries below remain valid intermediate main snapshots, not claims of three separate GitHub Releases.

## Unreleased
**Architecture-first Upstream roadmap (unreleased):** Add a named-source, plan-only contribution route for mapping assessment, native issues/PRs and proposed composable capabilities, with independent options for product code, Profile/Skills feedback and domain-specific forks. VSM-standardization and development-cost benefit remain hypotheses; no automatic assessment regrade, agent autonomy, new fork metadata enum, third-party publication, SemVer bump or Release.

**Autonomy preflight before Upstream Upgrade source ranking (unreleased):** Following the existing license/formalities read-only preflight, check whether a non-core agent-assisted contribution can actually reach a permitted PR: contributor path, issue/design approval, CLA/DCO and human-only attestations, AI disclosure, native test availability and review requirements. Report source-backed direct/conditional/issue-only/unknown paths without inventing permission or a new fork state; prefer viable autonomous PR paths among function-credible candidates before deeper feature/popularity ranking while preserving one-harness lock and exact public-publication consent.

**Function-scoped evidence-first Upgrade (unreleased):** Explicit `S1`–`S5` operator qualifiers now narrow bounded read-only source preselection to an independently grounded function-specific user need before the one-harness lock. After selection, research stays in the same original and requested function, with decisive owner, actual decision/feedback rights, enforcement versus ownership and return-to-operation closure checked against the normative Profile. S5 requires legitimate identity/ultimate-policy decision closure, not a static policy, guardrail, browser permission or routine human approval. Existing overlap, material capability-delta, native tests, classification, fork-local review and exact external-publication consent remain independent gates. Clarifying Unreleased contract, without new JSON enums, Index reassessment, version bump or release.
Expand Down
15 changes: 15 additions & 0 deletions PROTOCOL.md
Original file line number Diff line number Diff line change
Expand Up @@ -20,6 +20,21 @@ Read [docs/FORK_METADATA.md](docs/FORK_METADATA.md) for the initial JSON contrac
4. Check native **need, mechanism, counterfactual and scope**. Unsupported claims remain pending. No mandatory six-function S1–S5 scan or per-session batch.
5. Before implementation, apply the [material capability-delta gate](#material-capability-delta-gate-before-implementation). An Index link, a new configuration flag, a passing unit test or an absence in a VSM function vector is not independently a useful Upgrade.

## Architecture-first `upstream roadmap OWNER/REPO` (plan-only)

**Mission and uncertainty.** OpenSiro Upstream studies whether reusable organizational specifications and evidence-backed engineering can reduce the total cost of designing, integrating and maintaining AI agent harnesses. VSM is our current reference hypothesis, **not** mandatory architecture, a demonstrated cost saving, or a product-quality rating. Validate claims against the simplest original-native alternative and measured engineering effort.

**Route contract.** `upstream roadmap OWNER/REPO` is a **conversational, named-original, read-only-by-default architecture route**, separate from `upstream upgrade` and both batch commands. It is not a new CLI command, research batch, VSM assessment, implementation mandate, publication approval, or contribution state. A source-backed **plan-only** architecture issue draft may be a complete success with zero code changes and zero published PRs. Follow [Capability Roadmap](docs/CAPABILITY_ROADMAP.md) and [external issue template](templates/EXTERNAL_ARCHITECTURE_ISSUE.md).

1. **Freeze one source and check rights.** Pin the actual original default HEAD, source boundary/recursion, existing Index assessment file SHA plus historical `review_ref`/`reviewed_at`, Profile/Methodology versions and observed relevant PR/issue refs. An unmerged reassessment is not canonical. Perform the existing read-only license/formalities and autonomy preflights. Verify fork and owner controls before effectful work; unreadable metadata is unknown, not permission.
2. **Map real work and residual outcomes.** Identify shipped behavior, open or merged PR heads/diffs/tests, issues, experiments, and adjacent maintainer governance *separately*. For each relevant S1/S2/S3/S3*/S4/S5 mechanism name a native actor/task, disturbance, decisive owner/right, enforcement, feedback/closure and unserved user outcome. Record current main → competing PR → residual user capability with evidence and alternative; a missing historical grade does not independently justify a feature, a new controller, or a claimed grade.
3. **Design for useful composability before autonomy.** Prioritize a **function-specific** constructor that, when actually shipped and verified, can support `C`, not generic routing/hooks or an unrealized plan. Optional `C(P)` and `A(P)` are separate two-mode capabilities only for S3/S4/S5, under the published Methodology, not a universal grade ladder; `P` alone may be the legitimate final choice. S1/S2/S3* do not publish parent-mode notation. Never imply a stage or future PR changes the Index score or transfers rights to an agent.
4. **Offer three independent choices.** (a) Integration/limited source-native PRs that respect existing work; (b) feedback/PRs to normative [Profile](https://github.com/opensiro/vsm-harness-profile) or separate [Skills](https://github.com/opensiro/vsm-harness-skills) assessment method; (c) legally permitted domain-specific fork experiment with an explicit task/boundary, simple native alternative and no expectation of original-project adoption. None is obligatory for maintainers.
5. **Test the cost hypothesis.** Predeclare comparable native-vs-VSM-informed tasks, functionality and all-in implementation/integration/review/test/maintenance costs. Until independently measured, mark cost claims `NOT_MEASURED`, never "proven cheaper".
6. **Stop at a decision-ready draft.** Produce the [Capability Roadmap Receipt](docs/CAPABILITY_ROADMAP.md#capability-roadmap-receipt) and optionally an original-native external issue draft marked `DRAFT — NOT PUBLISHED`. Do **not** open an Upstream issue, fork-local improvement record, schedule, or second mutable ledger solely for an unimplemented roadmap. For an actual implementation, re-enter the existing full `upstream upgrade` material-delta, native validation, schema-v2 fork-local contribution and five-link handoff rules. External original issue/comment/PR and public fork-local PR still each need separate **exact current-conversation owner approval** of destination, action, full text and diff.

**Boundary:** roadmap success is a source-linked integration proposal, not delivery of code, confirmed `C`, formal Index reassessment, Profile amendment, implemented autonomy or measured cost savings. `upstream upgrade` and `upstream upgrade batch N` / `upstream batch [N]` remain unchanged.

## Capability-first `upstream upgrade` (new work, not historical batching)

These are **conversational operator routes**, not shell commands, a new scheduler, a frozen-batch producer, or automatic authority to write to forks. Their purpose is to find a **real new user/operator task or decision** that an agent harness cannot currently perform, explain why a VSM mechanism is a useful hypothesis for that need, and then independently test the smallest native improvement. Use the current [fork-local metadata](docs/FORK_METADATA.md) and [read-only aggregator](scripts/aggregate.py); the original repository and Index remain the respective product/assessment sources of truth.
Expand Down
6 changes: 6 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -67,6 +67,12 @@ As of **2026-11-16 12:00 UTC**, the **42 distinct original-repository PRs** link

[Full dated statistics, day-by-day counts, coverage and on-demand refresh instructions](docs/ACTIVITY.md). Each square contains **three independently shaded stripes**: **green** published, **blue** merged, **amber** closed without merge; a **purple dot** marks a closed PR with a GitHub `APPROVED` review (currently 0). The SVG uses original event dates rather than metadata backfill commits and is a static, manually refreshable view, **not a live counter**.

## Architecture-first Upstream roadmap

`upstream roadmap OWNER/REPO` is a **plan-only**, read-only-by-default contribution route. It maps a pinned general assessment against current original code, issues, PR heads and unresolved user tasks, then proposes the smallest useful **composable-first** improvements. It may finish with a draft architecture issue and **no code changes**. OpenSiro tests whether VSM-informed organizational specification (a hypothesis, not a mandate) can lower harness development/integration/maintenance cost versus simpler native alternatives; **no savings are claimed without measurement**. Maintainers may pursue product-native PRs, challenge/improve Profile or Skills, or try an optional domain-scoped fork.

[Roadmap procedure](docs/CAPABILITY_ROADMAP.md) · [external issue draft](templates/EXTERNAL_ARCHITECTURE_ISSUE.md) · [existing Upgrade](PROTOCOL.md#capability-first-upstream-upgrade-new-work-not-historical-batching). Public third-party communication still needs exact current-conversation approval.

## Capability-first upstream upgrade

`upstream upgrade` is a **one-harness, end-to-end engineering route (FULL CYCLE)**. When no source is specified, run bounded preselection, choose **one** eligible original harness, then lock the entire run to that source. Within that harness, investigate additional real functional hypotheses if early ones fail; **never switch to another original harness in the same invocation**. The goal is real code on a correctly parented `opensiro-contributions` product branch, source-native tests and **a fork-local PR for human review containing the exact prospective external PR**. Creating even that public fork PR requires its own current-conversation approval; without approval, show the exact diff/compare and PR body without claiming a PR exists. An external PR is never posted without separate owner approval. Rights, CLA/DCO, `DORMANT/PAUSE/STOP`, lack of a qualified improvement, and unrun tests remain honest, source-local stop reasons; this is not a background agent or mandatory patch quota.
Expand Down
Loading
Loading