muse-crew 0.7.9 → 0.7.11

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.

package/lib/AGENTS.md

@@ -14,3 +14,10 @@ Shell scripts for the crew's infrastructure. Called by workflow scripts, cron, a
 - `test-publish-skip.sh` — regression tests for the no-lock graceful publish skip (park 2026-09-11): `lock-status` returns exact `UNLOCKED`/`LOCKED by <holder> since <ts> (pid <pid>)`; a fake empty-diff integrate takes the MERGED_EMPTY branch and never takes the lock; the shipped step-5 block from publish-npm.sh (extracted by anchor) skips gracefully on UNLOCKED (no park, no `PUBLISH_COMPLETE`), follows the refresh path when a lock is held, and fails closed on a `lock-status` query failure; the gate sits inside the ALREADY_PUBLISHED=0 branch and mutation steps are gated on NO_LOCK_HELD=0
 - `publish-npm.sh` — deterministic npm publish: lock refresh, release install, version write/commit, pack, registry publish, verify, push, post-deploy. Takes TARGET_VERSION as input; idempotent on retry/resume.
 - `compose-evidence.py` — deterministic visual-evidence compositor (Pillow): pairs identical PNG stems from baseline/ and postchange/ dirs, emits `<stem>-sidebyside.png` and amplified-difference `<stem>-overlay.png` into composites/, prints `PAIR`/`SKIP` manifests. Byte-deterministic; nonzero exit on errors.
+- `compose-evidence-caption.js` — deterministic QA-evidence caption composer (2026-09-14): given `--crew-home`, `--task-id`, and the resolved `--audit-dir` name, extracts the task title/description, the latest `visual_verdict:` note, the `publish: verified` commit (or the global provenance record when it belongs to this task), and the merge commit's subject line from the project repo — and prints the out-of-context transition Eric asked for (problem → solution → evidence handoff) to stdout. The caller appends the desktop/mobile attachment lines after this caption. Honest labels: "provenance not yet stamped" when no commit is known, "no QA verdict recorded" when none exists, and the visual-protocol-unavailable note when the task's own run recorded `baseline: none`. Exits non-zero on missing input.
+- `edit-image.py` — deterministic pixel-level evidence editing (2026-09-15, Pillow): `crop --region x,y,w,h` (pixel-exact, rejects out-of-bounds), `zoom --factor <f> [--center x,y]` (nearest-neighbor, returns to source frame size), `label --text <caption>` (caption bar), `nup --cols <n> --in <a.png> --in <b.png> [--labels "a|b"]` (side-by-side grid). Byte-deterministic PNG output; no network, no time, no randomness. Derivatives supplement raw frames — the source frame stays archived.
+- `render-html.js` — deterministic HTML evidence composition (2026-09-15, headless Chromium): renders a local HTML layout to PNG (fixed viewport width, device scale 1, full-page screenshot). Hermetic: remote HTTP(S) assets are blocked and fail the render loudly; relative image paths resolve against the HTML file; local/system fonts only. Exit 3 reports NOT POSSIBLE when Chromium is unavailable. The composition layer above edit-image.py's pixel layer.
+- `see-act.js` — single-step browser driver for experiential QA (2026-09-14): one browser action per invocation (`aria`, `shot`, `click`, `scroll`, `type`), one JSON line on stdout, exit 0/2/3 (3 = NOT POSSIBLE: missing playwright-core or Chromium). Spawns its own loopback forward proxy on an ephemeral port (Chromium blocks direct loopback). The QA work agent closes the OODA loop: run a step, read the screenshot/aria, decide the next. Determinism: no wall-clock reads, no randomness. `SEE_ACT_ARCHIVE_DIR=<phase-dir>` (2026-09-14): every screenshot is archived automatically as `001-shot-desktop.png`, `002-click-mobile.png`, ... (counter in `<dir>/.seq`); `--out` becomes optional; JSON carries `screenshot` + `archived`; explicit `--out` + archive copies into the archive; unusable dir is NOT POSSIBLE exit 3.
+- `append-ooda-step.js` — deterministic writer for the OODA report log (2026-09-14, attempt identity 2026-09-15): `node append-ooda-step.js --log <path> --attempt <id> --step <n> --action <a> --exit <code> [--args <json>] [--screenshot <path>] [--observation <text>]` appends one JSON line to `<phase-dir>/ooda-log.jsonl` (`{step, attempt, action, args, exit, screenshot|null, observation}`). `--attempt` is required; steps must be strictly monotonic within an attempt (a rerun is a new attempt at step 1 — attempts accumulate, never overwrite). Actions: browser (`aria|shot|click|scroll|type`) and image (`crop|zoom|label|nup|compose` — the last five log evidence derivatives made with `lib/edit-image.py` / `lib/render-html.js`; frame-producing actions require `--screenshot`). Corrupt logs or sequence gaps fail loudly (exit 2). No wall-clock reads, no randomness.
+- `write-ooda-verdict.js` — deterministic writer for the OODA terminal verdict (2026-09-14, append-only ledger 2026-09-15): `node write-ooda-verdict.js --dir <phase-dir> --attempt <id> --verdict <PASS|FAIL|NOT_POSSIBLE> --summary <text> --expected <text> --actual <text> --missing <json-array>` writes `<phase-dir>/verdict.json` (the latest verdict) and appends one JSON line to `<phase-dir>/verdicts.jsonl` — the append-only ledger: every attempt's verdict is preserved with a mechanical `seq`, never overwritten; corrupt or non-contiguous ledgers fail loudly. Exit 2 on bad input. See `docs/ooda-report.md`.
+- `serve-artifact.js` — local server for a built TS space for experiential QA (2026-09-14): serves `<space-dir>/client/dist` statically and dispatches POST `*/actions` to the compiled server actions with a locally-built Ctx. Prints `READY port=<n>` then serves until killed. Read-only w.r.t. the space directory. Fidelity: the served client and action handlers are the artifact's own built code; the Ctx is locally built (privileged handlers run from the space's own `server/dist/privileged.js` when present; blobs are stored in a per-run temp dir and served back at `/__blobs/<key>`); environment is inherited from the caller. It is not the hosted runtime — tasks that cannot be judged under it must report `NOT POSSIBLE: <reason>`.

package/lib/append-ooda-step.js

@@ -0,0 +1,167 @@
+// append-ooda-step.js — deterministic writer for the OODA report log.
+//
+// The QA/repro agent runs the see-act loop itself; after each step it logs
+// what it did and what it observed. This script owns the schema so the agent
+// never hand-writes JSON: it supplies the fields as flags, the script
+// validates and appends one JSON line.
+//
+// Usage:
+//   node append-ooda-step.js --log <path> --attempt <id> --step <n>
+//     --action <a> --exit <code>
+//     [--args <json>] [--screenshot <path>] [--observation <text>] [--ts <iso>]
+//
+// --attempt is the attempt/run identity (e.g. "1", "2" for successive QA
+// loops; "repro-1" for a reproduce run). Steps are strictly monotonic PER
+// ATTEMPT: the first step of an attempt is 1 and each following step is
+// exactly previous+1. Retries never overwrite — they start a new attempt,
+// so the log preserves every attempt's full sequence. A step that is not
+// exactly previous+1 fails loudly (exit 2) and is not appended.
+//
+// Actions: aria, shot, click, scroll, type (see-act driver) plus the image
+// tools: crop, zoom, label, nup (edit-image.py) and compose (render-html.js).
+// Every action that produces a frame must carry --screenshot; a captured
+// frame that is not logged is invisible to everyone after the agent.
+//
+// The log is <phase-dir>/ooda-log.jsonl, one object per line:
+//   {step, attempt, action, args, exit, screenshot|null, observation, ts?}
+// Together with the archived screenshots and verdicts.jsonl, the log is the
+// task's OODA report — the complete experiential record of the session.
+//
+// Exit 0 on success, 2 on bad input. Determinism: no wall-clock reads, no
+// randomness; ts comes only from --ts (the agent's own clock) and is omitted
+// when not passed.
+"use strict";
+
+const { appendFileSync, mkdirSync, readFileSync, existsSync } = require("node:fs");
+const { dirname, resolve } = require("node:path");
+
+const ACTIONS = {
+  aria: 1, shot: 1, click: 1, scroll: 1, type: 1,
+  crop: 1, zoom: 1, label: 1, nup: 1, compose: 1,
+};
+
+// Actions that produce a frame the agent must have looked at.
+const FRAME_ACTIONS = { shot: 1, crop: 1, zoom: 1, label: 1, nup: 1, compose: 1 };
+
+function fail(msg) {
+  process.stdout.write(JSON.stringify({ ok: false, error: msg }) + "\n");
+  process.exit(2);
+}
+
+function parseArgs(argv) {
+  const out = {};
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === "--log") out.log = argv[++i];
+    else if (a === "--attempt") out.attempt = argv[++i];
+    else if (a === "--step") out.step = argv[++i];
+    else if (a === "--action") out.action = argv[++i];
+    else if (a === "--exit") out.exit = argv[++i];
+    else if (a === "--args") out.args = argv[++i];
+    else if (a === "--screenshot") out.screenshot = argv[++i];
+    else if (a === "--observation") out.observation = argv[++i];
+    else if (a === "--ts") out.ts = argv[++i];
+    else fail("unknown flag: " + a);
+  }
+  return out;
+}
+
+// Read the existing log's max step for this attempt. Malformed lines fail
+// loudly — a corrupt log is evidence of a broken run, not something to skip.
+function maxStepForAttempt(logPath, attempt) {
+  if (!existsSync(logPath)) return 0;
+  const raw = readFileSync(logPath, "utf8");
+  let max = 0;
+  let seen = false;
+  for (const line of raw.split("\n")) {
+    if (!line.trim()) continue;
+    let entry;
+    try {
+      entry = JSON.parse(line);
+    } catch (e) {
+      fail("existing log is corrupt (unparseable line): " + logPath);
+    }
+    if (entry && entry.attempt === attempt) {
+      seen = true;
+      if (!Number.isInteger(entry.step) || entry.step < 1) {
+        fail("existing log is corrupt (bad step for attempt " + attempt + "): " + logPath);
+      }
+      if (entry.step > max) max = entry.step;
+    }
+  }
+  // An attempt with entries must have a contiguous 1..max sequence; a gap
+  // means the log was hand-edited or a step was lost — fail loudly.
+  if (seen) {
+    const steps = new Set();
+    for (const line of raw.split("\n")) {
+      if (!line.trim()) continue;
+      const entry = JSON.parse(line);
+      if (entry && entry.attempt === attempt) steps.add(entry.step);
+    }
+    for (let n = 1; n <= max; n++) {
+      if (!steps.has(n)) fail("existing log has a gap at step " + n + " for attempt " + attempt + ": " + logPath);
+    }
+  }
+  return max;
+}
+
+function main() {
+  const args = parseArgs(process.argv.slice(2));
+  if (!args.log) fail("missing --log <path>");
+  if (args.attempt === undefined || String(args.attempt).trim() === "") {
+    fail("missing --attempt <id> (the attempt/run identity, e.g. \"1\", \"2\", \"repro-1\")");
+  }
+  if (args.step === undefined) fail("missing --step <n>");
+  if (!args.action) fail("missing --action <aria|shot|click|scroll|type|crop|zoom|label|nup|compose>");
+  if (args.exit === undefined) fail("missing --exit <code>");
+
+  const attempt = String(args.attempt).trim();
+  const step = parseInt(args.step, 10);
+  if (!Number.isFinite(step) || step < 1 || String(step) !== String(args.step).trim()) {
+    fail("--step must be a positive integer, got: " + args.step);
+  }
+  if (!ACTIONS[args.action]) fail("unknown --action: " + args.action);
+  const exit = parseInt(args.exit, 10);
+  if (!Number.isFinite(exit)) fail("--exit must be an integer, got: " + args.exit);
+
+  let parsedArgs = {};
+  if (args.args !== undefined) {
+    try {
+      parsedArgs = JSON.parse(args.args);
+    } catch (e) {
+      fail("--args must be valid JSON: " + e.message);
+    }
+    if (parsedArgs === null || typeof parsedArgs !== "object" || Array.isArray(parsedArgs)) {
+      fail("--args must be a JSON object");
+    }
+  }
+
+  if (FRAME_ACTIONS[args.action] && !args.screenshot) {
+    fail("--action " + args.action + " produces a frame: --screenshot is required (log the frame you looked at)");
+  }
+
+  const logPath = resolve(args.log);
+  mkdirSync(dirname(logPath), { recursive: true });
+
+  const expected = maxStepForAttempt(logPath, attempt) + 1;
+  if (step !== expected) {
+    fail("--step must be exactly previous+1 for attempt \"" + attempt + "\": expected " + expected + ", got " + step +
+      " (retries start a NEW --attempt; they never renumber or overwrite)");
+  }
+
+  const entry = {
+    step: step,
+    attempt: attempt,
+    action: args.action,
+    args: parsedArgs,
+    exit: exit,
+    screenshot: args.screenshot ? resolve(args.screenshot) : null,
+    observation: args.observation || "",
+  };
+  if (args.ts) entry.ts = args.ts;
+
+  appendFileSync(logPath, JSON.stringify(entry) + "\n");
+  process.stdout.write(JSON.stringify({ ok: true, log: logPath, attempt: attempt, step: step }) + "\n");
+}
+
+main();

package/lib/build-readback-request.js

@@ -0,0 +1,130 @@
+#!/usr/bin/env node
+// build-readback-request.js — deterministic builder for the parent publish
+// content read-back inspection request.
+//
+// The parent (tick worker) never hand-writes the inspection prompt: this
+// script builds the EXACT request from the merge commit's diff, so the
+// read-back asks about the real expected change, not an LLM's paraphrase.
+// Output is JSON on stdout: { verbatim_request }.
+//
+// Usage:
+//   node build-readback-request.js --repo-path <path> --commit <sha>
+//       --base <sha> --task-id <uuid> --slug <artifact-slug>
+//       [--build-agent-id <uuid>]
+//
+// --base is the previously-stamped provenance source_commit (the tree the
+// last verification certified), or the empty-tree sha
+// 4b825dc642cb6eb9a060e54bf8d69288fbee4904 for a first publish with no
+// prior stamp. It is REQUIRED because the merge commit's first parent is
+// NOT necessarily the previously-published tree: push-time reconcile
+// merges (2026-09-14, task 0c53af4e) put the task's own changes behind an
+// intermediate merge, so `commit^1..commit` covers only the reconcile
+// delta and the request would certify content it never checked.
+//
+// Exit codes: 0 ok · 2 usage/validation · 1 git/diff failure.
+
+import { execFileSync } from "node:child_process";
+
+const EMPTY_TREE = "4b825dc642cb6eb9a060e54bf8d69288fbee4904";
+
+function arg(name) {
+  const i = process.argv.indexOf(name);
+  if (i < 0 || i + 1 >= process.argv.length) {
+    process.stderr.write(JSON.stringify({ ok: false, error: "usage", message: `${name} is required.` }) + "\n");
+    process.exit(2);
+  }
+  return process.argv[i + 1];
+}
+
+const repoPath = arg("--repo-path");
+const commit = arg("--commit");
+const base = arg("--base");
+const taskId = arg("--task-id");
+const slug = arg("--slug");
+const buildAgentId = process.argv.includes("--build-agent-id")
+  ? arg("--build-agent-id") : null;
+
+if (!/^[0-9a-f]{40}$/.test(commit)) {
+  process.stderr.write(JSON.stringify({ ok: false, error: "usage", message: "commit must be a 40-char hex sha." }) + "\n");
+  process.exit(2);
+}
+if (!/^[0-9a-f]{40}$/.test(base)) {
+  process.stderr.write(JSON.stringify({ ok: false, error: "usage", message: "base must be a 40-char hex sha." }) + "\n");
+  process.exit(2);
+}
+// The publish delta is base..commit. Refuse a base that is not an ancestor:
+// certifying a diff against an unrelated tree is worse than no request.
+if (base !== EMPTY_TREE) {
+  try {
+    execFileSync("git", ["-C", repoPath, "merge-base", "--is-ancestor", base, commit], { stdio: "ignore" });
+  } catch (e) {
+    process.stderr.write(JSON.stringify({ ok: false, error: "usage", message: `base ${base} is not an ancestor of commit ${commit} — refusing to build a request that could certify an unrelated tree.` }) + "\n");
+    process.exit(2);
+  }
+}
+
+let diff;
+try {
+  diff = execFileSync("git", ["-C", repoPath, "diff", base, commit, "--"], {
+    encoding: "utf8", maxBuffer: 4 * 1024 * 1024,
+  });
+} catch (e) {
+  process.stderr.write(JSON.stringify({ ok: false, error: "git", message: `git diff failed: ${e.message}` }) + "\n");
+  process.exit(1);
+}
+if (!diff.trim()) {
+  process.stderr.write(JSON.stringify({ ok: false, error: "git", message: "empty diff for commit." }) + "\n");
+  process.exit(1);
+}
+
+// Parse the diff into per-file added/removed lines (the contract the
+// verifier will check the inspector's findings against).
+const files = [];
+let current = null;
+for (const line of diff.split("\n")) {
+  if (line.startsWith("diff --git")) {
+    const m = line.match(/^diff --git a\/(.+) b\/(.+)$/);
+    current = { path: m ? m[2] : "unknown", added: [], removed: [] };
+    files.push(current);
+  } else if (current && line.startsWith("+") && !line.startsWith("+++")) {
+    current.added.push(line.slice(1));
+  } else if (current && line.startsWith("-") && !line.startsWith("---")) {
+    current.removed.push(line.slice(1));
+  }
+}
+
+const buildIdLine = buildAgentId
+  ? `Expected builder build agent_id: ${buildAgentId} (the artifact system's in-flight correlation ID for this publish attempt — not a durable post-completion identifier).\nReport the live build's agent_id as seen in artifact_status (or state explicitly that no build/agent_id is visible). If an expected agent_id is given above and the live one differs, say so exactly — the read-back may be inspecting a different build's output.\n\n`
+  : "";
+
+const verbatim_request =
+`Publish content read-back for task ${taskId}, merge commit ${commit}.
+Expected change: the publish delta ${base}..${commit} (base = previously-stamped source commit, or the empty tree for a first publish).
+The unified diff below was supposed to be applied to this artifact's source tree and deployed. Do NOT modify anything.
+Do NOT rely on the builder's applied-changes report — it is derived from this same diff, so it cannot confirm the content. Read the artifact's CURRENT source directly.
+
+${buildIdLine}UNIFIED DIFF (expected change):
+\`\`\`diff
+${diff}\`\`\`
+
+For each file in the diff:
+1. Read the file's CURRENT content in the artifact source tree.
+2. Quote the exact current text of the regions around the changed lines.
+3. For every added (+) line in the diff, state whether that exact line is PRESENT in the current source.
+4. For every removed (-) line in the diff, state whether that exact line is ABSENT from the current source.
+5. Report build/deploy health and the console error count.
+
+MACHINE-READABLE FINDINGS (REQUIRED — the parent parses this block mechanically; if it is missing or malformed the verification FAILS CLOSED as blocked):
+For each file, emit exactly these lines, one per changed line, with the verdict at the end of the line:
+FILE: <path>
+ADDED: <exact added line from the diff> :: PRESENT
+ADDED: <exact added line from the diff> :: ABSENT
+REMOVED: <exact removed line from the diff> :: PRESENT
+REMOVED: <exact removed line from the diff> :: ABSENT
+END_FILE
+Emit one ADDED line per (+) diff line and one REMOVED line per (-) diff line — no more, no fewer. The verdict is PRESENT if that exact line occurs in the file's current source, ABSENT otherwise.
+
+Return the per-file present/absent findings with the quoted observed lines. Do not modify anything.
+This read-back feeds the parent content-verification protocol (docs/publish-verification.md): the parent stamps provenance only when every added line is present and every removed line is absent.`;
+
+process.stdout.write(JSON.stringify({ verbatim_request, files_changed: files.map((f) => f.path) }, null, 2) + "\n");

package/lib/compose-evidence-caption.js

@@ -0,0 +1,141 @@
+#!/usr/bin/env node
+// lib/compose-evidence-caption.js — deterministic QA-evidence caption composer.
+//
+// Screenshots delivered to chat can arrive out of context: the tick worker
+// delivers them on its own cadence, detached from the run that produced them.
+// This script builds the transition Eric asked for (2026-09-14): acknowledge
+// the out-of-context arrival, state the problem the task addressed and the
+// solution shipped, then hand off to the desktop/mobile attachments the
+// caller appends AFTER this caption. Deterministic: every line is extracted
+// mechanically from the Crew API, the task's events, and the merge commit —
+// no LLM prose. The caller (seed/cron-body-template.md Step 6) prints this
+// caption verbatim, then the two attachment lines, then logs delivery.
+//
+// Usage:
+//   node lib/compose-evidence-caption.js --crew-home <home> \
+//     --task-id <id> --audit-dir <resolved-dir-name>
+//
+// Prints the caption to stdout. Exits non-zero on any missing input.
+
+const { execFileSync } = require("node:child_process");
+const path = require("node:path");
+
+function usage(msg) {
+  process.stderr.write("compose-evidence-caption: " + msg + "\n");
+  process.exit(1);
+}
+
+const argv = process.argv.slice(2);
+const args = {};
+for (let i = 0; i < argv.length; i++) {
+  if (argv[i].startsWith("--")) {
+    const k = argv[i].slice(2).replace(/-/g, "_");
+    args[k] = (argv[i + 1] && !argv[i + 1].startsWith("--")) ? argv[++i] : true;
+  }
+}
+const crewHome = args.crew_home;
+const taskId = args.task_id;
+const auditDir = args.audit_dir;
+if (!crewHome) usage("--crew-home is required");
+if (!taskId) usage("--task-id is required");
+if (!auditDir) usage("--audit-dir is required");
+
+const CLI = path.join(__dirname, "crew-api.js");
+
+function api(command, payload) {
+  const out = execFileSync("node", [CLI, "--crew-home", crewHome, command, "--json", JSON.stringify(payload)], {
+    encoding: "utf8", stdio: ["ignore", "pipe", "pipe"],
+  });
+  return JSON.parse(out);
+}
+
+function gitSubject(repoPath, commit) {
+  try {
+    return execFileSync("git", ["-C", repoPath, "log", "-1", "--format=%s", commit], {
+      encoding: "utf8", stdio: ["ignore", "pipe", "pipe"], timeout: 15000,
+    }).trim();
+  } catch {
+    return "";
+  }
+}
+
+function trimWords(s, max) {
+  s = (s || "").replace(/\s+/g, " ").trim();
+  if (s.length <= max) return s;
+  const cut = s.slice(0, max - 1);
+  const at = cut.lastIndexOf(" ");
+  return (at > 0 ? cut.slice(0, at) : cut) + "…";
+}
+
+let state;
+try {
+  state = api("get-state", {});
+} catch (e) {
+  usage("cannot read crew state: " + (e.message || e));
+}
+const task = (state.tasks || []).find((t) => t.id === taskId);
+if (!task) usage("task " + taskId + " not found");
+
+let events = [];
+try {
+  events = api("get-events", { task_id: taskId, limit: 100 }).events || [];
+} catch (e) {
+  usage("cannot read task events: " + (e.message || e));
+}
+const notes = events.filter((e) => e.type === "note");
+
+// QA verdict: the workflow's own exact-prefix contract — the latest note
+// whose message starts exactly "visual_verdict: PASS" / "visual_verdict: FAIL".
+const verdictNote = [...notes].reverse()
+  .find((e) => /^visual_verdict:\s*(PASS|FAIL)/.test(e.message || ""));
+const verdict = verdictNote
+  ? verdictNote.message.replace(/^visual_verdict:\s*/, "").trim()
+  : null;
+
+// Provenance: this task's own `publish: verified` event first; the global
+// provenance record only when it belongs to this task.
+let commit = null;
+const verifiedNote = [...notes].reverse()
+  .find((e) => (e.message || "").includes("publish: verified"));
+if (verifiedNote) {
+  const m = /\b([0-9a-f]{40})\b/.exec(verifiedNote.message);
+  if (m) commit = m[1];
+}
+if (!commit) {
+  try {
+    const prov = api("get-provenance", {}).provenance;
+    if (prov && prov.task_id === taskId && /^[0-9a-f]{40}$/.test(prov.source_commit || "")) {
+      commit = prov.source_commit;
+    }
+  } catch {
+    // best-effort; absence is reported honestly below
+  }
+}
+
+// The solution shipped: the merge commit's subject line; fall back to the
+// task title when the commit is unknown or unreadable.
+let solution = "";
+if (commit) {
+  const proj = (state.projects || []).find((p) => p.id === task.project);
+  if (proj && proj.repo_path) solution = gitSubject(proj.repo_path, commit);
+}
+if (!solution) solution = task.title;
+
+const problem = trimWords(task.description || task.title, 280);
+// The task's own run record is authoritative for the honest label: a
+// `baseline: none` note means QA ran without the visual protocol.
+const visualUnavailable = notes.some((e) => /baseline:\s*none/i.test(e.message || ""));
+
+const lines = [];
+lines.push("These screenshots are dropping in out of context — quick transition.");
+lines.push("");
+lines.push("**" + task.title + "**");
+lines.push("Problem: " + problem);
+lines.push("Shipped: " + trimWords(solution, 160) +
+  (commit ? " (commit `" + commit.slice(0, 12) + "`, parent-verified)" : " (provenance not yet stamped)"));
+lines.push("Evidence: desktop + mobile captures below, taken by the platform audit harness after deploy (`" + auditDir + "`)." +
+  (verdict ? " QA verdict: " + trimWords(verdict, 200) + "." : " No QA verdict recorded."));
+if (visualUnavailable) {
+  lines.push("Note: the visual protocol is unavailable — these are the post-deploy capture plus QA's mechanical checks, not a QA visual inspection.");
+}
+process.stdout.write(lines.join("\n") + "\n");