muse-crew 0.17.2 → 0.17.3

package/lib/chore/phases/review.js

@@ -0,0 +1,255 @@
+// lib/chore/phases/review.js — Review (Cass) phase module (sandbox exit,
+// Piece 2). Import-safe: no side effects on import, bare `node` exits 0.
+//
+// Hybrid phase: the branch classification and npm-version checks run
+// mechanically (direct execFile, in-place instrument retries) BEFORE any
+// creative review. A mechanical failure uses synthetic prose through the
+// same extraction path and never dispatches Cass. FAIL increments the
+// durable rework count (re-derived from rejected events), records
+// rejection notes, and rewinds explicitly to Build.
+
+import {
+  runWorkBoundary, recordPhase, buildEventPreamble, summarizeReport,
+  closeoutPassed, ensureClaimed, latestSessionNotes, lifecycle, parkTask,
+  lifecycleEnvPrefix, log,
+} from "../phase-lib.js";
+import {
+  parseClassifyFerry, parseVersionFerry, extractVerdict,
+  extractReleaseDecision, releaseDecisionText, extractRepoDiffNone,
+} from "../extract.js";
+
+export const PHASE = { name: "Review", identity: "cass" };
+const MAX_REWORK = 2;
+
+// runClassifyGate — the mechanical branch classifier (blocker 34/42).
+// Direct execFile, no agent ferry. UNKNOWN retries in place (up to 2);
+// exhaustion parks honestly — never asserts empty-no-work.
+async function runClassifyGate(env) {
+  var taskId = env.taskId;
+  var branchState = null;
+  var branchStateErr = "";
+  var classifyFailedReturn = "";
+  for (var classifyAttempt = 0; classifyAttempt <= 2 && branchState === null; classifyAttempt++) {
+    var parsed;
+    try {
+      var out = await lifecycle(env, "classify-branch", [taskId]);
+      classifyFailedReturn = JSON.stringify({ stdout: out.stdout, stderr: out.stderr }).slice(0, 500);
+      parsed = parseClassifyFerry({ stdout: out.stdout, stderr: out.stderr });
+    } catch (e) {
+      var msg = String((e && e.message) || e);
+      classifyFailedReturn = msg.slice(0, 500);
+      parsed = { state: null, diagField: null, diagText: "", failReason: "classifier call failed: " + msg.slice(0, 120) };
+    }
+    if (parsed.state !== null) {
+      branchState = parsed.state;
+      branchStateErr = "";
+      if (parsed.diagField !== null) {
+        log("classify-branch DIAG pin (" + parsed.diagField + " field): " + parsed.diagText);
+      } else {
+        log("classify-branch: no DIAG: record-scan counter returned (scan unverifiable)");
+      }
+    } else {
+      branchStateErr = parsed.failReason;
+      if (classifyAttempt < 2) {
+        log("classify-branch unparseable (" + branchStateErr + ") — retrying in place (attempt " + (classifyAttempt + 1) + " of 2)");
+      }
+    }
+  }
+  if (branchState === null) {
+    return { parked: await parkTask(env, "Branch state unclassifiable after 2 instrument retries (" + branchStateErr + "; last failure: " + classifyFailedReturn + ") — the classifier instrument failed, not the branch. Human attention needed: inspect the task branch directly to determine its state — no trustworthy branch classification was produced.") };
+  }
+  var alreadyMergedSha = null;
+  if (branchState.indexOf("already-merged:") === 0) {
+    alreadyMergedSha = branchState.slice("already-merged:".length);
+    log("Branch state already-merged: " + alreadyMergedSha + " (DIAG pin present — tripwire satisfied) — Cass reviews the frozen merge diff");
+  } else {
+    log("Branch state: " + branchState);
+  }
+  return { branchState: branchState, branchStateErr: branchStateErr, alreadyMergedSha: alreadyMergedSha };
+}
+
+// runVersionGate — the mechanical package.json `version` check (npm
+// projects only). Same in-place retry shape as the classifier.
+async function runVersionGate(env) {
+  var taskId = env.taskId;
+  var versionState = null;
+  var versionStateErr = "";
+  var versionFailedReturn = "";
+  for (var versionAttempt = 0; versionAttempt <= 2 && versionState === null; versionAttempt++) {
+    var parsed;
+    try {
+      var out = await lifecycle(env, "version-check", [taskId]);
+      versionFailedReturn = JSON.stringify({ stdout: out.stdout }).slice(0, 500);
+      parsed = parseVersionFerry({ stdout: out.stdout });
+    } catch (e) {
+      var msg = String((e && e.message) || e);
+      versionFailedReturn = msg.slice(0, 500);
+      parsed = { versionState: null, failReason: "version-check call failed: " + msg.slice(0, 120) };
+    }
+    if (parsed.versionState !== null) {
+      versionState = parsed.versionState;
+      versionStateErr = "";
+    } else {
+      versionStateErr = parsed.failReason;
+      if (versionAttempt < 2) {
+        log("version-check unparseable (" + versionStateErr + ") — retrying in place (attempt " + (versionAttempt + 1) + " of 2)");
+      }
+    }
+  }
+  if (versionState === null) {
+    return { parked: await parkTask(env, "package.json `version` state unclassifiable after 2 instrument retries (" + versionStateErr + "; last failure: " + versionFailedReturn + ") — the version-check instrument failed, not the branch. Human attention needed: inspect the task branch directly to determine its state — no trustworthy version classification was produced.") };
+  }
+  var touched = (versionState === "touched");
+  log("Review: package.json `version` " + (touched ? "touched by the branch — mechanical FAIL, Cass not dispatched" : "untouched — mechanical check clean"));
+  return { versionTouched: touched };
+}
+
+// buildInstructions — pure function of ctx (+ gate facts). Verbatim from
+// workflows/chore.js (Review branch).
+export function buildInstructions(ctx, gate) {
+  var env = ctx.env;
+  var reviewChangeExam, reviewBranchRule;
+  if (gate.branchState === "has-work") {
+    reviewChangeExam =
+      "Examine the code changes by running:\n" +
+      lifecycleEnvPrefix(env) + env.lifecycle + " inspect " + env.taskId + "\n\n" +
+      "The inspect output is authoritative: it prints the task branch's actual tip commit (TIP) and every commit ahead of the integration target (inspect prints the target name). Base your review ONLY on this output — do NOT run git log yourself to pick commits, and do NOT discuss commit hashes from any other source (they may come from stale rework rounds or a different repo).\n\n";
+    reviewBranchRule =
+      "MECHANICAL FACT (computed by the workflow from git — never by a reviewer): branch state = has-work. The branch has commits ahead of the integration target. Review their content; branch emptiness is settled and is not yours to judge.\n";
+  } else if (gate.branchState.indexOf("already-merged:") === 0) {
+    reviewChangeExam =
+      "The change under review is the frozen merge " + gate.alreadyMergedSha + " — it is already on the integration target (see MECHANICAL FACT below). Examine it by running:\n" +
+      "cd " + env.repoPath + " && git diff " + gate.alreadyMergedSha + "^1 " + gate.alreadyMergedSha + "\n\n" +
+      "That first-parent diff is the frozen, attributable change. Base your review ONLY on this diff — do NOT run git log to pick commits, and do NOT discuss commit hashes from any other source (they may come from stale rework rounds or a different repo).\n\n";
+    reviewBranchRule =
+      "MECHANICAL FACT (computed by the workflow from git — never by a reviewer): branch state = already-merged:" + gate.alreadyMergedSha + ". The deliverable landed on the integration target via this task's own prior merge " + gate.alreadyMergedSha + " (verified ancestor of the integration target). The branch is empty by design — emptiness is settled fact, not a finding.\n";
+  } else if (gate.buildClaimedNoDiff) {
+    reviewChangeExam =
+      "The branch has no commits ahead of the integration target (see MECHANICAL FACT below) — there is no diff to examine. Judge the Build report's `repo_diff: none` claim on its plausibility.\n\n";
+    reviewBranchRule =
+      "MECHANICAL FACT (computed by the workflow from git — never by a reviewer): the branch has no commits ahead of the integration target and no task-attributed merge on the target was verified; the Build report declares `repo_diff: none` (no repo change). Approve ONLY if the task's deliverable is plausibly runtime state (e.g. a cron definition, scheduler change, or dashboard/config state created outside the repo). Otherwise report 'no commits ahead of the integration target and no plausible runtime-state deliverable — the branch is empty and no task-attributed merge was verified', then end your report with exactly this line: VERDICT: FAIL.\n";
+  } else {
+    // Mechanical FAIL — Cass is never dispatched. Instructions unused.
+    reviewChangeExam = "";
+    reviewBranchRule = "";
+  }
+  return "Review independently and cold. No prior context from the builder.\nDo NOT access the task dashboard, event log, or any comments. Your review is based solely on the spec and the code.\n\n" +
+    (gate.mapperSpec ? "MAPPER'S SPEC (the builder was asked to implement exactly this):\n" + gate.mapperSpec + "\n\n" : "Read the spec from the task description.\n\n") +
+    reviewChangeExam +
+    "You can also read specific files in the worktree at:\n" +
+    env.worktreeHint + "/\n\n" +
+    "Check quality, correctness, spec compliance.\n" +
+    (env.surfaceTerminal ? "TERMINAL UX REVIEW: judge the CLI surface against " + env.uxDoctrinePath + " — help accuracy, error quality, exit codes, output clarity. Reject when the bar is not met.\n" : "") +
+    (env.surfaceArtifact ? "ARTIFACT UX REVIEW: judge the rendered surface against " + env.uxDoctrinePath + " — 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" +
+    reviewBranchRule +
+    (env.publishType === "npm" ? "PACKAGE VERSION: this project publishes to the npm registry, and versions are assigned at publish time — never in branches.\n" +
+    "MECHANICAL FACT (computed by the workflow from git — never by a reviewer): the task branch did not change package.json's `version` field. A branch that touches `version` fails Review mechanically before any reviewer is dispatched, so this is settled — do not re-check it.\n" +
+    "The accepted Build report declares: " + releaseDecisionText(gate.releaseDecision) + ". " +
+    (gate.releaseDecision
+      ? "Validate this decision against the change: release must be 'yes' when the change is consumer-observable and 'no' when internal-only; the version_bump scope must fit the change (patch for fixes, minor for new behavior, major for breaking changes). If the decision is wrong or mis-scoped, report your notes, then end with exactly this line: VERDICT: FAIL."
+      : "The decision is missing or malformed — report 'Build report must end with release: yes|no and (when release is yes) version_bump: patch|minor|major lines', then end with exactly this line: VERDICT: FAIL.") + "\n" : "") +
+    "Write 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.";
+}
+
+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;
+
+  // Mechanical gates run BEFORE Cass is dispatched. Re-classified on
+  // every Review entry: rework rewinds here and the branch changed.
+  var cg = await runClassifyGate(env);
+  if (cg.parked) return cg.parked;
+  var versionTouched = false;
+  if (env.publishType === "npm") {
+    var vg = await runVersionGate(env);
+    if (vg.parked) return vg.parked;
+    versionTouched = vg.versionTouched;
+  }
+
+  // Cross-phase handoffs re-derived from durable session notes.
+  var buildNotes = await latestSessionNotes(env, "Build", "completed");
+  var gate = {
+    branchState: cg.branchState,
+    alreadyMergedSha: cg.alreadyMergedSha,
+    buildClaimedNoDiff: extractRepoDiffNone(buildNotes),
+    releaseDecision: extractReleaseDecision(buildNotes),
+    mapperSpec: await latestSessionNotes(env, "Map", "completed"),
+  };
+
+  var mechanicalFailReason = (versionTouched ? "version-touched" : (cg.branchState === "empty-no-work" && !gate.buildClaimedNoDiff ? "empty-no-work" : null));
+  var mechanicalReviewFail = (mechanicalFailReason !== null);
+  var workerText, verdictPassed;
+  if (mechanicalReviewFail) {
+    log("Review: " + mechanicalFailReason + " — mechanical FAIL, Cass not dispatched");
+    workerText =
+      "MECHANICAL REVIEW VERDICT (written by the workflow — no reviewer was dispatched).\n" +
+      (mechanicalFailReason === "version-touched"
+        ? "Package.json `version` (checked by the workflow from git): the task branch changed the `version` field. Versions are assigned at publish time — never in branches. Remove the version change.\n"
+        : "Branch state (classified by the workflow from git): empty-no-work — the task branch has no commits ahead of the integration target, " +
+          "no task-attributed merge on the target was verified" + (cg.branchStateErr ? " (branch classification itself failed: " + cg.branchStateErr + ")" : "") + ", " +
+          "and the accepted Build report declared no `repo_diff: none` deliverable. " +
+          "No change was reviewed because there is no change to review. The branch is empty and no task-attributed merge was verified.\n") +
+      "Worktree: " + env.worktreeHint + "\n" +
+      "Recovery: commit the deliverable on the task branch in the worktree above and re-run Review. If the deliverable is genuinely runtime state outside the repo, declare `repo_diff: none` in the Build report instead of leaving the branch empty without a declaration.\n" +
+      "VERDICT: FAIL";
+    verdictPassed = false;
+  } else {
+    var boundary = await runWorkBoundary(env, state, {
+      phase: PHASE.name, identity: PHASE.identity,
+      instructions: buildInstructions(ctx, gate),
+      eventPreamble: buildEventPreamble(env, PHASE.name),
+      crewApiLine: false, verdictStep: true,
+    });
+    if (boundary.type !== "BOUNDARY_DONE") return boundary;
+    workerText = boundary.workerText;
+    verdictPassed = closeoutPassed(boundary);
+  }
+
+  var passed = verdictPassed === true;
+  var summary = summarizeReport(workerText);
+  // Machine-readable review basis, prepended to the session notes.
+  var reviewBasisNote;
+  if (mechanicalReviewFail) {
+    reviewBasisNote = "REVIEW_BASIS: none — mechanical FAIL (" + mechanicalFailReason + "), no reviewer dispatched";
+  } else if (cg.branchState.indexOf("already-merged:") === 0) {
+    reviewBasisNote = "REVIEW_BASIS: frozen merge " + cg.alreadyMergedSha + " — reviewed via git diff " + cg.alreadyMergedSha + "^1 " + cg.alreadyMergedSha;
+  } else if (cg.branchState === "has-work") {
+    reviewBasisNote = "REVIEW_BASIS: branch diff — reviewed via inspect output (task branch vs integration target)";
+  } else {
+    reviewBasisNote = "REVIEW_BASIS: runtime-state-none — no repo change; plausibility of Build's repo_diff: none claim";
+  }
+  summary = reviewBasisNote + "\n" + summary;
+  var reviewBasis =
+    mechanicalReviewFail ? "mechanical-fail" :
+    cg.branchState.indexOf("already-merged:") === 0 ? "frozen-merge:" + cg.alreadyMergedSha :
+    cg.branchState === "has-work" ? "branch-diff" : "runtime-state-none";
+  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 },
+    verdict: {
+      step: "Review",
+      attempt: state.reworkCount,
+      reviewer: mechanicalReviewFail ? "workflow" : PHASE.identity,
+      verdict: passed ? "PASS" : "FAIL",
+      review_basis: reviewBasis,
+      grounds: workerText,
+    },
+  });
+
+  if (!passed) {
+    var newRework = state.reworkCount + 1;
+    if (newRework > MAX_REWORK) {
+      log("Max rework attempts reached for task " + taskId + " — worktree preserved at " + env.worktreePreservedHint + " for manual inspection");
+      return await parkTask(env, "Exceeded " + MAX_REWORK + " rework attempts after Review rejection. Worktree preserved.");
+    }
+    log("Review rejected — bouncing to Build (rework #" + newRework + ")");
+    return { type: "REWIND", next: "Build", reason: "Review rejected — bouncing to Build (rework #" + newRework + ")" };
+  }
+  log("Review completed for task " + taskId);
+  return { type: "ADVANCE", next: "Integrate" };
+}

package/lib/chore/phases/triage.js

@@ -0,0 +1,57 @@
+// lib/chore/phases/triage.js — Triage (Sage) phase module (sandbox exit,
+// Piece 2). Import-safe: no side effects on import, bare `node` exits 0.
+//
+// Reads: task/project/surface facts, claim/session context.
+// Writes: completed session + event; the machine-read `experiential: yes|no`
+// marker line. The durable cross-run handoff is the Triage session notes.
+
+import {
+  runWorkBoundary, recordPhase, buildEventPreamble, summarizeReport,
+  closeoutPassed, ensureClaimed, log,
+} from "../phase-lib.js";
+import { extractExperiential } from "../extract.js";
+
+export const PHASE = { name: "Triage", identity: "sage" };
+
+// buildInstructions — pure function of ctx. Verbatim from
+// workflows/chore.js (Triage branch).
+export function buildInstructions(ctx) {
+  var env = ctx.env;
+  return "Validate the task against the project's repo at " + env.repoPath + " — that exact checkout, not any other copy of the project on disk. If you run git commands, cd " + env.repoPath + " 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? " + env.surfaceTriageDesc + " 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 " + (env.uxDoctrinePath ? env.uxDoctrinePath + " — 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.";
+}
+
+export async function runPhase(ctx) {
+  var env = ctx.env, state = ctx.state;
+  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: false,
+  });
+  if (boundary.type !== "BOUNDARY_DONE") return boundary;
+
+  // Triage is not a verdict step: producing output means passed.
+  var passed = closeoutPassed(boundary);
+  var workerText = boundary.workerText;
+  var summary = summarizeReport(workerText);
+  var status = passed ? "completed" : "rejected";
+  await recordPhase(env, {
+    task_id: env.taskId,
+    session: { id: state.activeSessionId, task_id: env.taskId, identity: PHASE.identity, step: PHASE.name, status: status, notes: summary },
+    event: { task_id: env.taskId, type: status, identity: PHASE.identity, message: PHASE.name + " " + status + " by " + PHASE.identity },
+  });
+  if (!passed) {
+    // A rejected Triage still advances (source: only Review, Integrate,
+    // and Publish have special failure paths); the rejection is recorded.
+    log("Triage rejected for task " + env.taskId + " — advancing");
+    return { type: "ADVANCE", next: "Capture", experiential: null };
+  }
+  log("Triage complete for task " + env.taskId);
+  return {
+    type: "ADVANCE", next: "Capture",
+    experiential: extractExperiential(workerText),
+  };
+}

package/lib/chore/prompts/evidence-gatherer.js

@@ -0,0 +1,41 @@
+// lib/chore/prompts/evidence-gatherer.js — the evidence-gatherer prompt
+// builder (sandbox exit, Piece 2).
+//
+// Minimal placeholder: the kind is in the frozen creative vocabulary but
+// has no chore site (its only use is the standard workflow's QA phase,
+// deferred to Piece 4). The bridge's kind→builder map is closed, so the
+// kind needs a builder; the per-assignment content arrives as params and
+// the Piece 4 contract will flesh out the reporting grammar. Pure
+// function of declared params; no I/O, no clock, no randomness.
+
+import { TOOL_CHECK_PREAMBLE } from "./tool-check.js";
+
+function requiredString(params, name) {
+  var v = params[name];
+  if (typeof v !== "string" || v.length === 0) {
+    throw new Error("buildEvidenceGathererPrompt: missing required param '" + name + "'");
+  }
+  return v;
+}
+
+export function buildEvidenceGathererPrompt(params) {
+  var p = params || {};
+  var identity = requiredString(p, "identity");
+  var orchPath = requiredString(p, "orch_path");
+  var assignment = requiredString(p, "assignment");
+  var constraints = requiredString(p, "constraints");
+  var includeToolCheck = p.include_tool_check !== false;
+
+  return (
+    (includeToolCheck ? TOOL_CHECK_PREAMBLE : "") +
+    "Read the identity file at " + orchPath + "/identities/" + identity + ".md using the read tool, and embody that character fully.\n\n" +
+    "## Your Assignment\n\n" +
+    assignment + "\n\n" +
+    "CONSTRAINTS:\n" + constraints + "\n\n" +
+    "Stay in character. Do the work thoroughly.\n\n" +
+    "Your report is plain prose describing the evidence you gathered. " +
+    "Do NOT write a VERDICT line — this kind declares machine effects " +
+    "(note-event prefixes / OODA log entries), not a verdict; the exact " +
+    "reporting grammar is defined by the Piece 4 contract."
+  );
+}

package/lib/chore/prompts/evidence-gatherer.schema.json

@@ -0,0 +1 @@
+{"_note":"Extractor contract for the evidence-gatherer spawn kind — placeholder for the Piece 4 contract. The kind is in the frozen creative vocabulary but has no chore site; this file exists so the bridge's kind→builder/schema map stays closed.","contract":{"piece_4":"The full evidence grammar (OODA/verdict effects, permitted board writes under a declared identity) is deferred to Piece 4 — see DESIGN-chore-pilot.md §1.","verdict":{"function":"extractVerdict","grammar":"Exactly one line: 'VERDICT: PASS' or 'VERDICT: FAIL'. Read with extractVerdict; anything else → missing (null)."}},"extractor_module":"../extract.js","kind":"evidence-gatherer","prompt_builder":"./evidence-gatherer.js"}

package/lib/chore/prompts/tool-check.js

@@ -0,0 +1,15 @@
+// lib/chore/prompts/tool-check.js — the tool-check preamble for creative
+// spawn prompts (sandbox exit, Piece 2).
+//
+// Import-safe: pure constant, no I/O. Verbatim from workflows/chore.js
+// (byte-identical across standard/bugfix/chore/docs — pinned by
+// tests/artifact-tools.test.js). The two signal lines are the ONLY
+// machine-read tool-availability evidence — the extractor never guesses
+// from English prose.
+
+export const TOOL_CHECK_PREAMBLE =
+  "TOOL CHECK (do this first, before any other work):\n" +
+  "1. Call tool_search.load_tool_namespace with paths [\"artifact\"].\n" +
+  "2. Write exactly one line: artifact_tools: ok - or artifact_tools: missing if the call failed or the tool does not exist.\n" +
+  "3. Run the shell command: echo tool-probe-ok - then write exactly one line: shell_transport: ok - or shell_transport: unavailable if you cannot run shell commands.\n" +
+  "Then do the assignment below.\n\n";

package/lib/chore/prompts/trailers.js

@@ -0,0 +1,56 @@
+// lib/chore/prompts/trailers.js — retry trailers for creative spawn prompts
+// (sandbox exit, Piece 2).
+//
+// Import-safe: pure functions, no I/O, no clock, no randomness. Logic-
+// verbatim from workflows/chore.js with the exact source signatures:
+//   buildTransportRetryTrailer(stepName, repoPath, taskId, attempt, reason)
+//   classifyRetryTrailer(reason, failedReturn)
+//   versionRetryTrailer(reason, failedReturn)
+// buildTransportRetryTrailer is byte-identical across standard/bugfix/chore/docs
+// (pinned by tests/transport-retry.test.js); the classify/version trailers are
+// chore-local.
+//
+// Note: the classify/version trailers are retained for contract fidelity but
+// have no consumer in the worker layer — the mechanical gates they re-prompted
+// (classify-branch, version-check) now run via direct execFile, so there is no
+// agent ferry to re-prompt. Only buildTransportRetryTrailer is used, by the
+// work-agent transport-retry path.
+
+export function buildTransportRetryTrailer(stepName, repoPath, taskId, attempt, reason) {
+  // reason: "discarded" (the runtime threw the output away — the JSON-candidate
+  // scan found {...}-shaped fragments it could not parse), "empty" (the worker returned without throwing but produced
+  // nothing usable), "no-tools" (the worker's TOOL CHECK reported
+  // artifact_tools: missing), or "no-transport" (the worker's TOOL CHECK
+  // reported shell_transport: unavailable).
+  // The trailer tells the retry what to expect, not just to try again.
+  var why = reason === "empty"
+    ? "your previous attempt returned no usable output"
+    : reason === "no-tools"
+    ? "your previous attempt's TOOL CHECK reported artifact_tools: missing (this is a fresh launch, so run the TOOL CHECK's load step again before the work)"
+    : reason === "no-transport"
+    ? "your previous attempt's TOOL CHECK reported shell_transport: unavailable (this is a fresh launch, so run the TOOL CHECK's shell probe again before the work)"
+    : "your previous attempt's output was discarded by the transport because it contained {...}-shaped fragments the transport could not parse; write plain prose with no JSON-shaped fragments";
+  return "\n\nTRANSPORT RETRY (attempt " + attempt + " of 2): " + why + ". " +
+    "First check existing state (worktree/branch at " + repoPath + "/.worktrees/" + taskId + ", the task branch, dashboard sessions for this task) - " +
+    "if the " + stepName + " work is already complete, report on what was done rather than duplicating side effects. " +
+    "Then return your report in exactly the shape specified above.";
+}
+
+export function classifyRetryTrailer(reason, failedReturn) {
+  // Pass-2 simplification: the reason string already carries the truth
+  // (throw vs parse failure), so one neutral sentence replaces the
+  // throw/parse branch — the stringly-typed prefix contract between the
+  // call site and this function is deleted, not moved. Prompt accuracy,
+  // not prompt hardening.
+  return "\n\nCLASSIFY RETRY: the previous classifier attempt failed (" + reason + "). " +
+    "Return ONLY the two named fields: { \"stdout\": \"<the command's exact stdout>\", \"stderr\": \"<the command's exact stderr>\" }. " +
+    "Put each stream in its named field — do not add labels like \"stdout:\" in front of the content. " +
+    "Previous attempt detail (do not repeat this shape): " + String(failedReturn).slice(0, 200);
+}
+
+export function versionRetryTrailer(reason, failedReturn) {
+  return "\n\nVERSION-CHECK RETRY: the previous version-check attempt failed (" + reason + "). " +
+    "Return ONLY the named field: { \"stdout\": \"<the command's exact stdout>\" }. " +
+    "Put the command's stdout in the named field — do not add labels like \"stdout:\" in front of the content. " +
+    "Previous attempt detail (do not repeat this shape): " + String(failedReturn).slice(0, 200);
+}

package/lib/chore/prompts/verdict-reask.js

@@ -0,0 +1,28 @@
+// lib/chore/prompts/verdict-reask.js — the verdict re-ask prompt builder
+// (sandbox exit, Piece 2).
+//
+// A pure function of declared params (P1). Logic-verbatim from
+// workflows/chore.js buildVerdictReaskPrompt: the re-ask is a fresh content
+// judgment — it must NOT copy any VERDICT line from the report, it decides
+// from the content. Bounded to 2 attempts by the spawn bridge
+// (MAX_ATTEMPTS), 180s each.
+
+export function buildVerdictReaskPrompt(params) {
+  var p = params || {};
+  var stepName = p.step_name;
+  var workerText = p.worker_text;
+  if (typeof stepName !== "string" || stepName.length === 0) {
+    throw new Error("buildVerdictReaskPrompt: missing required param 'step_name'");
+  }
+  if (typeof workerText !== "string") {
+    throw new Error("buildVerdictReaskPrompt: missing required param 'worker_text'");
+  }
+  return (
+    "Mechanical transcription task. Read the work report below and emit its verdict.\n\n" +
+    "WORK REPORT (verbatim):\n" + workerText + "\n\n" +
+    "Decide from the report's own content whether the " + stepName + " step clearly describes successful completion: " +
+    "if it does, the verdict is PASS; otherwise — failure, error, unfinished work, or unclear — the verdict is FAIL. " +
+    "Do NOT copy any VERDICT line from the report — decide from the content.\n\n" +
+    "The result must be exactly one line and nothing else: VERDICT: PASS or VERDICT: FAIL."
+  );
+}

package/lib/chore/prompts/verdict-reask.schema.json

@@ -0,0 +1 @@
+{"_note":"Extractor contract for the verdict-reask spawn kind — the exact line grammar lib/chore/extract.js requires. This is NOT JSON Schema; 'schema' here means the machine-read report contract the agent's prose must satisfy.","contract":{"bounds":"2 attempts max, 180s each (MAX_ATTEMPTS['verdict-reask']); attempts are separate ledger rows kind='verdict-reask'. Terminal reask failures count toward the per-task transport budget.","verdict":{"function":"extractVerdict","grammar":"Exactly one line and nothing else: 'VERDICT: PASS' or 'VERDICT: FAIL'. Read with extractVerdict (same grammar as work-agent); anything else → missing (null) and the re-ask attempt is spent."}},"extractor_module":"../extract.js","kind":"verdict-reask","prompt_builder":"./verdict-reask.js"}

package/lib/chore/prompts/work-agent.js

@@ -0,0 +1,52 @@
+// lib/chore/prompts/work-agent.js — the work-agent prompt builder for the
+// worker-layer chore port (sandbox exit, Piece 2).
+//
+// A pure function of declared params (P1, 2026-09-26): prompts are NOT
+// verbatim-lifted (only 1 of 44 chore prompts was liftable). The frame below
+// reproduces the workPromptBase assembly from workflows/chore.js exactly;
+// the per-step instructions arrive as a param (built by the phase modules),
+// as do the conditional trailers.
+
+import { TOOL_CHECK_PREAMBLE } from "./tool-check.js";
+
+function requiredString(params, name) {
+  var v = params[name];
+  if (typeof v !== "string" || v.length === 0) {
+    throw new Error("buildWorkPrompt: missing required param '" + name + "'");
+  }
+  return v;
+}
+
+export function buildWorkPrompt(params) {
+  var p = params || {};
+  var identity = requiredString(p, "identity");
+  var orchPath = requiredString(p, "orch_path");
+  var taskId = requiredString(p, "task_id");
+  var stepName = requiredString(p, "step_name");
+  var instructions = requiredString(p, "instructions");
+  // Source equivalence (workflows/chore.js): task_title and task_description
+  // flow through `inputs.task_title || ""` — empty values are valid and must
+  // NOT be rejected. Only identity/orch_path/task_id/step_name/instructions
+  // are required.
+  var taskTitle = p.task_title || "";
+  var taskDescription = p.task_description || "";
+  var crewApi = typeof p.crew_api === "string" ? p.crew_api : "";
+  // Source equivalence: the "Crew API:" line is emitted for every step
+  // EXCEPT Review (Cass must not call the Crew API directly — the frame is
+  // `(step.name !== "Review" ? "Crew API: " + CREW_API + "\n" : "")`). The
+  // phase module passes the pinned crew-api path, or "" for Review.
+  var eventPreamble = typeof p.event_preamble === "string" ? p.event_preamble : "";
+  var retryTrailer = typeof p.transport_retry_trailer === "string" ? p.transport_retry_trailer : "";
+  var includeToolCheck = p.include_tool_check !== false;
+
+  return (
+    (includeToolCheck ? TOOL_CHECK_PREAMBLE : "") +
+    "Read the identity file at " + orchPath + "/identities/" + identity + ".md using the read tool, and embody that character fully.\n\n" +
+    "## Your Assignment\n\n" +
+    "Task: " + taskTitle + "\nTask ID: " + taskId + "\nDescription: " + taskDescription + "\nStep: " + stepName + "\n" +
+    (crewApi ? "Crew API: " + crewApi + "\n" : "") +
+    "\n## Instructions\n\n" + eventPreamble + instructions + "\n\nCONSTRAINT: Do NOT call logevent or upsertagentsession — the workflow handles all phase tracking after your step completes.\n\nStay in character. Do the work thoroughly.\n\n" +
+    "Your report is plain prose describing what you did and found. For verdict steps, end the report with exactly one line: VERDICT: PASS or VERDICT: FAIL." +
+    retryTrailer
+  );
+}

package/lib/chore/prompts/work-agent.schema.json

@@ -0,0 +1 @@
+{"_note":"Extractor contract for the work-agent spawn kind — the exact line grammars lib/chore/extract.js requires. This is NOT JSON Schema; 'schema' here means the machine-read report contract the agent's prose must satisfy.","contract":{"bump_version":{"function":"bumpVersion","grammar":"Deterministic semver bump (patch default); computed by the workflow, never by the agent."},"experiential":{"function":"extractExperiential","grammar":"'experiential: yes|no' → boolean; missing or malformed → null (opt-in flag, never parks on a garbled line)."},"marker_lines":{"function":"extractMarkerLines","grammar":"Known prefixes (repo_diff:, release:, version_bump:, VERDICT:, TARGET_VERSION=, published:, experiential:, layer:, capture_targets:, terminal_targets:, worktree:); identical lines deduped. Long reports cannot amputate them — they are re-appended after the summary slice."},"release_decision":{"function":"extractReleaseDecision","grammar":"'release: yes|no' → {release, version_bump}; missing release line → null; 'yes' without version_bump → null (fail closed)."},"repo_diff_none":{"function":"extractRepoDiffNone","grammar":"/repo_diff:\\s*none/im — the builder declared no repo change."},"tool_signals":{"function":"parseToolSignals","grammar":"Lines 'artifact_tools: ok|missing' and 'shell_transport: ok|unavailable' (anchored, first match each). Missing lines → 'unknown', never null."},"verdict":{"function":"extractVerdict","grammar":"The LAST 'VERDICT: PASS|FAIL' in the report; must be in the trailing 100 chars; conflicting verdicts in the trailing 200 chars fail closed. Returns {ok, passed} or {ok:false, count}. Word boundary prevents 'PASSING' matching."},"worktree":{"function":"extractWorktree","grammar":"Line 'worktree: <path>' (last wins); trailing slashes normalized. Missing → {ok:false}."}},"extractor_module":"../extract.js","kind":"work-agent","prompt_builder":"./work-agent.js"}

package/lib/chore/spawn-keys.js

@@ -0,0 +1,44 @@
+// lib/chore/spawn-keys.js — pure spawn-key builders for the worker-layer
+// chore port (sandbox exit, Piece 2).
+//
+// Import-safe: pure functions, no I/O, no clock, no randomness.
+// Key logic from workflows/chore.js:
+//   attemptKey(base, reworkCount)
+//   workRetryKey(stepName, reworkSuffix, attempt)
+//   verdictReaskKey(stepName, reworkSuffix, attempt)
+// plus workKeyBase (the first-attempt work key, inline in chore.js as
+// `"work-" + step.name + (reworkCount > 0 ? "-r" + reworkCount : "")`).
+//
+// Worker-layer difference (2026-09-26): the source's keys were implicitly
+// scoped per workflow process — the runtime keyed agent() calls by explicit
+// key per process, so `work-Triage` could never collide across tasks. The
+// worker-layer ledger (worker_runs) is global per crew home, so every key
+// carries the task id as a suffix. Without it, task B's driver would read
+// task A's completed `work-Triage` row as its own, and the global
+// duplicate-running guard in record-spawn-open would serialize unrelated
+// tasks. The task suffix is the mechanical equivalent of the runtime's
+// per-process scoping.
+
+// attemptKey — replay-key scoping: on rework a re-executed phase mints fresh
+// keys with the same -r<N> suffix as the phase loop. Pure function of inputs,
+// no clock, no randomness (determinism contract).
+export function attemptKey(base, reworkCount) {
+  return base + (reworkCount > 0 ? "-r" + reworkCount : "");
+}
+
+// workKeyBase — the first-attempt work-agent key for a phase visit.
+export function workKeyBase(taskId, stepName, reworkCount) {
+  return "work-" + stepName + (reworkCount > 0 ? "-r" + reworkCount : "") + "-" + taskId;
+}
+
+// workRetryKey — transport-retry work-agent keys: work-<Step>[-r<N>]-t<attempt>-<taskId>
+// (attempt is the 1-based retry number: first retry is -t1).
+export function workRetryKey(taskId, stepName, reworkSuffix, attempt) {
+  return "work-" + stepName + reworkSuffix + "-t" + attempt + "-" + taskId;
+}
+
+// verdictReaskKey — verdict re-ask keys: verdict-reask-<Step>[-r<N>]-a<attempt>-<taskId>
+// (note the -a- infix, not -t-).
+export function verdictReaskKey(taskId, stepName, reworkSuffix, attempt) {
+  return "verdict-reask-" + stepName + reworkSuffix + "-a" + attempt + "-" + taskId;
+}