diff --git a/CHANGELOG.md b/CHANGELOG.md index 74d014d..f62b262 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -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//`. 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. diff --git a/PROTOCOL.md b/PROTOCOL.md index d089402..955309f 100644 --- a/PROTOCOL.md +++ b/PROTOCOL.md @@ -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//` 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//` 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 @@ -24,7 +34,7 @@ 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//`. 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. @@ -32,13 +42,13 @@ Read [docs/FORK_METADATA.md](docs/FORK_METADATA.md) for the initial JSON contrac 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//`; 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:** diff --git a/docs/CAPABILITY_ROADMAP.md b/docs/CAPABILITY_ROADMAP.md index d6ce824..bb21c1c 100644 --- a/docs/CAPABILITY_ROADMAP.md +++ b/docs/CAPABILITY_ROADMAP.md @@ -8,6 +8,14 @@ This route tests whether reusable organizational specifications and source-nativ The normative [Profile](https://github.com/opensiro/vsm-harness-profile/blob/main/PROFILE.md) owns function semantics; [Skills](https://github.com/opensiro/vsm-harness-skills) owns grade/methodology; [Index](https://github.com/opensiro/vsm-harness-index) owns accepted assessments. Upstream does not overwrite their authority. +## Issue-local artifact storage and conditional original Issue + +`upstream roadmap` remains `PLAN_ONLY`. An explicitly requested persistent case belongs under the verified fork's `opensiro/meta:.opensiro/issues//` after checking the parent repository, meta HEAD and owner control. Store case-level `roadmap.md`, `constructor-acceptance.md`, external Issue drafts and technical receipts there, **not** in central Upstream. A public fork GitHub Issue for discussing/reviewing that case requires a separate exact approval of its full title/body; a case folder alone is not a GitHub Issue. + +Follow the [fork Issue → case evidence → original Issue route](../PROTOCOL.md#fork-github-issue--local-case--external-issue-separate-publication). Before any original Issue, dedupe the live original issue/PR set; link an existing original issue if it covers the outcome. For a new maintainer issue, request a **separate exact publication approval**, create a standalone original-native issue and read back its actual URL; store/cross-link it in the fork case. This is not GitHub native transfer across separate owners, nor automatic closure of the fork Issue. No grade change, product code implementation or public PR is implied by case publication. + +**Migrated case exemplars:** [Paperclip S4 roadmap](https://github.com/opensiro-contributions/paperclip/blob/opensiro/meta/.opensiro/issues/model-release-adaptation-20261117/roadmap.md) and [acceptance contract](https://github.com/opensiro-contributions/paperclip/blob/opensiro/meta/.opensiro/issues/model-release-adaptation-20261117/constructor-acceptance.md); [Browser Harness S3 roadmap](https://github.com/opensiro-contributions/browser-harness/blob/opensiro/meta/.opensiro/issues/browser-resource-control-20261117/roadmap.md). + ## 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. @@ -29,7 +37,7 @@ If the native delta or a true S4/S3/etc decision/closure witness is not establis ## Capability Roadmap Receipt -A compact, **read-only Markdown report** in chat, or a dated **non-authoritative example**. Do not create another issue/PR queue or a fork-local contribution ID just for a proposal. Required evidence sections: +A compact **plan-only Markdown report** in chat, or a dated **case record in the verified fork's `.opensiro/issues//`** when persistent storage is requested and authorized. Do not create an Upstream queue or an implementation contribution ID merely for the proposal. Required evidence sections: | Section | Required contents | | --- | --- | @@ -45,14 +53,14 @@ A compact, **read-only Markdown report** in chat, or a dated **non-authoritative **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. +For an implementation-oriented `C` target, see the [Paperclip S4=C proposed construction and acceptance contract](https://github.com/opensiro-contributions/paperclip/blob/opensiro/meta/.opensiro/issues/model-release-adaptation-20261117/constructor-acceptance.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: +The source-native receipt remains **PLAN_ONLY evidence in the fork metadata worktree**, not an implementation contribution, a public Issue, a fork-local review PR or Index assessment. For a dated Markdown case note, run: ~~~sh -python3 scripts/validate_capability_roadmap.py docs/examples/browser-harness-roadmap-20261117.md +python3 scripts/validate_capability_roadmap.py /path/to/fork-meta/.opensiro/issues//roadmap.md ~~~ The validator checks presence of pinned SHA/date fields, required receipt sections, an evidence link and explicit non-publication/cost status. **It does not read live GitHub, verify legal permissions, prove VSM function closure or certify lower cost.** Exact current GitHub readback and semantic review remain mandatory before any subsequent action. diff --git a/docs/FORK_METADATA.md b/docs/FORK_METADATA.md index 87707e6..696de8f 100644 --- a/docs/FORK_METADATA.md +++ b/docs/FORK_METADATA.md @@ -12,6 +12,8 @@ opensiro-contributions/ [verified parent: original owner/repo] └─ refs/heads/opensiro/meta [OpenSiro-only metadata branch] └─ .opensiro/ ├─ state.json [one fork identity, attention and owner control] + ├─ issues/ [case-level research, specs and issue drafts] + │ └─ / [README, roadmap, acceptance contract] ├─ contributions/ │ ├─ .json [one improvement; links to code/tests/PRs] │ └─ ... @@ -24,6 +26,16 @@ opensiro/upstream └─ links + latest source SHA + first-party PR readback (NOT duplicate logs) ``` +### Issue-local case worktree and two-Issue publication route + +For a verified working fork, authoritative **case-specific research and plan artifacts** belong at `.opensiro/issues//` on the **separate `opensiro/meta` worktree**. Use `README.md` for the identity, pinned refs, actual fork Issue number/URL (only when it exists), native overlap and next action; store `roadmap.md`, `constructor-acceptance.md`, draft external Issue and review receipts as needed. A plan is **not** an independently implemented improvement: never create `.opensiro/contributions/` solely for a case. `.opensiro/state.json` controls and append-only `events/` remain intact. + +A *public GitHub Issue* in the working fork is a separate discussion/index object, not synonymous with a file in `.opensiro/issues/`, a fork-local PR, or an original issue. Search for duplicate fork Issues and obtain **exact current-conversation publication approval** of the target, action and full public title/body before opening it. If no such approval exists, metadata-authorized case documents may remain without a GitHub Issue. Keep the internal Issue open until there is an actual independent closure reason. + +For an external original Issue, first check for an already-open equivalent original Issue/PR and **link rather than duplicate**. A fresh original Issue requires a **second independent exact publication approval**; write a maintainer-native self-contained proposal and then first-party-read back its actual URL. This is not native cross-owner Issue transfer; do not claim copied comments, numbering, reactions or ownership. Link publication in the fork's issue-local record; cross-reference from the fork Issue when separately permitted. Original GitHub owns its own state. + +Upstream stores only the shared protocol, templates, validators and source-linked aggregate—not named-fork roadmap/contract documents once the writable matching fork is verified. Historical committed versions are retained in Git history as provenance. Never put case files on the fork product/default branch or original PR diff, and fail closed for PAUSE/STOP or unknown metadata rights. + **Branch boundary.** Add `.opensiro/` only on the dedicated `opensiro/meta` branch, **never** on the original project's default branch, product/feature branch or an external third-party PR diff. First verify `fork=true`, actual `parent.full_name`, default branch, meta branch HEAD, rights and relevant contributor policy. Do not rewrite the original README or its CI. Do not force-push the meta branch or merge it into a product branch. If the source already uses `.opensiro/` or a branch collision exists, stop and resolve explicitly before writing. ## Materialize on demand during an authorized Upgrade @@ -119,9 +131,9 @@ For assessment-related types include `assessment_pin: {"url": ".json` record, and must not add a roadmap-state enum, ledger, owner-control override or metadata branch write. If actual native code is later authorized and independently qualified, reuse the existing schema-v2 **one improvement / one record** procedure on `opensiro/meta` and current source-linked provenance. No plan may silently promote `INSUFFICIENT` to `ASSESSMENT_DERIVED` or claim an external PR has merged based on the plan. +[Architecture-first `upstream roadmap OWNER/REPO`](CAPABILITY_ROADMAP.md) may link an accepted historical assessment, original issues/PRs and existing independent fork-local contributions. A **research-only architecture plan** or external issue draft is *not* itself a qualifying improvement and does **not** require a new `.opensiro/contributions/.json` record. If its durable storage is requested and current fork meta rights allow, persist it as `.opensiro/issues//` on the matched fork, not in Upstream. Do not add a new roadmap-state enum, ledger, or owner-control override. If actual native code is later authorized and independently qualified, reuse the existing schema-v2 **one improvement / one record** procedure on `opensiro/meta` and current source-linked provenance. No plan may silently promote `INSUFFICIENT` to `ASSESSMENT_DERIVED` or claim an external PR has merged based on the plan. ## One human-visible case, two independent facts diff --git a/docs/examples/browser-harness-roadmap-20261117.md b/docs/examples/browser-harness-roadmap-20261117.md deleted file mode 100644 index c8c3b61..0000000 --- a/docs/examples/browser-harness-roadmap-20261117.md +++ /dev/null @@ -1,88 +0,0 @@ -# Browser Harness — source-pinned architecture-first roadmap pilot - -**Snapshot:** 2026-11-17. **Status:** `DRAFT — NOT PUBLISHED`. Read-only, non-authoritative example for the [OpenSiro roadmap procedure](../CAPABILITY_ROADMAP.md); all GitHub statuses below can change. **This does not modify the original project, fork, accepted Index, or Profile.** - -## Identity and pins - -- Original repository: browser-use/browser-harness -- Original HEAD: bc274a297d893e94ee05b4901898809651876a2d -- Observed at: 2026-11-17 -- Accepted Index assessment: https://github.com/opensiro/vsm-harness-index/blob/d7d07e2f6db17d8ca9bc6c9c6c6d07892c611e1d/assessments/br/browser-harness.md -- Accepted assessment blob SHA: 7522febc97e2eff75e78ad781cec9ac64f480a94 -- Accepted review ref: afbcc381b963040c19627d788e40c7e7663171ee -- Accepted reviewed at: 2026-09-18 -- System in focus: shipped Browser Harness CLI, browser daemon, CDP/tab helpers, skill and MCP mode, with external agent actors; **not** Browser Use's separate maintainer organization or host product -- Assessment vector: `A C — — — —` (historical accepted Index, **not** a current-ref reassessment) -- Proposed Index re-review: [PR #3219](https://github.com/opensiro/vsm-harness-index/pull/3219), **open/unmerged at observation**, result `reassessed-unchanged` is **not canonical**. -- Profile reference: [Profile 0.2.4](https://github.com/opensiro/vsm-harness-profile/blob/main/PROFILE.md) (current semantic reference, not a retroactive source review) -- Skills reference: [Methodology 0.3.8](https://github.com/opensiro/vsm-harness-skills/blob/main/skills/assess-vsm-harness/references/autonomy-states.md) - -## Rights and authority - -- [MIT license](https://github.com/browser-use/browser-harness/blob/bc274a297d893e94ee05b4901898809651876a2d/LICENSE) permits copying/modifying subject to retained notice; third-party site terms and imported examples remain separate constraints. -- [CONTRIBUTING.md](https://github.com/browser-use/browser-harness/blob/bc274a297d893e94ee05b4901898809651876a2d/CONTRIBUTING.md) says focused improvements/PRs welcome and uncertain ideas may be proposed via issue. CLA/AI-specific attestations are **NOT VERIFIED** by this document, not presumed waived. -- Matching [fork](https://github.com/opensiro-contributions/browser-harness) and [fork metadata](https://github.com/opensiro-contributions/browser-harness/blob/opensiro/meta/.opensiro/state.json) were observed with `owner_control=ALLOW` and `attention=ACTIVE`; these are **not** a blanket approval to publish public issues, comments, fork PRs or external PRs. The fork may have advanced since this snapshot. -- External-publication route: separate exact owner approval for the concrete destination, full issue body/diff and action is **NOT GRANTED** by this pilot. - -## Existing work / overlap - -| Function hypothesis | Observed source | State at snapshot | What is established / not established | -| --- | --- | --- | --- | -| S1 task outcome safety | [fork PR #2](https://github.com/opensiro-contributions/browser-harness/pull/2) | OPEN fork-local proposal; head `0be45c484fe3a7a721bad48f37dc288ca9ee0fbc` | Guards non-idempotent action intent in a separate proposal; does not establish S3/S5 | -| S2 tab coordination | [issue #998](https://github.com/browser-use/browser-harness/issues/998) + [PR #1034](https://github.com/browser-use/browser-harness/pull/1034) | issue OPEN; original PR OPEN/unmerged; head `4056c5aece6e4a83ea999d60e42482b84f9eed7b` | Task-owned reconnection proposal, **not** shipped general whole-system S3 control | -| S3 resource/attachment control hypothesis | [issue #895](https://github.com/browser-use/browser-harness/issues/895) and [issue #901](https://github.com/browser-use/browser-harness/issues/901) | both issues OPEN | Browser preference and caller-owned health/metadata are real asks, **not** proof of an existing S3 constructor | -| S3* verification | [video-review path](https://github.com/browser-use/browser-harness/blob/bc274a297d893e94ee05b4901898809651876a2d/src/browser_harness/video_render.py) | SHIPPED artifact checks | Renderer review is not independent organizational audit judgment returning to S3 | -| S4 domain feedback hypothesis | [issue #934](https://github.com/browser-use/browser-harness/issues/934) and [merged PR #976](https://github.com/browser-use/browser-harness/pull/976) | issue OPEN, PR MERGED | Maintainer-curated skill policy at developer recursion; not a demonstrated prospective runtime S4 loop | -| S5 policy ownership | [CONTRIBUTING](https://github.com/browser-use/browser-harness/blob/bc274a297d893e94ee05b4901898809651876a2d/CONTRIBUTING.md) and [PR #976](https://github.com/browser-use/browser-harness/pull/976) | developer-level maintainer decisions | Does not establish runtime S5, S5=P or new identity-level use case | -| S1 domain skills discoverability | [fork PR #1](https://github.com/opensiro-contributions/browser-harness/pull/1) | OPEN fork-local proposal; head `13c404281b89003c3675d64a903cdc98b2139a96` | Optional export proposal; independent feature, not a general VSM solution | - -**Overlap boundary:** linked issues/PRs indicate active ideas; this snapshot inspected **PR metadata summaries and pinned first-party paths**, not every competing diff under matching native runtime tests. Function overlap and user-level impact therefore remain **UNVERIFIED** where stated. No third-party contributor branch can be edited without rights. - -## Function ownership - -- S1 browser actions: external task agent chooses navigation/interaction through first-party helpers; actual browser observations return to its next task action. -- S2: simultaneous external agents sharing one local daemon can interfere through tab switching; existing first-party skill prescribes serialization or isolated browser lane; host composes the coordinating actor. -- Candidate S3: **not established**. Host/operator may choose browsers and agent commitments, but source issue #895/#901 and a tab API do not demonstrate a whole-system allocator/decision owner with returned controls across tasks. -- S3*: video review checks media/source artifacts; no independent S3 corrective channel evidenced. -- S4: maintainer decisions on domain skills occur at another recursion; no first-party prospective options that return to S3 evidenced. -- S5: ordinary consent/preferences and maintainer PR policy are **not** a shipped identity/ultimate-policy decision and return loop; no inferred S5=P. - -## Capability priority - -**Candidate first user need (requires maintainer confirmation):** An operator running *multiple browser tasks* wants to inspect current task-owned lanes and commitments, choose a constrained shared-browser allocation, and obtain reliable subsequent-task feedback demonstrating that the choice applied, without mutating a user's unrelated tabs. - -- Baseline: existing first-party helpers and skill instructions support manual host-side serialization/isolation and tab targeting. -- Current alternatives: reuse [tab reconnection proposal #1034](https://github.com/browser-use/browser-harness/pull/1034) if accepted; or implement a simple host-side scheduler without new harness APIs. -- **S3=C is only a speculative target**, not an established current grade, not a mandate, and not an admission to implement a resource governor. Further source-native demand and competing-PR diff/behavior checks are needed. S2=C is already historically assessed. -- Stage P0: obtain maintainers' assessment of actual multi-agent task/resource-control need and overlap; if none, **NO_USEFUL_CHANGE**. -- Stage P1: if qualified, expose a minimal function-specific current-state/commitment/decision/feedback constructor and a *real* host assembly example; before/after native success, unauthorized ownership and compatibility checks. -- Stage P2 optional: independently proven parent-governed S3 current-control mode (`C(P)` or `P` if appropriate), with a legitimate decision owner and return to operations. -- Stage P3 optional: autonomous plus parent mode only if desired, with separate decisive-owner evidence for `A(P)`; no forced full autonomy. - -## Implementation options - -1. **Plan only first:** reorganize #895, #901, #998 and #1034 by current native user outcomes, distinguish overlap and choose no-code/integration or actual S3 constructor only if maintainers agree. This is not permission to edit those PRs. -2. **If qualified, small product PR:** a minimal host-composable shared-resource decision/feedback interface; keep S2 tab correctness work separate; each actual implementation follows full `upstream upgrade` tests, classification, fork-local review/publication gates. -3. **Native counterfactual:** compare a minimal external host scheduler using existing APIs against the proposed constructor under the same two-agent browser lane collision scenario. If new API does not improve a real task, omit it. - -## Specification and domain alternatives - -- Profile feedback: if the case reveals a real ambiguity in function-specific ownership/recursion/closure, propose evidence and counterexamples to [VSM Profile](https://github.com/opensiro/vsm-harness-profile) as a **separate normative review**, not a mandatory original project dependency. -- Skills feedback: if construction evidence / parent-mode calibration is ambiguous, send a separately scoped proposal to [VSM Skills](https://github.com/opensiro/vsm-harness-skills). -- Optional domain experiment: only with independent permission, explore an explicitly bounded **multi-tenant browser-work** fork; compare the smallest native scheduler to a VSM-informed constructor. This fork has **NOT BEEN CREATED** by this roadmap. - -## Cost experiment - -- Matched task: two external agents competing for one mutable browser lane while preserving each agent's tab ownership. -- Native baseline: simple host-side serialization and explicit isolated browser setup. -- Hypothetical variant: a verified first-party, composable current-control constructor with owner/feedback/closure. -- Costs to measure: engineering hours, integration/review/test effort, regressions and maintenance; task success and isolation correctness. -- Cost status: NOT_MEASURED -- No quantified developer saving, quality superiority, new VSM grade or maintainer endorsement is claimed. - -## Delivery and publication - -- Result: PLAN_ONLY -- External issue: DRAFT — NOT PUBLISHED -- Internal roadmap example: a dated, **non-authoritative snapshot**, not a durable fork event or original issue. -- External maintainer communication, original PR, public fork-local review PR, domain fork publication and normative Profile/Skills PR: **NONE CREATED** by this pilot. diff --git a/docs/examples/paperclip-roadmap-20261117.md b/docs/examples/paperclip-roadmap-20261117.md deleted file mode 100644 index 3f0c9cd..0000000 --- a/docs/examples/paperclip-roadmap-20261117.md +++ /dev/null @@ -1,97 +0,0 @@ -# Paperclip — architecture-first capability roadmap after Index re-assessment - -**Snapshot:** 2026-11-17. **Result:** `PLAN_ONLY`. **External issue: DRAFT — NOT PUBLISHED**. This is an internal, dated, **non-authoritative Upstream example** governed by [Capability Roadmap](../CAPABILITY_ROADMAP.md), not a second Index assessment, delivery promise, maintainer request, or third-party communication. - -## Identity and pins - -- Original repository: paperclipai/paperclip -- Original HEAD: 904c01d1a3a16de817792432d5d5a24f6e4bde12 -- Observed at: 2026-11-17 -- Accepted Index assessment: https://github.com/opensiro/vsm-harness-index/blob/975a58814b767cfca414c152480f787bfe80944b/assessments/pa/paperclip.md -- Accepted assessment blob SHA: 238863a500491b7851fa90478ae64b2471acb219 -- Accepted review ref: 7f9867895c4e7e9589b233a93aa9efceb0c992d0 -- Accepted reviewed at: 2026-11-17 -- Last successful assessment age: 0 calendar days at observation; **no 30-day freshness advisory**. The original default branch advanced five commits from the accepted review ref to the observed HEAD; those newer changes are **not part of the accepted Index assessment**, and their effect is not presumed. -- Accepted re-assessment lifecycle: [Index issue #3230](https://github.com/opensiro/vsm-harness-index/issues/3230), **CLOSED COMPLETED**; [Index PR #3235](https://github.com/opensiro/vsm-harness-index/pull/3235), **MERGED** at `975a58814b767cfca414c152480f787bfe80944b`; this source review changed the pin and evidence, not the six-function vector. -- System in focus: one supported **Paperclip company**, its first-party agent/runtime, goal, task, management, review and board-decision modes; not the Paperclip maintainers' development organization, a recursive manager subtree, non-installed provider/plugin actor, or private Cloud-only implementation. -- Assessment vector: **`S1=A S2=A S3=A(P) S3*=A S4=— S5=P`**, accepted and re-reviewed under [Profile 0.2.4](https://github.com/opensiro/vsm-harness-profile/blob/main/PROFILE.md) and [Methodology 0.3.8](https://github.com/opensiro/vsm-harness-skills/blob/main/skills/assess-vsm-harness/SKILL.md). This is a function-specific ownership observation, **not** a product-quality score or a reason to implement a missing VSM box. -- Original delta since accepted review: https://github.com/paperclipai/paperclip/compare/7f9867895c4e7e9589b233a93aa9efceb0c992d0...904c01d1a3a16de817792432d5d5a24f6e4bde12 ; five commits observed, no autonomous semantic reassessment at this newer head. - -## Rights and authority - -- Original source is [MIT-licensed](https://github.com/paperclipai/paperclip/blob/7f9867895c4e7e9589b233a93aa9efceb0c992d0/LICENSE). [Contributor rules](https://github.com/paperclipai/paperclip/blob/904c01d1a3a16de817792432d5d5a24f6e4bde12/CONTRIBUTING.md) require dedup, the source PR template, model-use disclosure, tests, and pre-coordination on Discord for larger core work; **no Discord contact was made**. CLA or human-attestation exemptions are **NOT VERIFIED** and are not assumed. -- [Matched fork](https://github.com/opensiro-contributions/paperclip) is verified to originate from `paperclipai/paperclip`; current [fork owner state](https://github.com/opensiro-contributions/paperclip/blob/opensiro/meta/.opensiro/state.json) was **ACTIVE / ALLOW** at 2026-11-17 15:11 UTC. This is not consent to publish a fork-local PR or contact Paperclip maintainers. Re-read controls before any future effectful step. -- External-publication approval for this receipt, any architecture issue, comment, fork-local public PR or external PR: **NOT GRANTED**. This receipt creates none. - -## Existing work / overlap - -| Function/need | Evidence | Observed status | Boundary | -| --- | --- | --- | --- | -| S4 model-release compatibility and upgrade choices | [Original issue #20848](https://github.com/paperclipai/paperclip/issues/20848) | **OPEN, issue only** | Proposes opt-in detection, capability-aware recommendation, authorization, canary/rollback; not shipped | -| S3/S4 adaptive subscription and CEO budget feedback | [Original issue #3406](https://github.com/paperclipai/paperclip/issues/3406) | **OPEN, issue only** | Current usage/threshold handling versus proposed future operating alternatives need separation | -| S3 scheduled resource admission | [Original issue #16504](https://github.com/paperclipai/paperclip/issues/16504) and [PR #13379](https://github.com/paperclipai/paperclip/pull/13379) | **Issue OPEN, PR OPEN / UNMERGED** (head `43b61148378cc045ff0eda5ad0f5b754c496b4be`) | Deferral under exhausted subscription is not itself prospective adaptation | -| AI account selection extension | [PR #14967](https://github.com/paperclipai/paperclip/pull/14967), [issue #16954](https://github.com/paperclipai/paperclip/issues/16954) | **PR MERGED**; **OSS reference router issue OPEN** | Host `ai.connections.route` is shipped; learned cooldown/Cloud policy not credited as a first-party S4 actor | -| S5 board decision-source identity | [Issue #18296](https://github.com/paperclipai/paperclip/issues/18296), [PR #17857](https://github.com/paperclipai/paperclip/pull/17857) | **Issue OPEN, PR OPEN / UNMERGED** (head `b6cd49d4b6926fae61a2c68a31ce7c659b69eaa6`) | Approval audit/source and budget control may be valuable, but generic approval is not a new S5 grade | -| S3* review-stage recovery | [PR #15265](https://github.com/paperclipai/paperclip/pull/15265) | **OPEN / UNMERGED** (head `28183072c57ef8f035a0851aed2e03f4df9b7f77`) | Existing optional distinct-reviewer mode is already `S3*=A`; don't duplicate it | -| Independent OpenSiro research | [S3/S4 resource research](https://github.com/opensiro-contributions/paperclip/blob/opensiro/meta/.opensiro/contributions/paperclip-s3-s4-adaptive-resource-feedback.json), [S5 decision source](https://github.com/opensiro-contributions/paperclip/blob/opensiro/meta/.opensiro/contributions/paperclip-s5-approval-decision-source.json), [S5 strategic authority](https://github.com/opensiro-contributions/paperclip/blob/opensiro/meta/.opensiro/contributions/paperclip-s5-strategy-approval-authority.json) | Existing separate fork-local **RESEARCH**, not shipped code or accepted Index evidence | Reuse these records, don't manufacture a fourth contribution simply for this roadmap | - -**Dedup limit:** The list above is a dated census of related original issues/PR heads and fork-local records, not a claim that every competing diff/test has been exhaustively evaluated. Before any implementation, re-read exact current code and heads, assess native behavior and maintainer decisions; do not duplicate an accepted PR or prescribe a controller from the `S4=—` label. - -## Function ownership - -- **S1=A:** first-party report agents autonomously checkout and execute assigned work, return results and affect subsequent tasks via the Paperclip heartbeat contract. -- **S2=A:** CEO/managers choose allocation/dependency/unblocking outcomes among distinct report-agent units, while deterministic single checkout and blockers enforce the decision; status feeds back into later wakes. -- **S3=A(P):** model-driven managers own current company resource/priority intervention in one mode; board users independently retain effective override over budget, assignments and agent state in another. These are separate operational arrangements. -- **S3*=A:** an optional first-party execution policy assigns a distinct non-executor reviewer who judges the claim and returns approval or change request into next task state. -- **S4=—:** pinned first-party evals, saved skills, routines, optional memories and model connection routing don't demonstrate a distinct external/future sensing → adaptation options → authorized choice → modified operating capability loop. [Self-Organization and Automatic Organizational Learning](https://github.com/paperclipai/paperclip/blob/7f9867895c4e7e9589b233a93aa9efceb0c992d0/ROADMAP.md) remain planned; no invented grade for an issue/open PR/plugin. -- **S5=P:** first-party company board approves or rejects purpose/CEO strategy and its decision returns to executable work; the ultimate policy owner is legitimately human/parent. **P can be the final desired mode**, not a deficiency. - -## Capability priority - -**P0 — optional model-release adaptation closure, conditional on the actual native gap.** Hypothetical actor: operator responsible for a Paperclip company's future model portfolio. Disturbance: announced changes to model availability, API, price or capability. Candidate user outcome: receive a compatible, evidence-ranked option, approve or reject a future-run-only configuration update, optionally canary/rollback, and later observe whether the chosen setting was applied. Start from [existing issue #20848](https://github.com/paperclipai/paperclip/issues/20848); inspect product and PR overlap before offering new code. This is a **proposed S4-specific first-party constructor**, not current `S4=C`. - -**P1 — current capacity-to-future policy feedback without duplicating quota admission.** Actor: CEO/board/operator managing several agents. A scheduled/subscription demand trend changes future run feasibility; the user needs alternatives with a real decision owner and verification on subsequent runs, not merely a reactive 429 handler. First compare shipped gateway resource management and [#3406](https://github.com/paperclipai/paperclip/issues/3406), [#16504](https://github.com/paperclipai/paperclip/issues/16504), [#13379](https://github.com/paperclipai/paperclip/pull/13379) and [#15791](https://github.com/paperclipai/paperclip/pull/15791). If a simpler native scheduling tweak closes the task, prefer it. - -**P1 — reserved strategic approval-authority boundary, not a new S5 grade.** Actor: company board establishing legitimate authorities for CEO strategy changes. Hypothesis: per-company named principals/channels and enforcement provide a material new ability beyond approval provenance. Check whether the operator can designate who is entitled to approve a **strategy-level** decision and whether the resulting policy actually prevents unauthorized approval across supported entry points. Existing [fork RFC](https://github.com/opensiro-contributions/paperclip/blob/opensiro/meta/.opensiro/proposals/paperclip-s5-strategy-approval-authority.md) and [issue #18296](https://github.com/paperclipai/paperclip/issues/18296) already cover parts; avoid a duplicate issue. Routine execution approvals are not automatically S5. - -**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 - -1. **First, plan-only/source validation:** trace current Paperclip code and exact issue/PR head/diff for P0; use existing issue #20848 instead of posting a duplicate. A roadmap is complete without source changes. -2. **Small product-native change only if qualified:** opt-in notification, compatibility/decision witness and future-run-only application, preferably first-party plugin or extension route if technically sufficient and admissible; do not bypass board authority, security and existing review stages. Route any actual implementation through standard `upstream upgrade`, a single stable contribution ID per independently useful change, native tests, disclosure and public-publication approval. -3. **Simpler alternative first:** manual release notification + a documented operator config change or a small scheduled check, with no new VSM-specific API if it meets the same user need. -4. **No change:** a credible final disposition if existing code/PRs solve it or product demand is not supported. - -## Specification and domain alternatives - -- **Profile feedback:** if the evidence exposes a genuine ambiguity about outside-and-future feedback, owner boundary, parent mode or recursion, propose a separately governed semantic question to [Profile](https://github.com/opensiro/vsm-harness-profile); do not alter its semantics in Upstream. -- **Skills feedback:** if current source exposes an actual ambiguity about `C` evidence or negative-state adjudication, propose a separate method-calibration issue/PR to [Skills](https://github.com/opensiro/vsm-harness-skills); do not edit accepted Index grades directly. -- **Optional domain-specific fork:** only if lawful and operator-approved, isolate a model-portfolio adaptation experiment within the matched Paperclip fork; specify first-party vs added actor and compare a simpler native mode. No product-branch change or fork PR was created here. - -## Cost experiment - -- Matched task: an external model provider releases a materially changed model while a multi-agent Paperclip company needs to decide whether and how to upgrade its agents without affecting unauthorized live sessions. -- Native baseline: existing model configuration, operator research and manual change (or small native notification feature). -- VSM-informed variant: bounded function-specific external-signal/option/authorization/feedback constructor with the same supported input, operator, acceptance criteria and future-run execution semantics. -- Measure: total engineering hours, onboarding/integration, review/CI and native test effort, observed task completion/correct authority/rollback behavior, code surface and subsequent maintenance/regression cost; repeat on comparable tasks before making a cost claim. -- Cost status: NOT_MEASURED -- No demonstrated lower cost, productivity gain, added VSM grade, original maintainer endorsement or deployment benefit is claimed. - -## Delivery and publication - -- Result: PLAN_ONLY -- External issue: DRAFT — NOT PUBLISHED -- Accepted Index source: https://github.com/opensiro/vsm-harness-index/blob/975a58814b767cfca414c152480f787bfe80944b/assessments/pa/paperclip.md -- This is a dated **internal Upstream non-authoritative receipt**, with a new same-day accepted Index assessment rather than the old two-month assessment. -- New external original issue/comment/PR, public fork-local review PR, Discord message, source-code change, fork-local contribution record, Index grade change, Profile/Skills change, experiment result or cost claim: **NONE**. -- Only a separate exact current-conversation approval can authorize any later third-party public communication or fork review. diff --git a/docs/examples/paperclip-s4-constructor-acceptance-20261117.md b/docs/examples/paperclip-s4-constructor-acceptance-20261117.md deleted file mode 100644 index 4559ecf..0000000 --- a/docs/examples/paperclip-s4-constructor-acceptance-20261117.md +++ /dev/null @@ -1,75 +0,0 @@ -# Paperclip S4=C — proposed construction and acceptance contract - -**Status:** `PLAN_ONLY / DESIGN CANDIDATE`, observed 2026-11-17. **No Paperclip implementation exists in this document.** This is a reproducible engineering *target* for a possible first-party S4-specific constructor, **not a new Index score, a proven missing user demand or permission to publish an external issue/PR**. It is subordinate to [the Paperclip roadmap](paperclip-roadmap-20261117.md) and the current [Skills Methodology 0.3.8](https://github.com/opensiro/vsm-harness-skills/blob/main/skills/assess-vsm-harness/references/autonomy-states.md). - -## 1. System, evidence and counterfactual - -- **System in focus:** one Paperclip company with supported first-party agent execution, company configuration, real task/run lifecycle, CEO/management (S3), human board ultimate policy (S5) and independently scoped review (S3*). An uninstalled plugin, provider agent, private Cloud router or the Paperclip OSS maintainer organization does not supply ownership by default. -- **Accepted Index baseline:** [Paperclip canonical reassessment](https://github.com/opensiro/vsm-harness-index/blob/975a58814b767cfca414c152480f787bfe80944b/assessments/pa/paperclip.md), source `7f9867895c4e7e9589b233a93aa9efceb0c992d0`, `S4=—`. The separately observed original `master` at roadmap time was `904c01d1a3a16de817792432d5d5a24f6e4bde12`; do not silently credit those unassessed commits. -- **Native issue / strongest overlap:** [#20848 — model-release notifications and compatibility-aware upgrade recommendations](https://github.com/paperclipai/paperclip/issues/20848), observed OPEN. Compare current catalog work [#16658](https://github.com/paperclipai/paperclip/issues/16658), protected settings [#10125](https://github.com/paperclipai/paperclip/issues/10125) and any later merged equivalent before proposing new code. -- **Existing first-party boundaries:** [CEO heartbeat](https://github.com/paperclipai/paperclip/blob/7f9867895c4e7e9589b233a93aa9efceb0c992d0/server/src/onboarding-assets/ceo/HEARTBEAT.md), [company core concepts](https://github.com/paperclipai/paperclip/blob/7f9867895c4e7e9589b233a93aa9efceb0c992d0/docs/start/core-concepts.md), [approval routes](https://github.com/paperclipai/paperclip/blob/7f9867895c4e7e9589b233a93aa9efceb0c992d0/server/src/routes/approvals.ts), [AI connection router host](https://github.com/paperclipai/paperclip/blob/7f9867895c4e7e9589b233a93aa9efceb0c992d0/server/src/services/ai-connection-router.ts). [Experimental router contract](https://github.com/paperclipai/paperclip/blob/7f9867895c4e7e9589b233a93aa9efceb0c992d0/doc/connections/AI-CONNECTION-ROUTERS.md) is default-off and delegates policy to a plugin; generic model/account routing does **not** already establish S4. -- **User-level unmet task to verify:** a company operator wants to consider an *external future change* (new/retired model + changed execution-compatibility/price), compare future operating options, delegate bounded analysis to an agent, and know that an accepted recommendation actually changed the next eligible operating run without affecting unapproved current tasks. **This is an engineering hypothesis until supported by native user evidence.** -- **Simplest existing alternative:** operator checks official release notes, inspects actual agent/adapter versions and eligible accounts, manually edits a compatible model setting and checks the next run. If this is sufficient, choose `NO_USEFUL_CHANGE` rather than adding a framework. - -## 2. Functional witness required for a positive S4 constructor - -A proposed `S4=C` mapping requires **all** of the following first-party reachable capabilities, not merely a code module named “adaptation”: - -| Link in loop | Proposed required output | Owner / negative control | -| --- | --- | --- | -| External and prospective observation | A dated, source-attributed model availability/deprecation/capability signal relevant to an actually configured company agent | Polling/storage are deterministic; release-note ingestion alone is not S4 | -| Model present vs possible future | At least **hold** and **candidate change** options, grounded in a snapshot of current agent configuration, adapter/client compatibility, eligible account, budget, reviewer role and predicted future-run impact; unknowns explicit | Internal task scheduling or a new-model notification alone is not prospective option formation | -| Decisive S4 decision/feedback constructor | A **function-specific first-party decision port** by which a developer can compose a real autonomous evaluator/agent and bind a bounded organization-level option-selection right | The composed actor owns choosing between options; generic event hooks or a human-only button do not establish autonomous `C` | -| Authorized selection | Persisted option choice (including reject/defer/hold), decision principal, policy/approval evidence, concurrency generation and reason | An evaluator cannot mint S5 authority; board/parent retains reserved policy approval | -| Return to S3/present capability | Controlled **future-run-only** configuration stage/commit, or another concrete first-party company-capability revision, with actual effective-state/next-run receipt and failure feedback | A recommendation in a dashboard, an unexecuted ticket, or a test mock with no first-party return path is not closure | - -**Owner counterfactual:** with a configured evaluator removed, the first-party interface still exposes a meaningful S4-specific choose/authorize/return path, but it cannot independently exercise autonomous option-selection judgment. With the developer-composed agent connected, its different decisions must lead to different authorized later company states through that same path. If the core itself selects and closes the function autonomously, examine `A`; if only a legitimate human parent closes a function-specific loop and no autonomous constructor is supported, examine `P`. A separate closed parent S4 mode might justify `C(P)`, **never** simply because a board can approve an ordinary configuration edit. - -## 3. Proposed minimal first-party ports (names illustrative, NOT existing endpoints) - -A *thin* slice may implement the following contracts using current Paperclip type/authorization/concurrency conventions; these logical names are proposals, not assertions about current routes, files or stable APIs. - -1. **`ReleaseSignalSource`**: import a verified provider release/change record with `companyId`, `provider`, `currentModelId`, `candidateModelId`, `sourceUrl`, `sourceObservedAt`, `effectiveAt`, `sourceDigest` and `idempotencyKey`. A test fixture or operator-imported official manifest is enough for the first slice; a live poller may be optional. Store provenance, never treat an unverified provider listing as account entitlement. -2. **`S4AdaptationCaseStore`**: persist `caseId`, source event revision, affected company/agent IDs, current configuration revisions, an environment snapshot, predicted differences, *at least hold and test/stage alternatives*, capability/price evidence, known/unknown/blocked compatibility and expiry. Distinguish `observation` → `options-ready` → `decision-pending` → `accepted/rejected/stale`; cap fanout/deduplicate by source/model/company. -3. **`S4DecisionPort`**: expose an explicit, company-scoped `evaluateAdaptationCase(caseId, snapshot)` / `submitAdaptationDecision(caseId, choice, actor, expectedVersion, reason)` path **for a configured autonomous agent actor**. The developer composes its model/authority within the existing Paperclip agent/harness contract. The core validates principal, delegated decision scope, idempotency and version but does **not** fabricate the substantive S4 option choice. -4. **`FutureRunCapabilityBridge`**: accept only an authorized **staged future-use** change after compatibility, reserved board approvals and concurrency checks. It must not silently rewrite an active run, agent's unrelated configuration, independent reviewer binding, credentials, shared access or budgets. Capture before/after configuration revision; reject stale proposals and revoked rights. A safe manual approval may be a gating policy, but is not evidence of an autonomous `C` owner. -5. **`S3ReturnAndObservation`**: attach an immutable decision→staged-revision→next-eligible-run reference. Confirm which model/config was *actually resolved* for that run, feed success/denial/fallback to the current company/CEO management view, and let the authorized owner hold/revise/revert a future-use choice. “Queued change” alone is not sufficient feedback. - -**Implementation boundary:** a generic MCP connection, webhook, task list, arbitrary callback registration, model catalog or `Ask first` permission is only supporting machinery. To count toward `C`, the *shipped first-party distribution* must expose an intentionally S4-specific constructor path and an example showing a developer-composed agent actually selecting a future-oriented adaptation option and receiving closure into later company operation. It may be opt-in, but its relevant host/bridge pieces must be real and reachable without proprietary unseen services. - -## 4. Ordered acceptance scenarios / release gates - -Each case is deterministic, runs against a **pinned Paperclip source revision**, includes a before/after expected state and records a native test or reproducible runner trace. A mock provider release catalog, test company and non-secret compatible adapter fixture may replace live paid model accounts. - -| ID | Input / decision | Required observable result | -| --- | --- | --- | -| `AC-01` External change | Official-model fixture announces a new successor used by an agent | One provenance-pinned case, source/time/affected agents, **hold** and **candidate** alternatives; stable dedup on repeated polling | -| `AC-02` Future/current coupling | Model option available but installed CLI version or account eligibility is unknown/incompatible | Case marks **unknown/blocked**; cannot claim ready-to-apply or execute the option | -| `AC-03` Actual constructor | Connect one real first-party company agent to the S4-specific decision port; feed same case under two controlled future scenarios | Agent-owned choice changes option receipt (hold vs stage); actor/principal, scope and reason are attributed; external decision logic remains developer-composable | -| `AC-04` Return into present capability | Authorized choice selects compatible candidate after required approval | Version-guarded future-use configuration change is staged; next **eligible** agent run uses expected resolution and returns a linked observation receipt; current run stays pinned | -| `AC-05` S5 reserved rights | Agent has S4 option-selection rights but not ultimate company policy or model-change approval rights | Without required approval, result stays pending/denied; no silent S5 transfer, new credential, grant, purchase or budget expansion | -| `AC-06` Wrong actor | Other company/agent/user attempts to submit or apply a case | Cross-company and unauthorized decisions fail closed; no state mutation and no leaked model/account data | -| `AC-07` Concurrency and revocation | Submitted against outdated agent config, removed account, expired signal or revoked delegated rights | Conflicting case rejects with reason; no change to protected config, reviewer selection or active sessions | -| `AC-08` Refusal/deferral | Configured actor chooses hold or authorized board rejects | Durable reason and suppression/snooze rule; no future-run change and no duplicate notifications for the same source revision | -| `AC-09` Negative S4 witness | Only notification, release notes, eval memory, plain job queue or human button is active | Test confirms **no autonomous constructor claim** from these components alone; labels stay `support/possible P`, never asserted `C` | -| `AC-10` Failure feedback | A staged model becomes unavailable at the next run or a canary fails | Failure is surfaced to S3/owner, with bounded stop/revert where provided; no silent repeated upgrade or lost decision provenance | - -**Native quality gates:** no credentials in fixtures; all new permissions map to existing role/company boundaries; source-verified compatibility checks; no control-plane bypass; robust idempotency/cancellation; audit with source and actor; unchanged ordinary agent/review/approval behavior. The first slice can defer sophisticated canary dashboards, ML ranking or many-provider polling, **not** the function-specific ownership/feedback path. - -## 5. Engineering sequence and evidence for Index re-review - -- **P0 — demand and dedup:** compare the full current first-party mode, issue #20848 and any competing implementation diff; show a current user task that manual settings cannot handle sufficiently well. If no credible user value, end `NO_USEFUL_CHANGE`. -- **P1 — smallest usable vertical slice:** import a trusted single-provider signal → persist two options and compatibility state → configure one first-party autonomous evaluator via S4 decision port → authorized future-use config stage → next-run actual-state receipt/feedback. Implement as a supported optional feature if that fits the original product better than a global controller. Tests `AC-01` through `AC-09` (plus safety aspects of `AC-10`) are mandatory for a `C` target. “Notification only” may be useful as a **product** contribution but cannot be described as a completed `C` constructor. -- **P2 — optional enhancement after demand:** live provider polling, better diff/cost projections, canary and rollback UX, multiple adapter backends, proactive retirement support; measure costs and avoid duplicate control surfaces. -- **Publication:** any actual product code requires the existing `upstream upgrade` functional-delta, native-test, verified fork, license/contributor/AI disclosure, fork-local review and separate external-publication gates. Plan-only has no permission to open a Paperclip issue/comment/PR or a public fork-local PR. -- **Reassessment gate:** only after code really ships at a newly pinned source ref, an **Index-owned fresh source-first review** may decide whether `S4=C` (or another state) is supported. The engineering tests prove a product feature; they are **not** an automatic grade or independent S4 semantic proof. -- **Cost hypothesis:** compare matched operator-run migration task against manual-native workflow with implementation/integration/testing, maintenance effort, actual future-run success, error and rollback safety. **Cost status: NOT_MEASURED**. - -## 6. Decisions still open - -- Is this desired as a first-party optional company feature or a plugin with a **genuinely first-party S4-specific host bridge**? A generic uninstalled plugin cannot independently establish `C`. -- What source is authoritative for model availability **and** actual adapter/account eligibility, and who may authorize each company-level configuration class? -- Is an autonomous evaluator a realistic product user need, or is board-only review sufficient (`P` candidate, not automatically `C`)? This must be resolved by source-native operator evidence rather than a target grade. -- Which single future-use setting can be changed safely without altering reviewer independence, current sessions, provider account access or budget policy? - -**Stop condition:** if any essential `C` witness (externally prospective input, structured options, developer-composable decisive actor, authorized first-party return or observed later-use feedback) cannot be made source-native and testable, record the unresolved condition and choose `NEEDS_EVIDENCE` or a smaller feature rather than calling a notification feature `S4=C`. diff --git a/tests/test_capability_roadmap_contract.py b/tests/test_capability_roadmap_contract.py index 23a6cef..7464c8b 100644 --- a/tests/test_capability_roadmap_contract.py +++ b/tests/test_capability_roadmap_contract.py @@ -1,52 +1,113 @@ -"""Plan-only receipt checks: structure, not live GitHub or VSM semantics.""" +"""Source-neutral plan-only receipt tests; real case artifacts live in the fork.""" from pathlib import Path +import re import sys import unittest ROOT = Path(__file__).resolve().parents[1] -sys.path.insert(0,str(ROOT/"scripts")) +sys.path.insert(0, str(ROOT / "scripts")) from validate_capability_roadmap import validate # noqa: E402 -PILOT=(ROOT/"docs/examples/browser-harness-roadmap-20261117.md").read_text(encoding="utf-8") + +RECEIPT = """# Synthetic source-neutral plan-only receipt + +## Identity and pins +- Original repository: example/harness +- Original HEAD: aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa +- Observed at: 2026-11-17 +- Accepted Index assessment: https://github.com/opensiro/vsm-harness-index/blob/bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb/assessments/ex/example.md +- Accepted assessment blob SHA: cccccccccccccccccccccccccccccccccccccccc +- Accepted review ref: dddddddddddddddddddddddddddddddddddddddd +- Accepted reviewed at: 2026-11-16 +- System in focus: one synthetic company in an imaginary harness + +## Rights and authority +No publication authority is assumed. + +## Existing work / overlap +Source overlap is hypothetical. + +## Function ownership +A planned capability is not a classification. + +## Capability priority +Native alternative must be considered. + +## Implementation options +No code changes are requested. + +## Specification and domain alternatives +Profile and Skills own semantics and method. + +## Cost experiment +- Cost status: NOT_MEASURED + +## Delivery and publication +- Result: PLAN_ONLY +- External issue: DRAFT — NOT PUBLISHED +""" class CapabilityRoadmapReceiptTests(unittest.TestCase): - def test_source_pinned_pilot_passes(self): - self.assertEqual(validate(PILOT), []) + def test_source_pinned_fixture_passes(self): + self.assertEqual(validate(RECEIPT), []) def test_missing_original_pin_fails(self): - import re - broken=re.sub(r"(?m)^- Original HEAD: .+$","- Original HEAD: missing",PILOT) - self.assertIn("invalid format: Original HEAD",validate(broken)) + broken = re.sub(r"(?m)^- Original HEAD: .+$", "- Original HEAD: missing", RECEIPT) + self.assertIn("invalid format: Original HEAD", validate(broken)) def test_unpinned_index_link_fails(self): - import re - broken=re.sub(r"(?m)^- Accepted Index assessment: .+$", - "- Accepted Index assessment: https://github.com/opensiro/vsm-harness-index/blob/main/assessments/br/browser-harness.md",PILOT) - self.assertIn("Index assessment must use a frozen commit, not main",validate(broken)) - - def test_no_external_write_authorization_from_plan(self): - self.assertIn("external issue must be explicitly DRAFT — NOT PUBLISHED", - validate(PILOT.replace("- External issue: DRAFT — NOT PUBLISHED","- External issue: PUBLISHED"))) - - def test_no_unmeasured_cost_shortcut(self): - self.assertIn("cost status must remain NOT_MEASURED until independently measured", - validate(PILOT.replace("- Cost status: NOT_MEASURED","- Cost status: VERIFIED_CHEAPER"))) - - def test_grade_claim_cannot_be_structurally_certified(self): - self.assertIn("S3=C is only a speculative target",PILOT) - self.assertIn("not a general VSM solution",PILOT) - self.assertIn("does not establish runtime s5",PILOT.lower()) - self.assertIn("NOT BEEN CREATED",PILOT) - - def test_guide_preserves_noncanonical_scope(self): - s=(ROOT/"docs/FORK_METADATA.md").read_text() - self.assertIn("Plan-only capability roadmaps are not new fork records",s) - self.assertIn("not* itself a qualifying improvement",s) - self.assertIn("schema-v2",s) - h=(ROOT/"docs/UPGRADE_PR_REVIEW.md").read_text() - self.assertIn("Architecture-roadmap dependency handoff",h) - self.assertIn("DRAFT — NOT PUBLISHED",h) - -if __name__=="__main__": + broken = re.sub( + r"(?m)^- Accepted Index assessment: .+$", + "- Accepted Index assessment: https://github.com/opensiro/vsm-harness-index/blob/main/assessments/ex/example.md", + RECEIPT, + ) + self.assertIn("Index assessment must use a frozen commit, not main", validate(broken)) + + def test_no_automatic_external_issue_from_plan(self): + broken = RECEIPT.replace("- External issue: DRAFT — NOT PUBLISHED", "- External issue: PUBLISHED") + self.assertIn("external issue must be explicitly DRAFT — NOT PUBLISHED", validate(broken)) + + def test_unmeasured_cost_not_assumed(self): + broken = RECEIPT.replace("- Cost status: NOT_MEASURED", "- Cost status: VERIFIED_CHEAPER") + self.assertIn("cost status must remain NOT_MEASURED until independently measured", validate(broken)) + + def test_validator_is_structural_not_grade_certification(self): + self.assertEqual(validate(RECEIPT + "\nA putative S4=C remains unverified.\n"), []) + guide = (ROOT / "docs/CAPABILITY_ROADMAP.md").read_text() + self.assertIn("not a changed Index grade", guide) + + def test_fork_case_and_contribution_are_distinct(self): + metadata = (ROOT / "docs/FORK_METADATA.md").read_text() + self.assertIn("Plan-only capability roadmaps are not new contribution records", metadata) + self.assertIn(".opensiro/issues//", metadata) + self.assertIn("not* itself a qualifying improvement", metadata) + self.assertIn("schema-v2", metadata) + self.assertIn("do not claim copied comments, numbering, reactions or ownership", metadata) + protocol = (ROOT / "PROTOCOL.md").read_text() + self.assertIn("Fork GitHub Issue", protocol) + self.assertIn("not a promised GitHub native cross-owner Issue transfer", protocol) + self.assertIn("obtain **new, separate, exact current-conversation owner approval**", protocol) + self.assertIn("Do **not** automatically close the internal Issue", protocol) + + def test_only_source_neutral_examples_in_upstream(self): + for name in ( + "browser-harness-roadmap-20261117.md", + "paperclip-roadmap-20261117.md", + "paperclip-s4-constructor-acceptance-20261117.md", + ): + self.assertFalse((ROOT / "docs/examples" / name).exists()) + guide = (ROOT / "docs/CAPABILITY_ROADMAP.md").read_text() + self.assertIn("opensiro-contributions/paperclip/blob/opensiro/meta/.opensiro/issues/", guide) + self.assertIn("opensiro-contributions/browser-harness/blob/opensiro/meta/.opensiro/issues/", guide) + self.assertNotIn("docs/examples/", guide) + + def test_roadmap_and_issue_are_not_publication_approval(self): + guide = (ROOT / "docs/CAPABILITY_ROADMAP.md").read_text() + self.assertIn("separate exact approval", guide) + self.assertIn("public fork GitHub Issue", guide) + self.assertIn("PLAN_ONLY", guide) + + +if __name__ == "__main__": unittest.main()