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

**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.
Expand Down
2 changes: 1 addition & 1 deletion PROTOCOL.md
Original file line number Diff line number Diff line change
Expand Up @@ -29,7 +29,7 @@ Read [docs/FORK_METADATA.md](docs/FORK_METADATA.md) for the initial JSON contrac
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. 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. **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.
Expand Down
5 changes: 4 additions & 1 deletion docs/CAPABILITY_ROADMAP.md
Original file line number Diff line number Diff line change
Expand Up @@ -14,7 +14,7 @@ The normative [Profile](https://github.com/opensiro/vsm-harness-profile/blob/mai
- **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.
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. A `C` **implementation target** must carry a source-native constructor/acceptance contract: precise user counterfactual, environmental/operational stimulus, function-specific first-party decision/feedback port (not generic hooks), an explicitly composable autonomous decision actor and authority boundary, proposed option/state lifecycle, closure into subsequent operation, exact tests including rejection/absence and compatibility, and proof of distribution reachability. Without those details call the case `NEEDS_EVIDENCE`, not an implementation-ready `C` roadmap. `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.
5. **Independent maintainer choices:** (a) original-native code/PR work, with existing Upgrade gates and separate independent contribution record per real improvement; (b) normative semantic feedback to Profile or separate Skills method/assessment improvement; (c) permitted experimental domain fork with declared boundary. Neither a spec issue nor a fork creates original maintainer obligations.
6. **Matched cost experiment:** Predeclare equivalent native vs VSM-informed user tasks and measure total implementation, integration, review/test, maintenance/regression effort and output quality. Report `NOT_MEASURED` until data exist. Never claim proven cheaper or performance superiority from a diagram.
7. **Handoff:** Produce [Capability Roadmap Receipt](#capability-roadmap-receipt) and optional [external architecture issue](../templates/EXTERNAL_ARCHITECTURE_ISSUE.md) with exact source links; keep `DRAFT — NOT PUBLISHED` until separate current owner consent for the exact destination/full text/diff. Plan-only ends even with zero code, zero PR, or no qualified improvement.
Expand All @@ -30,12 +30,15 @@ A compact, **read-only Markdown report** in chat, or a dated **non-authoritative
| 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 |
| Proposed capability | Actor/output and native alternative, meaningful constructor path, dependencies and small acceptance cases |
| Constructor target (when proposing `C`) | Function-specific first-party ports and distribution reachability; what a developer must compose (real autonomous decision actor/authority), option/state lifecycle, controlled return into future operation, negative cases and reproducible end-to-end acceptance. Explicitly distinguish proposed from shipped `C`. |
| Optional paths | Product-native code, Profile or Skills feedback, permitted domain-specific fork |
| 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 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.

For an implementation-oriented `C` target, see the [Paperclip S4=C proposed construction and acceptance contract](examples/paperclip-s4-constructor-acceptance-20261117.md) for a concrete (still plan-only) first-party interface/ownership/feedback design and falsifiable test matrix. The example demonstrates required specificity, not a changed Index grade or a mandatory VSM architecture.

## Optional structural receipt check

The source-native receipt stays **read-only documentation**, not a fork-local JSON state or an Index assessment. For a dated Markdown case note, run:
Expand Down
7 changes: 7 additions & 0 deletions docs/examples/paperclip-roadmap-20261117.md
Original file line number Diff line number Diff line change
Expand Up @@ -56,6 +56,13 @@

**P2 — integration guardrails only.** Any new S3/S4 constructor must respect existing S2 single-owner/blocker semantics, S3* independent review and board S5 reserved decisions; do not require six additional subsystems or force `C → C(P) → A(P)`. The optional parent variants require independent first-party closure and separate Index review after shipping.

### P0 proposed S4 constructor — implementation-ready acceptance conditions

The specific **proposed first-party S4 constructor** is now written as a separate, reviewable [Paperclip S4=C construction and acceptance contract](paperclip-s4-constructor-acceptance-20261117.md). It is a **hypothesis and engineering target**, not a shipped feature or a changed Index grade. The contract pins the accepted evidence, explicit S4 decision/feedback owner, a five-port minimum design and ten falsifiable acceptance scenarios (`AC-01`–`AC-10`).

**Required minimum before calling a future implementation a candidate `C`:** a source-attributed external/future model-change signal → durable comparison of `hold` versus `candidate` against actual current S3 capability → first-party **S4-specific** decision port into which a developer can compose an autonomous evaluator/agent with bounded authority → authorized **future-run-only** configuration/capability revision → receipt from subsequent actual agent operation returning success or denial into S3. Include a working actor-composition example, unauthorized/unknown-compatibility/rollback negative tests, first-party reachability and existing-simpler-native comparison. A release notification, model catalog, optional generic plugin hook or human-only approval **fails** the autonomous constructor witness.

**Grade gate:** `C` requires subsequent first-party shipping and an independent source-pinned Index assessment under Skills; `P` remains a valid human-only S4 possibility if separately established. `C(P)` requires two independent mode witnesses and is not the target by default. Existing `S4=—` remains canonical.
**Preimplementation test of materiality:** for each candidate, state actor, exact currently impossible/awkward task, best native workaround, measurable output, right owner, enforcement, trace of decision to later execution, and overlap. If a shipped path already closes the task, report `NO_USEFUL_CHANGE` for that idea.

## Implementation options
Expand Down
Loading
Loading