muse-crew 0.8.0 → 0.9.0

package/workflows/standard.js

@@ -123,6 +123,36 @@ const WORKTREE_HINT = REPO_PATH + "/.worktrees/" + taskId;
 const WORKTREE_PRESERVED_HINT = ".worktrees/" + taskId;
 
 const PUBLISH_TYPE = projectConfig.deploy_type || "";
+// User-facing surface for experiential QA routing: 'artifact' (a rendered
+// web UI Hazel drives with the see-act browser loop) | 'terminal' (a CLI
+// Hazel drives herself, keeping attempt-scoped transcripts) | null
+// (unclassified — no experiential QA). environment_type is the canonical
+// UX-surface axis; deploy_type names the deployment target, but
+// deploy_type === "artifact" remains a legacy artifact-surface signal so
+// pre-field projects keep today's experiential QA (the migration does not
+// backfill the column).
+const ENV_TYPE = projectConfig.environment_type || null;
+// Surface resolution: artifact wins on contradictory config (the deployed
+// artifact is what users see). Unclassified surface => Capture skips, QA
+// runs the plain code-blind prompt — today's behavior, unchanged.
+const SURFACE_ARTIFACT = (PUBLISH_TYPE === "artifact" || ENV_TYPE === "artifact");
+const SURFACE_TERMINAL = (!SURFACE_ARTIFACT && ENV_TYPE === "terminal");
+const SURFACE_CLASSIFIED = SURFACE_ARTIFACT || SURFACE_TERMINAL;
+// One-line surface description for the Triage prompt, so Sage judges the
+// experiential flag against the project's actual user-facing surface.
+const SURFACE_TRIAGE_DESC = SURFACE_ARTIFACT
+  ? "This project's user-facing surface is artifact: a rendered web UI."
+  : SURFACE_TERMINAL
+    ? "This project's user-facing surface is terminal: a command-line interface."
+    : "This project's user-facing surface is unclassified (environment_type not set): judge by what a user would directly observe.";
+// UX doctrine page: the shared UX bar for this run's surface, resolved
+// mechanically — every phase prompt reads UX_DOCTRINE_PATH, never a
+// hardcoded filename. Canonical map: lib/ux-doctrine.js (mirrored here as a
+// one-liner because the workflow runtime's relative-import support is
+// unverified; tests pin the mirror). Null on unclassified surfaces: no
+// shared page, and prompts say so instead of naming the wrong one.
+const UX_DOCTRINE_PAGE = SURFACE_TERMINAL ? "terminal-ux.md" : (SURFACE_ARTIFACT ? "artifact-ux.md" : null);
+const UX_DOCTRINE_PATH = UX_DOCTRINE_PAGE ? crewHome + "/current/docs/" + UX_DOCTRINE_PAGE : null;
 const PUBLISH_SLUG = projectConfig.deploy_slug || "";
 const PROJECT_DESC = projectConfig.description || "React + TypeScript web dashboard (client/src/, server/src/, drizzle/)";
 const RELEASE_SCRIPT = crewHome + "/crew-release.sh";
@@ -540,7 +570,7 @@ function extractMarkerLines(workerText) {
   var markers = [];
   for (var i = 0; i < lines.length; i++) {
     var line = lines[i].trim();
-    if (/^(repo_diff:|release:|version_bump:|VERDICT:|TARGET_VERSION=|published:|experiential:|layer:|capture_targets:|worktree:)/i.test(line)) {
+    if (/^(repo_diff:|release:|version_bump:|VERDICT:|TARGET_VERSION=|published:|experiential:|layer:|capture_targets:|terminal_targets:|worktree:)/i.test(line)) {
       markers.push(line);
     }
   }
@@ -730,6 +760,10 @@ let isExperiential = null;
 // notes are immutable within a run, so the lookup runs at most once.
 let experientialResolved = null;
 let captureTargets = "";
+// Sage's terminal_targets marker: the CLI commands/flags exercising the
+// changed surface (terminal-surface tasks). Falls back to the task
+// description when Sage omits it.
+let terminalTargets = "";
 let mapGateBounceCount = 0;
 // Merge-time versioning: the release decision is extracted deterministically
 // from the accepted Build worker report (extractReleaseDecision) so the Publish
@@ -1034,13 +1068,13 @@ while (i < STEPS.length) {
   if (step.name === "Capture") {
     var capExp = await resolveExperiential();
     var bounceSuffix = (mapGateBounceCount > 0 ? "-g" + mapGateBounceCount : "");
-    if (capExp !== "yes" || PUBLISH_TYPE !== "artifact") {
-      log("Capture skipped for task " + taskId + " — " + (capExp !== "yes" ? "not experiential" : "publish target is not artifact"));
+    if (capExp !== "yes" || !SURFACE_CLASSIFIED) {
+      log("Capture skipped for task " + taskId + " — " + (capExp !== "yes" ? "not experiential" : "surface unclassified (environment_type=" + (ENV_TYPE || "null") + ")"));
       await agent(
         "Update the session and log the event.\n" +
         "Run in shell and return the stdout verbatim:\n" + crewCmd("record-phase", {
           task_id: taskId,
-          session: { id: activeSessionId, task_id: taskId, identity: step.identity, step: step.name, status: "completed", notes: "Capture skipped — not an experiential artifact task" },
+          session: { id: activeSessionId, task_id: taskId, identity: step.identity, step: step.name, status: "completed", notes: "Capture skipped — not an experiential task on a classified surface" },
           event: { task_id: taskId, type: "completed", identity: step.identity, message: "Capture completed by " + step.identity }
         }),
         { key: "record-Capture" + bounceSuffix, label: "Recording Capture result" }
@@ -1048,6 +1082,34 @@ while (i < STEPS.length) {
       i++;
       continue;
     }
+    // Terminal-surface Capture: Hazel runs the CLI herself against the
+    // pre-change tree and archives attempt-scoped transcripts. No parent
+    // protocol exists for terminal projects (there is no see-act loop to
+    // drive), so the baseline is agent-driven in one shot — the Map gate
+    // reads the same "baseline: captured/none" note prefixes either way.
+    if (SURFACE_TERMINAL) {
+      var termBaseDir = crewHome + "/task-evidence/" + taskId + "/baseline";
+      log("Capture: terminal-surface baseline for task " + taskId + " — Hazel drives the CLI herself");
+      await agent(
+        "Run the pre-change terminal baseline yourself — there is no parent capture protocol for terminal-surface projects.\n" +
+        "1. The project's repo is at " + REPO_PATH + " (pre-change state; the task branch does not exist yet). The CLI under test is the project's own command-line interface in that tree — start like a new user with --help. You are code-blind: you may RUN the CLI, never READ its source.\n" +
+        "2. Terminal targets for this task: " + (terminalTargets || "not declared — derive them from --help and the task description") + ".\n" +
+        "3. Run in shell: mkdir -p " + termBaseDir + "\n" +
+        "4. For each target, run the command with stdout AND stderr captured to " + termBaseDir + "/<nn>-<short-slug>.txt (number them 01, 02, ...), appending the exit code as the final line. Pattern: <cmd> > " + termBaseDir + "/01-<slug>.txt 2>&1; echo \"exit=$?\" >> " + termBaseDir + "/01-<slug>.txt\n" +
+        "5. READ every transcript file you wrote — an unread transcript is not evidence.\n" +
+        "6. Log the baseline note — run in shell and return the stdout verbatim:\n" + crewCmd("log-event", { task_id: taskId, type: "note", identity: step.identity, message: "baseline: captured (terminal transcripts: <comma-separated filenames>)" }) + "\n" +
+        "   (replace <comma-separated filenames> with the real filenames). If the CLI cannot run from the pre-change tree (will not start, missing dependency), log instead: baseline: none (terminal targets not runnable: <reason>) — never fabricate a transcript.\n" +
+        "7. Record the phase — run in shell and return the stdout verbatim:\n" + crewCmd("record-phase", {
+          task_id: taskId,
+          session: { id: activeSessionId, task_id: taskId, identity: step.identity, step: step.name, status: "completed", notes: "Terminal baseline captured by the QA agent (transcripts archived)" },
+          event: { task_id: taskId, type: "completed", identity: step.identity, message: "Capture completed by " + step.identity }
+        }) + "\n" +
+        "Report back in plain prose: which commands you ran and what the pre-change baseline looks like.",
+        { key: "terminal-baseline-" + taskId + bounceSuffix, label: "Capturing terminal baseline" }
+      );
+      i++;
+      continue;
+    }
     var capStatus = await baselineStatus();
     // Stale-decision guard: a "baseline: none (visual protocol unavailable)"
     // note is only durable while the protocol is unavailable. When
@@ -1125,9 +1187,9 @@ while (i < STEPS.length) {
   var mapBaselineRefs = "";
   var mapBaselineNone = false;
   if (step.name === "Map") {
-    // Must match Capture's run condition (experiential + artifact publish):
+    // Must match Capture's run condition (experiential + classified surface):
     // when Capture skips, no baseline notes exist, so the gate must not apply.
-    if ((await resolveExperiential()) === "yes" && PUBLISH_TYPE === "artifact") {
+    if ((await resolveExperiential()) === "yes" && SURFACE_CLASSIFIED) {
       var gateStatus = await baselineStatus();
       if (!gateStatus.baseline_found) {
         log("Map gate: no baseline evidence for experiential task " + taskId + " — bouncing to Capture");
@@ -1149,13 +1211,16 @@ while (i < STEPS.length) {
     }
   }
 
-  // Experiential routing: experiential artifact tasks run the Hazel
-  // experiential QA prompt (built in the PUBLISH_TYPE === "artifact" branch
-  // of the QA step) — Hazel drives the artifact herself and owns the visual
-  // verdict through her OODA report and write-ooda-verdict ledger.
-  var qaVisual = false;
+  // Experiential routing: experiential tasks on a classified surface run the
+  // Hazel experiential QA prompt (built in the SURFACE_ARTIFACT /
+  // SURFACE_TERMINAL branches of the QA step) — Hazel drives the surface
+  // herself and owns the verdict through her OODA report and the
+  // write-ooda-verdict ledger. qaExperiential gates the closeout
+  // experiential-loop guard (a PASS with missing experiential evidence is
+  // never terminal).
+  var qaExperiential = false;
   if (step.name === "QA") {
-    qaVisual = (await resolveExperiential()) === "yes" && PUBLISH_TYPE === "artifact";
+    qaExperiential = (await resolveExperiential()) === "yes" && SURFACE_CLASSIFIED;
   }
 
   // Step-specific instructions
@@ -1163,7 +1228,7 @@ while (i < STEPS.length) {
   var instructions = "";
 
   if (step.name === "Triage") {
-    instructions = "Validate the task against the project's repo at " + REPO_PATH + " — that exact checkout, not any other copy of the project on disk. If you run git commands, cd " + REPO_PATH + " first.\nCheck clarity, note dependencies, confirm the standard workflow assignment.\nWrite a brief triage assessment as notes for the next step.\nReport back in plain prose — what you found.\nEXPERIENTIAL FLAG: does this task change anything rendered and visible in the project's user-facing artifact (pages, components, styles, layout, copy, visual states)? If yes it is experiential and gets baseline captures (plus a visual verdict where the workflow has a QA phase). End your report with exactly one line on its own, lowercase, unrephrased: experiential: yes — or experiential: no. This line is machine-read.";
+    instructions = "Validate the task against the project's repo at " + REPO_PATH + " — that exact checkout, not any other copy of the project on disk. If you run git commands, cd " + REPO_PATH + " first.\nCheck clarity, note dependencies, confirm the standard workflow assignment.\nWrite a brief triage assessment as notes for the next step.\nReport back in plain prose — what you found.\nEXPERIENTIAL FLAG: does this task change anything a user can directly observe in the project's user-facing surface? " + SURFACE_TRIAGE_DESC + " For an artifact surface that means rendered and visible — pages, components, styles, layout, copy, visual states. For a terminal surface it means the CLI experience — command output, help text, flags, error messages, defaults. The shared UX bar is " + (UX_DOCTRINE_PATH ? UX_DOCTRINE_PATH + " — flag experiential when the task touches anything it covers." : "not classified for this project — flag experiential when the task touches anything user-observable in the surface described above.") + " If yes it is experiential and gets baseline evidence (plus an experiential verdict where the workflow has a QA phase). For terminal-surface tasks also declare the CLI surface to exercise: end your report with a line `terminal_targets: <comma-separated CLI commands/flags>` (machine-read; optional — falls back to the task description). End your report with exactly one line on its own, lowercase, unrephrased: experiential: yes — or experiential: no. This line is machine-read.";
 
   } else if (step.name === "Map") {
     var mapGatePara = "";
@@ -1171,11 +1236,16 @@ while (i < STEPS.length) {
       mapGatePara = "\nBASELINE GATE (experiential task): " +
         (mapBaselineNone
           ? "no baseline was capturable (baseline: none recorded) — write the spec without baseline comparison and note it."
-          : "pre-change baseline captures: " + mapBaselineRefs + " — consult the affected views when writing the spec.") +
+          : "pre-change baseline evidence: " + mapBaselineRefs + " — consult it when writing the spec.") +
         " If the baseline evidence is missing with no baseline:none recorded, do not write the spec — report 'baseline evidence missing — Map gate bounce required' and stop.\n" +
-        "Declare capture targets for the post-change visual capture: end your report with a line `capture_targets: <comma-separated views/controls this change affects>` (optional; falls back to the task description).";
+        (SURFACE_TERMINAL
+          ? "Declare the CLI surface to exercise: end your report with a line `terminal_targets: <comma-separated CLI commands/flags>` (machine-read; optional — falls back to the task description)."
+          : "Declare capture targets for the post-change visual capture: end your report with a line `capture_targets: <comma-separated views/controls this change affects>` (optional; falls back to the task description).");
     }
-    instructions = "Research the problem space, evaluate options, pick the shortest path.\nWrite a clear spec that a builder can execute without asking questions.\nThe builder will edit source files in a git worktree.\nProject: " + PROJECT_DESC + "\nSave the spec to exactly this file: " + SPEC_PATH + " — run mkdir -p \"" + SPEC_DIR + "\" first. Do not save the spec anywhere else; this exact path is fixed and will be checked mechanically after your step.\nReport back in plain prose — what you specified." + mapGatePara;
+    instructions = "Research the problem space, evaluate options, pick the shortest path.\nWrite a clear spec that a builder can execute without asking questions.\n" +
+      (SURFACE_TERMINAL ? "TERMINAL SPEC: this project's surface is a CLI. Specify the exact commands, their expected stdout/stderr, exit codes, --help text, and error messages — Hazel judges the build against this spec and the shared bar at " + UX_DOCTRINE_PATH + ".\n" : "") +
+      (SURFACE_ARTIFACT ? "ARTIFACT SPEC: this project's surface is a rendered artifact. Specify the exact screens, flows, and visual states the change affects — Hazel judges the build against this spec and the shared bar at " + UX_DOCTRINE_PATH + ".\n" : "") +
+      "The builder will edit source files in a git worktree.\nProject: " + PROJECT_DESC + "\nSave the spec to exactly this file: " + SPEC_PATH + " — run mkdir -p \"" + SPEC_DIR + "\" first. Do not save the spec anywhere else; this exact path is fixed and will be checked mechanically after your step.\nReport back in plain prose — what you specified." + mapGatePara;
 
   } else if (step.name === "Build") {
     instructions = "STEP 1: Prepare your worktree.\n" +
@@ -1190,6 +1260,8 @@ while (i < STEPS.length) {
       "This is the project source: " + PROJECT_DESC + "\n" +
       "Edit source files directly. Do NOT use artifact_edit — that happens in the Publish phase.\n" +
       "Do not add unrequested features. Build exactly what the spec calls for.\n" +
+      (SURFACE_TERMINAL ? "TERMINAL UX: build to the shared bar at " + UX_DOCTRINE_PATH + " — --help text, error messages, and exit codes are user-facing and ship in this commit.\n" : "") +
+      (SURFACE_ARTIFACT ? "ARTIFACT UX: build to the shared bar at " + UX_DOCTRINE_PATH + " — the rendered result is what the user sees; it ships in this commit.\n" : "") +
       "PUBLIC DOCS: If your change is public-affecting (it alters anything a user or consumer can observe: API actions, parameters, behavior, or errors), update the public docs in the same commit — API.md for API changes. Documentation and implementation ship together.\n\n" +
       (PUBLISH_TYPE === "npm" ? "PACKAGE VERSION: this project publishes to the npm registry. Versions are assigned at PUBLISH time — never in your branch. Do NOT touch the `version` field in package.json (or package-lock). Instead, end your report with exactly these two lines:\n" +
       "release: yes|no — 'yes' if this change warrants a published release (anything a consumer can observe: workflow behavior, phase lists, identities, published docs, API); 'no' if internal-only.\n" +
@@ -1234,6 +1306,8 @@ while (i < STEPS.length) {
       "You can also read specific files in the worktree at:\n" +
       WORKTREE_HINT + "/\n\n" +
       "Check quality, correctness, and spec compliance.\n" +
+      (SURFACE_TERMINAL ? "TERMINAL UX REVIEW: judge the CLI surface against " + UX_DOCTRINE_PATH + " — help accuracy, error quality, exit codes, output clarity. Reject when the bar is not met.\n" : "") +
+      (SURFACE_ARTIFACT ? "ARTIFACT UX REVIEW: judge the rendered surface against " + UX_DOCTRINE_PATH + " — alignment, spacing, hierarchy, composition, balance, finish, correctness. Reject when the bar is not met.\n" : "") +
       "Check that public-affecting changes have matching public doc updates (API.md or the published API contract). If the docs are missing or inaccurate, report what is stale, then end your report with exactly this line: VERDICT: FAIL.\n" +
       "If the branch has no commits ahead of main (inspect shows an empty commit log), approve ONLY if the Build summary declares `repo_diff: none` with (a) a plausible runtime-state deliverable (e.g. a cron created via the cron tool), or (b) an already-merged declaration `repo_diff: none (already-merged: <sha>)` AND the mechanical fact below confirms the sha verified. MECHANICAL FACT (computed by the workflow, never by the builder): already_merged sha = " + (alreadyMergedSha ? alreadyMergedSha + " (verified ancestor of main: YES)" : "none declared") + ". Otherwise report 'no commits ahead of main and no valid repo_diff: none declaration — the builder likely forgot to commit', then end your report with exactly this line: VERDICT: FAIL.\n" +
       (PUBLISH_TYPE === "npm" ? "PACKAGE VERSION: this project publishes to the npm registry, and versions are assigned at publish time — never in branches. Two checks:\n" +
@@ -2137,9 +2211,10 @@ while (i < STEPS.length) {
       "Verify the bump SCOPE: the <scope> in that line MUST equal the accepted version_bump scope \"" + 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"
       : "";
-    if (PUBLISH_TYPE === "artifact") {
+    if (SURFACE_ARTIFACT) {
       var safeDesc = taskDescription.replace(/"/g, "'").replace(/\\/g, "\\\\").slice(0, 500);
-      instructions = "You are code-blind QA. You NEVER read source files.\n" +
+      instructions = "Read the shared UX bar FIRST: " + UX_DOCTRINE_PATH + " — 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" +
@@ -2173,6 +2248,40 @@ while (i < STEPS.length) {
         "(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 (SURFACE_TERMINAL) {
+      // Terminal-surface experiential QA: Hazel drives the CLI herself —
+      // the terminal counterpart to the see-act loop above. Same OODA
+      // discipline (append-ooda-step with --action terminal and a transcript
+      // per step; verdict via write-ooda-verdict), judged against the
+      // shared bar resolved via UX_DOCTRINE_PATH (the terminal doctrine page here). Transcripts are delivered;
+      // screenshots are never invented for terminal work.
+      var termEvidence = crewHome + "/task-evidence/" + taskId + "/postchange";
+      var termTargetsLine = 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: " + UX_DOCTRINE_PATH + " — 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 " + REPO_PATH + " (the merged change is on main 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" + crewCmd("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, run in shell:\n" +
+        "node " + CREW_API + " --crew-home " + crewHome + " create-task --json '{\"title\": \"<issue title>\", \"description\": \"<issue details>\", \"project\": \"" + LAUNCH_PROJECT_ID + "\", \"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" +
@@ -2184,10 +2293,10 @@ while (i < STEPS.length) {
         npmPublishCheck +
         "Report back in plain prose — what you tested and found. End your report with exactly one line: VERDICT: PASS or VERDICT: FAIL.";
     }
-    // qaVisual (experiential artifact tasks): Hazel owns the visual verdict
-    // through the experiential QA prompt built in the PUBLISH_TYPE ===
-    // "artifact" branch above (STEP 1 see-act loop + OODA report). There is
-    // no parent visual-verdict protocol anymore — no override here.
+    // qaExperiential: Hazel owns the experiential verdict through the QA
+    // prompt built in the SURFACE_ARTIFACT / SURFACE_TERMINAL branches above
+    // (see-act loop or terminal loop + OODA report). There is no parent
+    // visual-verdict protocol anymore — no override here.
   }
 
   // Task event history — Review and Publish are excluded. Review is cold by
@@ -2416,26 +2525,30 @@ while (i < STEPS.length) {
     }
   }
 
-  // QA visual-loop guard (clean-room defect 2026-09-16): Hazel's verdict.json
-  // is honest about missing visual evidence, but the closeout treated a PASS
-  // as terminal done even when the see-act loop never ran (playwright-core
+  // QA experiential-loop guard (clean-room defect 2026-09-16): Hazel's verdict.json
+  // is honest about missing experiential evidence, but the closeout treated a PASS
+  // as terminal done even when the experiential loop never ran (playwright-core
   // was unresolvable from the release layout — the dependency lived in the
   // npm install dir, severed from the crew home). A PASS verdict with missing
   // experiential evidence must never be terminal: the task parks fail-closed
-  // with unattributable_reason=qa-visual-loop-unavailable instead of
+  // with unattributable_reason=qa-visual-loop-unavailable (artifact surface)
+  // or qa-terminal-loop-unavailable (terminal surface) instead of
   // transitioning to done. Code, not prompt text: the check reads the
   // machine-readable verdict via lib/read-ooda-verdict.js, which reports
   // visual_loop_unavailable from the OODA log's NOT POSSIBLE browser steps
-  // and the verdict's missing_evidence tool-unavailability notes.
-  if (step.name === "QA" && qaVisual && verdictPassed === true) {
+  // and terminal_loop_unavailable from NOT POSSIBLE terminal steps, plus the
+  // verdict's missing_evidence tool-unavailability notes.
+  if (step.name === "QA" && qaExperiential && verdictPassed === true) {
     var qaLoopDir = crewHome + "/task-evidence/" + taskId + "/postchange";
+    var qaLoopSurface = SURFACE_TERMINAL ? "terminal" : "visual";
+    var qaLoopReason = SURFACE_TERMINAL ? "qa-terminal-loop-unavailable" : "qa-visual-loop-unavailable";
     var qaLoopOut = "";
     try {
       var qaLoopCheck = await agent(
-        "Check the QA visual loop's availability.\n" +
+        "Check the QA " + qaLoopSurface + " loop's availability.\n" +
         "Run: node " + crewHome + "/current/lib/read-ooda-verdict.js --dir " + qaLoopDir + " --expect PASS\n" +
         "Return JSON { \"output\": \"<the command's full stdout, trimmed>\" } and nothing else.",
-        { key: attemptKey("qa-visual-loop-check-" + taskId, totalReworkCount), label: "Checking QA visual-loop availability",
+        { key: attemptKey("qa-" + qaLoopSurface + "-loop-check-" + taskId, totalReworkCount), label: "Checking QA " + qaLoopSurface + "-loop availability",
           schema: { type: "object", properties: { output: { type: "string" } }, required: ["output"] } }
       );
       qaLoopOut = (qaLoopCheck && qaLoopCheck.output ? qaLoopCheck.output : "").trim();
@@ -2452,14 +2565,18 @@ while (i < STEPS.length) {
       qaLoopGate = null;
     }
     if (!qaLoopGate || qaLoopGate.ok !== true) {
-      log("QA visual-loop check unreadable — cannot confirm experiential evidence; parking fail-closed");
-      return await parkTask("QA visual loop unverifiable (unattributable_reason=qa-visual-loop-unavailable): 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.");
+      log("QA " + qaLoopSurface + "-loop check unreadable — cannot confirm experiential evidence; parking fail-closed");
+      return await parkTask("QA " + qaLoopSurface + " loop unverifiable (unattributable_reason=" + qaLoopReason + "): 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.");
     }
-    if (qaLoopGate.visual_loop_unavailable === true) {
-      log("QA visual loop unavailable — parking fail-closed (unattributable_reason=qa-visual-loop-unavailable), never done");
-      return await parkTask("QA visual loop unavailable (unattributable_reason=qa-visual-loop-unavailable): 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.");
+    var qaLoopUnavailable = SURFACE_TERMINAL ? qaLoopGate.terminal_loop_unavailable : qaLoopGate.visual_loop_unavailable;
+    if (qaLoopUnavailable === true) {
+      log("QA " + qaLoopSurface + " loop unavailable — parking fail-closed (unattributable_reason=" + qaLoopReason + "), never done");
+      return await parkTask("QA " + qaLoopSurface + " loop unavailable (unattributable_reason=" + qaLoopReason + "): " +
+        (SURFACE_TERMINAL
+          ? "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 " + REPO_PATH + ", 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 visual-loop guard passed: experiential evidence present");
+    log("QA " + qaLoopSurface + "-loop guard passed: experiential evidence present");
   }
 
   // Deterministic closeout: no formatter agent. The verdict is mechanical
@@ -2683,9 +2800,12 @@ while (i < STEPS.length) {
     captureTargets = ctm ? ctm[1].trim().slice(0, 300) : "";
   }
 
-  // Capture Sage's experiential flag (machine-read marker line).
+  // Capture Sage's experiential flag (machine-read marker line) and the
+  // terminal targets for terminal-surface tasks.
   if (step.name === "Triage" && passed) {
     isExperiential = extractExperiential(workerText);
+    var ttm = /^terminal_targets:\s*(.+)/im.exec(workerText);
+    terminalTargets = ttm ? ttm[1].trim().slice(0, 300) : "";
   }
 
   // Capture the accepted Build report's machine-readable release decision.