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 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
**Fork Issue → issue-local evidence → separately consented original Issue (unreleased):** Source-pinned case roadmaps, construction contracts, drafts and results belong in the verified matching fork's `opensiro/meta:.opensiro/issues/<case-id>/`. Public fork GitHub Issue creation and external original Issue publication each require their own exact owner approval; dedupe original issues and link rather than manufacture duplicates. Do not claim GitHub cross-owner native transfer, mirror comments/reactions, or auto-close internal Issues. Named Paperclip and Browser Harness case examples migrated to their forks; central Upstream retains generic methods and source-neutral validator fixtures. No product code, Index grade, version bump or Release.

**Roadmap-to-Upgrade execution continuity (unreleased):** Keep `upstream roadmap` strictly plan-only when that is the owner's request, but route a subsequent explicit instruction to implement the accepted `C` constructor through the existing single-original full-cycle Upgrade. Require verified source/overlap and capability delta, actual first-party vertical-slice code and native positive/negative tests, a verified fork product branch plus schema-v2 meta evidence, and exact draft fork-local PR handoff. The existing separate public fork-local and external-publication consent gates are unchanged; no automatic PR, Index grade, protocol version bump or Release.

**Roadmap C-target construction/acceptance contract (unreleased):** Require a function-specific first-party constructor interface, independently composable agent decision ownership, authorized return to subsequent operation, boundary reachability and native positive/negative acceptance cases before describing a roadmap target `C` as implementable. Add a Paperclip S4=C proposal with ten falsifiable test scenarios, tied to the accepted November Index reassessment; no first-party Paperclip code, external publication, automatic grade change, SemVer bump or Release.
Expand Down
16 changes: 13 additions & 3 deletions PROTOCOL.md
Original file line number Diff line number Diff line change
Expand Up @@ -10,6 +10,16 @@ Before a real fork exists, Upstream may own one **minimal intake issue** contain

Read [docs/FORK_METADATA.md](docs/FORK_METADATA.md) for the initial JSON contract and authority/branch rules. The original GitHub repository alone owns the actual external PR's open/merge/closure/reviews. Upstream only shows source-linked dated projections.

## Fork GitHub Issue → local case → external Issue (separate publication)

**One verified fork, one issue-local workspace per case.** After checking the actual working fork's parent and current `opensiro/meta` control, keep source-pinned roadmaps, native issue/PR overlap, constructor/acceptance contracts, issue drafts and technical review evidence in `.opensiro/issues/<case-id>/` of that fork's **separate metadata-branch worktree**. The fork GitHub Issue is a public discussion/navigation surface linking to this case; the case files remain the detailed working record. `opensiro/upstream` keeps only common methods, templates, validators and rebuildable links—not per-fork dossiers. The existing `.opensiro/contributions/` record is reserved for an actual independently implemented improvement, never automatically created for an issue or plan.

1. **Fork Issue gate.** Search for duplicate fork Issues; reuse any suitable one. Before creating a *public* fork GitHub Issue, show the exact destination, action, title and complete public body and obtain the current-conversation owner approval under [external-publication consent](#external-publication-consent). No inferred approval from a roadmap, local metadata access or the user's general process choice. A case file on `opensiro/meta` is **not** a public GitHub Issue.
2. **Issue-local evidence.** Under `.opensiro/issues/<case-id>/` keep a `README.md` with original and fork identity, actual fork Issue URL/number if created, immutable observed source and Index pointers, existing original issues/PRs, case status, next decision and artifact links; add `roadmap.md`, `constructor-acceptance.md`, external issue draft and results as appropriate. No second issue-state database, cloned canonical assessment, fake implementation claim or new contribution record for plan-only work. A fork Issue can remain OPEN throughout research.
3. **Original issue dedupe and separate approval.** Re-check the original maintainer's *current* first-party behavior, contribution rules and live issues/PRs. If an existing original issue already covers the user outcome, **link/reuse it**, don't create a duplicate. Otherwise prepare a maintainer-native standalone issue title/body with evidence, accurate model-use disclosure, plain product language and any relevant fork Issue link; obtain **new, separate, exact current-conversation owner approval** before opening the external original Issue. This is a new independently created Issue or source link, **not a promised GitHub native cross-owner Issue transfer**: numbering, discussion history, reactions and ownership are not transferred or mirrored automatically.
4. **Return and status separation.** Independently read back any published original Issue ID, URL and state. Cross-link the real original and fork issues where permitted and separately approved; store the source link and publication receipt in the fork's issue-local case. Original GitHub owns original Issue state; the fork's local case and Issue remain independently owned. Do **not** automatically close the internal Issue because an external Issue was created or closed. Never rewrite immutable event history.
5. **Fail closed.** Fork/meta unavailable or PAUSE/STOP means no case-file writes; absent fork Issue consent means no public fork Issue; no residual native delta means `DEDUPED/LINK_EXISTING` or `NO_MATERIAL_DELTA`; missing external consent means `EXTERNAL_DRAFT — NOT PUBLISHED`. These are narrative results, not new workflow enums. Neither filing a case nor creating a public fork Issue implies product implementation, a fork-local review PR, reassessment, or third-party publication.

**External maintainer issue watching:** when an upstream product or PR-admission decision is awaiting source review and no external PR exists, use [fork-local, source-linked `issue_watch`](docs/ISSUE_WATCHING.md) in the *existing* stable contribution, not a new issue/PR ledger or invented `work_state`. Observe original issues/comments/labels with bounded readback and durable cursor-based dedup; never infer publication consent. The watcher is on-demand by default and scheduled only by an explicit opt-in variable and fork-scoped credential. It cannot auto-publish third-party PRs.

## Research and qualification
Expand All @@ -24,21 +34,21 @@ Read [docs/FORK_METADATA.md](docs/FORK_METADATA.md) for the initial JSON contrac

**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).
**Route contract.** `upstream roadmap OWNER/REPO` is a **conversational, named-original, source-analysis-read-only-by-default architecture route**, with an explicitly requested persistent case stored only in the verified fork's `opensiro/meta:.opensiro/issues/<case-id>/`. It remains 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. **Recommend re-assessment when the accepted assessment is older than one month.** At the roadmap observation date, compare against the most recent **successful Index semantic re-review / reassessment** recorded for this harness (the accepted `reviewed_at`, or a later `last_checked_at` only when it is backed by successful longitudinal evidence under the applicable Skills Methodology). If **more than 30 calendar days** have passed, **recommend a source-pinned Index re-assessment before finalizing confident VSM gap/ownership claims**; also recommend it sooner when material product evolution is observed. Cite the dated canonical assessment, source HEAD and any actual Index re-review issue/PR; if none exists, offer the Index-owned `[Assessment re-review]` route. A calendar threshold is a **soft freshness recommendation, never an automatic grade change, mandatory waiting gate, new batch/round, or permission to open an issue or PR**. Without a completed accepted re-assessment, the roadmap may continue **read-only, explicitly provisional**, grounded in current original code and with the old accepted vector labeled historical. Unknown freshness remains unknown; a superficial source check, open issue/PR, or roadmap itself cannot reset it.
3. **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.
4. **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. **If the roadmap proposes implementing a `C` target, require an actionable construction contract before treating the plan as implementation-ready:** define the function's external/operational disturbance, proposed first-party entry point and durable state, inputs/options, who would own the decisive decision when an autonomous actor is composed, enforcement and return-to-operation feedback, distribution/mode reachability, native baseline and overlapping original work, plus positive and unauthorized/missing-closure acceptance tests. A notification, ordinary callback or optional generic plugin is not an independently justified `C`. Clearly label proposed interfaces rather than asserting they already exist. 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.
5. **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.
6. **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".
7. **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.
7. **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 *contribution* record, schedule, or second mutable ledger solely for an unimplemented roadmap. When durable case storage is requested, use only the verified fork's `.opensiro/issues/<case-id>/`; a public fork GitHub Issue remains a separate approved publication. 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. **Subsequent explicit implementation requests activate the bounded full-cycle Upgrade handoff below; they are not discharged by the original `PLAN_ONLY` result.** `upstream upgrade` and `upstream upgrade batch N` / `upstream batch [N]` retain their other gates and semantics.

### Roadmap → implementation handoff (explicit execution intent)

**Intent is binding, not the last artifact label.** A plain `upstream roadmap OWNER/REPO` request remains `PLAN_ONLY`. However, when the owner then says **"implement this roadmap/contract", "bring this C target to a fork-local PR", "продолжи до local PR"**, or otherwise explicitly requests product implementation, do **not** treat the prior `PLAN_ONLY` receipt as a stop instruction. Re-enter the existing **single-original `upstream upgrade OWNER/REPO`** engineering route; the named original stays locked and no new research batch, Profile update or automatic Index grade is authorized. A request to **edit the protocol only** is not an implementation mandate.
**Intent is binding, not the last artifact label.** A plain `upstream roadmap OWNER/REPO` request remains `PLAN_ONLY`. A request to create a **fork Issue** and preserve case artifacts under `.opensiro` does **not** request product implementation or a fork-local review **PR**. However, when the owner then says **"implement this roadmap/contract", "bring this C target to a fork-local PR", "продолжи до local PR"**, or otherwise explicitly requests product implementation, do **not** treat the prior `PLAN_ONLY` receipt as a stop instruction. Re-enter the existing **single-original `upstream upgrade OWNER/REPO`** engineering route; the named original stays locked and no new research batch, Profile update or automatic Index grade is authorized. A request to **edit the protocol only** is not an implementation mandate.

**Mandatory implementation handoff for a qualified `C` target:**

Expand Down
Loading
Loading