muse-crew 0.7.10 → 0.7.12

package/lib/AGENTS.md

@@ -14,3 +14,11 @@ 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> [--reason <text>]` 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. `--reason` is REQUIRED and must be non-empty for `FAIL` and `NOT_POSSIBLE` — a reason-less negative verdict fails with exit 2 before anything is written (2026-09-15). Exit 2 on bad input. See `docs/ooda-report.md`.
+- `read-ooda-verdict.js` — deterministic cross-checker for the OODA terminal verdict (2026-09-15): `node read-ooda-verdict.js --dir <phase-dir> --expect <PASS|FAIL>` reads `<dir>/verdict.json`, prints one JSON line to stdout, exits 0 with `{ok:true, verdict, reason, summary, expected, actual, attempt}` when the record agrees with the prose expectation and a FAIL carries a non-empty reason, or exits 2 with `{ok:false, code}` — `missing|corrupt|contradiction|no_reason`. No wall-clock reads, no randomness. The bugfix QA closeout runs it against the prose `VERDICT:` line before any rework routing: a failed cross-check records the phase as failed for retry, never routes to rework.
+- `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");