diff --git a/docs/CAPABILITY_ROADMAP.md b/docs/CAPABILITY_ROADMAP.md index 4f41b68..0ab18fb 100644 --- a/docs/CAPABILITY_ROADMAP.md +++ b/docs/CAPABILITY_ROADMAP.md @@ -35,6 +35,16 @@ A compact, **read-only Markdown report** in chat, or a dated **non-authoritative **Fail closed:** unknown source/ref/owner/diff stays unverified. 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. +## 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: + +~~~sh +python3 scripts/validate_capability_roadmap.py docs/examples/browser-harness-roadmap-20261117.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. + ## Ownership and stages - The roadmap is **not** an Index reassessment, normative Profile patch or second canonical ledger. diff --git a/docs/FORK_METADATA.md b/docs/FORK_METADATA.md index b755fab..87707e6 100644 --- a/docs/FORK_METADATA.md +++ b/docs/FORK_METADATA.md @@ -119,6 +119,10 @@ 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. + ## One human-visible case, two independent facts | Question | Truth owner | Example | diff --git a/docs/UPGRADE_PR_REVIEW.md b/docs/UPGRADE_PR_REVIEW.md index 5733e7d..7230a2a 100644 --- a/docs/UPGRADE_PR_REVIEW.md +++ b/docs/UPGRADE_PR_REVIEW.md @@ -38,6 +38,10 @@ Before declaring that an existing external PR covers S3/S4 or another VSM Upgrad When a useful residual is confirmed, evaluate continuation of an existing compatible OpenSiro contribution, a dependent/small follow-up, and the original alternative before proposing an unrelated competing feature. A third-party contributor's branch is not editable merely because its PR is open. Any communication or PR in the original repository (including a request to collaborate) still needs exact current-conversation owner approval. An inconclusive overlap or missing functional proof is `EVIDENCE_INSUFFICIENT`, not a reason to stop a one-harness Upgrade or fabricate a code change. +### Architecture-roadmap dependency handoff (non-public by default) + +A [Capability Roadmap](CAPABILITY_ROADMAP.md) may identify existing PR dependencies or a code sequence, but it does **not** qualify any feature or approve a fork-local/external PR. For an implementation derived from a roadmap, read back the pinned current original, competing original PR heads and maintainer decisions, actual first-party owner/closure, remaining user outcome, and intended compatibility/negative cases. Distinguish source-native patches from Profile/Skills specification feedback and a separately bounded domain fork; no one route implies approval of the others. Each *implemented* user-visible improvement still requires the ordinary native material-delta receipt, independent schema-v2 fork-local record, validation, five-link handoff and exact owner publication consents. A plan-only issue draft remains `DRAFT — NOT PUBLISHED` and **never** counts as fork-local review PR #1–#5 provenance. + ### Required material-capability evidence before proposing a review PR Before treating passing code/tests as an Upgrade candidate, read its [Capability Delta Receipt](../PROTOCOL.md#material-capability-delta-gate-before-implementation). The exact actor, previously blocked user/agent task, pinned baseline and best workaround, end-to-end matched new outcome, VSM mechanism, unsupported guarantees and **`MATERIAL_DELTA_SUPPORTED`** disposition must be source-backed. A new health-check flag or passing mock tests without an observable new task is **not sufficient**. Include the bounded user benefit and counterfactual in the proposed PR summary; native pass counts cannot replace this proof. diff --git a/docs/examples/browser-harness-roadmap-20261117.md b/docs/examples/browser-harness-roadmap-20261117.md new file mode 100644 index 0000000..c8c3b61 --- /dev/null +++ b/docs/examples/browser-harness-roadmap-20261117.md @@ -0,0 +1,88 @@ +# 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/scripts/validate_capability_roadmap.py b/scripts/validate_capability_roadmap.py new file mode 100644 index 0000000..94a01e4 --- /dev/null +++ b/scripts/validate_capability_roadmap.py @@ -0,0 +1,99 @@ +#!/usr/bin/env python3 +"""Structural check for a plan-only roadmap snapshot, NOT external/source validation.""" + +from __future__ import annotations + +import re +import sys +from pathlib import Path + +SECTIONS = ( + "Identity and pins", + "Rights and authority", + "Existing work / overlap", + "Function ownership", + "Capability priority", + "Implementation options", + "Specification and domain alternatives", + "Cost experiment", + "Delivery and publication", +) +FIELDS = ( + "Original repository", + "Original HEAD", + "Observed at", + "Accepted Index assessment", + "Accepted assessment blob SHA", + "Accepted review ref", + "Accepted reviewed at", + "System in focus", +) +HEX40 = re.compile(r"[0-9a-f]{40}\Z") +DATE = re.compile(r"\d{4}-\d{2}-\d{2}\Z") +REPO = re.compile(r"[A-Za-z0-9_.-]+/[A-Za-z0-9_.-]+\Z") +URL = re.compile(r"https://github\.com/[A-Za-z0-9_.-]+/[A-Za-z0-9_.-]+/(?:blob|commit|issues|pull)/[^\s)]+") +OUTCOMES = ("PLAN_ONLY", "NEEDS_EVIDENCE", "NO_USEFUL_CHANGE") + + +def value(contents: str, key: str) -> str | None: + match = re.search(r"^- "+re.escape(key)+r":\s*(.+?)\s*$", contents, re.M) + return match.group(1).strip() if match else None + + +def validate(contents: str) -> list[str]: + errors = [] + for section in SECTIONS: + if not re.search(r"^## "+re.escape(section)+r"\s*$", contents, re.M): + errors.append("missing section: "+section) + for field in FIELDS: + if not value(contents,field): + errors.append("missing field: "+field) + + for field,pattern in ( + ("Original repository",REPO), + ("Original HEAD",HEX40), + ("Accepted assessment blob SHA",HEX40), + ("Accepted review ref",HEX40), + ("Observed at",DATE), + ("Accepted reviewed at",DATE), + ): + actual=value(contents,field) + if actual and not pattern.fullmatch(actual): + errors.append("invalid format: "+field) + idx=value(contents,"Accepted Index assessment") + if idx and not idx.startswith("https://github.com/opensiro/vsm-harness-index/blob/"): + errors.append("Index assessment must be pinned to a GitHub blob URL") + if idx and "/blob/main/" in idx: + errors.append("Index assessment must use a frozen commit, not main") + result=value(contents,"Result") + if result not in OUTCOMES: + errors.append("missing/invalid Result (narrative only)") + if value(contents,"External issue") != "DRAFT — NOT PUBLISHED": + errors.append("external issue must be explicitly DRAFT — NOT PUBLISHED") + if value(contents,"Cost status") != "NOT_MEASURED": + errors.append("cost status must remain NOT_MEASURED until independently measured") + if not URL.search(contents): + errors.append("no first-party GitHub source link") + if "[placeholder]" in contents.lower() or "TODO" in contents: + errors.append("unresolved placeholder") + return errors + + +def main(argv: list[str]) -> int: + if len(argv) != 2: + print("usage: validate_capability_roadmap.py ",file=sys.stderr) + return 2 + path=Path(argv[1]) + if not path.is_file(): + print("roadmap receipt not found",file=sys.stderr) + return 2 + errors=validate(path.read_text(encoding="utf-8")) + if errors: + print("\n".join(errors),file=sys.stderr) + return 1 + print("Plan-only roadmap receipt structural contract: PASS (not semantic review)") + return 0 + + +if __name__ == "__main__": + raise SystemExit(main(sys.argv)) diff --git a/tests/test_capability_roadmap_contract.py b/tests/test_capability_roadmap_contract.py new file mode 100644 index 0000000..23a6cef --- /dev/null +++ b/tests/test_capability_roadmap_contract.py @@ -0,0 +1,52 @@ +"""Plan-only receipt checks: structure, not live GitHub or VSM semantics.""" +from pathlib import Path +import sys +import unittest + +ROOT = Path(__file__).resolve().parents[1] +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") + + +class CapabilityRoadmapReceiptTests(unittest.TestCase): + def test_source_pinned_pilot_passes(self): + self.assertEqual(validate(PILOT), []) + + 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)) + + 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__": + unittest.main()