muse-crew 0.17.2 → 0.17.3

package/lib/bugfix/phases/qa.js

@@ -0,0 +1,356 @@
+// lib/bugfix/phases/qa.js — Bugfix QA phase (worker layer).
+//
+// Hazel does final QA, code-blind. Derived from workflows/bugfix.js (the
+// Bugfix QA step).
+//
+// Contract:
+//   - Read: task description; prior phase events (context); experiential
+//     flag (from Triage); Build's release decision (for the npm publish
+//     backstop); Triage's terminal_targets (terminal QA).
+//   - qaArtifact/qaTerminal branch the instructions (experiential see-act
+//     vs CLI loops vs state verification).
+//   - Verdict gate (experiential only): read-ooda-verdict.js cross-checks
+//     the prose VERDICT: line against verdict.json. Disagreement, missing,
+//     corrupt, or reason-less FAIL → record "failed", return FAILED
+//     (dispatcher retry — never rework routing).
+//   - Experiential loop unavailable on PASS → park fail-closed (a PASS
+//     without experiential evidence is never terminal).
+//   - CONTENT-FINDINGS block: machine-read at closeout; each finding
+//     classified against the publish diff file set. task-change → file a
+//     bugfix; otherwise record with attribution. Missing/malformed block →
+//     record "failed", return FAILED (fail-closed, never "no findings").
+//   - QA rejection → shared Review/QA budget (spec.reworkPhases). Exhausted
+//     → park (worktree preserved). Otherwise REWIND to Build.
+//   - QA PASS → ADVANCE with next:null (driver closeout marks the task done).
+//
+// Phase I/O contract (Phase D):
+//   read:  task description, events, experiential flag, Build release
+//          decision, Triage terminal_targets, verdict.json, publish diff
+//   write: session (completed | rejected | failed), event, park row,
+//          follow-up tasks (content findings)
+//   out:   ADVANCE (next:null → done) | REWIND → Build | PARK | FAILED |
+//          NEED_SPAWN / STANDBY (boundary)
+
+import {
+  runWorkBoundary, recordPhase, buildEventPreamble, summarizeReport,
+  ensureClaimed, log, latestSessionNotes, crewApi, runCmd,
+  parkTask, logEvent,
+} from "../../workflow-lib.js";
+import { readFileSync } from "fs";
+import {
+  extractReleaseDecision, extractVerdict, extractContentFindings,
+  classifyContentFinding,
+} from "../../extract.js";
+
+export const PHASE = { name: "QA", identity: "hazel" };
+
+var MAX_REWORK = 2;
+
+// buildInstructions — verbatim from workflows/bugfix.js (variable
+// references remapped; logic and prose unchanged).
+// ctx: { env, taskDesc, phaseCtx, hazelPhaseCtx }.
+export function buildInstructions(ctx) {
+  var env = ctx.env;
+    // Backstop for merge-time versioning: when the accepted Build summary
+    // declared release: yes, QA verifies the registry actually moved. A silent
+    // publish skip becomes a loud QA failure with evidence, not a pass.
+    var npmPublishCheck = (env.publishType === "npm" && ctx.releaseDecision && ctx.releaseDecision.release === "yes")
+      ? "NPM PUBLISH CHECK: the accepted Build report declared release: yes, so this run's Publish phase must have published — UNLESS it was skipped deterministically on an empty-diff Integrate. Find this task's recorded Publish result: run in shell and return the stdout verbatim:\n" + crewCmdString(env, "get-state", { events_limit: 1 }) + "\n, then find the session for this task_id with step \"Publish\" (status completed) in the returned sessions array and read its session notes (the Publish agent's summary — event history does NOT carry it).\n" +
+      "CHECK THE SKIP PATH FIRST: if the notes contain a line matching skipped: no-lock-held, Publish was skipped deterministically — Integrate reported MERGED_EMPTY (no commits ahead of the integration target), so no merge lock was taken and there was nothing to ship. Verify the notes contain that skip-marker line and do NOT contain a line matching published: muse-crew@. Do NOT run npm view and do NOT demand registry movement — nothing was supposed to ship. Report 'npm publish check: Publish skipped deterministically (empty-diff Integrate — nothing to ship)' and PASS this check.\n" +
+      "Only when the notes contain no skip marker must the publish have landed — run the full verification below.\n" +
+      "Extract the line matching TARGET_VERSION=<new-version> computed as <base> + <scope> → <new-version> (the workflow appends it to the Publish notes, so it is always present). If the line is missing, report 'npm publish verification failed: Publish notes did not carry the computed target version', then end your report with exactly this line: VERDICT: FAIL.\n" +
+      "Verify the bump SCOPE: the <scope> in that line MUST equal the accepted version_bump scope \"" + ctx.releaseDecision.version_bump + "\" — if it differs, report the mismatch, then end your report with exactly this line: VERDICT: FAIL. Verify the ARITHMETIC: <base> + <scope> must equal <new-version> (patch increments the last segment only, e.g. 0.3.0 + patch → 0.3.1; minor increments the middle and resets the last to 0; major increments the first and resets the rest to 0) — if the math is wrong, report it, then end your report with exactly this line: VERDICT: FAIL.\n" +
+      "Extract the published version from the notes line matching published: muse-crew@<version>. It MUST equal <new-version> from the TARGET_VERSION line. Then run: npm view muse-crew version. The registry version MUST equal <new-version>. If any of these checks fails, report 'npm publish verification failed: [details]', then end your report with exactly this line: VERDICT: FAIL.\n"
+      : "";
+    var instructions = "Final QA testing. You are CODE-BLIND — do NOT read source code.\n" +
+      "Public docs (API.md, README, published action schemas) are NOT source code — read them freely, exactly as a user would.\n" +
+      "DOCS GATE: If the fix is public-affecting (it alters anything a user or consumer can observe: API actions, parameters, behavior, or errors), verify the public docs describe it. If public docs are missing or stale, report 'public docs missing/stale for [the change]', then end your report with exactly this line: VERDICT: FAIL. QA always fails when public-affecting changes lack public docs. Guide/tutorial gaps are lower priority — file a follow-up task for those instead of failing.\n" +
+      "To test, run in shell and read the stdout JSON:\n" + crewCmdString(env, "get-state", {}) + "\nThis returns current sessions, events, and tasks.\n" +
+      "Verify the fix against the task description in the returned data: the state the bug corrupted should now read correctly, and the task's own expected behavior should hold.\n" +
+      "You can also check specific data with: node " + env.crewApi + " --crew-home " + env.crewHome + " get-events --json '{\"task_id\":\"<the task id>\"}'.\n" +
+      "Do NOT use artifact_inspect — it was removed by the platform (2026-09-14) and does not exist; do not substitute artifact.inspect (malfunction diagnosis, not an inspection tool).\n" +
+      "File follow-up tasks by running in shell (EXCEPT content findings — user-visible content/data goes in the CONTENT-FINDINGS block at the end of these instructions, never through create-task):\n" + crewCmdString(env, "create-task", { title: "<short title>", description: "<details>", project: "<project id>", workflow: "bugfix", filed_by: "hazel" }) + "\n(substitute the real values for the placeholders).\n" +
+      npmPublishCheck +
+      "Report your test results as plain prose.\n" +
+      "End your report with exactly one line: VERDICT: PASS if testing passes, VERDICT: FAIL if it fails.";
+    // ctx.qaArtifact: Hazel runs the experiential see-act loop herself (STEP 1
+    // below) and owns the visual verdict — no parent capture protocol.
+    if (ctx.qaArtifact) {
+      instructions = "Read the shared UX bar FIRST: " + env.uxDoctrinePath + " — it is the bar the whole crew builds to, and your verdict judges against it point by point.\n\n" +
+        "You are code-blind QA. You NEVER read source files. Public docs are not source — read them as a user would.\n" +
+        "STEP 1: Experiential visual inspection — drive the fixed artifact as a user would, one browser step at a time, and verify the reported bug is actually fixed.\n" +
+        "You have a see-act driver: " + env.crewHome + "/current/lib/see-act.js (a node script; one browser action per invocation; it prints one JSON line to stdout). It launches its own Chromium through a self-contained loopback proxy — the ONLY url you may give it is the local artifact server you start below. Never point it at any other URL.\n" +
+        "SESSION PROTOCOL (multi-step flows): one-shot invocations launch a fresh browser each time, so they cannot drive flows where a later step needs an earlier step's living page state (open a dialog, then confirm it — the second step needs the first step's page state). For those, hold ONE browser alive: node " + env.crewHome + "/current/lib/see-act.js session-start --name qa --url http://localhost:<N>/ --log " + env.crewHome + "/task-evidence/" + env.taskId + "/postchange/ooda-log.jsonl — launches Chromium once in a detached daemon (its control server binds 127.0.0.1 only; the daemon exits after 10 min with no act). The --log path is the SAME ooda-log.jsonl the QA guard reads: every session-act appends its own JSON line in the exact step schema (step, attempt, action, args, exit, screenshot, observation), so you do NOT call append-ooda-step.js for session acts — READ each act's JSON result (the screenshot field is the path to READ with your read tool) and decide the next action. Then drive it: node " + env.crewHome + "/current/lib/see-act.js session-act --name qa --attempt \"1\" <aria|shot|click|scroll|type> [args] — one action inside the living page. Prefix EVERY session-act invocation with SEE_ACT_ARCHIVE_DIR=" + env.crewHome + "/task-evidence/" + env.taskId + "/postchange/ (shell env vars do not persist between your commands, so prefix each one). When done: node " + env.crewHome + "/current/lib/see-act.js session-end --name qa — closes the browser, prints the session summary, and keeps the session dir as evidence. If session-start exits 3 with a \"NOT POSSIBLE: <reason>\" string, the environment cannot drive a browser: report NOT POSSIBLE: <reason> and continue with the mechanical checks — your VERDICT then covers mechanical checks only.\n" +
+        "Actions: aria | shot [--out <png>] [--full] | click [--out <png>] --selector <css> | scroll [--out <png>] --y <pixels|bottom> | type [--out <png>] --selector <css> --text <text>. Add --viewport mobile for a 390x844 frame. The JSON reports console_errors — treat any as a defect signal. Exit code 3 with not_possible set (a \"NOT POSSIBLE: <reason>\" string) means this environment cannot drive a browser: report NOT POSSIBLE: <reason> and continue with the mechanical checks — your VERDICT then covers mechanical checks only.\n" +
+        "a. Verify the built artifact exists: test -d ~/workspace/ts-spaces/" + env.publishSlug + "/client/dist && test -f ~/workspace/ts-spaces/" + env.publishSlug + "/server/dist/actions.js — if either is missing, report NOT POSSIBLE: built artifact not present at ~/workspace/ts-spaces/" + env.publishSlug + " and continue with the mechanical checks.\n" +
+        "b. Start the local artifact server detached with a log file, then poll the log for readiness (single shell invocation): CREW_HOME=" + env.crewHome + " setsid nohup node " + env.crewHome + "/current/lib/serve-artifact.js --space-dir ~/workspace/ts-spaces/" + env.publishSlug + " --port 0 --tag " + env.taskId + "-qa > /tmp/qa-server-" + env.taskId + ".log 2>&1 < /dev/null & for i in $(seq 1 30); do grep -q READY /tmp/qa-server-" + env.taskId + ".log && break; sleep 1; done; grep -o 'READY port=[0-9]*' /tmp/qa-server-" + env.taskId + ".log | cut -d= -f2 — the printed number is <N>. If no READY appears, report NOT POSSIBLE: local artifact server did not start (see /tmp/qa-server-" + env.taskId + ".log) and continue with the mechanical checks.\n" +
+        "c. Bounded see-act loop, at most 8 steps: re-run the reproduction steps for the reported bug — does it still occur? Then check the surrounding views for regressions. Prefix EVERY see-act invocation with SEE_ACT_ARCHIVE_DIR=" + env.crewHome + "/task-evidence/" + env.taskId + "/postchange/ (shell env vars do not persist between your commands, so prefix each one) — every screenshot is then archived automatically as 001-shot-desktop.png, 002-click-desktop.png, ..., so no frame can be lost. Omit --out; the JSON's screenshot field is the path to READ with your read tool (you can see images).\n" +
+        "c2. After EVERY one-shot see-act invocation, append it to the OODA report: node " + env.crewHome + "/current/lib/append-ooda-step.js --log " + env.crewHome + "/task-evidence/" + env.taskId + "/postchange/ooda-log.jsonl --attempt \"1\" --step <N> --action <aria|shot|click|scroll|type> --exit <exit-code> --screenshot <screenshot-from-JSON> --observation \"<1-2 sentences: what the frame showed and what you concluded>\" (omit --screenshot for aria). (Session acts are self-logging — session-act already appended its line; for those, READ the result instead of re-logging.) Steps are strictly monotonic: your first step is --step 1, then 2, 3, ... — the script rejects anything else. If you run the loop again (a new idea, after a restart), that run is --attempt \"2\": attempts never overwrite, they accumulate. Your observation is the payload — say what you saw and what it means, not just what you did. A step you ran but did not log is invisible to everyone after you.\n" +
+"c2b. IMAGE TOOLS (when a raw screenshot is not enough evidence): python3 " + env.crewHome + "/current/lib/edit-image.py crop --in <frame.png> --out <crop.png> --region x,y,w,h — pixel-exact crop; zoom --factor <f> --center x,y — pixel-crisp zoom back to the original frame size; label --text \"<caption>\" — caption bar; nup --cols 2 --in <a.png> --in <b.png> --labels \"before|after\" — side-by-side grid. Deterministic, no network. Log each with --action crop|zoom|label|nup, --attempt \"1\", and --screenshot <the derivative you READ>. For rich compositions (before/after with real typography, annotated callouts), write an HTML page and render it: node " + env.crewHome + "/current/lib/render-html.js --in <page.html> --out <composed.png> [--width 1200] — headless Chromium, hermetic (remote assets are blocked and fail the render), deterministic; log with --action compose and --screenshot <the composition you READ>. Derivatives supplement, never replace: keep the source frame archived and name it in --args. READ every derivative you log — an unread image is not evidence.\n" +
+        "c3. Start with: SEE_ACT_ARCHIVE_DIR=" + env.crewHome + "/task-evidence/" + env.taskId + "/postchange/ node " + env.crewHome + "/current/lib/see-act.js --url http://localhost:<N>/ aria — read the JSON, log the step. Then: SEE_ACT_ARCHIVE_DIR=" + env.crewHome + "/task-evidence/" + env.taskId + "/postchange/ node " + env.crewHome + "/current/lib/see-act.js --url http://localhost:<N>/ shot — READ the screenshot, log the step. Act on what you see: click, scroll, type, then re-observe, logging each step. Prefer aria (cheap text) to find controls; screenshot when the view changes and for your final verdict frames (one desktop, one mobile). If a click exits non-zero, do NOT retry the same ref blindly: re-run aria first (refs go stale between invocations), then click the fresh ref exactly once. If it still fails, log the failure and move on — a flaky control is a finding, not a loop.\n" +
+        "d. Reach: with the session protocol, any flow reachable by N in-page actions is drivable — open the dialog, then confirm it, then judge the result. Without a session (one-shot invocations), anything reachable by (navigate, one action) is testable and sequences needing prior in-page state are not — use a session for those. Report NOT POSSIBLE only when the tooling itself fails (session-start exits 3): a flow you could not reach is not NOT POSSIBLE — name the exact step that stopped you in verdict.json's missing evidence and continue with the mechanical checks.\n" +
+        "e. Judge as a user against the task description: is the reported bug fixed AND is nothing else visibly broken? Look for broken layout, overflow, missing or wrong content, stale data, and console errors. Compare against the task's expected behavior, never against source code (you are code-blind). Every frame you captured is already archived under " + env.crewHome + "/task-evidence/" + env.taskId + "/postchange/ and indexed in ooda-log.jsonl. A frame you did not read is not evidence. Loading, error, or blank frames never pass. If you cannot complete the loop, say exactly which steps are missing — unknown is not PASS.\n" +
+        "f. Kill ONLY the server you started: pkill -f 'serve-artifact[.]js.*--tag " + env.taskId + "-qa' — never another task's server. (The [.] keeps pkill from matching its own command line.) Do not leave it running.\n" +
+        "Then continue with the mechanical checks below. Your VERDICT covers both the visual and the mechanical checks.\n\n" +
+        "MECHANICAL CHECKS:\n" +
+        "DOCS GATE: If the fix is public-affecting (it alters anything a user or consumer can observe: API actions, parameters, behavior, or errors), verify the public docs describe it. If public docs are missing or stale, report 'public docs missing/stale for [the change]', then end your report with exactly this line: VERDICT: FAIL. QA always fails when public-affecting changes lack public docs. Guide/tutorial gaps are lower priority — file a follow-up task for those instead of failing.\n" +
+        "To test, run in shell and read the stdout JSON:\n" + crewCmdString(env, "get-state", {}) + "\nThis returns current sessions, events, and tasks.\n" +
+        "Verify the fix against the task description in the returned data: the state the bug corrupted should now read correctly, and the task's own expected behavior should hold.\n" +
+        "You can also check specific data with: node " + env.crewApi + " --crew-home " + env.crewHome + " get-events --json '{\"task_id\":\"<the task id>\"}'.\n" +
+        npmPublishCheck +
+        "File follow-up tasks by running in shell (EXCEPT content findings — user-visible content/data goes in the CONTENT-FINDINGS block at the end of these instructions, never through create-task):\n" + crewCmdString(env, "create-task", { title: "<short title>", description: "<details>", project: "<project id>", workflow: "bugfix", filed_by: "hazel" }) + "\n(substitute the real values for the placeholders).\n\n" +
+        "BASELINE SANITY: in the event history you fetched, the task's note events must contain a message starting with `baseline: captured` or `baseline: none`. If no message starts with either prefix, report 'baseline evidence missing at QA — the Map gate was bypassed', then end your report with exactly this line: VERDICT: FAIL.\n\n" +
+        "Report your test results as plain prose.\n" +
+        "End your report with exactly one line: VERDICT: PASS if testing passes, VERDICT: FAIL if it fails on the visual or the mechanical checks. Checks you could not run are evidence gaps, not silent drops: name every one in --missing — unknown is neither PASS nor FAIL. First ensure the OODA log exists even if you logged zero steps (touch " + env.crewHome + "/task-evidence/" + env.taskId + "/postchange/ooda-log.jsonl — an empty log is honest, an absent one is a broken report). Also write the same verdict machine-readably: node " + env.crewHome + "/current/lib/write-ooda-verdict.js --dir " + env.crewHome + "/task-evidence/" + env.taskId + "/postchange/ --attempt \"1\" --verdict <PASS|FAIL|NOT_POSSIBLE> --summary \"<one line>\" --expected \"<the reported bug, fixed>\" --actual \"<what you observed>\" --missing '[\"honest evidence gap, if any\"]' [--reason \"<why it failed — REQUIRED and non-empty when verdict is FAIL or NOT_POSSIBLE; the script rejects a reason-less negative verdict with exit 2>\"] — this writes verdict.json (the latest verdict) and appends to verdicts.jsonl (the append-only ledger: every attempt's verdict is preserved, never overwritten). A FAIL verdict must carry a machine-readable reason: the workflow closeout cross-checks verdict.json against your prose VERDICT line, and an unreasoned or contradictory verdict fails the phase (never routes to rework).";
+    } else if (ctx.qaTerminal) {
+      // See docs/decisions/qa-reproduce.md#terminal-qa: Hazel drives CLI transcripts for terminal surfaces.
+      var btermEvidence = env.crewHome + "/task-evidence/" + env.taskId + "/postchange";
+      var btermTargetsLine = ctx.terminalTargets || "not declared — derive from --help and the task description";
+      instructions = "You are code-blind QA. You NEVER read source files.\n" +
+        "Public docs (API.md, README) are NOT source code — read them freely, exactly as a user would.\n" +
+        "Read the shared UX bar FIRST: " + env.uxDoctrinePath + " — it is the bar the whole crew builds to, and your verdict judges against it point by point.\n\n" +
+        "STEP 1: Experiential terminal inspection — drive the fixed CLI as a user would, one command at a time, and verify the reported bug is actually fixed.\n" +
+        "a. The CLI under test lives in " + env.repoPath + " (the merged change is on the integration target there). Start like a new user: run --help. You may RUN the CLI; you may never READ its source.\n" +
+        "b. Terminal targets for this task: " + btermTargetsLine + ".\n" +
+        "c. Bounded terminal loop — at most 8 commands. For each target: run it RIGHT (the happy path — the reported bug's scenario first), then run it WRONG on purpose (bad flags, missing args, nonexistent files, empty input, contradictory flags). Error quality is half the grade: every failure must exit non-zero, say what went wrong in plain language, and tell the user the fix. A raw stack trace shown to a user is a defect — file it as one.\n" +
+        "d. Evidence: capture EVERY invocation as a transcript. Run: mkdir -p " + btermEvidence + "\n" +
+        "   For each command: <cmd> > " + btermEvidence + "/<nn>-<short-slug>.txt 2>&1; echo \"exit=$?\" >> " + btermEvidence + "/<nn>-<short-slug>.txt (number them 01, 02, ...). Then READ the transcript before judging it — an unread transcript is not evidence.\n" +
+        "e. Log each step to the OODA log — run in shell, one command per step:\n" +
+        "   node " + env.crewHome + "/current/lib/append-ooda-step.js --log " + btermEvidence + "/ooda-log.jsonl --attempt \"1\" --step <N> --action terminal --exit <code> --transcript " + btermEvidence + "/<nn>-<short-slug>.txt --args '{\"cmd\":\"<the exact command>\"}' --observation \"<1-2 sentences: what the output said and what you concluded>\"\n" +
+        "   Steps are strictly monotonic within an attempt (1, 2, 3, ...). A rerun is a NEW attempt (\"2\", \"3\", ...) — never overwrite attempt 1. If the CLI will not run at all, log the step with --exit 3 and NOT POSSIBLE in the observation — never fabricate a transcript.\n" +
+        "f. Compare against the pre-change baseline transcripts in " + env.crewHome + "/task-evidence/" + env.taskId + "/baseline/ — every finding cites its baseline and post-change transcripts by step number.\n" +
+        "Then continue with the mechanical checks below. Your VERDICT covers both the experiential and the mechanical checks.\n\n" +
+        "STEP 2: Verify data integrity via the crew API.\n" +
+        "Run in shell and return the stdout verbatim:\n" + crewCmdString(env, "get-state", { events_limit: 1 }) + "\n" +
+        "Use the returned tasks, sessions, and events to check the task's data-level effects.\n" +
+        "DOCS GATE: If the change is public-affecting (it alters anything a user or consumer can observe: API actions, parameters, behavior, or errors), verify the public docs describe it. If public docs are missing or stale for a public-affecting change, report 'public docs missing/stale for [the change]', then end your report with exactly this line: VERDICT: FAIL. QA always fails when public-affecting changes lack public docs. Guide/tutorial gaps are lower priority — file a follow-up task for those instead of failing.\n\n" +
+        "STEP 3: File follow-up tasks for any related issues you discover.\n" +
+        "For each issue (EXCEPT content findings — user-visible content/data goes in the CONTENT-FINDINGS block at the end of these instructions, never through create-task), run in shell:\n" +
+        "node " + env.crewApi + " --crew-home " + env.crewHome + " create-task --json '{\"title\": \"<issue title>\", \"description\": \"<issue details>\", \"project\": \"" + env.projectId + "\", \"workflow\": \"bugfix\", \"filed_by\": \"hazel\"}'\n" +
+        "(replace <issue title> and <issue details> with the real values).\n\n" +
+        "BASELINE SANITY: in the event history you fetched, the task's note events must contain a message starting with `baseline: captured` or `baseline: none`. If no message starts with either prefix, report 'baseline evidence missing at QA — the Map gate was bypassed', then end your report with exactly this line: VERDICT: FAIL. When the baseline is terminal transcripts, confirm every terminal target you judged has a baseline transcript: a target with no pre-change transcript is an evidence gap — name it in --missing, never invent the baseline.\n\n" +
+        "Report your test results as plain prose. Checks you could not run are evidence gaps, not silent drops: name every one in --missing — unknown is neither PASS nor FAIL. End your report with exactly one line: VERDICT: PASS if testing passes, VERDICT: FAIL if it fails on the terminal or the mechanical checks. First ensure the OODA log exists even if you logged zero steps (touch " + btermEvidence + "/ooda-log.jsonl — an empty log is honest, an absent one is a broken report). Also write the same verdict machine-readably: node " + env.crewHome + "/current/lib/write-ooda-verdict.js --dir " + btermEvidence + " --attempt \"1\" --verdict <PASS|FAIL|NOT_POSSIBLE> --summary \"<one line>\" --expected \"<the reported bug, fixed>\" --actual \"<what you observed>\" --missing '[\"honest evidence gap, if any\"]' [--reason \"<why it failed — REQUIRED and non-empty when verdict is FAIL or NOT_POSSIBLE; the script rejects a reason-less negative verdict with exit 2>\"] — this writes verdict.json (the latest verdict) and appends to verdicts.jsonl (the append-only ledger: every attempt's verdict is preserved, never overwritten). A FAIL verdict must carry a machine-readable reason: the workflow closeout cross-checks verdict.json against your prose VERDICT line, and an unreasoned or contradictory verdict fails the phase (never routes to rework).";
+    }
+    if (env.publishType === "artifact") {
+      instructions = "PROVENANCE CHECK (this project publishes to a dashboard artifact).\n" +
+        "Provenance is crew-owned state: read it from the Crew API, never from the artifact's own getprovenance action (a different, non-authoritative store).\n" +
+        "Run in shell and return the stdout verbatim:\n" + crewCmdString(env, "get-provenance", { project_id: env.projectId }) + "\n" +
+        "If provenance is null, report 'provenance missing — publish did not stamp source/crew release', then end your report with exactly this line: VERDICT: FAIL.\n" +
+        "Run: cd " + env.repoPath + " && git rev-parse HEAD — call this LIVE_HEAD.\n" +
+        "Run: test -d " + env.crewHome + "/releases/<provenance.crew_release> (substitute the real stamped hash; do not run the literal placeholder). If the directory does not exist, report 'provenance mismatch: crew_release [value from get-provenance] not found in release registry', then end your report with exactly this line: VERDICT: FAIL.\n" +
+        "If provenance.source_commit equals LIVE_HEAD, the source check passes.\n" +
+        "Otherwise the check is NOT failed yet: the parent stamps provenance AFTER post-deploy (docs/publish-verification.md), and post-deploy may commit an artifact-builder staging commit (\"rebuild: <task_id>\"), so LIVE_HEAD may sit ahead of the stamped commit ONLY IF every commit in between is such a rebuild marker. Verify exactly:\n" +
+        "1. Run: cd " + env.repoPath + " && git merge-base --is-ancestor <provenance.source_commit> LIVE_HEAD && echo ANCESTOR_OK (substitute the real stamped hash and LIVE_HEAD; do not run the literal placeholders). If this command fails, report 'provenance mismatch: stamped source_commit is not an ancestor of live HEAD', then end your report with exactly this line: VERDICT: FAIL.\n" +
+        "2. Run: cd " + env.repoPath + " && git log --format=%s <provenance.source_commit>..LIVE_HEAD (substitute real values). Every subject line MUST start with \"rebuild: \". If any line does not, report 'provenance mismatch: live HEAD moved past the stamped commit with non-rebuild source commits: [paste the offending subject lines]', then end your report with exactly this line: VERDICT: FAIL.\n\n" +
+        instructions;
+    }
+    // Room #26 blocker 38 (2026-09-21): content-finding attribution
+    // protocol. Hazel reports user-visible content/data observations in a
+    // machine-readable CONTENT-FINDINGS block; the workflow classifies each
+    // against the task's publish diff and files follow-ups itself — Hazel
+    // never files bugfixes for content findings directly, and
+    // environment-attributable content never fails her verdict alone.
+    var contentFindingsProtocol =
+      "CONTENT FINDINGS (machine-read — room #26 blocker 38): if you observe user-visible content or data that looks wrong, stale, or out of place (decks, cards, rows, text, files in the artifact — anything this task did not obviously produce), report it here — do NOT file a follow-up task for it yourself and do NOT fail your verdict for it alone. Emit exactly one line in this shape, immediately BEFORE your final VERDICT line (the verdict stays the last line of your report):\n" +
+      "CONTENT-FINDINGS: [{\"subject\": \"<repo-relative file path, or the literal live-data for content in the artifact's runtime data stores>\", \"observation\": \"<what you saw, one line>\"}, ...]\n" +
+      "Use subject \"live-data\" for anything you saw in the running artifact (UI content, database rows, uploaded files) — you are code-blind and cannot name its file. Use a repo-relative file path only when you know the content lives in a specific file (e.g. from the task description or public docs). When you saw no such content, emit the empty array: CONTENT-FINDINGS: [].\n" +
+      "The workflow classifies each finding against the task's publish diff: a finding whose subject file is in the diff is attributable to this task's change and the workflow files a bugfix for it; anything else is recorded with its attribution (environment-attributable, or unknown when the diff is unavailable) — the finding itself never spawns an artifact bugfix. No finding is ever dropped for looking like test residue: it is classified by attribution and recorded with it. Your VERDICT judges this task's change; content you cannot attribute to it is not a failure of this task.\n";
+    // The content-findings block is machine-read at closeout (blocker 38).
+    // Hazel emits it immediately before the VERDICT line, so the verdict
+    // keeps its trailing-window contract with extractVerdict.
+    instructions += "\n" + contentFindingsProtocol;
+  return instructions;
+}
+
+export async function runPhase(ctx) {
+  var env = ctx.env, state = ctx.state;
+
+  var claimed = await ensureClaimed(env, state, PHASE);
+  if (claimed.type !== "CLAIMED") return claimed;
+
+  // Experiential dispatch (source: qaExp = resolveExperiential() === "yes").
+  var qaExp = (state.experiential === true);
+  ctx.qaArtifact = qaExp && env.surfaceArtifact;
+  ctx.qaTerminal = qaExp && env.surfaceTerminal;
+  ctx.qaBundleHash = null; // set below when versioned (source parity)
+
+  // Versioned-artifact bundle hash for findings classification (source:
+  // qaBundleHash from the Integrate QA deploy, when versioned_build).
+  if (ctx.qaArtifact && env.versionedBuild === true) {
+    try {
+      var integNotes = await latestSessionNotes(env, "Integrate", "completed");
+      var dm = /^deploy: ok ([0-9a-f]{7})$/m.exec(integNotes || "");
+      ctx.qaBundleHash = dm ? dm[1] : null;
+    } catch (e) { ctx.qaBundleHash = null; }
+  }
+
+  // Build's release decision (npm publish backstop).
+  var buildNotes = await latestSessionNotes(env, "Build", "completed");
+  ctx.releaseDecision = extractReleaseDecision(buildNotes);
+
+  // Triage's terminal_targets (terminal QA).
+  var triageNotes = await latestSessionNotes(env, "Triage", "completed");
+  var ttm = /^terminal_targets:\s*(.+)/im.exec(triageNotes || "");
+  ctx.terminalTargets = ttm ? ttm[1].trim().slice(0, 300) : "";
+
+  ctx.taskDesc = env.taskDescription;
+  // phaseCtx and hazelPhaseCtx: the source builds these from prior events.
+  // The worker layer passes the event preamble (which the boundary injects);
+  // the instruction text references ctx.phaseCtx/ctx.hazelPhaseCtx for the
+  // surface-specific context blocks.
+  ctx.phaseCtx = "";
+  ctx.hazelPhaseCtx = "";
+
+  var boundary = await runWorkBoundary(env, state, {
+    phase: PHASE.name,
+    identity: PHASE.identity,
+    instructions: buildInstructions(ctx),
+    eventPreamble: buildEventPreamble(env, PHASE.name),
+    crewApiLine: true,
+    verdictStep: true,
+  });
+  if (boundary.type !== "BOUNDARY_DONE") return boundary;
+  var workerText = boundary.workerText;
+  var verdictPassed = boundary.verdictPassed === true;
+
+  // QA verdict.json closeout gate (experiential paths only): the prose
+  // VERDICT: line is the routing signal; verdict.json is cross-checked
+  // before any rework routing.
+  if ((ctx.qaArtifact || ctx.qaTerminal) && boundary.verdictPassed !== null) {
+    var qaVerdictDir = env.taskEvidenceDir + "/postchange";
+    var qaVerdictExpect = verdictPassed ? "PASS" : "FAIL";
+    var qaVerdictOut = "";
+    try {
+      var qv = await runCmd(["node", env.crewHome + "/current/lib/read-ooda-verdict.js",
+        "--dir", qaVerdictDir, "--expect", qaVerdictExpect]);
+      qaVerdictOut = String(qv.stdout || "").trim();
+    } catch (e) {
+      qaVerdictOut = "";
+    }
+    var qaVerdictGate = null;
+    try {
+      var qaVerdictLines = qaVerdictOut.split("\n");
+      qaVerdictGate = JSON.parse(qaVerdictLines[qaVerdictLines.length - 1]);
+    } catch (e) {
+      qaVerdictGate = null;
+    }
+    if (!qaVerdictGate || qaVerdictGate.ok !== true) {
+      var qaGateCode = (qaVerdictGate && qaVerdictGate.code) ? qaVerdictGate.code : "unreadable";
+      var qaGateDetail = (qaVerdictGate && qaVerdictGate.error) ? qaVerdictGate.error : (qaVerdictOut ? qaVerdictOut.slice(0, 200) : "cross-checker produced no usable output");
+      log("QA verdict.json closeout gate failed (" + qaGateCode + "): " + qaGateDetail + " — marking QA failed for retry, NOT routing to rework");
+      await recordPhase(env, {
+        task_id: env.taskId,
+        session: {
+          id: state.activeSessionId, task_id: env.taskId, identity: PHASE.identity,
+          step: PHASE.name, status: "failed",
+          notes: "QA verdict.json closeout gate failed (" + qaGateCode + "): " + qaGateDetail + ". The prose VERDICT line said " + qaVerdictExpect + " but verdict.json is missing, corrupt, contradictory, or (for FAIL) carries no machine-readable reason. Unreasoned or contradictory verdicts never route to rework; phase failed for retry",
+        },
+        event: {
+          task_id: env.taskId, type: "failed", identity: PHASE.identity,
+          message: "QA verdict.json closeout gate failed (" + qaGateCode + ") — verdict unreasoned or contradictory, phase failed, dispatcher will retry QA",
+        },
+      });
+      return { type: "FAILED" };
+    }
+    log("QA verdict.json closeout gate passed: verdict.json agrees with prose VERDICT: " + qaVerdictExpect);
+
+    // Experiential loop guard: a PASS with missing experiential evidence
+    // parks fail-closed — never done.
+    var qaLoopSurface = env.surfaceTerminal ? "terminal" : "visual";
+    var qaLoopReason = env.surfaceTerminal ? "qa-terminal-loop-unavailable" : "qa-visual-loop-unavailable";
+    var qaLoopUnavailable = env.surfaceTerminal ? qaVerdictGate.terminal_loop_unavailable : qaVerdictGate.visual_loop_unavailable;
+    if (verdictPassed === true && qaLoopUnavailable === true) {
+      log("QA " + qaLoopSurface + " loop unavailable — parking fail-closed (unattributable_reason=" + qaLoopReason + "), never done");
+      return await parkTask(env, "QA " + qaLoopSurface + " loop unavailable (unattributable_reason=" + qaLoopReason + "): " +
+        (env.surfaceTerminal
+          ? "the terminal loop could not run — the CLI would not execute, and verdict.json records missing terminal evidence. A PASS without experiential evidence is never terminal. Human attention needed: check the project's runtime dependencies at " + env.repoPath + ", then re-queue QA."
+          : "the see-act browser loop could not run — verdict.json records missing visual evidence. A PASS without experiential evidence is never terminal. Human attention needed: repair the crew home's dependency symlink ($CREW_HOME/node_modules) or the npm install, then re-queue QA."));
+    }
+    log("QA " + qaLoopSurface + "-loop guard passed: experiential evidence present");
+  }
+
+  // Content-findings attribution (blocker 38): Hazel's CONTENT-FINDINGS
+  // block is machine-read at closeout; each finding is classified against
+  // the task's publish diff and filed/recorded by the workflow.
+  var contentFindings = extractContentFindings(workerText);
+  if (!contentFindings.ok) {
+    log("QA CONTENT-FINDINGS unreadable (" + contentFindings.reason + ") — marking failed for retry");
+    await recordPhase(env, {
+      task_id: env.taskId,
+      session: {
+        id: state.activeSessionId, task_id: env.taskId, identity: PHASE.identity,
+        step: PHASE.name, status: "failed",
+        notes: "QA report had no machine-readable CONTENT-FINDINGS block (" + contentFindings.reason + "); phase failed for retry",
+      },
+      event: {
+        task_id: env.taskId, type: "failed", identity: PHASE.identity,
+        message: "QA CONTENT-FINDINGS block unreadable (" + contentFindings.reason + ") — phase failed, dispatcher will retry",
+      },
+    });
+    return { type: "FAILED" };
+  }
+  // The publish-diff file set, persisted at Publish. Unreadable →
+  // attribution unknown (never environment-attributable, never a bugfix).
+  var qaDiffFiles = [];
+  var qaDiffFilesOk = false;
+  try {
+    var qaDiffFilesRaw = readFileSync(env.crewHome + "/.publish-diffs/" + env.taskId + ".files.json", "utf8").trim();
+    if (qaDiffFilesRaw && qaDiffFilesRaw !== "DIFF_FILES_MISSING") {
+      var qaDiffParsed = JSON.parse(qaDiffFilesRaw);
+      if (Array.isArray(qaDiffParsed)) {
+        qaDiffFiles = qaDiffParsed;
+        qaDiffFilesOk = true;
+      }
+    }
+  } catch (e) {
+    log("QA diff file list unreadable: " + String((e && e.message) || e).slice(0, 200));
+  }
+  if (!qaDiffFilesOk) {
+    log("QA publish diff file list unavailable — content findings record attribution unknown");
+  }
+  for (var cfi = 0; cfi < contentFindings.findings.length; cfi++) {
+    var cf = contentFindings.findings[cfi];
+    var cfc = qaDiffFilesOk ? classifyContentFinding(cf, qaDiffFiles)
+      : { attribution: "unknown", reason: "publish diff file set unavailable — cannot attribute" };
+    if (cfc.attribution === "task-change") {
+      log("QA content finding attributable to task change — filing bugfix: " + cf.subject + " :: " + String(cf.observation).slice(0, 120));
+      await crewApi(env, "create-task", {
+        title: "QA content finding: " + String(cf.observation).slice(0, 120),
+        description: "Content finding from QA on task " + env.taskId + " (subject: " + cf.subject + ", classified task-change: " + cfc.reason + "). Observation: " + cf.observation,
+        project: env.projectId, workflow: "bugfix", filed_by: "hazel",
+      });
+    } else {
+      log("QA content finding " + cfc.attribution + " — recording, no bugfix: " + cf.subject + " :: " + String(cf.observation).slice(0, 120));
+      await logEvent(env, {
+        task_id: env.taskId, type: "note", identity: PHASE.identity,
+        message: "content-finding: " + cfc.attribution + " — subject: " + cf.subject + " — " + cf.observation + " (" + cfc.reason + ")",
+      });
+    }
+  }
+
+  // Closeout.
+  var status = verdictPassed ? "completed" : "rejected";
+  await recordPhase(env, {
+    task_id: env.taskId,
+    session: {
+      id: state.activeSessionId, task_id: env.taskId, identity: PHASE.identity,
+      step: PHASE.name, status: status, notes: summarizeReport(workerText),
+    },
+    event: {
+      task_id: env.taskId, type: status, identity: PHASE.identity,
+      message: "QA " + status + " by " + PHASE.identity,
+    },
+  });
+
+  if (!verdictPassed) {
+    // Shared Review/QA rework budget (spec.reworkPhases).
+    if (state.reworkCount >= MAX_REWORK) {
+      log("Shared rework budget exhausted for task " + env.taskId + " — worktree preserved at " + env.worktreePreservedHint + " for manual inspection");
+      return await parkTask(env, "Exceeded shared rework budget (" + MAX_REWORK + " total rework attempts across Review and QA) after QA rejection. Worktree preserved.");
+    }
+    log("QA rejected — bouncing to Build (rework #" + (state.reworkCount + 1) + " of " + MAX_REWORK + ")");
+    return { type: "REWIND", next: "Build" };
+  }
+  // QA PASS is terminal: the driver closeout marks the task done.
+  return { type: "ADVANCE", next: null };
+}