muse-crew 0.7.10 → 0.7.12

package/docs/publish-verification.md

@@ -1,9 +1,26 @@
 # Publish content verification — parent protocol
 
+> **UNBLOCKED (2026-09-15):** the platform's `artifact_inspect` is still
+> gone, but no platform tool is needed anymore. The platform's artifact
+> edits land in its on-disk working copy of the artifact source
+> (`~/workspace/ts-spaces/<slug>/` — verified empirically 2026-09-15:
+> added lines present, removed lines absent across real platform commits),
+> so `lib/readback-disk.js` performs the read-back deterministically: it
+> reads the working copy and emits the exact machine-readable findings
+> block `lib/verify-publish.js` already parses. No LLM, no async handoff,
+> no prose to parse. The verifier is unchanged — the sensor changed, the
+> judge didn't.
+>
+> Authority boundary: the sensor reads the platform's working copy — the
+> tree the hosted artifact is built/served from. A working copy that is
+> stale relative to a just-applied edit yields honest ABSENT findings and
+> the verifier fails CLOSED (parked). Staleness can only park a task,
+> never stamp provenance.
+
 Provenance is the artifact's claim that its live content came from a specific
-repo commit. The workflow used to stamp it; it no longer does. This document
-is the parent-side runbook. The workflow script handles the mechanical
-halves; the parent handles the stamp.
+repo commit. The workflow never stamps it. This document is the parent-side
+protocol. Deterministic code detects, claims, and certifies; the tick worker
+(the live root agent) is only the async ferry for the inspection.
 
 ## Why the parent stamps
 
@@ -34,37 +51,132 @@ The contract is split on purpose:
 
 - **Workflow-owned:** carrying the merged diff to the builder, the
   applied-report observation (logged, never a park), the build-completion
-  poll, post-deploy cleanup, triggering an independent `artifact_inspect`
-  read-back of the changed regions (carrying the observed builder build
-  identifier for correlation), recording the Publish session completed, and
+  poll, post-deploy cleanup, recording the Publish session completed, and
   parking with `publish: verification-requested <commit>` instead of
-  stamping.
-- **Parent-owned:** reading back the artifact's actual content, comparing it
-  mechanically against the merged diff, checking for supersession, stamping
-  provenance only on a match, reading the stamp back exactly, and re-queuing
-  the task to `in_progress`. In standard/bugfix, QA's provenance check then
-  enforces the stamp — an unstamped publish fails loudly in QA instead of
-  passing silently. Chore has no QA: the parent's stamp read-back is the
-  final gate.
+  stamping. The workflow does NOT trigger the read-back inspection — an
+  async inspection triggered from inside a workflow run delivers its result
+  to the root agent, never back into the run, so a workflow-side trigger is
+  an orphan the verifier cannot consume. The parent triggers the one
+  inspection it can actually receive.
+- **Parent-owned (deterministic code, ferried by the tick worker):**
+  scanning for verification-pending parks, atomically claiming them,
+  building the read-back request, triggering the inspection, waiting for the
+  result, comparing it mechanically against the merged diff, checking
+  build-ID correlation and supersession, stamping provenance only on a
+  match, reading the stamp back exactly, logging the terminal verdict, and
+  re-queuing the task to `in_progress`.
 
 No artifact publish completes without parent-stamped provenance. A missing or
 mismatched read-back never stamps.
 
+## The carried diff: BASE..HEAD from the stamped provenance
+
+The "merged diff" the workflow carries is `BASE..HEAD` where `BASE` is the
+previously-stamped provenance `source_commit` — the artifact's actual
+content — never `HEAD^1`. (Task `0c53af4e`, 2026-09-14: a push-time
+reconcile merge put the task's own changes behind an intermediate merge, so
+`HEAD^1..HEAD` carried only the reconcile delta and silently omitted the
+task's fix; the artifact built without it. The stamped base is the only
+ground truth for what the artifact already has; `BASE..HEAD` is the complete
+unpublished delta.)
+
+The workflow reads the base via `get-provenance` before computing the diff,
+and the computation is guarded mechanically:
+
+- Empty base (no provenance stamped) → the empty tree
+  `4b825dc642cb6eb9a060e54bf8d69288fbee4904`, and only then. A present but
+  malformed base SHA parks fail-closed.
+- `git merge-base --is-ancestor BASE HEAD` must pass; a non-ancestor base
+  parks fail-closed (the stamped provenance must lead to the integrated
+  commit, otherwise the artifact has drifted or the stamp is wrong).
+- The agent-reported base must equal the stamped base; a mismatch parks.
+- The expected base content hashes (pre-publish observation) are computed at
+  the stamped base, not the merge parent — the artifact's tree should match
+  the stamp, and the observation is only meaningful against it.
+
+The parent verifier (`lib/verify-publish.js`, `--base`) and the read-back
+request builder (`lib/build-readback-request.js`, `--base`) use the identical
+base: the previously-stamped provenance, or the empty tree for a genuine
+first publish. Request builder and verifier never disagree on the base.
+
+## The shape: code detects, the tick ferries, code certifies
+
+A standalone verification workflow cannot work with the async inspection
+model: async inspection results are delivered to the root agent of the
+agent tree, never into a workflow run — so a verify workflow would wait
+forever for a result it can never receive. The tick worker IS the live
+root agent, so it is the only component that can both trigger an
+inspection and receive its result. (The inspection tool itself,
+`artifact_inspect`, was removed by the platform 2026-09-14 — see the
+BLOCKED notice at the top.)
+
+But the tick worker is a generalist LLM, and the certification decision is
+safety-critical: a misjudged "match" stamps unverified content, and nothing
+downstream can ever detect it (QA checks the stamp, not the content). So the
+LLM never judges. The division:
+
+1. **Scan (code):** `scan-verification-pending` finds parked tasks whose
+   latest parent note is `publish: verification-requested`, with no terminal
+   verdict and no unexpired claim. It atomically claims each one by logging
+   `publish: verification-claimed <expiry>` (1-hour lease) — the task stays
+   parked, so the dispatcher never dispatches QA mid-verification, and a
+   second tick cannot start a duplicate verification. It also reconciles the
+   verified-but-still-parked gap (verdict recorded, re-queue lost to a crash)
+   back to `in_progress`.
+2. **Build (code):** `build-readback-request.js` builds the EXACT inspection
+   request from the publish delta — `git diff <base> <commit>` where
+   `<base>` is the previously-stamped provenance `source_commit` (or the
+   empty tree for a first publish). The tick never hand-writes the request,
+   and never uses `commit^1` as the base: push-time reconcile merges put
+   the task's own changes behind an intermediate merge, so `commit^1`
+   covers only the reconcile delta (2026-09-14, task `0c53af4e`).
+3. **Ferry (tick worker):** runs the deterministic sensor
+   `lib/readback-disk.js` (`--repo-path`, `--commit`, `--base` — the same
+   base as step 2 — `--slug` from the project's `deploy_slug`, `--task-id`)
+   and saves its stdout to the result file. The sensor exits 0 only when it
+   actually read the working copy; on a non-zero exit the tick must NOT
+   save stdout — log `publish: verification-procedural-error <commit>
+   <stderr>` and leave the task parked for the next tick to retry (a sensor
+   failure is procedural — the read could not be performed — not a content
+   verdict). `build-readback-request.js` is retained for the manual LLM
+   fallback below.
+4. **Certify (code):** `verify-publish.js` parses the inspector's
+   machine-readable findings block, compares every added/removed diff line
+   against the reported present/absent verdicts, checks build-ID correlation
+   and supersession via git, and only then stamps provenance, reads the
+   stamp back exactly, logs the terminal verdict, and re-queues to
+   `in_progress`. Unparseable findings, mismatches, supersession, and stamp
+   failures all fail CLOSED with a terminal `publish: verification-failed`
+   verdict — never a stamp.
+   - **Envelope:** the tick saves the COMPLETE handoff — the full prose
+     report AND the full JSON result, both verbatim (raw prose, JSON, or
+     both concatenated are all accepted). Observed 2026-09-14: the
+     platform's JSON envelope carries NO machine-readable findings
+     block; the block lives in the prose handoff. The verifier locates
+     the findings block in prose text and JSON string values (including
+     double-encoded ones) and prefers the block whose file paths cover
+     the expected diff — an echoed request template or stray prose never
+     outranks the real block. No covering block => `unreadable-result`,
+     fail closed. Saving JSON-only strands verification.
+     fail closed.
+   - **Release identity:** `scan-verification-pending` resolves
+     `crew_release` through the crew home's `current` symlink (the immutable
+     active release) and cross-checks it against the running code's own
+     realpath. Unresolvable or disputed => the scan throws fail-closed
+     BEFORE writing any claim — provenance is never stamped `unknown`, and
+     a stale cron body running an old release cannot certify.
+
+The tick body (seed/cron-body-template.md, step 4.5) wires these together.
+The publisher never certifies itself, and the LLM never makes the
+safety-critical match decision.
+
 ## The park
 
 When the artifact build lands, the workflow parks the task with the message:
 
 ```
 publish: verification-requested <commit> (build <agent_id|agent_id unobserved>) — artifact build landed, post-deploy
-finalized, provenance NOT stamped. Parent: run docs/publish-verification.md
-(content read-back inspection <inspection_id> already triggered).
-```
-
-or, if the workflow's inspect trigger failed:
-
-```
-publish: verification-requested <commit> (build <agent_id|agent_id unobserved>) — ... (read-back inspect trigger
-failed: <reason> — parent: trigger artifact_inspect manually).
+finalized, provenance NOT stamped. Parent: run docs/publish-verification.md.
 ```
 
 The parked message is stored as `Parked: publish: verification-requested
@@ -80,71 +192,95 @@ task holds no resources.
 
 ## Parent verification procedure
 
+The automated path is the tick body's step 4.5 (scan → build → ferry →
+verify). The manual fallback below is the same protocol run by hand; it
+exists for when the artifact namespace is unavailable to the tick worker.
+
 For a task parked with `publish: verification-requested <commit>`:
 
 1. **Resolve the project.** Read the task's project via the Crew API
-   (`getproject`); you need `repo_path` (the git checkout) and the artifact
+   (`get-project`); you need `repo_path` (the git checkout) and the artifact
    slug (the project's publish target).
-2. **Expected change.** Run `git show <commit>` (or
-   `git diff <commit>^1 <commit>`) in `repo_path`. This is the expected
-   content — the same diff the workflow carried to the builder.
-3. **Actual content.** Get the read-back:
-   - If the park message names an `inspection_id`, read that inspection's
-     result (async `artifact_inspect` results are delivered to the parent,
-     like the visual-verdict inspections).
-   - If the trigger failed, call `artifact_inspect` yourself with
-     `repair_authorized: false` and the `verbatim_request` rebuilt from the
-     workflow source: `buildPublishReadbackRequest(taskId, commit, diff,
-     buildAgentId)` in `workflows/standard.js` (identical in `bugfix.js`
-     and `chore.js`) — pass the task id, the commit, the diff from step 2,
-     and the agent_id from the park message's `(build …)` suffix (ledger
-     lookup from step 4b if the suffix says `agent_id unobserved`; null if
-     neither is available).
-   - If no read-back can be obtained at all, log
-     `publish: verification-blocked <commit> <reason>` and leave the task
-     parked for human attention. Never stamp without a read-back.
+2. **Expected change.** The publish delta is `git diff <base> <commit>`
+   in `repo_path`, where `<base>` is the previously-stamped provenance
+   `source_commit` (read it via `get-provenance`; use the empty-tree sha
+   `4b825dc642cb6eb9a060e54bf8d69288fbee4904` when no provenance is
+   stamped yet — a first publish). Never use `commit^1` as the base and
+   never take the expected change from the builder's report: push-time
+   reconcile merges violate the `merge^1 == previously-published tree`
+   invariant, so `commit^1..commit` can omit the task's own fix
+   (2026-09-14, task `0c53af4e`).
+3. **Actual content.** Run `lib/readback-disk.js` with `--repo-path`,
+   `--commit`, `--base` (the same base as step 2), `--slug`, and
+   `--task-id`, and save its stdout to the result file — this is the
+   deterministic read-back; it emits the machine-readable findings block
+   directly. (LLM fallback: if the disk working copy is unavailable, call
+   the artifact inspector with `repair_authorized: false` and the
+   `verbatim_request` built by `lib/build-readback-request.js`, passing
+   `--build-agent-id` from the park message's `(build …)` suffix when it
+   is not `agent_id unobserved`.) The findings block grammar:
+   ```
+   FILE: <path>
+   ADDED: <exact added line> :: PRESENT|ABSENT
+   REMOVED: <exact removed line> :: PRESENT|ABSENT
+   END_FILE
+   ```
+   If no read-back can be obtained at all, log
+   `publish: verification-blocked <commit> <reason>` and leave the task
+   parked for human attention. Never stamp without a read-back.
 4. **Compare mechanically.** For every added (`+`) line in the diff, the
-   read-back must report it PRESENT in the artifact's current source. For
-   every removed (`-`) line, the read-back must report it ABSENT. Quote the
-   observed lines; do not infer from prose.
-4b. **Build-ID correlation.** Prove the read-back inspected the live build
-   of THIS publish attempt — not a different build's output:
+   read-back's machine-readable block must report it PRESENT in the
+   artifact's current source. For every removed (`-`) line, it must report
+   it ABSENT — with one mechanical exemption: a removed line that also
+   occurs verbatim in untouched code has zero discriminating power (its
+   presence proves nothing about whether the old block survived), so the
+   verifier exempts it instead of failing a good publish. The exemption is
+   computed, never judged: a removed line L in file F is exempt iff L
+   occurs in F's old tree (at `<base>`) strictly more times than the diff
+   removes it (2026-09-15, task `00bca4b8` — a valid publish parked because
+   two removed lines occurred identically in the untouched WorkflowSteps
+   component). The comparison is computed by `lib/verify-publish.js` —
+   never by eyeballing prose. A missing or malformed findings block fails
+   closed as `unreadable-result`, never as a pass.
+4b. **Build-ID correlation.** The read-back may have inspected a different
+   build's output than this publish attempt's:
    1. **Expected** = the agent_id in the park message's `(build …)` suffix.
       If the suffix says `agent_id unobserved`, look up the workflow's
       durable publish ledger at `$CREW_HOME/.publish-ledger/<slug>.jsonl`
       for the `submitted` entry with this `<commit>` and use its
       `agent_id` field (it may still be null — then this step is vacuous).
-   2. **Live** = the build agent_id the read-back reports for the live
-      build (the request asks for it explicitly; the inspector may state
-      that no build/agent_id is visible).
-   3. If expected and live are both non-null and DIFFER, the read-back may
-      have inspected a different build's output — log
-      `publish: build-mismatch <commit> expected <expected> observed <live>`,
-      stay parked, never stamp, never re-queue. This is not a retry signal:
-      a later inspection of the right build can be recorded by the human
-      if desired; the loop never re-drives the verification itself.
-   4. Otherwise the content match from step 4 decides; log the correlation
-      outcome (expected/live compared, or vacuous) in the `publish:
-      verified` note.
+   2. **Live** = whether the expected agent_id appears anywhere in the
+      read-back result (the live artifact status exposes no durable
+      agent_id — only an in-flight correlation ID that expires with the
+      publish attempt, so absence is the common case, not evidence of a
+      mismatch).
+   3. If expected is non-null and the read-back positively reports a
+      DIFFERENT live build identity for this attempt's output, log
+      `publish: build-mismatch <commit> expected <expected> observed
+      <live>`, stay parked, never stamp, never re-queue.
+   4. Otherwise the content match from step 4 decides — the stamp certifies
+      CONTENT, not the builder's identity. Log the correlation outcome
+      (correlated / unobserved) in the `publish: verified` note.
 5. **Supersession check.** Before stamping, prove the inspected live
-   artifact still represents the commit being certified. Read the crew's
-   current provenance record (`get-provenance`): if `source_commit` names a
-   commit NEWER than `<commit>` (a later Publish already landed), the
-   read-back is stale — do NOT stamp `<commit>` on top of it. Log
-   `publish: superseded <commit> by <newer_commit>` and leave the task
-   parked for human attention. Never claim commit A after commit B changed
-   the artifact.
-6. **Stamp, verify the stamp, then re-queue:**
+   artifact still represents the commit being certified: `git rev-parse
+   HEAD` in `repo_path` must equal `<commit>`. If HEAD has moved (a later
+   Publish landed), the read-back is stale — log
+   `publish: superseded <commit> by <head>` and leave the task parked for
+   human attention. Never stamp a superseded commit.
+6. **Stamp, verify the stamp, then re-queue** (all in `lib/verify-publish.js`;
+   the manual equivalent):
    - **Match** — stamp provenance with the Crew API CLI `set-provenance`
      (the crew-owned store). Do NOT use the artifact's `setprovenance`
      action — it writes a different, non-authoritative store that QA never
      reads, so the stamp would be invisible to every gate:
-     `set-provenance --json '{"source_commit":"<commit>","crew_release":"<basename of $crewHome/current>","published_at":"<date -u +%Y-%m-%dT%H:%M:%SZ>","task_id":"<task>"}'`.
-     Then read the stamp back with `get-provenance`
-     and confirm all four fields match exactly what was sent — a stamp
-     that cannot be read back is not a stamp. Only then log the task note
-     event `publish: verified <commit> (<inspection_id>)` and re-queue
-     with `update-task` → state `in_progress` (never `todo` — `todo`
+     `set-provenance --json '{"source_commit":"<commit>","crew_release":"<release>","task_id":"<task>"}'`
+     (crew_release is the basename of the active release, e.g.
+     `pkg-0.7.10`). Then read the stamp back with `get-provenance`
+     and confirm source_commit, crew_release, and task_id match exactly
+     what was sent — a stamp that cannot be read back is not a stamp. Only
+     then log the task note event
+     `publish: verified <commit> (<inspection_id>)` and re-queue with
+     `update-task` → state `in_progress` (never `todo` — `todo`
      restarts Triage and resets retry accounting). The dispatcher resumes
      at QA from the completed Publish session (standard/bugfix); chore has
      no QA — it proceeds to terminal completion. QA's provenance check
@@ -161,6 +297,61 @@ For a task parked with `publish: verification-requested <commit>`:
      for human attention. Never re-queue an unstamped-but-verified task into
      QA — QA would fail it and burn rework budget on a stamping problem.
 
+## Crash recovery
+
+- **Tick dies before triggering the inspection:** the claim expires after
+  1 hour; the next scan re-claims and re-verifies from scratch. The stamp
+  is an idempotent upsert, so a duplicate verification cannot corrupt it.
+- **Tick dies after the inspection but before the stamp:** same as above —
+  the next scan re-runs the whole verification (new inspection, new
+  comparison). Wasteful but correct.
+- **Crash between stamp and re-queue:** the next scan sees
+  `publish: verified` on a still-parked task and reconciles it to
+  `in_progress`. Failure verdicts are never reconciled — they stay parked
+  for human attention.
+- **Two ticks verify concurrently:** impossible — the atomic claim means the
+  second scan sees the unexpired `publish: verification-claimed` note and
+  skips. The lease expiry bounds the damage if a claimer dies.
+
+## Unknown-outcome recovery (2026-09-14, Gate 1 Journey 3 attempt 7)
+
+Attempt 7 parked at Publish with outcome `unknown`: the rebuild trigger's
+child failed structured closeout and the in-flight-only build-state poll
+could not see the completed build — even though the build HAD run (a fresh
+platform audit directory existed). Two mechanisms close this gap.
+
+**1. Workflow-side durable evidence.** Before the rebuild trigger, the
+workflow snapshots the artifact's audit-directory listing
+(`~/workspace/ts-spaces/<slug>/audits/` — best-effort, never a gate). On a
+structured-output failure with no in-flight build observed, it re-lists and
+diffs: a timestamped directory that appeared during the trigger window is
+positive evidence the edit went through and the build completed. The
+fallback never re-issues the edit, never stamps provenance, and only routes
+to the parent's independent content read-back. No new directory still parks
+`unknown` fail-closed. The ledger distinguishes the two confirmations: `edit
+confirmed via durable audit evidence …` vs `edit confirmed via build-state
+poll …`.
+
+The fallback's known limitation: audit directories are not attributed to
+tasks, so two concurrent publishes to the same artifact could cross-read.
+The consequence is bounded — the fallback only routes to the parent
+read-back, and the parent still certifies the exact commit's content
+mechanically (a wrong build's content fails closed as `publish:
+content-mismatch` / `publish: build-mismatch`, never stamps).
+
+**2. `resolve-publish-unknown` (Crew API).** For attempts already parked
+`unknown` before this fix: given a task parked with a latest ledger outcome
+of `unknown`, it derives the publish window (Integrate-completion event →
+unknown-outcome park event) and checks for a timestamped audit build inside
+that window. On evidence, it appends `unknown-resolved` to the ledger
+(never rewriting the original entry), writes `publish: unknown-resolved`
+and a mirrored `publish: verification-requested <commit>` note (the mirror
+is timestamped strictly later so the scan sees it as the latest), and leaves
+the task parked for the normal scan. Still-unknown cases stay parked:
+unparked task, non-`unknown` latest ledger outcome, missing commit, no audit
+build in the window, unobservable window, or an already-resolved attempt
+(idempotent).
+
 ## Exact note-event prefixes
 
 Case-sensitive, exact-prefix matches — match on prefixes, never on English
@@ -168,20 +359,29 @@ meaning:
 
 - `publish: verification-requested <commit>` — workflow park; contained in
   the stored `Parked: …` message.
+- `publish: verification-claimed <ISO-expiry>` — parent scan; atomic claim
+  with lease. Not a verdict.
 - `publish: verified <commit> (<inspection_id>)` — parent, after stamping
   AND reading the stamp back exactly; re-queued to `in_progress` (never
   `todo`).
 - `publish: content-mismatch <commit> <details>` — parent; exact FAIL
   evidence quoted; stays parked, never stamped, never re-queued to QA.
 - `publish: build-mismatch <commit> expected <expected> observed <live>` —
-  parent; the read-back inspected a different build's output than the
-  publish attempt (step 4b); stays parked, never stamped, never re-queued.
-- `publish: superseded <commit> by <newer_commit>` — parent; a later Publish
-  already landed; stays parked for human attention.
+  parent; the read-back positively identified a different build's output
+  (step 4b); stays parked, never stamped, never re-queued.
+- `publish: superseded <commit> by <head>` — parent; HEAD moved past the
+  commit; stays parked for human attention.
 - `publish: verification-blocked <commit> <reason>` — parent; no read-back
   obtainable; stays parked for a human.
+- `publish: unknown-resolved <commit>` — recovery; durable build evidence
+  found inside the publish window for a previously-unknown attempt (see
+  "Unknown-outcome recovery"). The original `unknown` outcome is preserved;
+  the mirrored `verification-requested` note (written strictly later) is
+  what the scan claims.
 - `publish: stamp-failed <commit> <reason>` — parent; read-back matched but
   the stamp call failed; stays parked for a human.
+- `publish: reconciled verified-but-parked -> in_progress` — parent scan;
+  the verified verdict was recorded but the re-queue was lost.
 
 ## Workflow differences
 
@@ -192,14 +392,3 @@ meaning:
   exact stamp read-back), the dispatcher proceeds to terminal completion.
   The parent's stamp read-back is the final gate — no downstream phase
   re-checks it.
-
-## Recovery: rebuilding the read-back request
-
-If the park message names no inspection and you must trigger the read-back
-manually, the request is deterministic — rebuild it from the workflow source
-(`buildPublishReadbackRequest` in `workflows/standard.js`, identical in
-`bugfix.js` and `chore.js`) with the task id, the `<commit>` from the park
-message, the diff from `git show <commit>` in the project's `repo_path`,
-and the agent_id from the park message's `(build …)` suffix (use the ledger
-lookup from step 4b if the suffix says `agent_id unobserved`; pass null if
-neither is available).

package/docs/visual-verdict.md

@@ -1,28 +1,85 @@
-# The Visual Verdict — parent protocol
+# The Visual Verdict — Hazel owns it
+
+> **UPDATE (2026-09-15):** the parent post-change verdict protocol is
+> **retired**. There is no `visual_verdict:` note contract, no
+> `visualVerdictStatus()` gate, no `visual: pending` marker, and no parent
+> capture/composition step. Hazel (the QA work agent) drives the artifact
+> herself with `lib/see-act.js`, logs every step to the OODA report, and
+> records her verdict machine-readably — the workflow trusts her verdict
+> and never parks for a parent one. The baseline-capture protocol below is
+> unchanged: baselines are still captured before the fix exists, which the
+> workflow cannot do synchronously.
+
+> **UPDATE (2026-09-14):** the agent-owned see-act loop superseded the
+> blocked platform path. `artifact_inspect` was removed by the platform and
+> `artifact.inspect` is malfunction diagnosis, not a substitute — but the
+> workflow no longer needs either: the QA/repro agent drives the artifact
+> itself with `lib/see-act.js` (one browser action per invocation, reads
+> its own screenshots) against `lib/serve-artifact.js` (local server for the
+> built artifact). Experiential tasks get agent-run visual inspection in
+> the QA phase (standard, bugfix) and experiential repro (bugfix).
 
 QA owns the visual verdict for experiential artifact tasks: does the change
-*look* right, judged by Hazel's artist-eye rubric, from rendered evidence.
-This document is the parent-side runbook. The workflow script handles the
-mechanical halves; the parent handles everything that needs eyes.
+*look* right, judged by Hazel's artist-eye rubric, from rendered evidence
+she captured herself.
 
-## Why the parent does it
+## Why Hazel does it herself
 
-Async `artifact_inspect` results are delivered to the root agent — the
-parent — not to the workflow run. A workflow script cannot synchronously
-await them, so the workflow cannot issue the visual verdict itself. The
-contract is split on purpose:
+The old model was async: rendered post-change evidence was delivered to
+the root agent — the parent — which then recorded a `visual_verdict:` note
+the workflow gated on. That split the verdict across two systems and left
+tasks parked whenever the parent path stalled.
 
-- **Workflow-owned:** the experiential flag, the Capture phase, the Map
-  baseline gate, the mechanical QA checks, the visual-verdict gate that
-  parks for a verdict instead of silently passing.
-- **Parent-owned:** triggering inspections, saving baseline/post-change
-  evidence, generating composites, launching Hazel only after rendered
-  evidence arrives, recording `visual_verdict`, and closing, reworking, or
-  parking the task.
+The new model is depth-1: the QA work agent IS the inspector. She starts
+the local artifact server, drives it one browser step at a time, reads
+every frame, edits and composes evidence when a raw screenshot is not
+enough, and records her verdict. The contract is:
 
-No experiential artifact task completes without a recorded visual PASS.
-Missing inspection results park visibly. Rendering impossibility never
-passes.
+- **Hazel-owned:** the experiential loop, the OODA report
+  (`ooda-log.jsonl` + archived frames + derivatives), `verdict.json` and
+  the append-only `verdicts.jsonl` ledger, the visual verdict itself.
+- **Workflow-owned:** the experiential flag, the Capture phase, the Map
+  baseline gate, the mechanical QA checks, trusting Hazel's verdict.
+- **Parent-owned:** baseline capture only (see below) — baselines are
+  captured before the fix exists, which the workflow cannot do
+  synchronously.
+
+No experiential artifact task completes without Hazel's recorded verdict.
+A missing OODA log is a broken report, not a pass. Unknown is neither
+PASS nor FAIL — un-runnable checks are named as explicit evidence gaps.
+
+## The OODA report
+
+Task evidence lives under `$CREW_HOME/task-evidence/<task-id>/<phase>/`
+(`repro/` for bugfix Reproduce, `postchange/` for QA):
+
+- `ooda-log.jsonl` — ordered steps with observations. Every step carries
+  an `--attempt` identity; steps are strictly monotonic within an attempt;
+  a rerun is a new attempt at step 1 — attempts accumulate, never
+  overwrite. Actions: `aria|shot|click|scroll|type` (browser) and
+  `crop|zoom|label|nup|compose` (evidence derivatives).
+- Archived frames — `001-shot-desktop.png`, `002-click-mobile.png`, … via
+  `SEE_ACT_ARCHIVE_DIR`. A frame Hazel did not read is not evidence.
+- `verdict.json` — the latest machine-readable verdict
+  (`{verdict, summary, expected, actual, missing_evidence}`).
+- `verdicts.jsonl` — the append-only ledger: every attempt's verdict is
+  preserved with a mechanical sequence number, never overwritten.
+
+## Evidence editing and composition
+
+When a raw screenshot is not enough evidence, Hazel has two deterministic
+layers:
+
+- **Pixel operations** (`lib/edit-image.py`, Pillow): `crop` (pixel-exact,
+  rejects out-of-bounds), `zoom` (nearest-neighbor, back to frame size),
+  `label` (caption bar), `nup` (side-by-side grid with labels).
+- **Composition** (`lib/render-html.js`, headless Chromium): renders a
+  local HTML layout to PNG for rich before/after presentations with real
+  typography. Hermetic — remote assets are blocked and fail loudly.
+
+Derivatives supplement, never replace: the source frame stays archived
+and is named in the step's args. Every derivative is logged and read —
+an unread image is not evidence.
 
 ## Evidence layout
 
@@ -31,16 +88,10 @@ Task evidence lives under:
 ```
 $CREW_HOME/task-evidence/<task-id>/
   baseline/      baseline captures (pre-change)
-  postchange/    post-change captures
-  composites/    side-by-side and difference images
+  postchange/    post-change captures + OODA report
+  repro/         bugfix reproduction captures + OODA report
 ```
 
-Capture filenames follow the deterministic frame used by the workflow's
-`buildVisualCapturePlan` output: `<kind>-<n>-<viewport>-<state>.png`
-(e.g. `baseline-01-desktop1440x900-top.png`). The composites are named
-`<stem>-sidebyside.png` and `<stem>-overlay.png` by
-`lib/compose-evidence.py`.
-
 ## Baseline capture protocol
 
 Triggered by the Capture phase when the task is experiential and no
@@ -69,33 +120,6 @@ baseline evidence is recorded yet. The workflow logs
 The workflow requests at most two attempts; after two it records
 `baseline: none (capture unavailable after 2 attempts)` itself.
 
-## Post-change capture, composition, Hazel, verdict
-
-After the QA step completes its mechanical checks, the QA session notes
-carry `visual: pending` and the deterministic `capture_plan:` — the parent
-then:
-
-1. Trigger the post-change inspection with the `capture_plan:` frame from
-   the QA session notes. Save captures under `postchange/`.
-2. Run `python3 lib/compose-evidence.py <baseline-dir> <postchange-dir>
-   <composites-dir>` and keep its `PAIR...` / `SKIP...` manifest output as
-   evidence refs.
-3. Launch Hazel with `identities/hazel.md` (artist-eye rubric + verdict
-   discipline), the baseline refs, the post-change refs, and the composite
-   manifest. She receives rendered evidence only — never a prose
-   description of what the change "looks like".
-4. Record her verdict as a task note event:
-   `visual_verdict: PASS <composite refs>` or
-   `visual_verdict: FAIL <reason> <refs>`.
-5. Routing:
-   - **PASS** — the task is done; close it.
-   - **FAIL** — send the task back to Build as budgeted rework, with the
-     FAIL reason and refs as the rejection notes.
-   - **FAIL with reason beginning `rendering impossible:`** — the target
-     cannot be rendered at all (never a rework loop). Park the task for
-     human attention. A verdict can never be issued without rendered
-     evidence; impossibility fails, it never passes.
-
 ## Exact note-event prefixes
 
 Case-sensitive, exact-prefix matches — the workflow matches on prefixes,
@@ -105,16 +129,6 @@ never on English meaning:
 - `baseline: captured <refs>` — parent, after saving baseline captures.
 - `baseline: none (<reason>)` — baseline not capturable; final QA judges
   on the rubric alone and states that explicitly.
-- `visual_verdict: PASS <composite refs>` — parent, after Hazel's verdict.
-- `visual_verdict: FAIL <reason> <refs>` — reason beginning exactly
-  `rendering impossible:` parks for a human; any other reason reworks at
-  Build within the shared budget.
-
-## Recovery: rebuilding the capture plan
-
-If the QA session notes are truncated (summary cap) and `capture_plan:`
-is lost, the frame is deterministic — rebuild it from the workflow
-source: `buildVisualCapturePlan(taskTitle, taskDescription,
-"postchange", captureTargets)` in `workflows/standard.js` (identical in
-`bugfix.js` and `chore.js`). Capture targets come from the Map step's
-`capture_targets:` marker line; fall back to the task description.
+
+The `visual_verdict:` prefixes are retired (2026-09-15) — Hazel's verdict
+lives in `verdict.json` / `verdicts.jsonl`, not in note events.