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
10 changes: 10 additions & 0 deletions docs/CAPABILITY_ROADMAP.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down
4 changes: 4 additions & 0 deletions docs/FORK_METADATA.md
Original file line number Diff line number Diff line change
Expand Up @@ -119,6 +119,10 @@ For assessment-related types include `assessment_pin: {"url": "<immutable Index

Events capture **significant** state changes, research conclusions, native test receipts, external PR readback, owner intervention and recovery, not every shell command or repetitive hourly poll. Unique filenames, immutable content, stable IDs, actor, timestamp, source links and non-overwriting commits enable audit and independent continuation. Previous events must not be edited or deleted; a mistake is corrected by a new event referencing the original. Never fabricate unavailable history. Never store secrets, private messages, unbounded logs, third-party unlicensed content or model chain-of-thought.

## Plan-only capability roadmaps are not new fork records

[Architecture-first `upstream roadmap OWNER/REPO`](CAPABILITY_ROADMAP.md) may link an accepted historical assessment, original issues/PRs and existing independent fork-local contributions. A **research-only architecture plan** or external issue draft is *not* itself a qualifying improvement, does **not** require a new `.opensiro/contributions/<stable-id>.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 |
Expand Down
4 changes: 4 additions & 0 deletions docs/UPGRADE_PR_REVIEW.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down
88 changes: 88 additions & 0 deletions docs/examples/browser-harness-roadmap-20261117.md
Original file line number Diff line number Diff line change
@@ -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.
99 changes: 99 additions & 0 deletions scripts/validate_capability_roadmap.py
Original file line number Diff line number Diff line change
@@ -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 <receipt.md>",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))
Loading
Loading