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
**Roadmap assessment-freshness advisory (unreleased):** If the most recent successful Index semantic review/check is more than 30 calendar days old, recommend an Index-owned source-pinned re-assessment before confident architecture-gap claims. Material product change can trigger an earlier recommendation. Preserve the old accepted vector until Index admission; allow explicitly provisional read-only roadmaps while the re-assessment is pending. No automatic regrade, periodic Index mandate, new assessment controller, third-party publication, SemVer bump or Release.

**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.
Expand Down
11 changes: 6 additions & 5 deletions PROTOCOL.md
Original file line number Diff line number Diff line change
Expand Up @@ -27,11 +27,12 @@ Read [docs/FORK_METADATA.md](docs/FORK_METADATA.md) for the initial JSON contrac
**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.
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. 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.

**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.

Expand Down
2 changes: 1 addition & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -69,7 +69,7 @@ As of **2026-11-16 12:00 UTC**, the **42 distinct original-repository PRs** link

## 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.
`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. If the last successful Index review is **more than 30 days old**, recommend a source-pinned **re-assessment** before relying on old VSM grades; this is advisory, not a roadmap blocker, and a pending reassessment does not replace accepted evidence. 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.

Expand Down
5 changes: 3 additions & 2 deletions docs/CAPABILITY_ROADMAP.md
Original file line number Diff line number Diff line change
Expand Up @@ -11,6 +11,7 @@ The normative [Profile](https://github.com/opensiro/vsm-harness-profile/blob/mai
## Procedure

1. **Source and authority pins:** Named original repository; exact current default HEAD; observation time; legal license/contributor/AI policy and autonomy preflight; accepted Index assessment URL *and file blob SHA*, historical review date/ref; explicitly label pending reassessments as unaccepted. Declare system-in-focus and excluded recursion. If a verified fork is relevant read original parent and `opensiro/meta` owner controls before writes.
- **Assessment freshness advisory:** Compute age in calendar days at the observation date from the latest accepted successful Index semantic review (`reviewed_at`, or a later successfully supported `last_checked_at`; do not credit informal source inspection). If older than **30 days**, **recommend an Index-owned, source-pinned re-assessment before relying on the historical vector for architectural conclusions**. Materially changed current behavior can justify the recommendation sooner. Cite the exact canonical assessment, date, current source HEAD and any live reassessment issue/PR. This recommendation is **not** a periodic reassessment mandate, universal Index policy, automated queue write, grade change or roadmap block. If re-assessment is pending or not feasible, continue **plan-only with provisional claims**, old assessment explicitly historical, and source-native evidence controlling current functionality. An open or unmerged proposal is not accepted freshness.
2. **Native work census:** For relevant S1/S2/S3/S3*/S4/S5, inspect current shipped code; exact original issue and PR state/head/diff and maintainer decision; existing OpenSiro fork work; competing original alternatives. Distinguish `SHIPPED`, `OPEN_PR`, `ISSUE_ONLY`, `EXPERIMENT`, `EXTERNAL_GOVERNANCE` and `UNVERIFIED` as *report labels only*, not stored metadata enums.
3. **Function-specific residual gap:** Name real actor → trigger → decision/action → observable result; actual disturbance; decisive right and owner; enforcement/transport; feedback into subsequent operation. Write `current main → competing proposal → remaining task`, overlap/alternative, uncertainty. No conclusion from a low Index grade or an issue title alone.
4. **Composability-first option:** Favor supported first-party, function-specific constructors where maintainers need them; only a shipped/composable closure can establish `C` in a later Index assessment. `C(P)` and `A(P)` are optional, independently demonstrated modes **only for S3/S4/S5**, not a mandated grade progression. `P` alone is a valid intentional goal; S1/S2/S3* have no published parent mode. Always prefer a simpler native design when appropriate.
Expand All @@ -24,7 +25,7 @@ A compact, **read-only Markdown report** in chat, or a dated **non-authoritative

| Section | Required contents |
| --- | --- |
| Identity | Original and HEAD SHA/date; boundary/recursion; pinned accepted Index assessment SHA, review date/ref and Profile/Skills refs |
| Identity | Original and HEAD SHA/date; boundary/recursion; pinned accepted Index assessment SHA, review date/ref and Profile/Skills refs; last successful review/check date, age in days and any proposed re-assessment link (provisional when pending) |
| Permission | License/contributor/CLA/AI policy, allowed paths and any actual fork owner state; no inferred write |
| Existing work | Original and fork issue/PR URLs, true open/merged status and head/diff evidence, shipped/proposed distinction |
| VSM witness | Function, disturbance, real decision/feedback owner/right, enabling first-party primitives and return-to-operation |
Expand All @@ -33,7 +34,7 @@ A compact, **read-only Markdown report** in chat, or a dated **non-authoritative
| Cost check | Paired native/VSM-informed task, all-in measures and observed values, else `NOT_MEASURED` |
| Delivery | `PLAN_ONLY`, `NEEDS_EVIDENCE` or `NO_USEFUL_CHANGE` as narrative outcomes only; external issue marked `DRAFT — NOT PUBLISHED` |

**Fail closed:** unknown source/ref/owner/diff stays unverified. An Issue or open PR does not certify shipped capability, a planned `C` is not an Index `C`, and a maintained project policy is not automatic runtime S5.
**Fail closed:** unknown source/ref/owner/diff or assessment freshness stays unverified. A >30-day historical assessment prompts a recommended re-review, not a hard stop, automatic Index write, or silent promotion of a pending reassessment. An Issue or open PR does not certify shipped capability, a planned `C` is not an Index `C`, and a maintained project policy is not automatic runtime S5.

## Optional structural receipt check

Expand Down
Loading