muse-crew 0.17.2 → 0.17.3

package/lib/chore/phases/build.js

@@ -0,0 +1,110 @@
+// lib/chore/phases/build.js — Build (Wren) phase module (sandbox exit,
+// Piece 2). Import-safe: no side effects on import, bare `node` exits 0.
+//
+// Reads: mapper spec (re-derived from the Map session notes), rejection
+// notes (re-derived from the rejected Review session notes),
+// worktree/project/surface facts. Writes: repository/worktree changes
+// (via the work agent) and marker lines (worktree:, release:,
+// version_bump:, repo_diff:, VERDICT). The worktree-confinement check and
+// the repo_diff:none claim capture are mechanical closeout gates.
+
+import {
+  runWorkBoundary, recordPhase, buildEventPreamble, summarizeReport,
+  closeoutPassed, ensureClaimed, latestSessionNotes,
+  lifecycleEnvPrefix, log,
+} from "../phase-lib.js";
+import { extractWorktree, extractRepoDiffNone } from "../extract.js";
+
+export const PHASE = { name: "Build", identity: "wren" };
+
+// buildInstructions — pure function of ctx (+ derived handoffs). Verbatim
+// from workflows/chore.js (Build branch).
+export function buildInstructions(ctx, handoffs) {
+  var env = ctx.env;
+  var h = handoffs || { mapperSpec: "", rejectionNotes: "" };
+  return "STEP 1: Prepare your worktree.\n" +
+    "Run: " + lifecycleEnvPrefix(env) + env.lifecycle + " 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 the TypeScript source files directly. Do NOT use artifact_edit — that happens in the Publish phase.\n" +
+    "Do not add unrequested features.\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 \"chore: " + 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 ? "REWORK after rejection. Address:\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-phase handoffs, re-derived from durable session notes so the run
+  // survives tick boundaries (source: in-process mapperSpec/rejectionNotes).
+  var handoffs = {
+    mapperSpec: await latestSessionNotes(env, "Map", "completed"),
+    rejectionNotes: await latestSessionNotes(env, "Review", "rejected"),
+  };
+
+  var boundary = await runWorkBoundary(env, state, {
+    phase: PHASE.name, identity: PHASE.identity,
+    instructions: buildInstructions(ctx, handoffs),
+    eventPreamble: buildEventPreamble(env, PHASE.name),
+    crewApiLine: true, verdictStep: true,
+  });
+  if (boundary.type !== "BOUNDARY_DONE") return boundary;
+
+  var passed = closeoutPassed(boundary);
+  var workerText = boundary.workerText;
+
+  // Worktree confinement (Build only): the declared worktree path must
+  // match the hint exactly. A builder that worked in any other checkout
+  // fails the phase here — the dispatcher retries Build under its
+  // consecutive-failure cap, and the retry re-runs prepare against the
+  // configured repo. Missing or mismatched lines fail closed.
+  if (passed) {
+    var wt = extractWorktree(workerText);
+    if (!wt.ok || wt.path !== env.worktreeHint) {
+      log("Build worktree confinement failed — declared: " + (wt.ok ? wt.path : "<none>") + ", expected: " + env.worktreeHint + " — marking failed for retry");
+      await recordPhase(env, {
+        task_id: taskId,
+        session: { id: state.activeSessionId, task_id: taskId, identity: PHASE.identity, step: PHASE.name, status: "failed", notes: "Build declared worktree " + (wt.ok ? wt.path : "<none>") + " — expected " + env.worktreeHint + ". The builder worked outside the configured repo checkout; phase failed for retry" },
+        event: { task_id: taskId, type: "failed", message: "Build worktree confinement failed — builder worked outside " + env.worktreeHint + ", phase failed, dispatcher will retry" },
+      });
+      return { type: "FAILED", reason: "Build worked outside the configured repo checkout", detail: "The builder declared worktree " + (wt.ok ? wt.path : "<none>") + " but the task's worktree is " + env.worktreeHint + ". The phase is marked failed; the dispatcher will retry Build against the configured repo." };
+    }
+    log("Build worktree confinement passed: " + wt.path);
+  }
+
+  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 },
+  });
+  // The plain `repo_diff: none` claim is captured from the full Build
+  // report (fresh each round); Review re-derives it from the session
+  // notes. Returned for the driver's observability.
+  var claimedNoDiff = extractRepoDiffNone(workerText);
+  log("Build " + status + " for task " + taskId);
+  return { type: "ADVANCE", next: "Review", buildClaimedNoDiff: claimedNoDiff };
+}

package/lib/chore/phases/capture.js

@@ -0,0 +1,82 @@
+// lib/chore/phases/capture.js — Capture (Hazel) phase module (sandbox
+// exit, Piece 2). Import-safe: no side effects on import, bare `node`
+// exits 0.
+//
+// Fully mechanical — no creative spawn. Reads the experiential status and
+// baseline notes; writes exact-prefix baseline notes and phase/session
+// state; advances to Map, or requests/carries evidence.
+
+import {
+  resolveExperiential, baselineStatus, recordPhase, logEvent, parkTask,
+  crewApi, ensureClaimed, log,
+} from "../phase-lib.js";
+
+export const PHASE = { name: "Capture", identity: "hazel" };
+
+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);
+  // Chore has no QA phase, so Capture stays artifact-only: terminal
+  // baselines would be unused evidence.
+  if (capExp !== "yes" || !env.surfaceArtifact) {
+    log("Capture skipped for task " + taskId + " — " + (capExp !== "yes" ? "not experiential" : "no QA phase to consume terminal-surface baselines"));
+    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 artifact task" },
+      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 — continuing without baseline comparison" },
+      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/chore/phases/integrate.js

@@ -0,0 +1,109 @@
+// lib/chore/phases/integrate.js — Integrate (Wren) phase module (sandbox
+// exit, Piece 2). Import-safe: no side effects on import, bare `node`
+// exits 0.
+//
+// The work agent runs the lifecycle's `integrate` command (merge,
+// reconcile, record, push under the merge lock) and reports VERDICT.
+// The workflow then verifies mechanically: `verify-merge <taskId>` must
+// print a VERIFIED: line — the agent cannot verify integrate itself.
+
+import {
+  runWorkBoundary, recordPhase, buildEventPreamble, summarizeReport,
+  closeoutPassed, ensureClaimed, lifecycle, crewCmdString,
+  lifecycleEnvPrefix, log, runCmd,
+} from "../phase-lib.js";
+
+export const PHASE = { name: "Integrate", identity: "wren" };
+
+// buildInstructions — pure function of ctx. Verbatim from
+// workflows/chore.js (Integrate branch).
+export function buildInstructions(ctx) {
+  var env = ctx.env;
+  var taskId = env.taskId;
+  var lockHolder = taskId + "/" + ctx.state.activeSessionId;
+  return "Merge the approved task branch into the integration target and push the result.\n" +
+    "The integration target is the repo's current checkout — a branch name, or the literal word HEAD when detached (no branch name exists when detached). Print the exact token with: "+ lifecycleEnvPrefix(env) + env.lifecycle + " integration-target\n" +
+    "NEVER run git checkout — the lifecycle merges into the current checkout; moving it abandons the line Publish verifies.\n\n" +
+    "Read the staged publish base (return its stdout verbatim):\n" + crewCmdString(env, "get-provenance", { project_id: env.projectId }) + "\n" +
+    "Then run: "+ lifecycleEnvPrefix(env) + "WORKFLOW_RUN_ID=" + lockHolder + " CREW_STAGED_BASE=<provenance.source_commit, empty when null> integrate " + taskId + " \"merge: chore: " + env.safeTitle + "\\\"\\n" +
+    "The script merges, reconciles, records, and pushes under the merge lock. Informational only: RECONCILED, NO_REMOTE, NO_REMOTE_RECONCILE. Read the output:\n" +
+    "- STAGED_BASE_MISMATCH: the line left the staged base (stray checkout). VERDICT: FAIL.\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" +
+    "- STALE_MERGE: the recorded merge no longer matches the task branch (rework moved it after the merge) — the script refused to push stale state. Report the STALE_MERGE line, VERDICT: FAIL.\n" +
+    "- LOCK_HELD: 10-minute backoff exhausted. VERDICT: FAIL.\n" +
+    "- CONFLICT: the plain merge failed — aborted, the target is clean, and your task still holds the merge lock. Do NOT fail yet. Resolve it:\n" +
+    "RESOLUTION:\n" +
+    "R1. Refresh the merge lock FIRST (a long resolution must not silently lose the lock to the orphan sweep): "+ lifecycleEnvPrefix(env) + " refresh-lock " + taskId + ". Create a scratch worktree WITH A NEW BRANCH (the integration target is checked out in the repo, so create the scratch worktree from HEAD — never check out another branch in the repo checkout): cd " + env.repoPath + " && git worktree add -b resolve/" + taskId + " /tmp/crew-resolve-" + taskId + " HEAD. Reproduce the conflict in the scratch worktree: cd /tmp/crew-resolve-" + taskId + " && git merge " + env.taskBranch + ". This reproduces the exact conflict (the integration target has not moved — the lock was held throughout). The task branch " + env.taskBranch + " is never modified.\n" +
+    "R2. For each conflicted file, read the three sides: git show :1:<file> (base), git show :2:<file> (ours = the integration target), git show :3:<file> (theirs = task branch). Resolve each hunk by keeping both sides' changes when they do not semantically overlap. Version-only hunks resolve to the higher semver (safety net). Never invent new behavior. Leave no markers.\n" +
+    "R3. Verify in the scratch worktree, in this order: (a) git diff --check is clean; (b) git grep -n '^<<<<<<<' -- . returns nothing; (c) node --check every changed .js file (conflicted files plus everything listed by git diff --name-only). If any check fails, refresh the merge lock ("+ lifecycleEnvPrefix(env) + " refresh-lock " + taskId + "), then retry using the failure output as context — max 3 attempts total.\n" +
+    "R4. Commit the resolution on resolve/" + taskId + ": git add -A && git commit -m \"resolve conflicts: " + taskId + "\".\n" +
+    "R5. Back in " + env.repoPath + ": git merge --ff-only resolve/" + taskId + " — merges the resolution into the current checkout (the integration target; no git checkout anywhere). It fast-forwards — the target has not moved under the lock. Report the merged hash.\n" +
+    "R6. Clean up: cd " + env.repoPath + " && git worktree remove --force /tmp/crew-resolve-" + taskId + " && git branch -D resolve/" + taskId + ".\n" +
+    "ESCALATE — 'conflict needs human resolution', VERDICT: FAIL — when: 3 attempts are exhausted; the conflict touches generated files, migrations, or public API contracts; or 'looks right + checks pass' is not sufficient for any other reason. On escalation, RELEASE THE LOCK so the task can be reworked later: run CREW_HOME=" + env.crewHome + " CREW_REPO=" + env.repoPath + " " + env.mergeLock + " release " + taskId + " (release is keyed on task id; no PID needed). Do NOT run post-deploy on escalation — it would delete the untouched task branch the human still needs.\n" +
+    "- ERROR: report it. VERDICT: FAIL.\n\n" +
+    "R5-PUSH (manual R5 resolution only — the normal path pushed inline). Run: " + lifecycleEnvPrefix(env) + env.lifecycle + " push-target " + taskId + "\n" +
+    "PUSHED — report the merged hash (detached prints PUSHED: origin/main (refspec HEAD:main)), VERDICT: PASS; PUSH_SKIPPED — no push attempted (no record + no lock); NO_REMOTE_PUSH — no remote; VERDICT: PASS; ERROR or CONFLICT — report it, VERDICT: FAIL.\n" +
+    "NEVER force-push.\n\n" +
+    "Report what happened at each step, ending with exactly one line: VERDICT: PASS or VERDICT: FAIL.";
+}
+
+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: true, verdictStep: true,
+  });
+  if (boundary.type !== "BOUNDARY_DONE") return boundary;
+
+  var passed = closeoutPassed(boundary);
+  var workerText = boundary.workerText;
+
+  // See docs/decisions/publish-path.md#integrate-verify: the agent cannot
+  // verify integrate mechanically; the workflow checks the diff. The
+  // command's stdout is captured even on non-zero exit (the source's
+  // `2>&1 || true`); runCmd surfaces it on the thrown error.
+  var summary = workerText;
+  if (passed) {
+    var integrateVerifyOut = "";
+    try {
+      var vr = await lifecycle(env, "verify-merge", [taskId]);
+      integrateVerifyOut = String(vr.stdout || "").trim();
+    } catch (e) {
+      integrateVerifyOut = String((e && e.stdout) || "").trim();
+    }
+    if (/^VERIFIED:/m.test(integrateVerifyOut)) {
+      log("Integrate verified for task " + taskId + ": task branch tip is an ancestor of the integration target");
+    } else {
+      var integrateVerifyReason = integrateVerifyOut
+        ? integrateVerifyOut.split("\n")[0].slice(0, 200)
+        : "verify-merge produced no usable output";
+      log("Integrate verification failed for task " + taskId + ": " + integrateVerifyReason + " — marking failed for retry");
+      summary = (summary || "") + "\nintegrate_verify: FAILED — " + integrateVerifyReason;
+      passed = false;
+    }
+  }
+
+  // "rejected" is an explicit phase verdict routed through rework (Review).
+  // Integrate work that did not finish is operational — "failed",
+  // retryable under the dispatcher's consecutive-failure cap.
+  var status = passed ? "completed" : "failed";
+  var finalSummary = summarizeReport(summary);
+  await recordPhase(env, {
+    task_id: taskId,
+    session: { id: state.activeSessionId, task_id: taskId, identity: PHASE.identity, step: PHASE.name, status: status, notes: finalSummary },
+    event: { task_id: taskId, type: status, identity: PHASE.identity, message: PHASE.name + " " + status + " by " + PHASE.identity },
+  });
+  if (!passed) {
+    log("Integration failed for task " + taskId + ": " + finalSummary);
+    return { type: "FAILED", reason: "Integration failed: " + finalSummary, detail: "The integrate step failed. The dispatcher will retry under its consecutive-failure cap." };
+  }
+  log("Integrate completed for task " + taskId);
+  return { type: "ADVANCE", next: "Publish" };
+}

package/lib/chore/phases/map.js

@@ -0,0 +1,81 @@
+// lib/chore/phases/map.js — Map (Mara) phase module (sandbox exit,
+// Piece 2). Import-safe: no side effects on import, bare `node` exits 0.
+//
+// Reads: experiential/baseline gate, task context, prior events, rejection
+// notes. Writes: mapper specification (durable cross-run handoff in the
+// Map session notes). A missing baseline bounces back to Capture — never
+// to Build, never a task failure. captureTargets is dead/write-only in
+// chore.js and is NOT ported.
+
+import {
+  runWorkBoundary, recordPhase, buildEventPreamble, summarizeReport,
+  closeoutPassed, ensureClaimed, resolveExperiential, baselineStatus, log,
+} from "../phase-lib.js";
+
+export const PHASE = { name: "Map", identity: "mara" };
+
+// buildInstructions — pure function of ctx. Verbatim from
+// workflows/chore.js (Map branch). mapGate: {refs, none} from the gate.
+export function buildInstructions(ctx, mapGate) {
+  var env = ctx.env;
+  var gate = mapGate || { refs: "", none: false };
+  var mapGatePara = "";
+  if (gate.refs || gate.none) {
+    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 captures: " + gate.refs + " — 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).";
+  }
+  return "Research options, pick the path, write a clear spec for the builder.\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 — build and review 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 — build and review against this spec and the shared bar at " + env.uxDoctrinePath + ".\n" : "") +
+    "The builder will edit source files in a git worktree of the project at " + env.repoPath + ".\nProject: " + env.projectDesc + "\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;
+}
+
+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. Must match
+  // Capture's run condition (experiential + artifact surface): when
+  // Capture skips, no baseline notes exist, so the gate must not apply.
+  var mapGate = { refs: "", none: false };
+  if ((await resolveExperiential(env, state)) === "yes" && env.surfaceArtifact) {
+    var gateStatus = await baselineStatus(env);
+    if (!gateStatus.baseline_found) {
+      log("Map gate: no baseline evidence for experiential 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 recorded for this experiential task — no spec was written. Baseline evidence must be captured before the spec." },
+        event: { task_id: taskId, type: "failed", identity: PHASE.identity, message: "Map gate bounce — baseline evidence missing, returning to Capture" },
+      });
+      return { type: "REWIND", next: "Capture", reason: "Map gate bounce — baseline evidence missing" };
+    }
+    mapGate = { refs: gateStatus.baseline_refs, none: gateStatus.baseline_kind === "none" };
+  }
+
+  var boundary = await runWorkBoundary(env, state, {
+    phase: PHASE.name, identity: PHASE.identity,
+    instructions: buildInstructions(ctx, mapGate),
+    eventPreamble: buildEventPreamble(env, PHASE.name),
+    crewApiLine: true, verdictStep: false,
+  });
+  if (boundary.type !== "BOUNDARY_DONE") return boundary;
+
+  var passed = closeoutPassed(boundary);
+  var workerText = boundary.workerText;
+  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 },
+  });
+  // captureTargets is dead/write-only in the source — not ported.
+  log("Map " + status + " for task " + taskId);
+  return { type: "ADVANCE", next: "Build" };
+}