muse-crew 0.17.2 → 0.17.3

package/lib/standard/phases/qa.js

@@ -0,0 +1,399 @@
+// lib/standard/phases/qa.js — QA (hazel) phase module (sandbox exit,
+// Phase C Piece 1). Import-safe: no side effects on import, bare `node`
+// exits 0.
+//
+// Reads: claim/session context, the ensure-deployed bundle hash (0.16.0 QA
+//   deploy pipeline), the release decision from durable Build notes (npm
+//   backstop), the publish-diff file list persisted by Publish, the OODA
+//   verdict record, the terminal_targets declaration from Triage notes.
+// Writes: completed/rejected/failed session + event, bugfix tasks for
+//   task-attributable content findings (filed_by hazel), note events for
+//   environment/unknown-attribution findings.
+// Transitions: ADVANCE (terminal, next null) on pass. Verdict FAIL records
+//   "rejected" and rewinds to Build against the SHARED Review/QA rework
+//   budget (MAX_TOTAL_REWORK = 2, derived durably from rejected events).
+//   FAILED on operational failure (unreadable verdict, hash mismatch,
+//   unreadable CONTENT-FINDINGS). PARK on missing experiential evidence
+//   (a PASS without experiential evidence is never terminal).
+//
+// 0.16.0 note: the numeric qa-bundle-stale / BUILD_NUMBER gate was
+// deliberately removed from the source (commit b7319ca). Freshness is now
+// constructive: Integrate rebuilds the QA bundle from merged source via
+// qa-deploy.mjs, QA ensure-deploys, and the closeout verifies the bundle
+// hash. No numbers, no comparison.
+
+import {
+  runWorkBoundary, recordPhase, buildEventPreamble, summarizeReport,
+  closeoutPassed, ensureClaimed, latestSessionNotes, crewApi, runCmd,
+  resolveExperiential, parseDeployResult, parkTask, crewCmdString, log,
+} from "../../workflow-lib.js";
+import {
+  extractContentFindings, classifyContentFinding, extractReleaseDecision,
+  extractMarkerLines,
+} from "../../extract.js";
+import { join } from "path";
+import { readFileSync, readdirSync, statSync } from "fs";
+
+export const PHASE = { name: "QA", identity: "hazel" };
+const MAX_TOTAL_REWORK = 2;
+
+// buildInstructions — pure function of ctx. The QA facts are stashed in
+// ctx.state.memo.qaFacts by runPhase before the call (keeps the signature
+// pure). Instruction text verbatim from workflows/standard.js (QA branch:
+// artifact / terminal / generic surfaces, npm publish backstop, and the
+// machine-readable CONTENT-FINDINGS protocol).
+export function buildInstructions(ctx) {
+  var env = ctx.env;
+  var facts = (ctx.state.memo && ctx.state.memo.qaFacts) || {};
+  var taskId = env.taskId;
+  var crewHome = env.crewHome;
+  var crewApiCmd = env.crewApiPinned;
+
+  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";
+
+  var npmPublishCheck = (env.publishType === "npm" && facts.releaseDecision && facts.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 \"" + facts.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;
+  if (env.surfaceArtifact) {
+    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.\n" +
+      "Public docs (API.md, README, published action schemas) are NOT source code — read them freely, exactly as a user would.\n\n" +
+      "STEP 1: Experiential visual inspection — drive the artifact as a user would, one browser step at a time.\n" +
+      "You have a see-act driver: " + 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 deck, then click Study — the second step needs the first step's page state). For those, hold ONE browser alive: node " + crewHome + "/current/lib/see-act.js session-start --name qa --url http://localhost:<N>/ --log " + crewHome + "/task-evidence/" + 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 " + 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=" + crewHome + "/task-evidence/" + taskId + "/postchange/ (shell env vars do not persist between your commands, so prefix each one). When done: node " + 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 judge what you can.\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=" + crewHome + " setsid nohup node " + crewHome + "/current/lib/serve-artifact.js --space-dir ~/workspace/ts-spaces/" + env.publishSlug + " --port 0 --tag " + taskId + "-qa > /tmp/qa-server-" + taskId + ".log 2>&1 < /dev/null & for i in $(seq 1 30); do grep -q READY /tmp/qa-server-" + taskId + ".log && break; sleep 1; done; grep -o 'READY port=[0-9]*' /tmp/qa-server-" + 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-" + taskId + ".log) and continue with the mechanical checks.\n" +
+      "c. Bounded see-act loop, at most 8 steps: drive the artifact as a user would, one browser step at a time. Prefix EVERY see-act invocation with SEE_ACT_ARCHIVE_DIR=" + crewHome + "/task-evidence/" + 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 " + crewHome + "/current/lib/append-ooda-step.js --log " + crewHome + "/task-evidence/" + 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 " + 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 " + 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=" + crewHome + "/task-evidence/" + taskId + "/postchange/ node " + crewHome + "/current/lib/see-act.js --url http://localhost:<N>/ aria — read the JSON, log the step. Then: SEE_ACT_ARCHIVE_DIR=" + crewHome + "/task-evidence/" + taskId + "/postchange/ node " + 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 deck, then click Study, then judge the study view. 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 judge what you did reach.\n" +
+      "e. Judge as a user against the task description: does the change render correctly? 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 " + crewHome + "/task-evidence/" + 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 " + 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" +
+      "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" +
+      "PROVENANCE CHECK: 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 " + crewHome + "/releases/<provenance.crew_release> (substitute the real stamped hash; do not run the literal placeholder). If the directory does not exist, FAIL: { \"passed\": false, \"summary\": \"provenance mismatch: crew_release [value from get-provenance] not found in release registry\" }.\n" +
+      "If provenance.source_commit equals LIVE_HEAD, the source check passes — continue to STEP 3.\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, FAIL: { \"passed\": false, \"summary\": \"provenance mismatch: stamped source_commit is not an ancestor of live HEAD\" }.\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" +
+      "If both pass, the source check passes — the only drift since the stamp is builder staging output committed by post-deploy. Continue to STEP 3.\n\n" +
+      "STEP 3: File follow-up tasks for any related issues you discover — EXCEPT content findings (user-visible content/data): those go in the CONTENT-FINDINGS block at the end of these instructions, never through create-task. The workflow files follow-ups for attributable content itself.\n" +
+      "For each issue, run in shell:\n" +
+      "node " + crewApiCmd + " --crew-home " + 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.\n\n" +
+      "Report back in plain prose — what checks you ran and their results. 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 or VERDICT: FAIL. First ensure the OODA log exists even if you logged zero steps (touch " + crewHome + "/task-evidence/" + 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 " + crewHome + "/current/lib/write-ooda-verdict.js --dir " + crewHome + "/task-evidence/" + taskId + "/postchange/ --attempt \"1\" --verdict <PASS|FAIL|NOT_POSSIBLE> --summary \"<one line>\" --expected \"<what the task required>\" --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).";
+  } else if (env.surfaceTerminal) {
+    var termEvidence = crewHome + "/task-evidence/" + taskId + "/postchange";
+    var termTargetsLine = facts.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 CLI as a user would, one command at a time.\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: " + termTargetsLine + ".\n" +
+      "c. Bounded terminal loop — at most 8 commands. For each target: run it RIGHT (the happy path), 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 " + termEvidence + "\n" +
+      "   For each command: <cmd> > " + termEvidence + "/<nn>-<short-slug>.txt 2>&1; echo \"exit=$?\" >> " + termEvidence + "/<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 " + crewHome + "/current/lib/append-ooda-step.js --log " + termEvidence + "/ooda-log.jsonl --attempt \"1\" --step <N> --action terminal --exit <code> --transcript " + termEvidence + "/<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 " + crewHome + "/task-evidence/" + 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 — EXCEPT content findings (user-visible content/data): those go in the CONTENT-FINDINGS block at the end of these instructions, never through create-task. The workflow files follow-ups for attributable content itself.\n" +
+      "For each issue, run in shell:\n" +
+      "node " + crewApiCmd + " --crew-home " + 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" +
+      npmPublishCheck +
+      "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 back in plain prose — what checks you ran and their results. 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 or VERDICT: FAIL. First ensure the OODA log exists even if you logged zero steps (touch " + termEvidence + "/ooda-log.jsonl — an empty log is honest, an absent one is a broken report). Also write the same verdict machine-readably: node " + crewHome + "/current/lib/write-ooda-verdict.js --dir " + termEvidence + " --attempt \"1\" --verdict <PASS|FAIL|NOT_POSSIBLE> --summary \"<one line>\" --expected \"<what the task required>\" --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).";
+  } else {
+    instructions = "Test from a user's perspective. You are CODE-BLIND — do NOT read source code.\n" +
+      "Public docs (API.md, README) are NOT source code — read them freely, exactly as a user would.\n" +
+      "Verify the change is working as described in the task.\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, 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" +
+      "File follow-up tasks for related issues found (EXCEPT content findings — user-visible content/data goes in the CONTENT-FINDINGS block at the end of these instructions, never through create-task) by running in shell:\n" +
+      "node " + crewApiCmd + " --crew-home " + 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" +
+      npmPublishCheck +
+      "Report back in plain prose — what you tested and found. End your report with exactly one line: VERDICT: PASS or VERDICT: FAIL.";
+  }
+  // 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;
+}
+
+// ensureDeployed — idempotent precondition for experiential artifact QA on
+// versioned projects: the QA environment serves a bundle built from merged
+// source. Fast path when the bundle is already current. A failed deploy is
+// an operational failure (retryable), never a park. Direct qa-deploy.mjs
+// call — no agent ferry. The module self-records the bundle hash to the
+// event log.
+async function ensureDeployed(env) {
+  var qaEnvDir = env.crewHome + "/qa-envs/" + env.projectId;
+  var out = "";
+  try {
+    out = String((await runCmd(["node", join(env.runLib, "qa-deploy.mjs"),
+      "--repo", env.repoPath, "--qa-dir", qaEnvDir,
+      "--task", env.taskId, "--crew-home", env.crewHome, "--crew-api", env.crewApiPinned,
+      "--serve-artifact", join(env.runLib, "serve-artifact.js"), "--ensure"], {})).stdout || "").trim();
+  } catch (e) {
+    out = "";
+  }
+  var parsed = parseDeployResult(out);
+  if (!parsed.ok) {
+    return { failed: parsed.reason };
+  }
+  log("QA ensure-deployed ok for task " + env.taskId + ": bundle " + parsed.hash);
+  return { ok: true, hash: parsed.hash };
+}
+
+// runLoopGuard — the experiential-loop guard (qa-reproduce.md): a PASS with
+// missing experiential evidence parks fail-closed, never completes. Reads
+// the machine-readable OODA verdict record directly.
+async function runLoopGuard(env) {
+  var surface = env.surfaceTerminal ? "terminal" : "visual";
+  var reason = env.surfaceTerminal ? "qa-terminal-loop-unavailable" : "qa-visual-loop-unavailable";
+  var reader = join(env.runLib, "read-ooda-verdict.js");
+  try {
+    statSync(reader);
+  } catch (e) {
+    // The reader is a release-lib script, not a pinned script.
+    reader = env.crewHome + "/current/lib/read-ooda-verdict.js";
+  }
+  var out = "";
+  try {
+    out = String((await runCmd(["node", reader, "--dir", env.taskEvidenceDir + "/postchange", "--expect", "PASS"], {})).stdout || "").trim();
+  } catch (e) {
+    out = "";
+  }
+  // The script prints exactly one JSON line; the parsed object is the gate
+  // signal.
+  var gate = null;
+  try {
+    var lines = out.split("\n");
+    gate = JSON.parse(lines[lines.length - 1]);
+  } catch (e) {
+    gate = null;
+  }
+  if (!gate || gate.ok !== true) {
+    return { parked: await parkTask(env, "QA " + surface + " loop unverifiable (unattributable_reason=" + reason + "): lib/read-ooda-verdict.js could not confirm the QA verdict record — a PASS without a machine-readable experiential record is never terminal. Human attention needed.") };
+  }
+  var unavailable = env.surfaceTerminal ? gate.terminal_loop_unavailable : gate.visual_loop_unavailable;
+  if (unavailable === true) {
+    var why = 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.";
+    return { parked: await parkTask(env, "QA " + surface + " loop unavailable (unattributable_reason=" + reason + "): " + why) };
+  }
+  log("QA " + surface + "-loop guard passed: experiential evidence present");
+  return { ok: true };
+}
+
+// closeoutHashCheck — the bundle Hazel tested must match the ensure-deployed
+// hash from QA start. Mismatch/unreadable = operational failure, never a park.
+async function closeoutHashCheck(env, qaBundleHash) {
+  var qaEnvDir = env.crewHome + "/qa-envs/" + env.projectId;
+  var out = "";
+  try {
+    out = String((await runCmd(["node", join(env.runLib, "qa-deploy.mjs"), "--hash-only", "--qa-dir", qaEnvDir], {})).stdout || "");
+  } catch (e) {
+    out = "";
+  }
+  var hm = /BUNDLE_HASH ([0-9a-f]{40})/.exec(out);
+  var closeHash = hm ? hm[1].slice(0, 7) : "";
+  if (closeHash !== qaBundleHash) {
+    return { ok: false, reason: "bundle hash " + (closeHash ? "changed during QA" : "unreadable") };
+  }
+  return { ok: true };
+}
+
+// closeoutContentFindings — blocker 38: Hazel's CONTENT-FINDINGS block is
+// extracted deterministically and each finding is classified against the
+// task's publish-diff file set (persisted at Publish). Attributable
+// findings become bugfix tasks filed by the workflow; environment/unknown
+// findings are recorded as task note events — never suppressed, never a
+// bugfix, never a park. No automatic FAIL override: if Hazel still reports
+// FAIL, it stands — finding attribution informs follow-up filing only.
+async function closeoutContentFindings(env, workerText) {
+  var taskId = env.taskId;
+  var contentFindings = extractContentFindings(workerText);
+  if (!contentFindings.ok) {
+    // Unknown attribution fails closed: a missing or malformed
+    // CONTENT-FINDINGS block blocks the phase for retry — the way an
+    // unreadable VERDICT line does. It must never degrade to "no
+    // findings": unknown attribution converted to an empty set silently
+    // drops the observations the prose grounds carry.
+    await recordPhase(env, {
+      task_id: taskId,
+      session: { id: undefined, task_id: 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: taskId, type: "failed", identity: PHASE.identity, message: "QA CONTENT-FINDINGS block unreadable (" + contentFindings.reason + ") — phase failed, dispatcher will retry" },
+    });
+    return { failed: "QA worker report had no machine-readable CONTENT-FINDINGS block (" + contentFindings.reason + ")" };
+  }
+  // The publish-diff file set, persisted at Publish. Unreadable →
+  // attribution unknown: every finding records "unknown" with the reason
+  // naming the missing diff (never environment-attributable, never a
+  // bugfix). The QA verdict stands on its own.
+  var qaDiffFiles = [];
+  var qaDiffFilesOk = false;
+  try {
+    var raw = readFileSync(env.publishDiffsDir + "/" + taskId + ".files.json", "utf8").trim();
+    var parsed = JSON.parse(raw);
+    if (Array.isArray(parsed)) {
+      qaDiffFiles = parsed;
+      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 i = 0; i < contentFindings.findings.length; i++) {
+    var cf = contentFindings.findings[i];
+    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 + " :: " + cf.observation.slice(0, 120));
+      await crewApi(env, "create-task", {
+        title: "QA content finding: " + cf.observation.slice(0, 120),
+        description: "Content finding from QA on task " + taskId + " (subject: " + cf.subject + ", classified task-change: " + cfc.reason + "). Observation: " + cf.observation,
+        project: env.projectId, workflow: "bugfix", filed_by: "hazel",
+      });
+    } else {
+      // environment-attributable and unknown findings are recorded as task
+      // note events with their attribution — never suppressed, never a
+      // bugfix, never a park by themselves.
+      log("QA content finding " + cfc.attribution + " — recording, no bugfix: " + cf.subject + " :: " + cf.observation.slice(0, 120));
+      await crewApi(env, "log-event", {
+        task_id: taskId, type: "note",
+        message: "content-finding: " + cfc.attribution + " — subject: " + cf.subject + " — " + cf.observation + " (" + cfc.reason + ")",
+      });
+    }
+  }
+  return { ok: true };
+}
+
+export async function runPhase(ctx) {
+  var env = ctx.env, state = ctx.state;
+  var taskId = env.taskId;
+  var claimed = await ensureClaimed(env, state, PHASE);
+  if (claimed.type !== "CLAIMED") return claimed;
+
+  // Experiential routing: experiential tasks on a classified surface run
+  // the Hazel experiential QA prompt — Hazel drives the surface herself
+  // and owns the verdict through her OODA report.
+  var qaExperiential = (await resolveExperiential(env, state)) === "yes" && (env.surfaceArtifact || env.surfaceTerminal);
+  var qaBundleHash = null;
+  if (qaExperiential && env.surfaceArtifact && env.versionedBuild) {
+    var dep = await ensureDeployed(env);
+    if (dep.failed) {
+      await recordPhase(env, {
+        task_id: taskId,
+        session: { id: state.activeSessionId, task_id: taskId, identity: PHASE.identity, step: PHASE.name, status: "failed",
+          notes: "QA ensure-deployed failed: " + dep.failed },
+        event: { task_id: taskId, type: "failed", identity: PHASE.identity, message: "QA ensure-deployed failed: " + dep.failed + " — phase failed, dispatcher will retry" },
+      });
+      return { type: "FAILED", reason: "QA ensure-deployed failed: " + dep.failed };
+    }
+    qaBundleHash = dep.hash;
+  }
+
+  // Cross-phase handoffs re-derived from durable session notes.
+  var releaseDecision = extractReleaseDecision(await latestSessionNotes(env, "Build", "completed"));
+  var triageMarkers = extractMarkerLines(await latestSessionNotes(env, "Triage", "completed"));
+  var ttMatch = /^terminal_targets:\s*(.+)$/im.exec(triageMarkers);
+  state.memo.qaFacts = {
+    qaExperiential: qaExperiential,
+    qaBundleHash: qaBundleHash,
+    releaseDecision: releaseDecision,
+    terminalTargets: ttMatch ? ttMatch[1].trim() : "",
+  };
+
+  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 passed = closeoutPassed(boundary) === true;
+  var summary = summarizeReport(workerText);
+
+  // Experiential-loop guard: a PASS with missing experiential evidence is
+  // never terminal.
+  if (passed && qaExperiential) {
+    var lg = await runLoopGuard(env);
+    if (lg.parked) return lg.parked;
+  }
+
+  // Closeout integrity (experiential artifact on versioned builds): the
+  // bundle Hazel tested must match the ensure-deployed hash, and her
+  // content findings are classified against the Publish diff file set.
+  // The QA verdict stands on its own and is never overridden by finding
+  // attribution.
+  if (qaBundleHash !== null) {
+    var hc = await closeoutHashCheck(env, qaBundleHash);
+    if (!hc.ok) {
+      log("QA closeout hash mismatch for task " + taskId + " — marking failed for retry");
+      summary += "\nqa_closeout: FAILED — bundle hash " + hc.reason;
+      passed = false;
+    }
+    var cfr = await closeoutContentFindings(env, workerText);
+    if (cfr.failed) {
+      return { type: "FAILED", reason: cfr.failed };
+    }
+  }
+
+  var status = passed ? "completed" : "rejected";
+  await recordPhase(env, {
+    task_id: taskId,
+    session: { id: state.activeSessionId, task_id: taskId, identity: PHASE.identity, step: PHASE.name, status: status, notes: summary },
+    event: { task_id: taskId, type: status, identity: PHASE.identity, message: PHASE.name + " " + status + " by " + PHASE.identity },
+  });
+
+  if (!passed) {
+    // Shared rework budget: Review and QA rejections draw from the SAME
+    // pool of 2 (derived durably by counting "rejected" events). The
+    // rejected event above is already recorded, so the new count is
+    // state.reworkCount + 1.
+    var newRework = state.reworkCount + 1;
+    if (newRework > MAX_TOTAL_REWORK) {
+      log("Shared rework budget exhausted for task " + taskId + " after QA rejection");
+      return await parkTask(env, "Exceeded shared rework budget (" + MAX_TOTAL_REWORK + " total rework attempts across Review and QA) after QA rejection.");
+    }
+    log("QA rejected — bouncing to Build (rework #" + newRework + " of " + MAX_TOTAL_REWORK + ")");
+    return { type: "REWIND", next: "Build", reason: "QA rejected — bouncing to Build (rework #" + newRework + " of " + MAX_TOTAL_REWORK + ")" };
+  }
+  log("QA complete for task " + taskId + " — workflow terminal");
+  return { type: "ADVANCE", next: null };
+}