Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 2 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,6 +5,8 @@
**Release status:** a protocol version merged to `main` is **not** automatically a published GitHub Release. Check [published Releases](https://github.com/opensiro/upstream/releases). At the 2026-11-16 review, v0.13.0 was the latest published release, and the [v0.16.0 consolidated candidate](docs/RELEASE_CANDIDATE_v0.16.0.md) awaits final owner approval. Individual v0.14–v0.16 history entries below remain valid intermediate main snapshots, not claims of three separate GitHub Releases.

## Unreleased
**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/<case-id>/`. 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.
Expand Down
2 changes: 1 addition & 1 deletion PROTOCOL.md
Original file line number Diff line number Diff line change
Expand Up @@ -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/<case-id>/`. 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/<case-id>/`. 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.
Expand Down
4 changes: 2 additions & 2 deletions docs/CAPABILITY_ROADMAP.md
Original file line number Diff line number Diff line change
@@ -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

Expand All @@ -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/<case-id>/` 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/<case-id>/` 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.

Expand Down
68 changes: 68 additions & 0 deletions templates/FORK_CAPABILITY_ROADMAP_ISSUE.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,68 @@
# [PROJECT] — capability roadmap for [user/operator outcome]

<!-- Fork Issue template. Fill brackets with verified evidence and remove this note.
Copy to opensiro-contributions/<fork> only after exact public-Issue approval.
Case-specific research belongs on the fork's opensiro/meta branch, not Upstream.
This is NOT the external maintainer issue template. -->

## 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/<case-id>/` 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/<case-id>/`. 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.
63 changes: 63 additions & 0 deletions tests/test_fork_roadmap_issue_template.py
Original file line number Diff line number Diff line change
@@ -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/<case-id>/", 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()
Loading