muse-crew 0.17.2 → 0.17.3

package/API.md

@@ -147,6 +147,17 @@ Records a worker-layer execution in the `worker_runs` ledger (Piece 1, 2026-09-2
 
 Bad transitions (start with an `id`, finish without one, finish with `running`, missing `phase`) throw usage errors (exit 2). Returns `{ "ok": true, "id" }` on start and `{ "ok": true, "finished": true }` on finish. Orphan note: a dispatcher killed between start and finish leaves a `running` row — readers treat a `running` row with no live dispatcher as stale, never as success.
 
+### `get-worker-run`
+
+Reads back the newest orchestration-telemetry row for a task and phase (Piece 3, 2026-09-26). The chore driver has no run-state file, so a relaunched invocation re-discovers its own `worker_runs` row through this read and finishes it instead of minting a duplicate.
+
+| Field | Type | Required | Notes |
+|-------|------|----------|-------|
+| `task_id` | uuid | yes | |
+| `phase` | string | yes | e.g. `chore` |
+
+Returns `{ "ok": true, "row": <worker_runs row> }` for the newest row with matching `task_id`+`phase` and NULL `kind` (spawn-ledger rows carry a `kind` and are never returned); `{ "ok": false, "error": "not_found" }` (exit 3) when no such row exists. Missing args are a usage error (exit 2).
+
 ### `record-version-ack`
 
 Stamps a version acknowledgement (0.14.6). The version must name an issued attempt for the task/commit.

package/docs/decisions/composition-machinery.md

@@ -0,0 +1,180 @@
+# Composition Machinery — Phase A Design Note
+
+**Status:** Proposal — awaiting Eric's ruling.
+**Date:** 2026-09-26
+**In service of:** Park 14 (a real Standard task is the reason this exists).
+
+## 1. What this is
+
+One generic driver replaces the per-workflow drivers (`chore-run.js`, and the
+future `standard-run.js` / `bugfix-run.js` that we are deliberately NOT
+writing). Workflows become declarative specs: phase sequences, transition
+rules, guards, typed handoffs. The driver interprets the spec. Phases remain
+code modules with declared I/O contracts (the §6 discipline from the chore
+port).
+
+Three workflows prove the machinery: Chore (first spec, equivalence proof),
+Standard (validated against Park 14's known trajectory), Bugfix. The
+composition UI comes after the spec is proven — it is a view over the spec,
+not a second source of truth.
+
+## 2. The declarative gradient — recommendation
+
+**Recommendation: declarative about composition, code-backed phases.**
+
+The spec declares *structure*: which phases run, in what order, under what
+guards, with what typed handoffs between them. The phases themselves are code
+— they already are, and they stay that way. The UI composes specs visually
+and renders each phase as a node showing its I/O contract, never its
+internals.
+
+This is not derived from first principles. It is where the incumbent
+landscape converged:
+
+- **n8n, Node-RED, Retool, Langflow, Botpress** (visual-first): the canvas
+  owns structure — sequencing, branching, wiring. Code lives inside opaque
+  nodes with typed edges (n8n's Code node, Node-RED's Function node,
+  Retool's Code block). The UI never breaks on code; it renders the node
+  and its contract.
+- **Temporal, Airflow, Dagster, LangGraph Studio** (code-first): the UI is
+  read-only observability. Nobody draws boxes to define logic.
+- **Nobody does code↔canvas round-trip authoring well.** Every system picks
+  a primary side. The visual-first systems keep the canvas as the durable
+  artifact and code as a contained inline escape.
+
+Eric's P0/P1 maps onto this exactly:
+
+- **P0** (writers, world-builders, problem-solvers composing powerfully):
+  the canvas owns composition. Sequencing, guards, handoffs are all
+  declarative and therefore all visual. A non-programmer can string up a
+  real workflow.
+- **P1** (power users, capabilities not expressed in the UI): the phase is
+  the escape hatch. A code-backed phase appears on the canvas as a node
+  with its declared I/O contract visible — typed edges in, typed edges
+  out — and its implementation opaque. The UI renders it the way n8n
+  renders a Code node: present, honest, unbroken.
+
+**What the spec does NOT get:** conditionals, loops, or scripting in the
+spec format. Retool's docs steer users explicitly toward visual blocks for
+control flow and reserve code blocks for transformation — and their
+community's failure mode is "JavaScript glue scattered across the canvas."
+Our three workflows don't need spec-level branching; they need sequencing,
+guards, and rework loops, all of which are structural. If a future workflow
+needs real branching, that arrives as a phase (code) or as a spec-format
+extension with its own design note — not as an accident.
+
+## 3. Spec format sketch
+
+A workflow spec is data, not code. Sketch (exact syntax TBD in
+implementation):
+
+```
+workflow: standard
+phases:
+  - triage      (contract: reads task, writes classification)
+  - capture     (contract: reads classification, writes evidence bundle)
+  - map         (contract: reads bundle, writes plan)
+  - build       (contract: reads plan, writes worktree + merge record)
+  - review      (contract: reads merge record, writes verdict)
+  - integrate   (contract: reads verdict, writes merge commit)
+  - qa          (contract: reads merge commit, writes qa verdict)
+  - publish     (contract: reads qa verdict, writes published artifact)
+transitions:
+  - on: review.rework   -> to: map        (rework loop)
+  - on: qa.stale        -> to: park       (the Park 14 gate, declarative)
+  - on: phase.failed    -> to: failed
+guards:
+  - qa-bundle-fresh     (named guard, implemented once, referenced by name)
+
+rejectedResume: Build  # Phase B: where a rejected latest session resumes
+                    # (rework entry point — workflow knowledge, spec-declared;
+                    # undeclared + rejected session = fail closed)
+```
+
+What makes this the right level:
+
+- Every transition our three workflows need is expressible: advance,
+  rework-to-earlier-phase, park, fail. These are the typed results the
+  chore driver already handles (ADVANCE / REWIND / PARK / FAILED /
+  NEED_SPAWN / WAIT).
+- Guards are named and implemented once (e.g. the QA staleness check),
+  referenced by name. The spec says *which* guard; code says *how*.
+- Phase I/O contracts are the same §6 contracts the chore port already
+  captured. No new concept.
+
+## 4. Generic driver extraction
+
+`chore-run.js`'s `driveLoop` is already generic. The extraction:
+
+- **Stays in the driver (generic):** derive start phase from ledger state,
+  run phase module, interpret typed result, apply transition table, handle
+  NEED_SPAWN via the ferry, WAIT/re-drive semantics, terminal closeout
+  (DONE/parked/failed), pin lifecycle, the pre-refusal protocol.
+- **Moves to the spec (per-workflow):** phase order, transition table,
+  guard references, phase-to-module mapping.
+- **Stays in phase modules (per-phase):** everything else — the actual
+  work, prompts, guards' implementations.
+
+Transition enforcement note (Phase B, 2026-09-26): the spec's
+`transitions` table is validated (endpoints must name declared phases) but
+not enforced by the driver — the mechanical rule is `result.next ∈
+phaseNames`, which is exact parity with chore-run.js. The table is
+documentation for the future composition UI. Enforcing named transitions
+is a spec-format extension with its own design note, not an accident.
+
+Terminal-transition note (Phase C, 2026-09-26): PARK/FAILED/DONE are result
+types, not phase-to-phase edges, and are NOT declared in the spec's
+`transitions` table — the validator requires `to` to name a declared
+phase, and a terminal outcome has no destination phase. The Standard spec
+initially carried a `QA→park` transition (with a `reason_prefix` the closed
+schema also rejected); both were removed. The park behavior lives in the
+phase module (QA's staleness gate) and the driver's `handlePhaseResult`;
+the spec documents it via the phase's contract string. If the future
+composition UI needs to render terminal edges, that's a spec-format
+extension with its own design note.
+
+Runtime-library note (Phase B): the driver's run helpers (`deriveRunEnv`,
+`pinLifecycle`, `deriveReworkCount`, `projectGuard`, `parkTask`) still
+come from `lib/chore/phase-lib.js`. Generalizing that library is Phase
+C/D work. Known workflow-shaped behavior inside it (must be generalized
+or spec-driven when Standard/Bugfix arrive):
+- `projectGuard`'s abort path writes a failed session with `step: "Build"`
+  and tells the dispatcher to re-launch from Build — chore's rework
+  entry, not a generic one.
+- The experiential seed reads the `"Triage"` session by name.
+
+The driver never imports a workflow by name. It takes a spec path. This is
+what makes the future UI possible: the UI edits specs, the driver runs
+them, and neither knows about the other beyond the spec format.
+
+## 5. Migration path
+
+Same discipline as the chore cutover — additive, proven, then flipped:
+
+1. Build the generic driver + spec loader alongside `chore-run.js`.
+   Nothing changes at runtime.
+2. Express Chore as the first spec. Prove equivalence on scratch: same
+   inputs → same phase sequence → same terminal states. Suite green.
+3. Cut Chore over to the generic driver on the soak cell (one release,
+   same release machinery as 817241c). `chore-run.js`'s bespoke loop
+   retires.
+4. Standard as spec, validated against Park 14's recorded trajectory
+   (Phase C). Bugfix as spec (Phase D).
+5. Read-only visualization (Phase E). Composition editor later, as its
+   own project.
+
+At no point do two drivers run the same workflow. At no point does the
+soak cell run unproven code.
+
+## 6. Open questions for Eric
+
+1. **Gradient:** is "declarative about composition, code-backed phases"
+   the right landing? The alternative is thinner (ordered phase list only,
+   transitions hardcoded in the driver) or thicker (spec-level
+   conditionals). Recommendation is the middle.
+2. **Spec syntax:** JSON, YAML, or a small DSL? Recommendation: start with
+   JSON (mechanical, validatable, no parser to maintain); revisit if
+   humans hand-author specs often.
+3. **Guard implementation:** guards as phase-module exports, or as
+   first-class spec-referenced functions? Recommendation: phase-module
+   exports — fewer concepts, guards live next to the phases they protect.

package/docs/decisions/publish-path.md

@@ -766,6 +766,12 @@ The fix is in the lifecycle, not the prompt. The old merged-but-unpushed recover
 
 Applies to: lib/worktree-lifecycle.sh; standard, bugfix, chore (one marker line).
 
+### Fast-forward recovery (2026-09-27, Park 14)
+
+Park 14's Integrate failed 3x with STALE_MERGE: the archive work had landed on soak/main by fast-forward (no merge commit exists), so `current_branch_merge()` found nothing — but a merge WAS recorded and the branch tip is exactly the target tip. The `ahead==0` recovery now also recognizes this shape via `ff_integrated()`: branch tip == target tip, exact equality only. Ancestry alone is NOT accepted — a branch reset backward after integration remains an ancestor of the target, and accepting it would defeat blocker-35 (fixture F3). The ff recovery fires only when a merge is recorded (genuine empty diffs still take MERGED_EMPTY with no lock). No merge record is appended for the ff shape: the state is self-describing (tip == target tip).
+
+Applies to: lib/worktree-lifecycle.sh (ff_integrated, cmd_integrate, cmd_push_target).
+
 <a id="publish-diff-base"></a>
 ## Publish diff base (BASE..HEAD)
 

package/docs/decisions/workflow-core.md

@@ -193,14 +193,15 @@ Applies to: standard, bugfix, chore.
 <a id="discarded-reason"></a>
 ## Discarded reason
 
-Invariant: the runtime threw the output away; reason is discarded.
+Invariant: a throw is classified — only the runtime scanner's "output was not JSON" throw is a brace discard; any other throw is an agent error (2026-09-27, Park 14: Integrate errored on a real STALE_MERGE while the trailer claimed a brace discard). Reason is "discarded" for scanner discards, "errored" for agent errors — the retry must not be told to reword prose when the underlying command failed.
 
-Applies to: standard, bugfix, chore.
+Applies to: standard, bugfix, chore, docs.
 
 ```
   // reason: "discarded" (the runtime threw the output away - it could not be
-  // machine-read), "empty" (agent() returned without throwing but produced
-  // nothing usable), "no-tools" (the worker's TOOL CHECK reported
+  // machine-read), "errored" (the attempt errored before producing a usable
+  // report — not a brace discard), "empty" (agent() 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.

package/lib/AGENTS.md

@@ -10,9 +10,10 @@ Shipped library: ESM JavaScript CLIs and import-safe modules, shell scripts for
 
 - `build-registry.js` — deterministic extractor that generates `workflows/registry.json` (workflow step registry) from the workflow files' `meta` blocks at release time; invoked by `crew-release.sh` deploy
 - `crew-api.js` — the crew-owned task-service API (dependency inversion, 2026-09-11): a zero-dependency Node CLI implementing the API.md contract against `$CREW_HOME/crew-state.db` (schema in `schema.sql`). Workflows call it through their agents' shell; the dashboard delegates to it. All state-machine invariants live as CHECK constraints in the schema, never in client prose. Includes the `record-phase` composite (session + event in one transaction; 2026-09-21 optionally carries a structured Review verdict payload — validated at the API boundary, written to the `verdicts` table in the same transaction, session-keyed first-write-wins idempotency — plus the `get-verdicts` read surface) and a one-time `migrate` import from a dashboard app.db. Active-release resolution is split in two (room #15): `resolveActiveReleaseName` (symlink-only — writers like the initial-provenance stamp record the active release without proving they are it) and `resolveActiveRelease` (symlink + self-path cross-check — verifiers like `scan-ack-pending` refuse to stamp claims when the running code isn't the active release's own). Provenance is per-project (2026-09-18, room #15 blocker 8): nullable `provenance_*` columns on the projects row, a single `stampProvenance()` writer, `set-provenance`/`get-provenance` require `project_id` (no silent global fallback), and a watermarked openDb backfill that attributes the legacy `config.provenance.*` triple to exactly-one ancestor match — never fabricated, otherwise deferred.
-- `crew-dispatch-worker.js` — worker-layer port of the sandboxed dispatch dispatcher (Piece 1, 2026-09-26): full-privilege Node, reads the board through crew-api.js via execFile (argv only, no shell), reproduces the eligibility / retry / reservation / playtest / tick-release / dispatch-decision logic, and tags every claim `executor: "worker"`. In Piece 1 it runs `--read-only` as the tick's shadow BEFORE the authoritative sandboxed dispatcher — both read the same board state; the shadow never mutates it, never launches, never writes the tick-release or dispatch-decision logs. Appends its own shadow evidence line to `$CREW_HOME/.dispatch-shadow.jsonl` (machine-written, no agent transcription). Claims are recommendations only: `executor` names the layer that computed the recommendation, not the layer that launched it — in Piece 1 no `executor: "worker"` claim is ever launched.
+- `crew-dispatch-worker.js` — worker-layer port of the sandboxed dispatch dispatcher (Piece 1, 2026-09-26): full-privilege Node, reads the board through crew-api.js via execFile (argv only, no shell), reproduces the eligibility / retry / reservation / playtest / tick-release / dispatch-decision logic, and tags every claim `executor: "worker"`. Modes: default is the safe shadow (compute claims, no writes — `--read-only` is an explicit alias); `--authoritative` acquires claims via `reserve-dispatch` (the same atomic UPSERT the sandbox uses), acknowledges the poll, and writes the tick-release/dispatch-decision logs. In Piece 1 it runs `--read-only` as the tick's shadow BEFORE the authoritative sandboxed dispatcher — both read the same board state; the shadow never mutates it, never launches, never writes the tick-release or dispatch-decision logs. Appends its own shadow evidence line to `$CREW_HOME/.dispatch-shadow.jsonl` (machine-written, no agent transcription). Claims are recommendations only: `executor` names the layer that computed the recommendation, not the layer that launched it — in Piece 1 no `executor: "worker"` claim is ever launched.
 - `compare-dispatch-shadow.js` — mechanical shadow verdict (Piece 1, 2026-09-26): pairs each `.dispatch-shadow.jsonl` line with the authoritative `.dispatch-decisions.jsonl` line for the same tick (`decision.tick_seq === shadow.tick_seq_before + 1` — the shadow runs first, the sandbox dispatcher then writes its tick-release line and its decision) and compares the sorted `task_id|workflow|step` claim triples, ignoring `executor`. Emits `SHADOW_MATCH` / `SHADOW_DIVERGE` (names the differing triples) / `SHADOW_UNPAIRED` (decision missing — the authoritative dispatcher died) and appends the verdict to `$CREW_HOME/.dispatch-shadow-verdicts.jsonl`; idempotent (already-verdict shadows are skipped). Exit 0 on a verdict — divergence is evidence for the cutover review, not a tick failure; exit 2 on usage/IO errors.
 - `spawn-boundary.js` — fail-closed spawn-bounds validator (Piece 1, 2026-09-26): import-safe ESM, `validateSpawnBounds()` requires prompt/schema co-location, cwd inside the workdir, rejection of cwd inside crew state/observer paths or crewHome, and rejection of sensitive env-key patterns; throws `BOUNDS_REJECTED`. Bare module execution exits 0 (release entry-gate contract). The production spawn/request wrapper is Piece-3 work; this is only the validator.
+- `chore-run.js` — Chore driver loop (sandbox-exit Piece 3, 2026-09-26): the worker-layer port of `workflows/chore.js`. Shebang CLI, per-boundary stateless invocation — `node lib/chore-run.js --crew-home <dir> --task-id <id> --tick-seq <n>`; stdout carries exactly one JSON frame (`NEED_SPAWN` | `WAIT` | `DONE`), all logs on stderr. Sequences the seven phase modules in `lib/chore/phases/` (Triage → Publish) with ADVANCE/REWIND routing, fresh per-phase claims (one session per phase, source parity), task-scoped spawn keys, and fail-closed derivation (a derivation failure emits `DONE failed`, never a partial advance). No `agent()` calls; deterministic work is `execFile` to the pinned `crew-api.js` (argv only, no shell); creative boundaries are emitted as `NEED_SPAWN` for the spawn bridge. `--help` usage on stdout, exit 0 (shebang⇔CLI contract).
 - `schema.sql` — the crew-owned state schema: projects, tasks, poll_state, config, agent_sessions, events. Vocabularies enforced by CHECK constraints; `rejected` is a valid event type (the 2026-09-11 crash was a stored session whose event was rejected). Column names match the historical dashboard tables for a verbatim migration.
 - `crew-release.sh` — immutable release manager: deploy, rollback, prune
 - `merge-lock.sh` — serialized merge lock for concurrent agents: time-based holder lease (bug 2fc8f52f — an unexpired lease is held regardless of process liveness; only an expired lease may be broken). Requires both `CREW_REPO` and `CREW_HOME` (fail closed: BLOCKED, exit 2 when either is unset). Lock file is key=value: task_id, opaque holder identity (never a PID), acquired_at epoch, lease_seconds (default 600, override via MERGE_LOCK_LEASE_SECONDS). acquire/refresh/release/status/force-release; holder-only refresh and release; every op appends to $CREW_HOME/.merge-lock.log. Stale-lease breaks serialize on a sidecar `$LOCK_FILE.flock` with an in-critical-section lease re-read (R-B1, 2026-09-21); refresh rewrites via temp-file + atomic rename so readers never see a torn file, and takes the same sidecar flock with an identity-only re-check inside the critical section — a reclaim always changes `task_id`, so identity alone closes the clobber (no expiry check on refresh: a long build that outran the lease legitimately revives its lock); release takes the same flock with the identity re-check inside (review pass 2, 2026-09-21) so a release can never `rm` a reclaimer's fresh lock.

package/lib/bugfix/phases/build.js

@@ -0,0 +1,168 @@
+// lib/bugfix/phases/build.js — Bugfix Build phase (worker layer).
+//
+// Wren implements Mara's spec in a git worktree, commits as
+// "fix: <title>", and declares a machine-readable verdict. Derived from
+// workflows/bugfix.js (the Bugfix Build step).
+//
+// Contract:
+//   - Read: mapper spec (re-derived from the latest completed Map session
+//     notes — the durable handoff); rejection notes (re-derived from the
+//     latest rejected Review/QA session notes on rework); task title;
+//     project surface/description; publish type.
+//   - Instructions: exact Bugfix prompt — worktree prepare, heartbeat,
+//     mapper spec, worktree hint, UX bars, public docs, npm release
+//     declaration (when publish type is npm), commit as "fix: <title>",
+//     repo_diff:none allowance, rework notes, worktree + VERDICT markers.
+//   - Worktree confinement (verdict PASS only): the declared `worktree:`
+//     path must match the worktree hint exactly, else the phase fails for
+//     dispatcher retry.
+//   - Verdict FAIL still falls through to Review (recorded "rejected") —
+//     Build never parks and never rewinds on its own verdict.
+//   - The release decision (release:/version_bump:) is extracted by Review
+//     from these durable session notes (marker lines survive the summary
+//     truncation).
+//   - Advance: Review (on both PASS and FAIL).
+//
+// Phase I/O contract (Phase D):
+//   read:  Map session notes (completed), Review/QA session notes
+//          (rejected, for rework), task title, project surface/desc,
+//          publish type
+//   write: session (completed | rejected | failed [confinement]),
+//          event (completed | rejected | failed [confinement])
+//   out:   ADVANCE → Review | NEED_SPAWN / STANDBY / FAILED (boundary /
+//          confinement)
+
+import {
+  runWorkBoundary, recordPhase, buildEventPreamble, summarizeReport,
+  ensureClaimed, log, latestSessionNotes, crewApi, lifecycleEnvPrefix,
+} from "../../workflow-lib.js";
+import { extractWorktree } from "../../extract.js";
+
+export const PHASE = { name: "Build", identity: "wren" };
+
+// buildInstructions — verbatim from workflows/bugfix.js (variable
+// references remapped; logic and prose unchanged).
+// ctx: { env, state, mapperSpec, rejectionNotes, safeTitle }.
+export function buildInstructions(ctx) {
+  var env = ctx.env, state = ctx.state;
+  var instructions = "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\": \"" + 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" +
+      (ctx.mapperSpec ? "MAPPER'S SPEC (implement exactly this):\n" + ctx.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. 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 \"fix: " + ctx.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" +
+      (ctx.rejectionNotes ? "This is REWORK after rejection. Address these specific issues:\n" + ctx.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 \u2014 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 \u2014 it must match character-for-character), then exactly one line: VERDICT: PASS if the build is complete, VERDICT: FAIL if it is not.");
+
+  
+  return instructions;
+}
+
+// latestRejectionNotes — the notes of the latest rejected Review or QA
+// session (the worker-layer equivalent of the source's in-memory
+// rejectionNotes, set when Review/QA rejects and read by the next Build).
+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 || "") : "";
+}
+
+export async function runPhase(ctx) {
+  var env = ctx.env, state = ctx.state;
+
+  // Mapper spec: the durable handoff from Map (the truncated summary Map
+  // recorded — marker lines preserved).
+  ctx.mapperSpec = await latestSessionNotes(env, "Map", "completed");
+  // Rework: the rejecting reviewer's notes, when this Build follows a
+  // Review/QA rejection.
+  ctx.rejectionNotes = await latestRejectionNotes(env);
+  // safeTitle: the commit-message-safe title (source: safeTitle).
+  ctx.safeTitle = String(env.taskTitle || "").replace(/"/g, "'").replace(/\\/g, "\\\\").replace(/`/g, "'");
+
+  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 workerText = boundary.workerText;
+  var verdictPassed = boundary.verdictPassed === true;
+
+  // Worktree confinement (verdict PASS only): the declared worktree path
+  // must match the hint exactly. A builder that worked outside the
+  // configured checkout fails the phase for dispatcher retry.
+  if (verdictPassed) {
+    var wt = extractWorktree(workerText);
+    if (!wt.ok || wt.path !== env.worktreeHint) {
+      var declared = wt.ok ? wt.path : "<none>";
+      log("Build worktree confinement failed — declared: " + declared + ", expected: " + env.worktreeHint + " — marking failed for retry");
+      await recordPhase(env, {
+        task_id: env.taskId,
+        session: {
+          id: state.activeSessionId, task_id: env.taskId, identity: PHASE.identity,
+          step: PHASE.name, status: "failed",
+          notes: "Build declared worktree " + declared + " — expected " + env.worktreeHint + ". The builder worked outside the configured repo checkout; phase failed for retry",
+        },
+        event: {
+          task_id: env.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 " + declared + " but the task's worktree is " + env.worktreeHint + ". The phase is marked failed; the dispatcher will retry Build against the configured repo.",
+      };
+    }
+  }
+
+  // Closeout: a FAIL still falls through to Review (recorded "rejected").
+  // The release decision rides in the session notes' marker lines for
+  // Review to extract.
+  var status = verdictPassed ? "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: summarizeReport(workerText),
+    },
+    event: {
+      task_id: env.taskId, type: status, identity: PHASE.identity,
+      message: "Build " + status + " by " + PHASE.identity,
+    },
+  });
+  return { type: "ADVANCE", next: "Review" };
+}

package/lib/bugfix/phases/capture.js

@@ -0,0 +1,170 @@
+// lib/bugfix/phases/capture.js — Capture (hazel) phase module (sandbox
+// exit, Phase D). Import-safe: no side effects on import, bare `node`
+// exits 0.
+//
+// The capture mechanism is identical to the standard workflow's (same
+// baseline note protocol, same terminal/artifact paths, same park path);
+// the only bugfix difference is the advance target: Capture feeds
+// Reproduce, not Map.
+//
+// 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 → Reproduce 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, shared with
+// the standard workflow's Capture (same steps, same machine-read
+// declaration contract). Steps 1–5 verbatim from workflows/bugfix.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: "Reproduce" };
+  }
+
+  // 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: "Reproduce" };
+  }
+
+  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: "Reproduce" };
+  }
+
+  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: "Reproduce" };
+  }
+
+  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: "Reproduce" };
+  }
+  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;
+}