muse-crew 0.17.2 → 0.17.3

package/lib/standard/phases/build.js

@@ -0,0 +1,120 @@
+// lib/standard/phases/build.js — Build (wren) phase module (sandbox exit,
+// Phase C Piece 1). Import-safe: no side effects on import, bare `node`
+// exits 0.
+//
+// Reads: Map session notes (the mapper spec), latest rejected Review/QA
+// session notes (rework), claim/session context.
+// Writes: completed/rejected session + event (notes = summarized report
+// incl. the machine-read `release:`/`version_bump:`/`repo_diff:`/`worktree:`
+// marker lines).
+// Transitions: ADVANCE → Review on pass. A VERDICT: FAIL records a
+// "rejected" session and still advances to Review (source fall-through:
+// Review's mechanical branch gate turns an empty failed build into a
+// rework bounce; only Review/QA rejections spend the shared budget).
+
+import {
+  runWorkBoundary, recordPhase, buildEventPreamble, summarizeReport,
+  closeoutPassed, ensureClaimed, crewApi, latestSessionNotes,
+  lifecycleEnvPrefix, log,
+} from "../../workflow-lib.js";
+import { extractReleaseDecision } from "../../extract.js";
+
+export const PHASE = { name: "Build", identity: "wren" };
+
+// latestRejectionNotes — the latest "rejected" session notes among the
+// verdict steps that bounce to Build (Review, QA). Cross-run durable:
+// re-derived from session notes so a run survives tick boundaries
+// (source: run-local rejectionNotes, set on every Review/QA rejection).
+async function latestRejectionNotes(env) {
+  var st = await crewApi(env, "get-state", { events_limit: 1 });
+  var sessions = (st && st.sessions) || [];
+  var best = null;
+  for (var i = 0; i < sessions.length; i++) {
+    var s = sessions[i];
+    if (s.task_id === env.taskId && (s.step === "Review" || s.step === "QA") && s.status === "rejected") {
+      if (!best || String(s.started_at || "") > String(best.started_at || "")) best = s;
+    }
+  }
+  return best ? (best.notes || "") : "";
+}
+
+// buildInstructions — pure function of ctx. The mapper spec and rejection
+// notes are stashed in ctx.state.memo.buildHandoffs by runPhase before the
+// call (keeps the signature pure). Instruction text verbatim from
+// workflows/standard.js (Build branch).
+export function buildInstructions(ctx) {
+  var env = ctx.env;
+  var h = (ctx.state.memo && ctx.state.memo.buildHandoffs) || { mapperSpec: "", rejectionNotes: "" };
+  return "STEP 1: Prepare your worktree.\n" +
+    "Run: " + lifecycleEnvPrefix(env) + " prepare " + env.taskId + "\n" +
+    "If the output says CREATED or REUSED, proceed. If it says ERROR, stop and report the failure clearly.\n\n" +
+    "HEARTBEAT: Start a background heartbeat loop NOW (before STEP 2) to signal you are still alive during this build. Run this once:\n" +
+    "(while node " + env.crewApiPinned + " --crew-home " + env.crewHome + " heartbeat-session --json '{\"id\": \"" + ctx.state.activeSessionId + "\"}' >/dev/null 2>&1; do sleep 900; done) &\n" +
+    "The loop heartbeats every 15 minutes and exits on its own when the session ends. This prevents the dispatcher from mistaking a long build for a dead session and launching a duplicate.\n\n" +
+    "STEP 2: Edit source files to implement the mapper's spec below.\n" +
+    (h.mapperSpec ? "MAPPER'S SPEC (implement exactly this):\n" + h.mapperSpec + "\n\n" : "") +
+    "Your working directory: " + env.worktreeHint + "/\n" +
+    "This is the project source: " + env.projectDesc + "\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" +
+    (env.surfaceTerminal ? "TERMINAL UX: build to the shared bar at " + env.uxDoctrinePath + " — --help text, error messages, and exit codes are user-facing and ship in this commit.\n" : "") +
+    (env.surfaceArtifact ? "ARTIFACT UX: build to the shared bar at " + env.uxDoctrinePath + " — 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" +
+    (env.publishType === "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" +
+    "version_bump: patch|minor|major — patch for fixes (default), minor for new behavior, major for breaking changes. Omit this line only when release is no.\n" +
+    "Example: release: yes\\nversion_bump: minor\n\n" : "") +
+    "STEP 3: Commit your changes.\n" +
+    "cd " + env.worktreeHint + "\n" +
+    "git add -A\n" +
+    "git commit -m \"" + env.safeTitle + "\"\n\n" +
+    "If the task's deliverable is runtime state (a cron definition, scheduler change, or dashboard/config state created outside the repo) and the repository genuinely needs no change, do NOT fabricate a commit: leave the branch with no commits ahead of the integration target and declare `repo_diff: none` in your report, naming the runtime-state deliverable. If you verified the deliverable is already on the integration target (a prior merge landed it — do NOT re-implement working code), make no commit and declare `repo_diff: none` in your report. The workflow verifies the claim mechanically from git — the task's own merge records, never your declaration, are the proof of delivery. Otherwise commit your changes normally.\n\n" +
+    (h.rejectionNotes ? "This is REWORK after rejection. Address these specific issues:\n" + h.rejectionNotes + "\n\n" : "") +
+    "Report back in plain prose: what you built and the outcome." +
+    (env.publishType === "npm" ? " End your report with the release: and version_bump: lines exactly as specified above — keep them on their own lines, lowercase, unrephrased — then a line `worktree: ` followed by the exact working directory path from above (copy it verbatim — it must match character-for-character), then a final line with exactly: VERDICT: PASS if the build is complete, VERDICT: FAIL if it is not." : " End your report with a line `worktree: ` followed by the exact working directory path from above (copy it verbatim — it must match character-for-character), then exactly one line: VERDICT: PASS if the build is complete, VERDICT: FAIL if it is not.");
+}
+
+export async function runPhase(ctx) {
+  var env = ctx.env, state = ctx.state;
+  var taskId = env.taskId;
+  var claimed = await ensureClaimed(env, state, PHASE);
+  if (claimed.type !== "CLAIMED") return claimed;
+
+  // Cross-run handoffs, re-derived from durable session notes (source:
+  // run-local mapperSpec/rejectionNotes).
+  state.memo.buildHandoffs = {
+    mapperSpec: await latestSessionNotes(env, "Map", "completed"),
+    rejectionNotes: await latestRejectionNotes(env),
+  };
+
+  var boundary = await runWorkBoundary(env, state, {
+    phase: PHASE.name, identity: PHASE.identity,
+    instructions: buildInstructions(ctx),
+    eventPreamble: buildEventPreamble(env, PHASE.name),
+    crewApiLine: true, verdictStep: true,
+  });
+  if (boundary.type !== "BOUNDARY_DONE") return boundary;
+
+  // Capture the accepted Build report's machine-readable release decision.
+  // Deterministic extraction from the full worker report. A missing or
+  // malformed declaration fails closed to null and Review rejects.
+  var passed = closeoutPassed(boundary);
+  var workerText = boundary.workerText;
+  var releaseDecision = passed ? extractReleaseDecision(workerText) : null;
+  state.memo.releaseDecision = releaseDecision;
+  var summary = summarizeReport(workerText);
+  var status = passed ? "completed" : "rejected";
+  await recordPhase(env, {
+    task_id: taskId,
+    session: { id: state.activeSessionId, task_id: taskId, identity: PHASE.identity, step: PHASE.name, status: status, notes: summary },
+    event: { task_id: taskId, type: status, identity: PHASE.identity, message: PHASE.name + " " + status + " by " + PHASE.identity },
+  });
+  if (!passed) {
+    // Source fall-through: a failed Build still advances — Review's
+    // mechanical branch gate owns the empty-branch bounce.
+    log("Build rejected for task " + taskId + " — advancing to Review (source fall-through)");
+  } else {
+    log("Build complete for task " + taskId);
+  }
+  return { type: "ADVANCE", next: "Review" };
+}

package/lib/standard/phases/capture.js

@@ -0,0 +1,163 @@
+// lib/standard/phases/capture.js — Capture (hazel) phase module (sandbox
+// exit, Phase C Piece 1). Import-safe: no side effects on import, bare
+// `node` exits 0.
+//
+// Reads: experiential status (durable Triage session notes), surface
+// classification, baseline note events, terminal targets.
+// Writes: exact-prefix `baseline:` note events, completed/failed session +
+// event. The durable cross-run handoff is the `baseline:` notes themselves
+// (Map's gate reads them).
+// Transitions: ADVANCE → Map on every path except the park path (PARK
+// with the baseline-request reason).
+//
+// Worker-layer shape: the artifact-surface paths are fully mechanical
+// (direct Crew API calls). The terminal-surface baseline is creative
+// (Hazel drives the CLI herself, reads transcripts) and crosses the work
+// boundary via NEED_SPAWN; the phase owns the deterministic recording
+// (log-event + record-phase) after the boundary resolves. Map-gate
+// bounce re-visits pass state.gateBounceCount as the spawn visitSuffix so
+// the second visit mints fresh keys.
+
+import {
+  resolveExperiential, baselineStatus, recordPhase, logEvent, parkTask,
+  crewApi, runWorkBoundary, buildEventPreamble, closeoutPassed,
+  ensureClaimed, log,
+} from "../../workflow-lib.js";
+
+export const PHASE = { name: "Capture", identity: "hazel" };
+
+// buildInstructions — the creative terminal-baseline prompt. Steps 1–5
+// verbatim from workflows/standard.js (Capture branch); the recording tail
+// is adapted: the worker layer owns log-event / record-phase
+// deterministically, so the agent ends with a machine-read baseline
+// declaration instead of running the recording commands itself.
+export function buildInstructions(ctx) {
+  var env = ctx.env, state = ctx.state;
+  var termBaseDir = env.taskEvidenceDir + "/baseline";
+  var terminalTargets = state.memo.terminalTargets || "";
+  return "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 " + env.repoPath + " (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" +
+    "End your report with exactly one line on its own: either `baseline: captured (terminal transcripts: <comma-separated filenames>)` listing the transcript files you archived, or `baseline: none (terminal targets not runnable: <reason>)` when the CLI cannot run from the pre-change tree — never fabricate a transcript. This line is machine-read.\n" +
+    "Report back in plain prose: which commands you ran and what the pre-change baseline looks like.";
+}
+
+// buildTerminalBaselineInstructions — legacy alias for buildInstructions
+// (the creative terminal-baseline prompt).
+export function buildTerminalBaselineInstructions(ctx) {
+  return buildInstructions(ctx);
+}
+
+export async function runPhase(ctx) {
+  var env = ctx.env, state = ctx.state;
+  var taskId = env.taskId;
+  var claimed = await ensureClaimed(env, state, PHASE);
+  if (claimed.type !== "CLAIMED") return claimed;
+
+  var capExp = await resolveExperiential(env, state);
+  var surfaceClassified = env.surfaceArtifact || env.surfaceTerminal;
+  if (capExp !== "yes" || !surfaceClassified) {
+    log("Capture skipped for task " + taskId + " — " + (capExp !== "yes" ? "not experiential" : "surface unclassified"));
+    await recordPhase(env, {
+      task_id: taskId,
+      session: { id: state.activeSessionId, task_id: taskId, identity: PHASE.identity, step: PHASE.name, status: "completed", notes: "Capture skipped — not an experiential task on a classified surface" },
+      event: { task_id: taskId, type: "completed", identity: PHASE.identity, message: "Capture completed by " + PHASE.identity },
+    });
+    return { type: "ADVANCE", next: "Map" };
+  }
+
+  // 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 (env.surfaceTerminal) {
+    log("Capture: terminal-surface baseline for task " + taskId + " — Hazel drives the CLI herself");
+    var visitSuffix = (state.gateBounceCount > 0) ? "-g" + state.gateBounceCount : "";
+    var boundary = await runWorkBoundary(env, state, {
+      phase: PHASE.name, identity: PHASE.identity,
+      instructions: buildInstructions(ctx),
+      eventPreamble: buildEventPreamble(env, PHASE.name),
+      crewApiLine: true, verdictStep: false,
+      visitSuffix: visitSuffix,
+    });
+    if (boundary.type !== "BOUNDARY_DONE") return boundary;
+    var workerText = boundary.workerText || "";
+    var decls = [];
+    var dm;
+    var dRe = /^baseline:\s*(captured|none)\b.*$/gim;
+    while ((dm = dRe.exec(workerText)) !== null) decls.push(dm[0].trim());
+    if (decls.length === 0 || !closeoutPassed(boundary)) {
+      var failNotes = "Terminal baseline agent produced no machine-read baseline declaration — cannot record evidence";
+      log("Capture: " + failNotes + " for task " + taskId);
+      await recordPhase(env, {
+        task_id: taskId,
+        session: { id: state.activeSessionId, task_id: taskId, identity: PHASE.identity, step: PHASE.name, status: "failed", notes: failNotes },
+        event: { task_id: taskId, type: "failed", identity: PHASE.identity, message: "Capture failed for task " + taskId + " — no baseline declaration" },
+      });
+      return { type: "FAILED", reason: failNotes };
+    }
+    var declaration = decls[decls.length - 1];
+    var captured = /^baseline:\s*captured\b/i.test(declaration);
+    await logEvent(env, { task_id: taskId, type: "note", identity: PHASE.identity, message: declaration });
+    await recordPhase(env, {
+      task_id: taskId,
+      session: { id: state.activeSessionId, task_id: taskId, identity: PHASE.identity, step: PHASE.name, status: "completed",
+        notes: captured ? "Terminal baseline captured by the QA agent (transcripts archived)" : "baseline: none — terminal targets not runnable, final QA judges on rubric alone" },
+      event: { task_id: taskId, type: "completed", identity: PHASE.identity, message: "Capture completed by " + PHASE.identity },
+    });
+    return { type: "ADVANCE", next: "Map" };
+  }
+
+  var capStatus = await baselineStatus(env);
+  // See docs/decisions/qa-reproduce.md#stale-decision-guard: a stale baseline decision parks fail-closed.
+  var baselineLatestMessage = ("baseline: " + capStatus.baseline_kind + capStatus.baseline_refs).trim();
+  var baselineStale = env.visualProtocolAvailable && baselineLatestMessage === "baseline: none (visual protocol unavailable)";
+  if (capStatus.baseline_found && !baselineStale) {
+    var evidenceN = capStatus.evidence_count + 1;
+    var carryNote = "baseline: " + capStatus.baseline_kind + " (#" + evidenceN + " carries forward prior:" + capStatus.baseline_refs + ")";
+    log("Capture: baseline evidence already recorded for task " + taskId + " (" + capStatus.baseline_kind + ") — logging per-attempt carry-forward note (evidence #" + evidenceN + ")");
+    await logEvent(env, { task_id: taskId, type: "note", identity: PHASE.identity, message: carryNote });
+    await recordPhase(env, {
+      task_id: taskId,
+      session: { id: state.activeSessionId, task_id: taskId, identity: PHASE.identity, step: PHASE.name, status: "completed",
+        notes: "Baseline evidence already recorded: " + capStatus.baseline_kind + " " + capStatus.baseline_refs + " (evidence #" + evidenceN + ")" },
+      event: { task_id: taskId, type: "completed", identity: PHASE.identity, message: "Capture completed by " + PHASE.identity },
+    });
+    return { type: "ADVANCE", next: "Map" };
+  }
+
+  var attemptN = capStatus.requested_count + 1;
+  if (capStatus.requested_count >= 2) {
+    log("Capture: baseline capture unavailable after 2 requests for task " + taskId + " — recording baseline:none");
+    await logEvent(env, { task_id: taskId, type: "note", identity: PHASE.identity, message: "baseline: none (capture unavailable after 2 attempts)" });
+    await recordPhase(env, {
+      task_id: taskId,
+      session: { id: state.activeSessionId, task_id: taskId, identity: PHASE.identity, step: PHASE.name, status: "completed", notes: "baseline: none — final QA judges on rubric alone" },
+      event: { task_id: taskId, type: "completed", identity: PHASE.identity, message: "Capture completed by " + PHASE.identity },
+    });
+    return { type: "ADVANCE", next: "Map" };
+  }
+
+  log("Capture: requesting baseline capture (attempt " + attemptN + ") for task " + taskId);
+  await logEvent(env, { task_id: taskId, type: "note", identity: PHASE.identity, message: "baseline: requested (attempt " + attemptN + ")" });
+  await crewApi(env, "upsert-session", {
+    id: state.activeSessionId, task_id: taskId, identity: PHASE.identity, step: PHASE.name, status: "failed",
+    notes: "Baseline capture requested (attempt " + attemptN + ") — parent protocol: run the baseline capture protocol in docs/visual-verdict.md, then re-queue the task at Map. The Capture step re-checks baseline evidence when re-run.",
+  });
+  if (!env.visualProtocolAvailable) {
+    log("Capture: visual protocol not available (VISUAL_PROTOCOL_AVAILABLE=false) — recording baseline:none instead of parking for task " + taskId);
+    await logEvent(env, { task_id: taskId, type: "note", identity: PHASE.identity, message: "baseline: none (visual protocol unavailable)" });
+    await recordPhase(env, {
+      task_id: taskId,
+      session: { id: state.activeSessionId, task_id: taskId, identity: PHASE.identity, step: PHASE.name, status: "completed", notes: "baseline: none — visual protocol unavailable, final QA judges on rubric alone" },
+      event: { task_id: taskId, type: "completed", identity: PHASE.identity, message: "Capture completed by " + PHASE.identity },
+    });
+    return { type: "ADVANCE", next: "Map" };
+  }
+  var parked = await parkTask(env, "Baseline capture requested (attempt " + attemptN + ") — parent: run the baseline capture protocol in docs/visual-verdict.md, then re-queue the task at Map");
+  return parked;
+}

package/lib/standard/phases/integrate.js

@@ -0,0 +1,172 @@
+// lib/standard/phases/integrate.js — Integrate (wren) phase module (sandbox
+// exit, Phase C Piece 1). Import-safe: no side effects on import, bare
+// `node` exits 0.
+//
+// Reads: claim/session context, merge outcome markers (MERGED /
+//   MERGED_EMPTY / PUSHED) from the pinned integrate script's verbatim
+//   output, mechanical verify-merge result, qa-deploy.mjs result.
+// Writes: completed/failed session + event (notes carry deploy markers),
+//   a rebuilt QA bundle via qa-deploy.mjs (versioned artifact projects).
+// Transitions: ADVANCE → Publish on verified PASS. FAILED on any
+//   operational failure (verdict FAIL, verify-merge failure, deploy
+//   failure) — the dispatcher retries under its consecutive-failure cap.
+//
+// 0.16.0 note: the BUILD_NUMBER bump and REQUIRED_BUILD marker were
+// deliberately removed from the source (commit b7319ca). Freshness is
+// constructive (rebuild via qa-deploy.mjs), not numeric.
+
+import {
+  runWorkBoundary, recordPhase, buildEventPreamble, summarizeReport,
+  closeoutPassed, ensureClaimed, lifecycle, parkTask, runCmd,
+  lifecycleEnvPrefix, log,
+} from "../../workflow-lib.js";
+import { join } from "path";
+import { readFileSync, writeFileSync } from "fs";
+
+export const PHASE = { name: "Integrate", identity: "wren" };
+
+// buildInstructions — pure function of ctx. Verbatim from
+// workflows/standard.js (Integrate branch).
+export function buildInstructions(ctx) {
+  var env = ctx.env;
+  return "Integrate the change into the main codebase.\\n" +
+    "Run the integration script:\\n" +
+    lifecycleEnvPrefix(env) + env.lifecycle + " integrate " + env.taskId + "\\n\\n" +
+    "The script merges, reconciles, records, and pushes under the merge lock — report what it prints, do not improvise git commands.\\n" +
+    "The script prints machine-readable marker lines:\\n" +
+    "- INTEGRATION_TARGET=<branch-or-ref> — the target you merged into\\n" +
+    "- MERGE_BASE=<sha> — the merge base the script reconciled against (verify: run `git -C " + env.repoPath + " merge-base HEAD <INTEGRATION_TARGET>` and confirm it prints the same sha; if it differs, report the discrepancy and VERDICT: FAIL — the script did not reconcile against the true base)\\n" +
+    "- MERGED_EMPTY — check FIRST (it contains the word MERGED): either a runtime-state deliverable or a task-attributed merge the workflow verified from the task's own merge records. No lock taken, no new commit. Report 'merged empty: no repo changes'. VERDICT: PASS.\\n" +
+    "- MERGED: the merge landed; the script pushed inline. Read the push line: PUSHED — report the hash (detached prints PUSHED: origin/main (refspec HEAD:main)), VERDICT: PASS; NO_REMOTE_PUSH — no remote configured, VERDICT: PASS; ERROR after MERGED — a retry recovers the push; report it, VERDICT: FAIL.\\n" +
+    "- CONFLICT — conflicts; resolve them per the script's conflict output, re-run the script, then report.\\n" +
+    "- ERROR — report the error line, VERDICT: FAIL.\\n" +
+    "Do not run your own git merge, rebase, or push commands. If the script's output is ambiguous, report the ambiguity and VERDICT: FAIL — never guess the merge state.\\n" +
+    "If you changed public-affecting behavior, the branch must carry the matching public doc updates (API.md or the published API contract) before you report PASS — Review already checked this, but a merge that drops the docs fails here too.\\n" +
+    "End your report with exactly one line: VERDICT: PASS if the merge landed (or MERGED_EMPTY), VERDICT: FAIL otherwise.";
+}
+
+// verifyMerge — mechanical post-PASS check (publish-path.md#integrate-verify:
+// the agent cannot verify integrate mechanically; the workflow checks the
+// diff). Direct lifecycle call, no agent ferry.
+async function verifyMerge(env) {
+  var out = "";
+  try {
+    var res = await lifecycle(env, "verify-merge", [env.taskId]);
+    out = String((res && res.stdout) || "").trim();
+  } catch (e) {
+    out = "";
+  }
+  if (/^VERIFIED:/m.test(out)) {
+    log("Integrate verified for task " + env.taskId + ": task branch tip is an ancestor of the integration target");
+    return { ok: true };
+  }
+  var reason = out ? out.split("\n")[0].slice(0, 200) : "verify-merge produced no usable output";
+  log("Integrate verification failed for task " + env.taskId + ": " + reason + " — marking failed for retry");
+  return { ok: false, reason: reason };
+}
+
+// deployQaBundle — after a verified merge on a versioned artifact project,
+// ensure the QA environment serves a bundle built from merged source
+// (0.16.0: this REPLACES the old numeric version gate — freshness is
+// constructive, not comparative). Direct qa-deploy.mjs call — no agent
+// ferry. A failed deploy is an operational failure (retryable), never a
+// park.
+async function deployQaBundle(env) {
+  var qaDeploy = join(env.runLib, "qa-deploy.mjs");
+  var qaEnvDir = env.crewHome + "/qa-envs/" + env.projectId;
+  var serveArtifact = join(env.runLib, "serve-artifact.js");
+  var out = "";
+  try {
+    var res = await runCmd(
+      ["node", qaDeploy, "--repo", env.repoPath, "--qa-dir", qaEnvDir,
+       "--task", env.taskId, "--crew-home", env.crewHome, "--crew-api", env.crewApiPinned,
+       "--serve-artifact", serveArtifact],
+      {}
+    );
+    out = String((res && res.stdout) || "").trim();
+  } catch (e) {
+    out = "";
+  }
+  var m = /^DEPLOY_OK ([0-9a-f]{7})$/m.exec(out);
+  if (m) {
+    log("QA deploy ok for task " + env.taskId + ": bundle " + m[1]);
+    return { ok: true, hash: m[1] };
+  }
+  var f = /^DEPLOY_FAIL ([a-z-]+):(.{1,200})$/m.exec(out);
+  var reason = f ? f[1] + ": " + f[2].trim() : "unrecognized deploy output";
+  log("QA deploy failed for task " + env.taskId + ": " + reason + " — marking failed for retry");
+  return { ok: false, reason: reason };
+}
+
+export async function runPhase(ctx) {
+  var env = ctx.env, state = ctx.state;
+  var taskId = env.taskId;
+  var claimed = await ensureClaimed(env, state, PHASE);
+  if (claimed.type !== "CLAIMED") return claimed;
+
+  var boundary = await runWorkBoundary(env, state, {
+    phase: PHASE.name, identity: PHASE.identity,
+    instructions: buildInstructions(ctx),
+    eventPreamble: buildEventPreamble(env, PHASE.name),
+    crewApiLine: false, verdictStep: true,
+  });
+  if (boundary.type !== "BOUNDARY_DONE") return boundary;
+  var workerText = boundary.workerText;
+  var passed = closeoutPassed(boundary) === true;
+
+  var summary = summarizeReport(workerText);
+  var markers = [];
+
+  if (passed) {
+    // Mechanical merge verification (the agent cannot self-certify).
+    var mv = await verifyMerge(env);
+    if (!mv.ok) {
+      summary += "\nintegrate_verify: FAILED — " + mv.reason;
+      await recordPhase(env, {
+        task_id: taskId,
+        session: { id: state.activeSessionId, task_id: taskId, identity: PHASE.identity, step: PHASE.name, status: "failed", notes: summary },
+        event: { task_id: taskId, type: "failed", identity: PHASE.identity, message: PHASE.name + " failed by " + PHASE.identity },
+      });
+      return { type: "FAILED", reason: "Integrate merge verification failed: " + mv.reason };
+    }
+
+    var mergedEmpty = /MERGED_EMPTY/.test(workerText || "");
+    // 0.16.0: freshness is constructive — rebuild the QA bundle from the
+    // merged source so the bundle QA tests is current. No version bump,
+    // no REQUIRED_BUILD marker, no numeric comparison.
+    if (env.versionedBuild) {
+      // Rebuild the QA bundle from the merged source.
+      if (env.surfaceArtifact) {
+        var dep = await deployQaBundle(env);
+        if (!dep.ok) {
+          summary += "\ndeploy: FAILED — " + dep.reason;
+          await recordPhase(env, {
+            task_id: taskId,
+            session: { id: state.activeSessionId, task_id: taskId, identity: PHASE.identity, step: PHASE.name, status: "failed", notes: summary },
+            event: { task_id: taskId, type: "failed", identity: PHASE.identity, message: PHASE.name + " failed by " + PHASE.identity },
+          });
+          return { type: "FAILED", reason: "Integrate QA deploy failed: " + dep.reason };
+        }
+        markers.push("deploy: ok " + dep.hash);
+      }
+    }
+
+    var notes = (markers.length ? markers.join("\n") + "\n" : "") + summary;
+    await recordPhase(env, {
+      task_id: taskId,
+      session: { id: state.activeSessionId, task_id: taskId, identity: PHASE.identity, step: PHASE.name, status: "completed", notes: notes },
+      event: { task_id: taskId, type: "completed", identity: PHASE.identity, message: PHASE.name + " completed by " + PHASE.identity },
+    });
+    log("Integrate complete for task " + taskId);
+    return { type: "ADVANCE", next: "Publish" };
+  }
+
+  // Integrate failure is operational (there is no rework loop — the
+  // failure is not a verdict on the change, it is the merge not landing).
+  await recordPhase(env, {
+    task_id: taskId,
+    session: { id: state.activeSessionId, task_id: taskId, identity: PHASE.identity, step: PHASE.name, status: "failed", notes: summary },
+    event: { task_id: taskId, type: "failed", identity: PHASE.identity, message: PHASE.name + " failed by " + PHASE.identity },
+  });
+  return { type: "FAILED", reason: "Integration failed" };
+}

package/lib/standard/phases/map.js

@@ -0,0 +1,119 @@
+// lib/standard/phases/map.js — Map (mara) phase module (sandbox exit,
+// Phase C Piece 1). Import-safe: no side effects on import, bare `node`
+// exits 0.
+//
+// Reads: experiential status (durable Triage session notes), `baseline:`
+// note events, claim/session context.
+// Writes: completed/failed session + event (notes = the mapper
+// specification — the durable cross-run handoff Build reads).
+// Transitions: REWIND → Capture (Map gate bounce — session `failed`,
+// never a task failure); ADVANCE → Build. A Map spec verification failure
+// is operational (FAILED — the dispatcher retries at Map under its
+// consecutive-failure cap).
+
+import { statSync } from "fs";
+import {
+  resolveExperiential, baselineStatus, recordPhase, summarizeReport,
+  runWorkBoundary, buildEventPreamble,
+  ensureClaimed, log,
+} from "../../workflow-lib.js";
+
+export const PHASE = { name: "Map", identity: "mara" };
+
+// buildInstructions — pure function of ctx. The baseline-gate paragraph
+// inputs are stashed in ctx.state.memo.mapGate by runPhase before the
+// call (keeps the signature pure). Instruction text verbatim from
+// workflows/standard.js (Map branch).
+export function buildInstructions(ctx) {
+  var env = ctx.env;
+  var gate = (ctx.state.memo && ctx.state.memo.mapGate) || { refs: "", none: false, applies: false };
+  var mapGatePara = "";
+  if (gate.applies) {
+    mapGatePara = "\nBASELINE GATE (experiential task): " +
+      (gate.none
+        ? "no baseline was capturable (baseline: none recorded) — write the spec without baseline comparison and note it."
+        : "pre-change baseline evidence: " + gate.refs + " — 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" +
+      (env.surfaceTerminal
+        ? "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).");
+  }
+  return "Research the problem space, evaluate options, pick the shortest path.\nWrite a clear spec that a builder can execute without asking questions.\n" +
+    (env.surfaceTerminal ? "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 " + env.uxDoctrinePath + ".\n" : "") +
+    (env.surfaceArtifact ? "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 " + env.uxDoctrinePath + ".\n" : "") +
+    "The builder will edit source files in a git worktree.\nProject: " + env.projectDesc + "\nSave the spec to exactly this file: " + env.specPath + " — run mkdir -p \"" + env.specDir + "\" 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;
+}
+
+export async function runPhase(ctx) {
+  var env = ctx.env, state = ctx.state;
+  var taskId = env.taskId;
+  var claimed = await ensureClaimed(env, state, PHASE);
+  if (claimed.type !== "CLAIMED") return claimed;
+
+  // ── Map gate: experiential tasks need baseline evidence ────────────
+  // Mara must verify baseline evidence exists before writing the spec. If
+  // missing, bounce back to Capture — never to Build, never a task failure.
+  // Must match Capture's run condition (experiential + classified surface):
+  // when Capture skips, no baseline notes exist, so the gate must not apply.
+  var surfaceClassified = env.surfaceArtifact || env.surfaceTerminal;
+  var mapExp = await resolveExperiential(env, state);
+  var gateApplies = (mapExp === "yes" && surfaceClassified);
+  var gateRefs = "", gateNone = false;
+  if (gateApplies) {
+    var gateStatus = await baselineStatus(env);
+    var baselineLatestMessage = ("baseline: " + gateStatus.baseline_kind + gateStatus.baseline_refs).trim();
+    var baselineStale = env.visualProtocolAvailable && baselineLatestMessage === "baseline: none (visual protocol unavailable)";
+    if (!gateStatus.baseline_found || baselineStale) {
+      log("Map gate: no baseline evidence for task " + taskId + " — bouncing to Capture");
+      await recordPhase(env, {
+        task_id: taskId,
+        session: { id: state.activeSessionId, task_id: taskId, identity: PHASE.identity, step: PHASE.name, status: "failed", notes: "Map gate bounce — no baseline evidence, re-running Capture" },
+        event: { task_id: taskId, type: "failed", identity: PHASE.identity, message: "Map gate bounce for task " + taskId + " — no baseline evidence" },
+      });
+      // The driver increments state.gateBounceCount on this REWIND so the
+      // re-visited Capture mints fresh spawn keys (visitSuffix "-g<N>").
+      return { type: "REWIND", next: "Capture", reason: "Map gate: no baseline evidence for experiential task — bounced to Capture" };
+    }
+    gateRefs = (gateStatus.baseline_refs || []).join(", ");
+    gateNone = gateStatus.baseline_kind === "none";
+  }
+  state.memo.mapGate = { applies: gateApplies, refs: gateRefs, none: gateNone };
+
+  var boundary = await runWorkBoundary(env, state, {
+    phase: PHASE.name, identity: PHASE.identity,
+    instructions: buildInstructions(ctx),
+    eventPreamble: buildEventPreamble(env, PHASE.name),
+    crewApiLine: true, verdictStep: false,
+  });
+  if (boundary.type !== "BOUNDARY_DONE") return boundary;
+
+  // Map spec failure is operational (the spec file did not land at the
+  // workflow-computed SPEC_PATH), not a verdict: the session is recorded
+  // "failed" and the dispatcher retries at Map under its
+  // consecutive-failure cap. The retry re-runs Map with the same
+  // exact-path instructions against the same SPEC_PATH.
+  var specExists = false;
+  try { specExists = statSync(env.specPath).isFile(); } catch (e) { specExists = false; }
+  if (!specExists) {
+    log("Map spec verification failed for task " + taskId + " — returning failed for dispatcher retry");
+    await recordPhase(env, {
+      task_id: taskId,
+      session: { id: state.activeSessionId, task_id: taskId, identity: PHASE.identity, step: PHASE.name, status: "failed", notes: "Map spec verification failed: no spec file at " + env.specPath },
+      event: { task_id: taskId, type: "failed", identity: PHASE.identity, message: "Map spec verification failed for task " + taskId },
+    });
+    return { type: "FAILED", reason: "Map spec verification failed: no spec file at " + env.specPath };
+  }
+
+  // The session notes carry the mapper specification — the durable
+  // cross-run handoff Build re-derives via latestSessionNotes. Marker
+  // lines are re-attached after the slice (source: stepResult.summary
+  // construction).
+  var summary = summarizeReport(boundary.workerText);
+  await recordPhase(env, {
+    task_id: taskId,
+    session: { id: state.activeSessionId, task_id: taskId, identity: PHASE.identity, step: PHASE.name, status: "completed", notes: summary },
+    event: { task_id: taskId, type: "completed", identity: PHASE.identity, message: PHASE.name + " completed by " + PHASE.identity },
+  });
+  log("Map complete for task " + taskId);
+  return { type: "ADVANCE", next: "Build" };
+}