muse-crew 0.8.0 → 0.9.0

package/workflows/bugfix.js

@@ -115,6 +115,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";
@@ -528,7 +558,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);
     }
   }
@@ -779,6 +809,10 @@ let layerResolved = 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
@@ -1083,13 +1117,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" }
@@ -1097,6 +1131,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
@@ -1189,9 +1251,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");
@@ -1215,13 +1277,17 @@ while (i < STEPS.length) {
     }
   }
 
-  // Visual verdict routing (2026-09-15): experiential artifact tasks route
-  // to Hazel's own experiential QA instructions below — she drives the
-  // see-act loop herself and owns the visual verdict (verdict.json +
+  // Experiential verdict routing (2026-09-15): experiential tasks on a
+  // classified surface route to Hazel's own experiential QA instructions
+  // below — she drives the surface herself (see-act loop for artifact,
+  // terminal loop for terminal) and owns the verdict (verdict.json +
   // verdicts.jsonl). No parent verdict gate remains.
-  var qaVisual = false;
+  var qaArtifact = false;
+  var qaTerminal = false;
   if (step.name === "QA") {
-    qaVisual = (await resolveExperiential()) === "yes" && PUBLISH_TYPE === "artifact";
+    var qaExp = (await resolveExperiential()) === "yes";
+    qaArtifact = qaExp && SURFACE_ARTIFACT;
+    qaTerminal = qaExp && SURFACE_TERMINAL;
   }
 
   // Reproduce-layer routing (2026-09-16): Sage's Triage classifies the bug's
@@ -1239,11 +1305,22 @@ 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 bugfix workflow assignment.\nIf the task needs decomposition, note that in your assessment.\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.\nLAYER FLAG: classify the bug's layer — where the reported misbehavior lives. artifact: user-facing behavior of the project's rendered artifact (something a user sees or clicks). engine: the crew's own machinery — workflows, lib scripts, shell scripts, tests, scheduler. docs: a documentation gap or error. End your report with exactly one line on its own, lowercase, unrephrased: layer: artifact — or layer: engine — or layer: docs. This line is machine-read. If the bug genuinely spans layers, pick the layer where reproduction must happen and note the ambiguity in prose.";
+    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 bugfix workflow assignment.\nIf the task needs decomposition, note that in your assessment.\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.\nLAYER FLAG: classify the bug's layer — where the reported misbehavior lives. artifact: user-facing behavior of the project's rendered artifact (something a user sees or clicks). engine: the crew's own machinery — workflows, lib scripts, shell scripts, tests, scheduler. docs: a documentation gap or error. End your report with exactly one line on its own, lowercase, unrephrased: layer: artifact — or layer: engine — or layer: docs. This line is machine-read. If the bug genuinely spans layers, pick the layer where reproduction must happen and note the ambiguity in prose.";
 
   } else if (step.name === "Reproduce") {
     if (reproLayer !== "engine" && reproLayer !== "docs") {
-      instructions = "Reproduce the bug from a user's perspective — by USING the artifact, not by reading data. You are CODE-BLIND — do NOT read source code.\n" +
+      if (SURFACE_TERMINAL) {
+        instructions = "Reproduce the bug from a user's perspective — by USING the CLI, not by reading source code. You are CODE-BLIND — do NOT read source code.\n" +
+        "This project's user-facing surface is a terminal: a command-line interface. Read the shared UX bar FIRST: " + UX_DOCTRINE_PATH + " — it is what correct CLI behavior looks like.\n" +
+        "a. Work in the project checkout at " + REPO_PATH + " — that exact checkout, not any other copy of the project on disk. Drive the CLI the way a user would: start with --help to discover the surface, then the commands the bug report implicates.\n" +
+        "b. Bounded CLI loop, at most 8 commands: drive the CLI to TRIGGER the reported bug. For EVERY command, save a transcript file under " + crewHome + "/task-evidence/" + taskId + "/repro/ named 01-<slug>.txt, 02-<slug>.txt, ... — each transcript holds the exact command line, its stdout, its stderr, and its exit code. Never invent output: a transcript you did not run is not evidence.\n" +
+        "c. After EVERY command, append it to the OODA report: node " + crewHome + "/current/lib/append-ooda-step.js --log " + crewHome + "/task-evidence/" + taskId + "/repro/ooda-log.jsonl --attempt \"1\" --step <N> --action terminal --exit <exit-code> --transcript <the transcript file you saved> --observation \"<1-2 sentences: what the command showed and what you concluded>\" — the script requires --transcript for terminal actions and rejects --screenshot (there is nothing to see). Steps are strictly monotonic: your first step is --step 1, then 2, 3, ... 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 the output showed and what it means, not just what you ran. A command you ran but did not log is invisible to everyone after you. If the CLI will not run at all (missing runtime, broken install), log ONE step with --exit 3, --observation \"NOT POSSIBLE: <reason>\" and a transcript holding the failed invocation, then fall back to the data-level investigation at the end.\n" +
+        "Data-level fallback (only if the CLI loop above is NOT POSSIBLE): run in shell and read the stdout JSON:\n" + crewCmd("get-state", {}) + "\n" +
+        "This returns current sessions, events, and tasks — capture concrete evidence from the data you retrieve.\n" +
+        "Report your reproduction steps and evidence as plain prose.\n" +
+        "End your report with exactly one line: VERDICT: PASS if you reproduced the reported bug (your transcripts show the reported misbehavior), VERDICT: FAIL if you could not. --expected names the bug as reported (its CLI manifestation); --actual names what your commands actually showed. Checks you could not run are evidence gaps, not silent drops: name every one in --missing. First ensure the OODA log exists even if you logged zero steps (touch " + crewHome + "/task-evidence/" + taskId + "/repro/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 + "/repro/ --attempt \"1\" --verdict <PASS|FAIL|NOT_POSSIBLE> --summary \"<one line>\" --expected \"<the bug as reported — its CLI manifestation>\" --actual \"<what your commands actually showed>\" --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 or NOT_POSSIBLE verdict without a machine-readable --reason cannot be written — state the reason.";
+      } else {
+        instructions = "Reproduce the bug from a user's perspective — by USING the artifact, not by reading data. You are CODE-BLIND — do NOT read source code.\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" +
       "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 fall back to the data-level investigation at the end.\n" +
       "a. Verify the built artifact exists: test -d ~/workspace/ts-spaces/" + PUBLISH_SLUG + "/client/dist && test -f ~/workspace/ts-spaces/" + PUBLISH_SLUG + "/server/dist/actions.js — if either is missing, report NOT POSSIBLE: built artifact not present at ~/workspace/ts-spaces/" + PUBLISH_SLUG + " and fall back to the data-level investigation.\n" +
@@ -1259,6 +1336,7 @@ while (i < STEPS.length) {
       "This returns current sessions, events, and tasks — capture concrete evidence from the data you retrieve.\n" +
       "Report your reproduction steps and evidence as plain prose.\n" +
       "End your report with exactly one line: VERDICT: PASS if you reproduced the reported bug (your frames show the reported misbehavior), VERDICT: FAIL if you could not. --expected names the bug as reported (its visible manifestation); --actual names what your frames actually showed. Checks you could not run are evidence gaps, not silent drops: name every one in --missing. First ensure the OODA log exists even if you logged zero steps (touch " + crewHome + "/task-evidence/" + taskId + "/repro/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 + "/repro/ --attempt \"1\" --verdict <PASS|FAIL|NOT_POSSIBLE> --summary \"<one line>\" --expected \"<the bug as reported — its visible manifestation>\" --actual \"<what your frames actually showed>\" --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 or NOT_POSSIBLE verdict without a machine-readable --reason cannot be written — state the reason.";
+      }
     } else if (reproLayer === "engine") {
       instructions = "REPRODUCE AT THE BUG'S LAYER. Triage classified this bug as layer: engine — it lives in the crew's own machinery (workflows, lib scripts, shell scripts, tests, scheduler), not in the rendered artifact. Reproduce it deterministically with shell commands in the repo checkout at " + REPO_PATH + " — that exact checkout, not any other copy of the project on disk. You are NOT code-blind here: reading source to find the failing mechanism is expected.\n" +
       "Do NOT start an artifact server. Do NOT invoke see-act.js or any browser loop — the experiential loop is for artifact-layer bugs only, and driving it here fails the phase loudly. If you cannot reproduce without a browser, say so and FAIL with a reason naming the layer you tried.\n" +
@@ -1278,11 +1356,15 @@ 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).";
-    }
-    instructions = "Update the task with a solution-oriented spec. Research options, pick the shortest path.\nThe builder will edit source files in a git worktree.\nProject: " + PROJECT_DESC + "\nWrite it clearly enough that the builder does not need to ask questions.\nReport back in plain prose — what you specified." + mapGatePara;
+        (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 = "Update the task with a solution-oriented spec. Research options, pick the shortest path.\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 + "\nWrite it clearly enough that the builder does not need to ask questions.\nReport back in plain prose — what you specified." + mapGatePara;
 
   } else if (step.name === "Build") {
     instructions = "STEP 1: Prepare your worktree.\n" +
@@ -1297,6 +1379,8 @@ while (i < STEPS.length) {
       "This is the project source: " + PROJECT_DESC + "\n" +
       "Edit the TypeScript 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" +
@@ -1341,6 +1425,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" +
@@ -2255,10 +2341,11 @@ while (i < STEPS.length) {
       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.";
-    // qaVisual: Hazel runs the experiential see-act loop herself (STEP 1
+    // qaArtifact: Hazel runs the experiential see-act loop herself (STEP 1
     // below) and owns the visual verdict — no parent capture protocol.
-    if (qaVisual) {
-      instructions = "You are code-blind QA. You NEVER read source files. Public docs are not source — read them as a user would.\n" +
+    if (qaArtifact) {
+      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. 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: " + 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" +
         "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" +
@@ -2282,6 +2369,39 @@ while (i < STEPS.length) {
         "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 " + 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 \"<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 (qaTerminal) {
+      // 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 btermEvidence = crewHome + "/task-evidence/" + taskId + "/postchange";
+      var btermTargetsLine = 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 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 " + 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: " + 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 " + 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 " + 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" +
+        "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 " + 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 (PUBLISH_TYPE === "artifact") {
       instructions = "PROVENANCE CHECK (this project publishes to a dashboard artifact).\n" +
@@ -2490,8 +2610,8 @@ while (i < STEPS.length) {
   // gate, a bare VERDICT: FAIL with an all-positive report (canary
   // 2026-09-15, task 1d692d91) rebuilt nothing and parked at Publish on an
   // unobserved artifact build. The gate applies only to the experiential QA
-  // path (qaVisual), the only path that writes verdict.json.
-  if (step.name === "QA" && qaVisual && verdictPassed !== null) {
+  // path (qaArtifact / qaTerminal), the paths that write verdict.json.
+  if (step.name === "QA" && (qaArtifact || qaTerminal) && verdictPassed !== null) {
     var qaVerdictDir = crewHome + "/task-evidence/" + taskId + "/postchange";
     var qaVerdictExpect = verdictPassed ? "PASS" : "FAIL";
     var qaVerdictOut = "";
@@ -2541,23 +2661,28 @@ while (i < STEPS.length) {
     }
     log("QA verdict.json closeout gate passed: verdict.json agrees with prose VERDICT: " + qaVerdictExpect);
 
-    // 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 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
-    // transitioning to done. Code, not prompt text: visual_loop_unavailable
-    // comes from lib/read-ooda-verdict.js (the OODA log's NOT POSSIBLE
-    // browser steps and the verdict's missing_evidence tool-unavailability
-    // notes), already parsed into qaVerdictGate above.
-    if (verdictPassed === true && qaVerdictGate.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.");
+    // 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. A PASS verdict with missing experiential evidence must
+    // never be terminal: the task parks fail-closed 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 loop-availability
+    // flags come from lib/read-ooda-verdict.js (the OODA log's NOT POSSIBLE
+    // steps and the verdict's missing_evidence tool-unavailability notes),
+    // already parsed into qaVerdictGate above.
+    var qaLoopSurface = SURFACE_TERMINAL ? "terminal" : "visual";
+    var qaLoopReason = SURFACE_TERMINAL ? "qa-terminal-loop-unavailable" : "qa-visual-loop-unavailable";
+    var qaLoopUnavailable = SURFACE_TERMINAL ? 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("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");
   }
 
   // Reproduce wrong-layer guard (2026-09-16): for engine/docs tasks the
@@ -2920,6 +3045,8 @@ while (i < STEPS.length) {
   // Capture Sage's experiential flag (machine-read marker line).
   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 Sage's bug-layer flag (machine-read marker line): drives the
     // Reproduce strategy dispatch. Unknown (null) degrades to "artifact" at
     // resolveLayer — never parks on a garbled line.

package/workflows/chore.js

@@ -172,6 +172,31 @@ const WORKTREE_HINT = REPO_PATH + "/.worktrees/" + taskId;
 const WORKTREE_PRESERVED_HINT = ".worktrees/" + taskId;
 
 const PUBLISH_TYPE = projectConfig.deploy_type || "";
+// User-facing surface for experiential routing: 'artifact' (a rendered
+// web UI) | 'terminal' (a CLI) | null (unclassified). 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 behavior (the migration does not backfill
+// the column).
+// Chore has no QA phase: Capture stays artifact-only (terminal baselines
+// would be unused evidence), but the crew still specs, builds, and reviews
+// terminal-surface changes against the shared bar.
+const ENV_TYPE = projectConfig.environment_type || null;
+const SURFACE_ARTIFACT = (PUBLISH_TYPE === "artifact" || ENV_TYPE === "artifact");
+const SURFACE_TERMINAL = (!SURFACE_ARTIFACT && ENV_TYPE === "terminal");
+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";
@@ -585,7 +610,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);
     }
   }
@@ -1090,8 +1115,11 @@ 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"));
+    // Chore has no QA phase, so Capture stays artifact-only: terminal
+    // baselines would be unused evidence. (Chore crew members are still on
+    // the terminal-UX page via the Triage/Map/Build/Review prompts.)
+    if (capExp !== "yes" || !SURFACE_ARTIFACT) {
+      log("Capture skipped for task " + taskId + " — " + (capExp !== "yes" ? "not experiential" : "no QA phase to consume terminal-surface baselines"));
       await agent(
         "Update the session and log the event.\n" +
         "Run in shell and return the stdout verbatim:\n" + crewCmd("record-phase", {
@@ -1180,9 +1208,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 + artifact 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_ARTIFACT) {
       var gateStatus = await baselineStatus();
       if (!gateStatus.baseline_found) {
         log("Map gate: no baseline evidence for experiential task " + taskId + " — bouncing to Capture");
@@ -1208,7 +1236,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 chore workflow assignment.\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. 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 chore workflow assignment.\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 captures. 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 = "";
@@ -1216,11 +1244,14 @@ 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 captures: " + mapBaselineRefs + " — consult them 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).";
     }
-    instructions = "Research options, pick the path, write a clear spec for the builder.\nThe builder will edit source files in a git worktree of the project at " + REPO_PATH + ".\nProject: " + PROJECT_DESC + "\nTo understand the current code, read source files directly using the read tool. 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).\nIdentify the exact files and changes needed. Be specific: file paths, what to add or change.\nReport back in plain prose — what you specified." + mapGatePara;
+    instructions = "Research options, pick the path, write a clear spec for the builder.\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 — build and review 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 — build and review against this spec and the shared bar at " + UX_DOCTRINE_PATH + ".\n" : "") +
+      "The builder will edit source files in a git worktree of the project at " + REPO_PATH + ".\nProject: " + PROJECT_DESC + "\nTo understand the current code, read source files directly using the read tool. 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).\nIdentify the exact files and changes needed. Be specific: file paths, what to add or change.\nReport back in plain prose — what you specified." + mapGatePara;
 
   } else if (step.name === "Build") {
     instructions = "STEP 1: Prepare your worktree.\n" +
@@ -1235,6 +1266,8 @@ while (i < STEPS.length) {
       "This is the project source: " + PROJECT_DESC + "\n" +
       "Edit the TypeScript source files directly. Do NOT use artifact_edit — that happens in the Publish phase.\n" +
       "Do not add unrequested features.\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" +
@@ -1279,6 +1312,8 @@ while (i < STEPS.length) {
       "You can also read specific files in the worktree at:\n" +
       WORKTREE_HINT + "/\n\n" +
       "Check quality, correctness, 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" +

package/workflows/crew-dispatch.js

@@ -383,7 +383,11 @@ for (var pi = 0; pi < projects.length; pi++) {
     repo_path: proj.repo_path,
     deploy_type: proj.deploy_type,
     deploy_slug: proj.deploy_slug,
-    description: proj.description
+    description: proj.description,
+    // The user-facing surface for experiential QA routing (artifact |
+    // terminal | null=unclassified). Carried alongside deploy_type — it is a
+    // separate axis, not a redeclaration of the deployment target.
+    environment_type: proj.environment_type || null
   };
 }
 

package/workflows/crew-init.js

@@ -362,13 +362,30 @@ try {
     "   node " + crewHome + "/current/lib/crew-api.js --crew-home " + crewHome + " get-project --json '{\"id\": \"" + dashboardSlug + "\"}'\n" +
     "2. If it returns a project (ok: true):\n" +
     "   a. Compare its repo_path to: " + gateFacts.dashboardRepoExpanded + "\n" +
-    "   b. If they match, return { action: \"exists\", project_id: \"" + dashboardSlug + "\" }.\n" +
+    "   b. If they match, make sure the project declares its user-facing surface:\n" +
+    "      node " + crewHome + "/current/lib/crew-api.js --crew-home " + crewHome + " get-project --json '{\"id\": \"" + dashboardSlug + "\"}'\n" +
+    "      If the returned project has environment_type null, run:\n" +
+    "      node " + crewHome + "/current/lib/crew-api.js --crew-home " + crewHome + " update-project --json '{\"id\": \"" + dashboardSlug + "\", \"environment_type\": \"artifact\"}'\n" +
+    "      (the dashboard's user-facing surface is its rendered web UI).\n" +
+    "      Return { action: \"exists\", project_id: \"" + dashboardSlug + "\" }.\n" +
     "   c. If they differ, repair it:\n" +
-    "      node " + crewHome + "/current/lib/crew-api.js --crew-home " + crewHome + " update-project --json '{\"id\": \"" + dashboardSlug + "\", \"repo_path\": \"" + safeDashboardRepo + "\"}'\n" +
+    "      node " + crewHome + "/current/lib/crew-api.js --crew-home " + crewHome + " update-project --json '{\"id\": \"" + dashboardSlug + "\", \"repo_path\": \"" + safeDashboardRepo + "\", \"environment_type\": \"artifact\"}'\n" +
     "      Return { action: \"repaired\", project_id: \"" + dashboardSlug + "\" }.\n" +
     "3. If not found (error), create it:\n" +
-    "   node " + crewHome + "/current/lib/crew-api.js --crew-home " + crewHome + " create-project --json '{\"id\": \"" + dashboardSlug + "\", \"display_name\": \"" + safeDashboardName + "\", \"repo_path\": \"" + safeDashboardRepo + "\", \"deploy_type\": \"artifact\", \"deploy_slug\": \"" + dashboardSlug + "\", \"description\": \"The dashboard task service — the crew\\u0027s first project\"}'\n" +
+    "   node " + crewHome + "/current/lib/crew-api.js --crew-home " + crewHome + " create-project --json '{\"id\": \"" + dashboardSlug + "\", \"display_name\": \"" + safeDashboardName + "\", \"repo_path\": \"" + safeDashboardRepo + "\", \"deploy_type\": \"artifact\", \"deploy_slug\": \"" + dashboardSlug + "\", \"environment_type\": \"artifact\", \"description\": \"The dashboard task service — the crew\\u0027s first project\"}'\n" +
     "   Return { action: \"created\", project_id: \"" + dashboardSlug + "\" }.\n\n" +
+    "4. Seed the update watcher's trusted dashboard base (enrollment) — the\n" +
+    "   commit this installation starts from. Only ever seeds when no base\n" +
+    "   exists; an established base is never moved by a re-init:\n" +
+    "   a. Run: git -C \"" + safeDashboardRepo + "\" rev-parse HEAD\n" +
+    "   b. If it prints a 40-hex sha, run:\n" +
+    "      node " + crewHome + "/current/lib/update-watch.js --crew-home " + crewHome + " --record-dashboard-sha <sha>\n" +
+    "      Exit 0 with 'already' in the output means a base is already enrolled —\n" +
+    "      that is the correct outcome, report it.\n" +
+    "   c. If rev-parse fails (empty repo), skip seeding and report\n" +
+    "      'base not seeded: empty repo' — the watcher will file the first\n" +
+    "      dashboard upgrade with oldSha unknown and park it with enrollment\n" +
+    "      guidance, fail-closed.\n\n" +
     "The repo_path must be the dashboard git repository — never the crew home.\n" +
     "Return JSON with action (\"exists\", \"repaired\", or \"created\") and project_id (string).",
     {

package/workflows/docs.js

@@ -62,6 +62,20 @@ const REPO_PATH = projectConfig.repo_path || "";
 if (!REPO_PATH) {
   throw new Error("Project '" + (inputs.project_id || "unknown") + "' has no repo_path configured — set it via updateproject before dispatching tasks.");
 }
+// UX surface resolution (same doctrine as standard.js/bugfix.js/chore.js):
+// environment_type is the canonical axis; docs have no deploy target, so
+// only environment_type resolves the surface here.
+const ENV_TYPE = projectConfig.environment_type || null;
+const SURFACE_TERMINAL = (ENV_TYPE === "terminal");
+const SURFACE_ARTIFACT = (ENV_TYPE === "artifact");
+// 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.
+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;
 
 if (!taskId) {
   throw new Error("task_id is required in args");
@@ -409,10 +423,13 @@ function describeWorkAgentFailure(stepName, identity, attempts) {
     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, confirm the docs workflow assignment.\nReport back in plain prose — your assessment.";
   } else if (step.name === "Write") {
     instructions = "Write or revise the documentation the task asks for.\nFollow Tate's voice — clear, conversational, no jargon unless it earns its place.\nDo your work in the project repository at " + REPO_PATH + " — all doc files go there, not under the crew home." +
+      (UX_DOCTRINE_PATH ? "\nJudge the docs against the shared UX bar at " + UX_DOCTRINE_PATH + " — it is what correct behavior looks like for this project's surface. " + (SURFACE_TERMINAL ? "When the docs describe CLI behavior (commands, flags, help text, error messages, exit codes), document what the user actually experiences, verified against the real CLI, never from source-code inference." : "When the docs describe the UI (screens, flows, visual states, copy), document what the user actually sees, verified against the real artifact, never from source-code inference.") : "") +
       (rejectionNotes ? "\n\nREWORK after review rejection. Address:\n" + rejectionNotes : "") +
       "\nReport back in plain prose — what you wrote and where.";
   } else if (step.name === "Review") {
-    instructions = "Review the docs independently and cold — clarity, accuracy, completeness.\nNo prior context from the writer.\nWrite your review as plain prose — findings, then decision. End your report with exactly one line: VERDICT: PASS if it passes, VERDICT: FAIL if it fails.";
+    instructions = "Review the docs independently and cold — clarity, accuracy, completeness.\nNo prior context from the writer." +
+      (UX_DOCTRINE_PATH ? "\nCheck the docs against the shared UX bar at " + UX_DOCTRINE_PATH + ". Flag any " + (SURFACE_TERMINAL ? "CLI" : "UI") + " claim you cannot verify — undocumented behavior and documented-but-wrong behavior both fail." : "") +
+      "\nWrite your review as plain prose — findings, then decision. End your report with exactly one line: VERDICT: PASS if it passes, VERDICT: FAIL if it fails.";
   }
 
   // Work agent returns the runtime's native envelope {"status": "ok",