Synchronize suite versions, guides, and reference validation

README.md

@@ -5,8 +5,8 @@ Canonical, reviewable documentation for the StructuPath Herdr Suite, published a
 The product surface is organized by workflow readiness:
 
 - **Explore / Swarm** is the ready first workflow: bounded parallel candidates, reviewable worktrees, and operator-selected harvest.
-- **Deliver / Conductor** is an attended Stage 2 lifecycle: task-bound role panes, strict run state, private report outboxes, deterministic integration, exact-SHA gates, and archival stand-down.
-- **Browser** and **Guard** are supporting visibility and advisory text-policy capabilities.
+- **Deliver / Conductor** is an attended Stage 3 lifecycle: task-bound roles, exact-SHA gates, operator approval receipts, single-local-ref apply, and archival stand-down on exactly Herdr 0.7.5.
+- **Browser** provides Chromium launch, external attach, shared sessions, and agent-browser recording. **Guard** provides text policy and an optional fail-open harness reporter.
 
 The four plugins can be installed together, but they do not form one automatic runtime pipeline.
 
@@ -21,11 +21,11 @@ The four plugins can be installed together, but they do not form one automatic r
 ## Truthful suite boundaries
 
 - Swarm agents commit locally; the operator reviews and selects what merges. A clean-slot selection can perform the merge after preview, so selection is the approval action.
-- Guard is advisory/best-effort rendered-text policy for agent TUIs; it is not a sandbox or authorization boundary.
-- Conductor creates and harvests its own worktrees and does not delegate either operation to Swarm. The pinned runtime provides strict task/report contracts and exact-SHA gates, but no approval receipts or approval-aware apply, suite adapter, unattended automation, or automatic recovery.
+- Guard's pane watcher is advisory/best-effort. Its optional Claude Code hook can deny reported Bash calls before execution but fails open on unavailable or malformed responses; it is not a sandbox or same-user security boundary.
+- Conductor creates and harvests its own worktrees. It supports attended preview, unauthenticated operator receipts, and one-local-ref apply. It does not delegate to Swarm or provide a suite adapter, unattended automation, or general automatic recovery.
 - Write-capable agents and plugins are trusted same-user principals. Worktrees isolate changes for review, not security.
 - Compatibility/testing claims are plugin-specific and pinned in `data/plugins.json`; there is no blanket suite-wide tested-version or marketplace claim.
-- Conductor exposes five actions: `assemble`, `board`, `status`, `harvest`, and `stand-down`.
+- Conductor exposes seven actions: `assemble`, `board`, `status`, `harvest`, `preview`, `apply`, and `stand-down`.
 
 ## Build and check
 

data/plugins.json

@@ -7,48 +7,83 @@
       "name": "Browser",
       "id": "structupath.browser",
       "repository": "https://github.com/StructuPath/herdr-browser",
-      "commit": "952e1601006cce2ca45edef56676d18a1f016151",
+      "commit": "5fc6a9a52b4f817f21a531c288f36c3820bf93ca",
       "version": "0.7.0",
       "min_herdr_version": "0.7.0",
-      "tested_herdr_versions": ["0.7.4"],
+      "tested_herdr_versions": [
+        "0.7.4"
+      ],
       "manifest_sha256": "975685f637d75b2f4b0151b7cecbb3eaa1fb3b8849c13a356e3ebfb5a90fea8a",
-      "actions": ["open", "close", "browse", "record-start", "record-stop"]
+      "actions": [
+        "open",
+        "close",
+        "browse",
+        "record-start",
+        "record-stop"
+      ]
     },
     {
       "slug": "guard",
       "name": "Guard",
       "id": "structupath.guard",
       "repository": "https://github.com/StructuPath/herdr-guard",
-      "commit": "7327dc4f310987e05059a20cec7d8fc50bbf0cc5",
-      "version": "0.1.1",
+      "commit": "12e3fd6f7d65bd4c846f5da23cb2f24ee617cd48",
+      "version": "0.2.0",
       "min_herdr_version": "0.7.5",
-      "tested_herdr_versions": ["0.7.5"],
-      "manifest_sha256": "36cd8ab09f82f07f56e08d15013221d4f5a46a8c2d3aca1255581b24c70dc50b",
-      "actions": ["open", "pause", "resume", "test", "reset-rules"]
+      "tested_herdr_versions": [
+        "0.7.5"
+      ],
+      "manifest_sha256": "a56fb32ccb97d91dba6462c483120156208075bd52c36c1366590b0215326769",
+      "actions": [
+        "open",
+        "pause",
+        "resume",
+        "test",
+        "reset-rules"
+      ]
     },
     {
       "slug": "swarm",
       "name": "Swarm",
       "id": "structupath.swarm",
       "repository": "https://github.com/StructuPath/herdr-swarm",
-      "commit": "0dc0a2b0a77e590d854fafd5eae0e76dbcc00017",
-      "version": "0.1.0",
+      "commit": "4f0e2a7fcf25c94437e323bf1fa56a53fb4f34fb",
+      "version": "0.3.0",
       "min_herdr_version": "0.7.4",
-      "tested_herdr_versions": ["0.7.4", "0.7.5"],
-      "manifest_sha256": "54b3806f30816115743dd7d6e908c09c352d90b006a6f7885d46e292373d47b4",
-      "actions": ["fanout", "status", "harvest", "abort", "prune"]
+      "tested_herdr_versions": [
+        "0.7.4",
+        "0.7.5"
+      ],
+      "manifest_sha256": "c4d7a6d653bb94ea6e0a3efef4fe3722d5b826ee24e7895fc8ba2439b119b0f5",
+      "actions": [
+        "fanout",
+        "status",
+        "harvest",
+        "abort",
+        "prune"
+      ]
     },
     {
       "slug": "conductor",
       "name": "Conductor",
       "id": "structupath.conductor",
       "repository": "https://github.com/StructuPath/herdr-conductor",
-      "commit": "712863c34d6126c9d95fa3b9bd6caf5220cbfc43",
-      "version": "0.3.0",
+      "commit": "bf67d318067c60318dcd7089897f513bfefe3af7",
+      "version": "0.4.0",
       "min_herdr_version": "0.7.5",
-      "tested_herdr_versions": ["0.7.5"],
-      "manifest_sha256": "95958ade511f422b65a07f3d4a305581cdb236e1cd616da7d6c57aa0660aa35e",
-      "actions": ["assemble", "board", "status", "harvest", "stand-down"]
+      "tested_herdr_versions": [
+        "0.7.5"
+      ],
+      "manifest_sha256": "b8898d549216485c2bd599a101808030ce534b9c32625b6e6bdc51da04644672",
+      "actions": [
+        "assemble",
+        "board",
+        "status",
+        "harvest",
+        "preview",
+        "apply",
+        "stand-down"
+      ]
     }
   ]
 }

docs-src/Browser.md

@@ -11,7 +11,7 @@ Repo: [StructuPath/herdr-browser](https://github.com/StructuPath/herdr-browser)
 | Plugin release | `0.7.0` |
 | Minimum Herdr | `0.7.0` |
 | Explicitly tested Herdr | `0.7.4` |
-| Evidence commit | `952e1601006cce2ca45edef56676d18a1f016151` |
+| Evidence commit | `5fc6a9a52b4f817f21a531c288f36c3820bf93ca` |
 
 The [pinned source](https://github.com/StructuPath/herdr-browser/tree/952e1601006cce2ca45edef56676d18a1f016151) includes the merged session-preservation and stream-recovery fixes. The manifest version remains 0.7.0; the commit identifies the exact implementation behind this guide.
 

docs-src/Conductor.md

@@ -1,42 +1,43 @@
 # 🎩 Deliver with Conductor (`structupath.conductor`)
 
-**Attended Stage 2 delivery.** Conductor `0.3.0` coordinates task-bound builders, validators, and reviewers as visible Herdr agent panes. A human or trusted orchestrating agent explicitly drives every transition. This release is operational for strict task/report contracts and exact-SHA gates on exactly Herdr `0.7.5`; it is not an approval system, suite adapter, unattended pipeline, automatic recovery service, cryptographic attestation system, or same-user security boundary.
+**Attended Stage 3 delivery.** Conductor `0.4.0` coordinates task-bound builders, validators, and reviewers as visible Herdr agent panes, then supports an explicitly approved fast-forward of one local ref. An operator drives every transition and records each approval receipt. It requires exactly Herdr `0.7.5`, protocol `17`, API schema `1`; it is not an authenticated approval system, suite adapter, unattended pipeline, general automatic recovery service, cryptographic attestation system, or same-user security boundary.
 
-Repo: [StructuPath/herdr-conductor](https://github.com/StructuPath/herdr-conductor) · [Release `v0.3.0`](https://github.com/StructuPath/herdr-conductor/releases/tag/v0.3.0) · Detailed reference: the repo [README](https://github.com/StructuPath/herdr-conductor/tree/v0.3.0#readme)
+Repo: [StructuPath/herdr-conductor](https://github.com/StructuPath/herdr-conductor) · Detailed reference: the repo [README](https://github.com/StructuPath/herdr-conductor#readme)
 
 ## Pinned evidence
 
 | Field | Value |
 | --- | --- |
-| Plugin release | `0.3.0` |
+| Plugin release | `0.4.0` |
 | Minimum Herdr | `0.7.5` |
 | Explicitly tested Herdr | `0.7.5` |
-| Runtime candidate | `0ed952992ef1559808da4d25a2e7166d075b1ce9` |
-| Evidence commit | `712863c34d6126c9d95fa3b9bd6caf5220cbfc43` |
-| Manifest SHA-256 | `95958ade511f422b65a07f3d4a305581cdb236e1cd616da7d6c57aa0660aa35e` |
-| Live evidence digest | `8547d5cd3215bf79cdb973437de867e803baba1a86d80916eb0ca8b5f2d8bcfd` |
+| Evidence commit | `bf67d318067c60318dcd7089897f513bfefe3af7` |
+| Manifest SHA-256 | `b8898d549216485c2bd599a101808030ce534b9c32625b6e6bdc51da04644672` |
 
-The release retains an immutable [Stage 2 source manifest](https://github.com/StructuPath/herdr-conductor/blob/v0.3.0/docs/evidence/stage2-runtime-source-manifest.json) and [installed-Herdr live contract report](https://github.com/StructuPath/herdr-conductor/blob/v0.3.0/docs/evidence/2026-07-28-stage2-live-contracts.md). Historical [B0 identity-capability evidence](https://github.com/StructuPath/herdr-conductor/blob/v0.3.0/docs/evidence/2026-07-28-herdr-0.7.5-identity-capability.md) and the [Stage 1 B4 lifecycle report](https://github.com/StructuPath/herdr-conductor/blob/v0.3.0/docs/evidence/2026-07-28-stage1-b4-live-smoke.md) remain compatibility evidence. These are sanitized, operator-observed local records—not cryptographic remote attestation or authentication against malicious same-UID processes.
+The retained [Stage 2 source manifest](https://github.com/StructuPath/herdr-conductor/blob/712863c34d6126c9d95fa3b9bd6caf5220cbfc43/docs/evidence/stage2-runtime-source-manifest.json) and [installed-Herdr live contract report](https://github.com/StructuPath/herdr-conductor/blob/712863c34d6126c9d95fa3b9bd6caf5220cbfc43/docs/evidence/2026-07-28-stage2-live-contracts.md) are historical compatibility evidence, not a live validation of Stage 3. These are sanitized, operator-observed local records—not cryptographic remote attestation or authentication against malicious same-UID processes. Older and newer Herdr binaries do not satisfy Conductor's exact 0.7.5 requirement; passing local tests is not evidence that another Herdr version is supported.
 
-## All five actions
+## All seven actions
 
 | Action ID | Attended behavior |
 | --- | --- |
 | `structupath.conductor.assemble` | Bind the exact repository/workspace, publish immutable producer tasks and private report outboxes, create run-unique worktrees/refs, then start task-bound panes and agents. |
 | `structupath.conductor.board` | Print one passive lifecycle snapshot for the invoking repository/workspace; it does not open, focus, or mutate a pane. |
 | `structupath.conductor.status` | Print context-bound task, report, integration, gate, and exact live-identity status. |
 | `structupath.conductor.harvest` | Collect terminal reports, reject invalid committed reports durably, perform deterministic zero-or-one-CAS integration, and dispatch reviewer/validator tasks at the exact observed integration SHA. |
+| `structupath.conductor.preview` | Journal the proposed local-ref fast-forward, exact integration and target observations, and gate assertions; return the exact approval command. |
+| `structupath.conductor.apply` | Consume a matching operator approval receipt once, then perform or resolve the attempt's single local-ref compare-and-swap. |
 | `structupath.conductor.stand-down` | Revalidate each complete live pane/agent tuple before close, archive strict authority, and retain all worktrees, branches, tasks, reports, outboxes, gate sources, recordings, logs, artifacts, and Guard files. |
 
 Conductor owns this lifecycle. It does **not** invoke Swarm or provide an automatic Conductor→Swarm pipeline. Supported composition remains human-selected and sequential.
 
 ## Attended quickstart
 
-Create `.herdr-conductor.json` in a clean Git repository:
+Use Herdr exactly 0.7.5, Node.js 20 or current LTS, Python 3.11+, and Git with 40-hex SHA-1 object IDs. Create `.herdr-conductor.json` in a clean Git repository. This first-run example explicitly disables apply:
 
 ```json
 {
-  "version": 2,
+  "version": 3,
+  "apply": null,
   "state_root": { "kind": "default" },
   "worktree_root": ".conductor-worktrees",
   "roles": [
@@ -78,7 +79,7 @@ Create `.herdr-conductor.json` in a clean Git repository:
 }
 ```
 
-Then explicitly drive the lifecycle from that Herdr workspace:
+Commit `.herdr-conductor.json` before assembly so the repository is clean, then explicitly drive the lifecycle from that Herdr workspace:
 
 ```bash
 herdr plugin action invoke assemble --plugin structupath.conductor
@@ -93,6 +94,20 @@ herdr plugin action invoke stand-down --plugin structupath.conductor
 
 `assemble` returns exact task paths, source roots, outbox slots, and task-bound publisher commands. Reports are closed canonical JSON supplied through bounded stdin. Producer collection and exact-SHA gate collection may require separate attended `harvest` invocations. Harvest and stand-down are mutating attended actions. Failed or uncertain external effects become `needs_attention` and are never silently replayed.
 
+### Optional attended apply
+
+To enable apply for a new run, set `apply` to `{ "target_ref": "refs/heads/release" }` before assembly. The named local branch must already exist, differ from the integration branch, be checked out in no worktree, and remain exactly at the run's integration base. The proposed change must be a nonempty, rename-free fast-forward. Configuration v2 remains supported with apply disabled; do not edit a run-bound configuration mid-run.
+
+After producer and gate collection, use this sequence instead of standing down immediately:
+
+1. Invoke `herdr plugin action invoke preview --plugin structupath.conductor`.
+2. Review the exact target, diff, gate assertions, and preview entry digest.
+3. Follow the exact `npm run apply:approve` command returned by preview and provide the operator's canonical approve or reject receipt through stdin. Do not manufacture a receipt from a generic example or treat a worker's `approve` report as operator consent.
+4. Invoke `herdr plugin action invoke apply --plugin structupath.conductor` only for the reviewed, approved attempt.
+5. Inspect status, then invoke stand-down when finished.
+
+The receipt is consumed durably before any Git effect and cannot be reused. A moved target records an unapplied outcome with zero target changes. Only the attended apply action can resolve an uncertain apply publication from an exact target-SHA observation; other ambiguous operations remain refused. Rejected or voided attempts permit a fresh preview, up to eight attempts. Apply never pushes, tags, publishes, deploys, or updates multiple refs.
+
 ## Trust and completion limits
 
 - State is strict, non-executable private JSON indexed by physical Git common-directory and Herdr workspace identity. Atomic writes, repository locks, generations, canonical digests, and hash-chained journals are cooperative coordination controls—not authentication.
@@ -101,5 +116,5 @@ herdr plugin action invoke stand-down --plugin structupath.conductor
 - Missing, malformed, duplicate, foreign, stale, replayed, ambiguous, dirty, or durability-uncertain authority fails closed. Integration performs exactly zero or one target compare-and-swap.
 - Herdr `0.7.5` closes by `pane_id`. Conductor re-reads the full workspace, pane, terminal, agent, cwd, run, and generation tuple immediately before close, but a same-user TOCTOU window remains.
 - The repository lock does not stop unrelated Git or same-user processes. Worktrees are review boundaries, not sandboxes. Guard observes rendered text and cannot prove prevention.
-- Stage 2 does not provide approval receipts, approval consumption, approval-aware apply, automatic recovery, suite adapters, unattended orchestration, automatic cleanup/prune, or Browser promotion. Those remain later-stage work.
+- Stage 3 receipts are unauthenticated same-user operator records, not signatures or authorization proof. Apply changes one configured local ref; it does not provide general automatic recovery, suite adapters, unattended orchestration, automatic cleanup/prune, or Browser promotion.
 - Stand-down closes only identity-proven panes and archives authority. It does not remove worktrees, branches, tasks, outboxes, reports, gate sources, artifacts, recordings, logs, or Guard files; retained resources continue consuming disk.