From 0efd239b8ad1ac968bac99955eb308b9daa69de1 Mon Sep 17 00:00:00 2001 From: alexruidan <41616537+xLagerFeuer@users.noreply.github.com> Date: Wed, 18 Nov 2026 00:51:38 +0300 Subject: [PATCH 1/2] docs(roadmap): require useful C sufficiency paths and adopt Issue v2 Prioritize first-party C construction for functions without evidenced C or A, exclude already-autonomous functions from mandatory C engineering, preserve legitimate parent rights, separate P0 targets from P1 prerequisites and P2 optional modes. Adopt eight-section target/dependency/sufficiency Issue template with tests. --- CHANGELOG.md | 2 + PROTOCOL.md | 6 +- docs/CAPABILITY_ROADMAP.md | 15 ++- templates/FORK_CAPABILITY_ROADMAP_ISSUE.md | 122 +++++++++++++-------- tests/test_fork_roadmap_issue_template.py | 102 +++++++++++------ 5 files changed, 164 insertions(+), 83 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index c14f548..dbeda45 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 +**C-first capability roadmap + approved v2 fork Issue template (unreleased):** Roadmap research now explicitly seeks a minimal, user-justified first-party `C` construction path for relevant functions without confirmed `C` or `A`. Existing `A`/`A(P)` and `C`/`C(P)` are exempt from mandatory C targets; `P` rights remain legitimate. Distinguish P0 C sufficiency, P1 enabling dependencies and P2 optional independent modes. Adopt the eight-section evidence and target-matrix fork Issue template v2; require a source-native coverage/acceptance and no-grade gate. No automatic implementation, Index write, version bump or external publication. + **Generic fork-local roadmap Issue template (unreleased):** Add a concise, project-neutral, evidence-first Issue skeleton for Opensiro's own verified working forks. It ties the user's outcome to existing original code/Issues/PRs, optional VSM-derived priorities, acceptance, native alternatives, paired cost measurement and a conditional handoff, while keeping case artifacts on `opensiro/meta`. This is distinct from the existing external architecture Issue template and authorizes no public Issue, implementation or new grade. No named-fork research edited, version bump or Release. **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. diff --git a/PROTOCOL.md b/PROTOCOL.md index fbaa6a3..3dbfd61 100644 --- a/PROTOCOL.md +++ b/PROTOCOL.md @@ -36,10 +36,14 @@ Read [docs/FORK_METADATA.md](docs/FORK_METADATA.md) for the initial JSON contrac **Route contract.** `upstream roadmap OWNER/REPO` is a **conversational, named-original, 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), the [fork-local roadmap Issue template](templates/FORK_CAPABILITY_ROADMAP_ISSUE.md) for OpenSiro discussion, and the separate [external architecture Issue template](templates/EXTERNAL_ARCHITECTURE_ISSUE.md) for a permitted original-project proposal. +**Roadmap default objective — function-scoped C sufficiency, not grade maximization.** For each relevant function without confirmed `C`/`C(P)` or `A`/`A(P)` at the declared first-party boundary, **investigate a minimal, useful, function-specific construction path sufficient for a future `C` witness**. First resolve stale `?` evidence and source drift, and retain `P` as a valid autonomous-actor-absent, parent-governed arrangement with reserved authority. A function already at `A`/`A(P)` is **not required** to be converted into `C`: `A` does not logically prove a reusable `C` constructor, but it satisfies this route's default no-mandatory-C-work exclusion. `C`/`C(P)` also need no duplicate constructor target. Prioritize user need and defensible engineering materiality; do not manufacture changes simply to fill a historical low grade. If no useful `C` target survives current-source validation, explicitly report `NO_USEFUL_CHANGE` or `NEEDS_EVIDENCE`, with reasons, rather than silently substituting unrelated general enhancements. + +**Mandatory research priority and sufficiency receipt:** `P0` = the strongest qualified, useful **C-target capability** with complete proposed minimal coverage; `P1` = dependencies and integration/authority/test changes required to enable that target (these may execute first); `P2` = optional independent modes `C(P)`/`A(P)` and other separately justified enhancements. These are **work priorities**, not a maturity ordering of `A`, `C`, `P`. For every candidate, show accepted historical state, actual current-source evidence, original Issues/PRs with status, target and smallest necessary new changes, exact decision/feedback constructor, rights, supported reachability, observable positive/negative acceptance and **why the combined set would be sufficient** for a later `C` assessment. State what remains unverified. When a selected function already has `A`/`A(P)` or `C`/`C(P)`, mark it **excluded from mandatory C targets**; any further source-native enhancement needs a separate material user benefit. Preserve the legitimate parent `P` boundary. + 1. **Freeze one source and check rights.** Pin the actual original default HEAD, source boundary/recursion, existing Index assessment file SHA plus historical `review_ref`/`reviewed_at`, Profile/Methodology versions and observed relevant PR/issue refs. An unmerged reassessment is not canonical. Perform the existing read-only license/formalities and autonomy preflights. Verify fork and owner controls before effectful work; unreadable metadata is unknown, not permission. 2. **Recommend re-assessment when the accepted assessment is older than one month.** At the roadmap observation date, compare against the most recent **successful Index semantic re-review / reassessment** recorded for this harness (the accepted `reviewed_at`, or a later `last_checked_at` only when it is backed by successful longitudinal evidence under the applicable Skills Methodology). If **more than 30 calendar days** have passed, **recommend a source-pinned Index re-assessment before finalizing confident VSM gap/ownership claims**; also recommend it sooner when material product evolution is observed. Cite the dated canonical assessment, source HEAD and any actual Index re-review issue/PR; if none exists, offer the Index-owned `[Assessment re-review]` route. A calendar threshold is a **soft freshness recommendation, never an automatic grade change, mandatory waiting gate, new batch/round, or permission to open an issue or PR**. Without a completed accepted re-assessment, the roadmap may continue **read-only, explicitly provisional**, grounded in current original code and with the old accepted vector labeled historical. Unknown freshness remains unknown; a superficial source check, open issue/PR, or roadmap itself cannot reset it. 3. **Map real work and residual outcomes.** Identify shipped behavior, open or merged PR heads/diffs/tests, issues, experiments, and adjacent maintainer governance *separately*. For each relevant S1/S2/S3/S3*/S4/S5 mechanism name a native actor/task, disturbance, decisive owner/right, enforcement, feedback/closure and unserved user outcome. Record current main → competing PR → residual user capability with evidence and alternative; a missing historical grade does not independently justify a feature, a new controller, or a claimed grade. -4. **Design for useful composability before autonomy.** Prioritize a **function-specific** constructor that, when actually shipped and verified, can support `C`, not generic routing/hooks or an unrealized plan. **If the roadmap proposes implementing a `C` target, require an actionable construction contract before treating the plan as implementation-ready:** define the function's external/operational disturbance, proposed first-party entry point and durable state, inputs/options, who would own the decisive decision when an autonomous actor is composed, enforcement and return-to-operation feedback, distribution/mode reachability, native baseline and overlapping original work, plus positive and unauthorized/missing-closure acceptance tests. A notification, ordinary callback or optional generic plugin is not an independently justified `C`. Clearly label proposed interfaces rather than asserting they already exist. Optional `C(P)` and `A(P)` are separate two-mode capabilities only for S3/S4/S5, under the published Methodology, not a universal grade ladder; `P` alone may be the legitimate final choice. S1/S2/S3* do not publish parent-mode notation. Never imply a stage or future PR changes the Index score or transfers rights to an agent. +4. **C sufficiency first; useful composability before autonomy.** Use the `P0/P1/P2` research priority above. For each qualifying function lacking confirmed `C` or `A`, either produce a **complete, source-native constructor/acceptance contract** explaining the minimal *combined* set of shipped primitives, reusable original Issues/PRs and additional proposed work sufficient for `C`, or name why no such path can be responsibly proposed. The contract must establish a real actor counterfactual, specific operational/external disturbance, first-party function-specific decision/feedback port (not generic hooks), independently developer-composable autonomous actor and legitimate authority, state/options lifecycle, enforcement, return into subsequent operation, supported boundary reachability, positive and unauthorized/missing-closure/compatibility native acceptance tests. No existing Issue/open PR or future plan itself certifies shipped `C`; only a subsequent Index-owned review can classify actually shipped source. `C(P)` and `A(P)` are separately supported optional modes only for S3/S4/S5, not a mandatory progression. `P` alone can remain appropriate; S1/S2/S3* have no published parent notation. A simpler project-native solution or `NO_USEFUL_CHANGE` is preferable to a fake C controller. 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 *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. diff --git a/docs/CAPABILITY_ROADMAP.md b/docs/CAPABILITY_ROADMAP.md index d68551a..b84e8bc 100644 --- a/docs/CAPABILITY_ROADMAP.md +++ b/docs/CAPABILITY_ROADMAP.md @@ -8,9 +8,17 @@ 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. +## Default target and work priority + +**Target-first roadmap:** for relevant VSM functions without a confirmed `C`/`C(P)` or `A`/`A(P)` first-party path, investigate the **minimum source-native set of existing and proposed changes sufficient for a meaningful `C` constructor**. Use accepted Index grades only as dated evidence; inspect current source and resolve `?` before concluding a function is missing. Already-`A`/`A(P)` functions **do not need C engineering work** for this roadmap, even though `A` does not logically imply a reusable `C` interface. Already-`C`/`C(P)` functions also do not need another constructor. Parent-governed `P` is legitimate, and may be retained as the final mode when an autonomous constructor adds no user value or violates reserved authority. + +**P0** is the best evidence-backed, useful function-specific *C sufficiency target*, backed by the combination of actual first-party primitives, original Issues/PRs and necessary missing changes. **P1** covers **prerequisites** for that target, including integration, authorization and tests; these dependencies may have to execute before P0 can be delivered. **P2** is independently valuable but optional: a separately evidenced `C(P)`/`A(P)` mode, refinements or optimizations. Priority is based on material user benefit, composability feasibility, reuse of existing work, dependencies and measured-or-hypothesized effort—not the lowest historical grade or a supposed `A > C > P` maturity scale. + +A plan **MUST show the accepted historical state → observed source-native current state → C construction target or justified exclusion → minimum necessary integration set → sufficiency evidence/acceptance** for each relevant function. It is not sufficient to list P0/P1 ideas without specifying why the complete set could later support `C`. For any qualified C target, link a function-specific first-party constructor and positive/negative acceptance contract. A plan does not assert a shipped C; if there is no defensible useful target, `NEEDS_EVIDENCE` or `NO_USEFUL_CHANGE` is a successful **explicit** plan-only outcome. There is no compulsory implementation, new grade or maintainer adoption. + ## 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. For OpenSiro discussion, use the [generic fork roadmap Issue template](../templates/FORK_CAPABILITY_ROADMAP_ISSUE.md), populated with current source-native evidence. 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. The [external architecture template](../templates/EXTERNAL_ARCHITECTURE_ISSUE.md) is a distinct maintainer-facing artifact and does not become public automatically. +`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. For Opensiro discussion, use the [generic fork roadmap Issue template](../templates/FORK_CAPABILITY_ROADMAP_ISSUE.md), populated with current source-native evidence. 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. The [external architecture template](../templates/EXTERNAL_ARCHITECTURE_ISSUE.md) is a distinct maintainer-facing artifact and does not become public automatically. 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. @@ -22,7 +30,7 @@ Follow the [fork Issue → case evidence → original Issue route](../PROTOCOL.m - **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. 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. +4. **C-construction target, completeness and priority:** Apply the [default target and P0/P1/P2 order](#default-target-and-work-priority) to functions lacking confirmed `C` or `A`. A qualified C implementation target **requires** source-native evidence of the exact user counterfactual, environmental/operational stimulus, first-party function-specific decision/feedback port, independently developer-composable autonomous decision actor and authority boundary, options/state lifecycle, enforcement, return-to-operation receipt, distribution reachability, and positive/negative/compatibility acceptance tests. Identify existing PR/Issue coverage vs remaining edits **and why their combined behavior would be sufficient**. Without those, call it `NEEDS_EVIDENCE`, never implementation-ready `C`. `C(P)`/`A(P)` are optional independent modes only for S3/S4/S5, not mandatory stages; a legitimate `P` can remain final. No shipped or grade assertions from plans. Prefer simpler native mechanisms whenever they meet the operator need. 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. @@ -46,7 +54,8 @@ A compact **plan-only Markdown report** in chat, or a dated **case record in the | 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`. | +| Target matrix and work priority | Relevant functions: accepted historical state, current source witness, `C` target or justified exclusion (already `A`/`A(P)` or `C`/`C(P)`), P0 capability, P1 necessary dependencies, P2 optional modes, and why the proposed *full change set* is sufficient for the C target or explicitly blocked | +| Constructor sufficiency (for each qualified `C` target) | 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` | diff --git a/templates/FORK_CAPABILITY_ROADMAP_ISSUE.md b/templates/FORK_CAPABILITY_ROADMAP_ISSUE.md index 6cbf1c4..3983597 100644 --- a/templates/FORK_CAPABILITY_ROADMAP_ISSUE.md +++ b/templates/FORK_CAPABILITY_ROADMAP_ISSUE.md @@ -1,68 +1,104 @@ -# [PROJECT] — capability roadmap for [user/operator outcome] +# [PROJECT] — capability integration roadmap for [operator outcome] - + -## Why this Issue exists +**Status:** PLAN_ONLY / [NEEDS_EVIDENCE | DECISION_READY | NO_USEFUL_CHANGE] +**Working fork:** [verified opensiro-contributions/ URL] +**Case artifacts:** [.opensiro/issues// on opensiro/meta] -Opensiro is testing whether reusable organizational specifications and a VSM-informed methodology can **standardize and reduce the cost of developing AI-agent harnesses**. This is a research hypothesis, **not** a proven cost reduction or a request to implement every VSM function. +## 1. Goal -**User outcome we want to improve:** [Who needs to do what, and what currently prevents or complicates it?] +Opensiro is investigating whether reusable organizational specifications informed by the Viable System Model (VSM) can **standardize and reduce the total cost of developing AI-agent harnesses**. Cost reduction and improved outcomes are hypotheses, not proven results. No project is required to adopt VSM or implement six new subsystems. -## Source and evidence +**User/operator outcome:** [Name the actor, task and measurable benefit over the simplest project-native alternative.] -- **Original repository / observed HEAD:** [owner/repo, immutable SHA link, date]. -- **Working fork and issue-local case:** [fork URL] · [`.opensiro/issues//` at `opensiro/meta`]. -- **Index baseline:** [pinned accepted assessment URL, assessment source SHA, review date, Profile/Skills versions]. The Index grade is historical, not a claim about current main. [Freshness/reassessment uncertainty if material.] -- **System boundary:** [whose operation is being evaluated; excluded recursion/integrations]. -- **Contribution constraints:** [verified license, contributor/CLA/AI terms, fork owner control; unknowns marked as unknown]. +**Roadmap design objective:** for useful VSM functions that lack a **confirmed `C` or `A`** construction/ownership path at the declared boundary, find the **smallest source-native, evidence-backed set of changes sufficient to offer a real `C` constructor**. This is a target for analysis, not a promised implementation or assessment grade. Already-confirmed `A`/`A(P)` functions are **not mandatory `C` targets**; `C`/`C(P)` already meet the constructor objective. A legitimate `P` authority remains legitimate and may be the intentional end state. An unresolved `?` must be investigated before declaring a gap. -## What already exists? +## 2. Evidence baseline -Map only relevant shipped behavior and original Issues/PRs. A proposed/open PR is **not** a shipped feature. +- **Original repository / current default HEAD:** [owner/repo at immutable commit SHA; observed date]. +- **Accepted Index assessment:** [immutable assessment file/blob SHA, `review_ref`, review date, Profile and Skills versions]. This is a **historical source-relative observation**, never an automatic current grade. +- **Freshness:** [days since successful Index semantic review; recommend Index-owned re-assessment if over 30 days or current changes materially affect the mapping; otherwise mark provisional unknowns]. +- **Working fork and owner state:** [verified parent, opensiro/meta HEAD, current ACTIVE/PAUSE/STOP and ALLOW control; unknown => no write]. +- **System in focus:** [operating boundary and supported first-party mode; excluded recursion, uninstalled plugins and private services]. +- **License / contributor permissions:** [verified policy links, CLA, AI disclosure, allowed contribution route; note blockers]. -| User need / VSM function (if relevant) | Current implementation | Existing Issue/PR and verified status | Remaining gap | +## 3. Existing work and remaining gaps + +Map **shipped** code separately from **open/unmerged** PRs, Issues, experiments and external governance. Inspect relevant original source and competing PR heads/diffs; a historical low grade or proposal title does not prove a missing current capability. + +| VSM function / user need | Shipped first-party path and source link | Existing original Issues/PRs and live statuses | Concrete residual operator outcome | | --- | --- | --- | --- | -| [Actor and task] | [Code/docs link] | [Issue/PR link, open/merged and head SHA] | [Concrete unserved user outcome, or none] | -| [Second relevant need, or remove] | [Link] | [Link/status] | [Gap/none] | +| [Sx / actor → task] | [source and behavior] | [URL, OPEN/MERGED and PR head/diff if applicable] | [gap or already achieved] | +| [second relevant need, or remove row] | [link] | [link or none found] | [gap / none] | + +**Best original-native alternative:** [Existing feature or documented manual/small-change workflow; say if it is already sufficient.] + +## 4. VSM capability targets and prioritized development plan + +**Target matrix (required):** list the relevant VSM functions, including **excluded already-autonomous functions** when they matter to the proposal. Do not infer `C` from `A`—the two are distinct ownership arrangements. We only exclude `A` from *mandatory C engineering work*. + +| Function | Accepted historical state | Current first-party evidence / uncertainty | Construction target | Minimum set of source-native changes | Sufficiency / verification status | +| --- | --- | --- | --- | --- | --- | +| [Sx without verified C or A] | [— / ? / P] | [actual source evidence] | [`C` when materially useful; otherwise no change with reason] | [existing Issue/PR + exact missing first-party ports and integration] | [NEEDS_EVIDENCE / CONTRACT_READY; never VERIFIED_C merely from a plan] | +| [Sx already at A / A(P) / C / C(P)] | [actual state] | [actual source evidence] | [No mandatory C target] | [none; constraints/dependencies only if relevant] | [existing assessment remains historical] | + +**Prioritization rule (research priority, not an autonomy-grade ladder):** +- **P0 — useful C sufficiency target(s):** prioritize a *material, verifiable operator outcome* with the smallest defensible missing construction path, strongest reuse of source-native Issues/PRs, and reasonable implementation/integration cost. If no eligible target is justified, say `NEEDS_EVIDENCE` or `NO_USEFUL_CHANGE` instead of fabricating one. +- **P1 — necessary enabling work:** dependencies, compatible integrations, authority enforcement and tests **required for P0 closure**; some prerequisites execute before the P0 deliverable. Name their issue/PR links and owners. P1 can also identify separately justified native work, but it is not an obligatory extra function target. +- **P2 — optional improvements:** independent parent modes `C(P)`/`A(P)` (where applicable and separately proven), refinements and cost optimizations. Neither `C → C(P) → A(P)` nor `A → C` is a mandatory progression. + +**Ordered integration / dependencies:** + +| Priority | User capability / deliverable | Reuse and missing change | Depends on | Decision owner, rights and measurable acceptance | +| --- | --- | --- | --- | --- | +| P0 | [candidate C construction and user outcome] | [native links + required delta] | [P1 prerequisites / none] | [first-party functional owner + positive and negative closure] | +| P1 | [required supporting integration] | [code/issues/PRs and gap] | [other constraints] | [compatibility/authority outcome] | +| P2 (optional) | [additional mode/optimization] | [smallest useful change] | [P0 proof where relevant] | [independent acceptance] | + +**C sufficiency contract (required for each proposed C target):** link [case-local constructor-acceptance.md], specifying (1) a real VSM-specific disturbance and operator counterfactual, (2) first-party function-specific input/option/decision and durable state ports **rather than generic hooks**, (3) what a developer independently composes, including an **actual autonomous decision actor** and legitimate rights, (4) enforcement, fail-closed denials and future-operation feedback/closure, (5) supported distribution/mode reachability and (6) native end-to-end positive, negative, unauthorized and compatibility tests. State explicitly which existing PRs/Issues cover each element and which new changes are required. -**Simplest original-native alternative:** [Existing feature, manual workflow or small project-native change]. Prefer this if it solves the same task. +**Sufficiency verdict:** [complete *design* coverage / missing evidence / disproved] with links for every dependency. **Design completeness is not shipping, and shipping is not an accepted Index `C` without separate Index review.** For `P` preserve legitimate parent authority; for `A(P)` exclude mandatory C work but retain constraints. `A`, `C`, `P` are ownership arrangements, not performance or maturity grades. -## Proposed priorities +## 5. Acceptance, alternatives and stop conditions -Do not propose a feature merely because an Index grade is low. First reuse, integrate or extend existing original work. +| Gate | Evidence required | Negative / stop condition | +| --- | --- | --- | +| Existing-work and material-delta check | Current original HEAD plus exact competing Issue/PR evidence; new user action unavailable or materially better than native baseline | Native workaround or shipped solution already covers it => NO_USEFUL_CHANGE | +| Positive operator scenario | [actor → stimulus → legitimate autonomous/composed decision → enforced first-party result and next-operation receipt] | A notification/UI mock or standalone generic plugin cannot establish C | +| Negative/authority case | [non-delegated actor, stale/unknown input, incompatible configuration, unavailable owner => safe denial and observable feedback] | No enforced owner/feedback or bypassable protected decision => NEEDS_EVIDENCE / blocked | +| Constructor completeness | [ports, actual developer composition, authority, distribution and native tests from case contract] | A proposal/open PR is not shipped C; no automatic Index grade | +| Native alternative | [paired simple native task and comparable outcome] | Smaller project-native solution wins; do not build solely to fill a VSM grade | -- **P0:** [Smallest useful new capability; actor → trigger/disturbance → authorized decision/action → observable result and later feedback]. [Which existing Issue/PR it extends.] -- **P1 (optional):** [Dependent improvement and why it is lower priority], or **none**. -- **Optional later stages:** [C → C(P) → A(P) only when the relevant function and independent evidence allow them; otherwise none]. **No mandatory grade progression.** +## 6. Independent development paths -**If proposing a C-level constructor:** link a separate case-local acceptance contract for the function-specific first-party entry point, developer-composable autonomous actor, authority boundary, options/state, enforcement, subsequent-operation feedback, reachability and positive/negative native tests. A draft or generic plugin is not a delivered `C`; `P` may be the legitimate endpoint. +These are **independent choices**, not three compulsory tasks: +1. **Harness-native integration:** organize original Issues/PRs; if qualified and separately authorized, implement a narrow tested improvement via `upstream upgrade`. +2. **Methodology feedback:** bring evidence-backed semantic counterexamples to [VSM Profile](https://github.com/opensiro/vsm-harness-profile) or assessment-method concerns to [VSM Skills](https://github.com/opensiro/vsm-harness-skills). +3. **Scoped experiment:** compare a legally permitted domain fork with a simpler original-native approach; no maintainer adoption implied. -## How would we know it helps? +**Selected research path / next decision:** [choose independent branch(es), state what is blocked]. -- **New action / counterfactual:** [What can a user or agent do that they could not meaningfully do before?] -- **Positive case:** [Actor, input, expected outcome, first-party observable evidence]. -- **Negative case:** [Missing permission / incompatible option / refusal / failure and safe outcome]. -- **Dependencies and conflicts:** [Original decisions, maintainers, other PRs, licensing, compatibility]. -- **No-change condition:** [Evidence that the existing solution is sufficient, or the proposed value cannot be demonstrated]. +## 7. Value evaluation -## Independent next steps +**Matched task:** [the same operator input, permitted decisions and outcome with native/manual vs VSM-informed alternative]. -Select **one**, not all three: +**Measures:** end-to-end user result, implementation/integration time, review and negative-case tests, maintenance/regression burden, operational compatibility and failure modes. **Cost status: `NOT_MEASURED`** until independently observed. Never assert guaranteed cost savings from a proposed constructor. -1. **Project-native integration:** organize existing Issues/PRs; propose a small useful source change *only through a separately authorized Upstream Upgrade*. -2. **Methodology feedback:** submit a separate, evidence-backed Profile or Skills proposal if the research finds a real specification gap. -3. **Scoped experiment:** test a legally permissible domain-specific fork, without obligating original maintainers. +## 8. Decision and handoff -**Cost experiment:** compare the *same user task* using the simplest native approach and the VSM-informed one. Measure implementation, integration, testing/review, maintenance and result quality. **Status: `NOT_MEASURED`** until observed. +**Result:** `PLAN_ONLY / [NEEDS_EVIDENCE | DECISION_READY | NO_USEFUL_CHANGE]` (report disposition only, not fork metadata enums). -## Decision / handoff +**Priority decision:** [P0 nominated functions, excluded already-A/C functions, prerequisite order and sufficiency gaps]. -**State:** `PLAN_ONLY` — [`NEEDS_EVIDENCE` / `DECISION_READY` / `NO_USEFUL_CHANGE`] (report labels only, not metadata enums). -**Open question:** [What decision or evidence is needed next?] +**Next action:** [exact current-source investigation or a separately requested Upgrade]. This Issue is **Opensiro's fork-local discussion surface**, not an original maintainer request. Store detailed evidence, original Issue deduplication, constructor contract and any third-party draft in the verified fork's `.opensiro/issues//` on its separate `opensiro/meta` branch. -Store detailed research, roadmap, construction contracts and external-Issue draft under the verified fork's `.opensiro/issues//`. This Issue is for **Opensiro's fork-local discussion**, not an external request. Before contacting the original repository, dedupe existing original Issues; a new external Issue needs **separate exact approval** and is newly created, **not a cross-owner transfer**. No automatic implementation, product PR, Index regrade or internal Issue closure. +No public fork Issue, original Issue/comment/PR, product implementation, fork-local public review PR, delegated authority, automatic Index regrade or implicit cross-owner GitHub Issue transfer is authorized by this draft. **Each public publication requires its own exact current-conversation owner approval.** Existing original Issues must be reused rather than duplicated. -**AI disclosure:** Draft and evidence synthesis prepared with AI assistance; no human review, shipped result or measured cost saving is claimed unless independently evidenced. +**AI disclosure:** Prepared with AI assistance. No independent human validation, shipped constructor, accepted grade change or measured cost saving is implied. diff --git a/tests/test_fork_roadmap_issue_template.py b/tests/test_fork_roadmap_issue_template.py index bb861ec..9372d67 100644 --- a/tests/test_fork_roadmap_issue_template.py +++ b/tests/test_fork_roadmap_issue_template.py @@ -1,65 +1,95 @@ -"""Guardrails for the reusable Opensiro fork-local roadmap Issue template.""" +"""Guardrails for Opensiro's v2 fork-local capability roadmap Issue template.""" from pathlib import Path import unittest ROOT = Path(__file__).resolve().parents[1] TEMPLATE = ROOT / "templates" / "FORK_CAPABILITY_ROADMAP_ISSUE.md" +PROTOCOL = ROOT / "PROTOCOL.md" +ROADMAP = ROOT / "docs" / "CAPABILITY_ROADMAP.md" class ForkCapabilityRoadmapIssueTemplateTests(unittest.TestCase): - def test_template_is_generic_and_source_driven(self): + def test_template_is_generic_and_structurally_complete_v2(self): text = TEMPLATE.read_text(encoding="utf-8") self.assertTrue(text.startswith("# [PROJECT]")) self.assertIn("Opensiro", text) self.assertNotIn("OpenSiro", text) - for part in ( - "## Why this Issue exists", - "## Source and evidence", - "## What already exists?", - "## Proposed priorities", - "## How would we know it helps?", - "## Independent next steps", - "## Decision / handoff", - ): - self.assertIn(part, text) - self.assertIn("Current implementation", text) - self.assertIn("Remaining gap", text) - self.assertIn("Simplest original-native alternative", text) + headings = [ + "## 1. Goal", + "## 2. Evidence baseline", + "## 3. Existing work and remaining gaps", + "## 4. VSM capability targets and prioritized development plan", + "## 5. Acceptance, alternatives and stop conditions", + "## 6. Independent development paths", + "## 7. Value evaluation", + "## 8. Decision and handoff", + ] + self.assertEqual([line for line in text.splitlines() if line.startswith("## ")], headings) self.assertNotIn("paperclipai/", text) self.assertNotIn("browser-use/", text) + self.assertIn("Existing original Issues/PRs", text) + self.assertIn("Best original-native alternative", text) + + def test_target_and_priority_invariants(self): + text = TEMPLATE.read_text(encoding="utf-8") + protocol = PROTOCOL.read_text(encoding="utf-8") + roadmap = ROADMAP.read_text(encoding="utf-8") + for doc in (text, protocol, roadmap): + for requirement in ("P0", "P1", "P2", "A(P)", "C(P)", "NEEDS_EVIDENCE", + "NO_USEFUL_CHANGE"): + self.assertIn(requirement, doc) + for requirement in ( + "Target matrix (required)", + "Already-confirmed `A`/`A(P)` functions", + "not mandatory `C` targets", + "An unresolved `?` must be investigated", + "P0 — useful C sufficiency", + "P1 — necessary enabling work", + "P2 — optional improvements", + "C sufficiency contract (required", + "Sufficiency verdict", + "Cost status: `NOT_MEASURED`", + ): + self.assertIn(requirement, text) + self.assertIn("already at `A`/`A(P)` is **not required**", protocol) + self.assertIn("already-`a`/`a(p)` functions **do not need c engineering work**", roadmap.lower()) + self.assertIn("why their combined behavior would be sufficient", roadmap) + self.assertNotIn("a maturity ordering", text) def test_no_unearned_capability_or_cost_claims(self): text = TEMPLATE.read_text(encoding="utf-8") - for required in ( + for requirement in ( + "mandatory progression", + "design", # design and shipment remain distinct + "not shipping", + "later `C`", "NOT_MEASURED", - "No automatic implementation", - "not a delivered", - "No mandatory grade progression", - "No-change condition", - "Positive case", - "Negative case", + "Native alternative", + "Positive operator scenario", + "Negative/authority case", + "No public fork Issue", + "exact current-conversation owner approval", ): - self.assertIn(required, text) + self.assertIn(requirement.lower(), text.lower()) - def test_case_location_and_publication_boundaries(self): + def test_case_storage_and_external_boundary(self): text = TEMPLATE.read_text(encoding="utf-8") self.assertIn(".opensiro/issues//", text) self.assertIn("opensiro/meta", text) - self.assertIn("separate exact approval", text) - self.assertIn("not a cross-owner transfer", text) - self.assertIn("fork-local discussion", text) + self.assertIn("fork-local discussion surface", text) + self.assertIn("original maintainer request", text) self.assertIn("AI disclosure", text) - self.assertIn("This is NOT the external maintainer issue template", text) + self.assertIn("NOT the original maintainer repository", text) - def test_protocol_routes_to_correct_templates(self): - p = (ROOT / "PROTOCOL.md").read_text(encoding="utf-8") - g = (ROOT / "docs/CAPABILITY_ROADMAP.md").read_text(encoding="utf-8") - for s in (p, g): - self.assertIn("FORK_CAPABILITY_ROADMAP_ISSUE.md", s) - self.assertIn("EXTERNAL_ARCHITECTURE_ISSUE.md", s) - self.assertTrue((ROOT / "templates/EXTERNAL_ARCHITECTURE_ISSUE.md").exists()) - external = (ROOT / "templates/EXTERNAL_ARCHITECTURE_ISSUE.md").read_text(encoding="utf-8") + def test_protocol_routes_to_internal_and_external_templates(self): + for path in (PROTOCOL, ROADMAP): + text = path.read_text(encoding="utf-8") + self.assertIn("FORK_CAPABILITY_ROADMAP_ISSUE.md", text) + self.assertIn("EXTERNAL_ARCHITECTURE_ISSUE.md", text) + external = (ROOT / "templates" / "EXTERNAL_ARCHITECTURE_ISSUE.md").read_text( + encoding="utf-8" + ) self.assertIn("Opensiro", external) self.assertNotIn("OpenSiro", external) From 00f07a768bf8904bf791135d7c28b1ab5aa408b9 Mon Sep 17 00:00:00 2001 From: alexruidan <41616537+xLagerFeuer@users.noreply.github.com> Date: Wed, 18 Nov 2026 00:53:16 +0300 Subject: [PATCH 2/2] test(roadmap): retain explicit no-grade-ladder contract and fix v2 assertion --- PROTOCOL.md | 2 +- tests/test_fork_roadmap_issue_template.py | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/PROTOCOL.md b/PROTOCOL.md index 3dbfd61..61ca15d 100644 --- a/PROTOCOL.md +++ b/PROTOCOL.md @@ -38,7 +38,7 @@ Read [docs/FORK_METADATA.md](docs/FORK_METADATA.md) for the initial JSON contrac **Roadmap default objective — function-scoped C sufficiency, not grade maximization.** For each relevant function without confirmed `C`/`C(P)` or `A`/`A(P)` at the declared first-party boundary, **investigate a minimal, useful, function-specific construction path sufficient for a future `C` witness**. First resolve stale `?` evidence and source drift, and retain `P` as a valid autonomous-actor-absent, parent-governed arrangement with reserved authority. A function already at `A`/`A(P)` is **not required** to be converted into `C`: `A` does not logically prove a reusable `C` constructor, but it satisfies this route's default no-mandatory-C-work exclusion. `C`/`C(P)` also need no duplicate constructor target. Prioritize user need and defensible engineering materiality; do not manufacture changes simply to fill a historical low grade. If no useful `C` target survives current-source validation, explicitly report `NO_USEFUL_CHANGE` or `NEEDS_EVIDENCE`, with reasons, rather than silently substituting unrelated general enhancements. -**Mandatory research priority and sufficiency receipt:** `P0` = the strongest qualified, useful **C-target capability** with complete proposed minimal coverage; `P1` = dependencies and integration/authority/test changes required to enable that target (these may execute first); `P2` = optional independent modes `C(P)`/`A(P)` and other separately justified enhancements. These are **work priorities**, not a maturity ordering of `A`, `C`, `P`. For every candidate, show accepted historical state, actual current-source evidence, original Issues/PRs with status, target and smallest necessary new changes, exact decision/feedback constructor, rights, supported reachability, observable positive/negative acceptance and **why the combined set would be sufficient** for a later `C` assessment. State what remains unverified. When a selected function already has `A`/`A(P)` or `C`/`C(P)`, mark it **excluded from mandatory C targets**; any further source-native enhancement needs a separate material user benefit. Preserve the legitimate parent `P` boundary. +**Mandatory research priority and sufficiency receipt:** `P0` = the strongest qualified, useful **C-target capability** with complete proposed minimal coverage; `P1` = dependencies and integration/authority/test changes required to enable that target (these may execute first); `P2` = optional independent modes `C(P)`/`A(P)` and other separately justified enhancements. These are **work priorities**, not a maturity ordering of `A`, `C`, `P` and **not a universal grade ladder**. For every candidate, show accepted historical state, actual current-source evidence, original Issues/PRs with status, target and smallest necessary new changes, exact decision/feedback constructor, rights, supported reachability, observable positive/negative acceptance and **why the combined set would be sufficient** for a later `C` assessment. State what remains unverified. When a selected function already has `A`/`A(P)` or `C`/`C(P)`, mark it **excluded from mandatory C targets**; any further source-native enhancement needs a separate material user benefit. Preserve the legitimate parent `P` boundary. 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. diff --git a/tests/test_fork_roadmap_issue_template.py b/tests/test_fork_roadmap_issue_template.py index 9372d67..56eb478 100644 --- a/tests/test_fork_roadmap_issue_template.py +++ b/tests/test_fork_roadmap_issue_template.py @@ -63,7 +63,7 @@ def test_no_unearned_capability_or_cost_claims(self): "mandatory progression", "design", # design and shipment remain distinct "not shipping", - "later `C`", + "separate Index review", "NOT_MEASURED", "Native alternative", "Positive operator scenario",