From 72ca8fa90fff9b79e5b8fc4386bd2a1384d5fd2b Mon Sep 17 00:00:00 2001 From: alexruidan <41616537+xLagerFeuer@users.noreply.github.com> Date: Wed, 18 Nov 2026 00:03:03 +0300 Subject: [PATCH] docs(roadmap): add project-neutral fork-local capability Issue template Separate source-grounded internal discussion from external maintainer-facing architecture issues. Preserve PLAN_ONLY, case-local evidence, original issue dedupe, native alternatives and independent publication approvals. --- CHANGELOG.md | 2 + PROTOCOL.md | 2 +- docs/CAPABILITY_ROADMAP.md | 4 +- templates/FORK_CAPABILITY_ROADMAP_ISSUE.md | 68 ++++++++++++++++++++++ tests/test_fork_roadmap_issue_template.py | 63 ++++++++++++++++++++ 5 files changed, 136 insertions(+), 3 deletions(-) create mode 100644 templates/FORK_CAPABILITY_ROADMAP_ISSUE.md create mode 100644 tests/test_fork_roadmap_issue_template.py diff --git a/CHANGELOG.md b/CHANGELOG.md index f62b262..e855d08 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 +**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. **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. diff --git a/PROTOCOL.md b/PROTOCOL.md index 955309f..fbaa6a3 100644 --- a/PROTOCOL.md +++ b/PROTOCOL.md @@ -34,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, 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). +**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. 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/docs/CAPABILITY_ROADMAP.md b/docs/CAPABILITY_ROADMAP.md index bb21c1c..d68551a 100644 --- a/docs/CAPABILITY_ROADMAP.md +++ b/docs/CAPABILITY_ROADMAP.md @@ -1,6 +1,6 @@ # Capability Roadmap — architecture-first, plan-only -[Protocol](../PROTOCOL.md#architecture-first-upstream-roadmap-ownerrepo-plan-only) · [issue template](../templates/EXTERNAL_ARCHITECTURE_ISSUE.md) +[Protocol](../PROTOCOL.md#architecture-first-upstream-roadmap-ownerrepo-plan-only) · [fork-local roadmap Issue template](../templates/FORK_CAPABILITY_ROADMAP_ISSUE.md) · [external architecture Issue template](../templates/EXTERNAL_ARCHITECTURE_ISSUE.md) ## Purpose @@ -10,7 +10,7 @@ The normative [Profile](https://github.com/opensiro/vsm-harness-profile/blob/mai ## 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. +`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. diff --git a/templates/FORK_CAPABILITY_ROADMAP_ISSUE.md b/templates/FORK_CAPABILITY_ROADMAP_ISSUE.md new file mode 100644 index 0000000..659d0ba --- /dev/null +++ b/templates/FORK_CAPABILITY_ROADMAP_ISSUE.md @@ -0,0 +1,68 @@ +# [PROJECT] — capability roadmap for [user/operator outcome] + + + +## Why this Issue exists + +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. + +**User outcome we want to improve:** [Who needs to do what, and what currently prevents or complicates it?] + +## Source and evidence + +- **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]. + +## What already exists? + +Map only relevant shipped behavior and original Issues/PRs. A proposed/open PR is **not** a shipped feature. + +| User need / VSM function (if relevant) | Current implementation | Existing Issue/PR and verified status | Remaining gap | +| --- | --- | --- | --- | +| [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] | + +**Simplest original-native alternative:** [Existing feature, manual workflow or small project-native change]. Prefer this if it solves the same task. + +## Proposed priorities + +Do not propose a feature merely because an Index grade is low. First reuse, integrate or extend existing original work. + +- **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.** + +**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. + +## How would we know it helps? + +- **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]. + +## Independent next steps + +Select **one**, not all three: + +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. + +**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. + +## Decision / handoff + +**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?] + +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. + +**AI disclosure:** Draft and evidence synthesis prepared with AI assistance; no human review, shipped result or measured cost saving is claimed unless independently evidenced. diff --git a/tests/test_fork_roadmap_issue_template.py b/tests/test_fork_roadmap_issue_template.py new file mode 100644 index 0000000..3ebb924 --- /dev/null +++ b/tests/test_fork_roadmap_issue_template.py @@ -0,0 +1,63 @@ +"""Guardrails for the reusable OpenSiro fork-local roadmap Issue template.""" + +from pathlib import Path +import unittest + +ROOT = Path(__file__).resolve().parents[1] +TEMPLATE = ROOT / "templates" / "FORK_CAPABILITY_ROADMAP_ISSUE.md" + + +class ForkCapabilityRoadmapIssueTemplateTests(unittest.TestCase): + def test_template_is_generic_and_source_driven(self): + text = TEMPLATE.read_text(encoding="utf-8") + self.assertTrue(text.startswith("# [PROJECT]")) + 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) + self.assertNotIn("paperclipai/", text) + self.assertNotIn("browser-use/", text) + + def test_no_unearned_capability_or_cost_claims(self): + text = TEMPLATE.read_text(encoding="utf-8") + for required in ( + "NOT_MEASURED", + "No automatic implementation", + "not a delivered", + "No mandatory grade progression", + "No-change condition", + "Positive case", + "Negative case", + ): + self.assertIn(required, text) + + def test_case_location_and_publication_boundaries(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("AI disclosure", text) + self.assertIn("This is NOT the external maintainer issue template", 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()) + + +if __name__ == "__main__": + unittest.main()