cclaw-cli 0.51.24 → 0.51.26

package/dist/content/examples.js

@@ -490,7 +490,7 @@ const GOOD_BAD_EXAMPLES = {
         },
         {
             label: "Scope change trace",
-            good: "Scope delta at 2026-04-15: user asked to add per-user mute preferences. Decision: moved from Out-of-scope → In-scope; acknowledged cost (≈1 day, +1 schema migration); risk: touches settings surface. Recorded in \`03-design.md#scope-trace\`. Requires re-running scope review before design lock.",
+            good: "Scope delta at 2026-04-15: user asked to add per-user mute preferences. Decision: moved from Out-of-scope → In-scope; acknowledged cost (≈1 day, +1 schema migration); risk: touches settings surface. Recorded in \`.cclaw/artifacts/03-design-<slug>.md#scope-trace\`. Requires re-running scope review before design lock.",
             bad: "Added mute preferences to scope.",
             lesson: "Scope changes silently are how projects drift. Every in↔out move needs a timestamp, a cost estimate, and a link to the next review it invalidates."
         }
@@ -676,12 +676,13 @@ function exampleSummaryBullets(stage) {
 const STAGE_EXAMPLE_SECTION_HEADINGS = {
     brainstorm: [
         "Problem Decision Record (product or technical-maintenance framing)",
-        "Candidate approaches with trade-offs",
+        "Reference Pattern Candidates and approaches with trade-offs",
         "Recommended direction + open questions",
         "Clarification log and decision record"
     ],
     scope: [
         "In-scope / out-of-scope / deferred lists with concrete capabilities",
+        "Reference Pattern Registry with accepted/rejected/deferred dispositions",
         "Requirements table with stable R# IDs",
         "Boundary stress-tests and non-negotiables",
         "Decision record for premise challenges"
@@ -689,6 +690,7 @@ const STAGE_EXAMPLE_SECTION_HEADINGS = {
     design: [
         "Blast-radius file list",
         "Mandatory architecture diagram (Mermaid)",
+        "Reference-Grade Contracts for mirrored patterns",
         "Failure-mode table with detection + mitigation",
         "Test strategy + performance budget",
         "Completion dashboard + unresolved decisions"
@@ -706,7 +708,7 @@ const STAGE_EXAMPLE_SECTION_HEADINGS = {
         "No-Placeholder scan row + WAIT_FOR_CONFIRM marker"
     ],
     tdd: [
-        "RED evidence per slice (failing test output)",
+        "RED evidence per vertical slice (failing test output)",
         "Acceptance mapping per slice",
         "GREEN evidence (full-suite pass)",
         "REFACTOR notes with behavior-preservation confirmation",
@@ -716,10 +718,11 @@ const STAGE_EXAMPLE_SECTION_HEADINGS = {
         "Spec-compliance findings (Layer 1)",
         "Code-quality findings (Layer 2)",
         "Severity, evidence, and status per finding",
-        "Go / no-go verdict"
+        "Victory Detector-backed go / no-go verdict"
     ],
     ship: [
         "Release checklist (version, changelog, tag, artifacts)",
+        "Victory Detector: valid review, fresh preflight, rollback, finalization enum",
         "Rollback plan with trigger, steps, verification",
         "Runbook (how to verify the release post-deploy)",
         "Sign-off block"
@@ -732,7 +735,7 @@ const DOMAIN_LABELS = {
     "data-pipeline": "Data pipeline / ETL"
 };
 export const RESEARCH_FLEET_USAGE_EXAMPLE = [
-    "Before drafting `03-design.md`, run `research/research-fleet.md` once and",
+    "Before drafting `.cclaw/artifacts/03-design-<slug>.md`, run `research/research-fleet.md` once and",
     "capture all four lenses in `.cclaw/artifacts/02a-research.md`.",
     "Dispatch semantics by harness: Claude/OpenCode/Codex = native subagents;",
     "Cursor = generic-dispatch Task mapping; role-switch only as degraded fallback.",

package/dist/content/harness-doc.d.ts

@@ -0,0 +1 @@
+export declare function harnessIntegrationDocMarkdown(): string;

package/dist/content/harness-doc.js

@@ -0,0 +1,3 @@
+export function harnessIntegrationDocMarkdown() {
+    return "# Harness Integration Matrix\n\nGenerated from `src/harness-adapters.ts` capabilities and hook event mappings. For the end-to-end subagent dispatch model, proof sequence, controller/worker responsibilities, and future roadmap, see [`docs/subagent-flow.md`](./subagent-flow.md).\n\n## Capability tiers\n\n| Harness | ID | Tier | declaredSupport | runtimeLaunch | Fallback | proofRequired | proofSource | Hook surface | Structured ask |\n|---|---|---|---|---|---|---|---|---|---|\n| Claude Code | `claude` | `tier1` (full native automation) | full | native Task launch | native | spanId+dispatchId or workerRunId+ACK | `.cclaw/state/delegation-events.jsonl` + ledger | full | AskUserQuestion |\n| Cursor | `cursor` | `tier2` (supported with fallback paths) | generic | generic Task/Subagent role prompt | generic-dispatch | spanId+dispatchId/evidenceRefs | events + artifact evidenceRefs | full | AskQuestion |\n| OpenCode | `opencode` | `tier2` hooks, native dispatch declared | full | prompt-level launch via Task / `@agent` against `.opencode/agents` | native | spanId+dispatchId+ackTs+completedTs | `.opencode/agents/<agent>.md` + events | plugin | question |\n| OpenAI Codex | `codex` | `tier2` hooks, native dispatch declared | full | prompt-level request to spawn `.codex/agents` custom agents | native | spanId+dispatchId+ackTs+completedTs | `.codex/agents/<agent>.toml` + events | limited | request_user_input |\n\nFallback legend:\n\n- `native` \u2014 first-class named subagent dispatch (Claude).\n- `generic-dispatch` \u2014 generic Task dispatcher mapped to cclaw roles (Cursor).\n- `role-switch` \u2014 degraded fallback for a runtime where declared native/generic dispatch is unavailable; explicit role headers, artifact outputs, and non-empty delegation-log evidenceRefs are required.\n- `waiver` \u2014 no parity path; reserved for harnesses that cannot role-switch (none shipped).\n\n## Stage-Aware Native Dispatch Workflow\n\nOpenCode and Codex receive generated native isolated subagents. Use them before considering role-switch fallback:\n\n1. Use the active stage skill's generated dispatch table as the source of truth.\n2. OpenCode: invoke `.opencode/agents/<agent>.md` via Task or `@<agent>`; Codex: ask Codex to spawn `.codex/agents/<agent>.toml` by name, in parallel when lanes are independent.\n3. Load `.cclaw/agents/<agent>.md`, execute only that role's stage task, and write outputs into the active stage artifact.\n4. Append `.cclaw/state/delegation-events.jsonl` for scheduled/launched/acknowledged/completed/failed/waived/stale, then mirror current state in `.cclaw/state/delegation-log.json`. The ledger is current state; the event log is proof/audit.\n5. Treat completed role-switch rows without `evidenceRefs` as unresolved; treat native isolated completion without matching `spanId` + `dispatchId`/`workerRunId` + `ackTs` + `completedTs` as fake isolated completion. Native isolated rows are not a role-switch substitute and should reflect a real dispatched worker.\n\nThis is staged agent work backed by the harness-native subagent surfaces. Role-switch remains only a degraded fallback when that surface is unavailable in the active runtime.\n\n## Parallel research dispatch semantics\n\nDesign-stage research fleet uses the same parity model:\n\n- **Claude / Cursor**: dispatch all four research lenses in one turn\n  (stack, features, architecture, pitfalls) and synthesize into\n  `.cclaw/artifacts/02a-research.md`.\n- **OpenCode / Codex**: dispatch generated native subagents for the same\n  four lenses and run independent lanes in parallel where the active runtime\n  permits. Use role-switch with evidence only as a degraded fallback.\n\n## Semantic hook event coverage\n\n| Event | Claude | Cursor | OpenCode | Codex |\n|---|---|---|---|---|\n| `session_rehydrate` | SessionStart matcher startup|resume|clear|compact | sessionStart/sessionResume/sessionClear/sessionCompact | plugin event handlers + transform rehydration | SessionStart matcher startup|resume |\n| `pre_tool_prompt_guard` | PreToolUse -> prompt-guard | preToolUse -> prompt-guard | plugin tool.execute.before -> prompt-guard | PreToolUse matcher Bash -> prompt-guard (plus UserPromptSubmit for non-Bash prompts) |\n| `pre_tool_workflow_guard` | PreToolUse -> workflow-guard | preToolUse -> workflow-guard | plugin tool.execute.before -> workflow-guard | PreToolUse matcher Bash -> workflow-guard (Bash-only) |\n| `post_tool_context_monitor` | PostToolUse -> context-monitor | postToolUse -> context-monitor | plugin tool.execute.after -> context-monitor | PostToolUse matcher Bash -> context-monitor (Bash-only) |\n| `stop_handoff` | Stop -> stop-handoff | stop -> stop-handoff | plugin session.idle -> stop-handoff | Stop -> stop-handoff |\n| `precompact_compat` | PreCompact -> pre-compact | sessionCompact -> pre-compact | plugin session.compacted -> pre-compact | missing |\n| `strict_state_verify` | missing | missing | missing | UserPromptSubmit -> verify-current-state (blocks only in strict mode) |\n\n## Hook lifecycle aliases\n\nThe generated Node dispatcher accepts a small compatibility alias set for lifecycle names: `stop` and `stop-checkpoint` route to `stop-handoff`, `precompact` routes to `pre-compact`, and `session-rehydrate` routes to `session-start`. The `pre-compact` handler is intentionally a no-op compatibility marker; rehydration remains the `session-start` responsibility after compact events. Harness JSON should still emit the canonical handler names from `src/content/hook-manifest.ts`.\n\n## Hook event casing\n\nHook keys are intentionally harness-native and must not be normalized:\n\n| Harness | ID | Event key casing |\n|---|---|---|\n| Claude Code | `claude` | PascalCase (`SessionStart`, `PreToolUse`) |\n| Cursor | `cursor` | camelCase (`sessionStart`, `preToolUse`) |\n| OpenCode | `opencode` | camelCase (`sessionStart`, `preToolUse`) |\n| OpenAI Codex | `codex` | PascalCase (`SessionStart`, `PreToolUse`) |\n\nUse the exact event names from each harness schema. Treating all hooks as one\nshared casing silently breaks generated wiring.\n\n## Interpretation\n\n- `tier1`: full native delegation + structured asks + full hook surface.\n- `tier2`: usable flow with capability gaps; mandatory delegation can require waivers.\n- Codex-specific ceiling: `PreToolUse` can only intercept `Bash`. Direct\n  `Write`/`Edit` to `.cclaw/state/flow-state.json` cannot be hard-blocked\n  at hook level, so the canonical path is\n  `node .cclaw/hooks/stage-complete.mjs <stage>` plus the non-blocking\n  `UserPromptSubmit` state nudge.\n- In `strict` mode, Codex additionally runs the generated Node/runtime `verify-current-state` path on `UserPromptSubmit` as a fail-closed check. Advisory mode remains non-blocking, including when the generated local Node entrypoint is missing; doctor reports that install drift separately. This strict-only coverage is represented explicitly by the `strict_state_verify` semantic row above.\n\n## Shared command contract\n\nAll harnesses receive the same utility commands:\n\n- `/cc` - flow entry and resume\n- `/cc-next` - stage progression and post-ship closeout\n- `/cc-ideate` - ideate mode for ranked repo-improvement backlog\n- `/cc-view` - read-only router for status/tree/diff\n\nRead-only subcommands:\n- `/cc-view status` - visual flow snapshot\n- `/cc-view tree` - deep flow tree (stages, artifacts, stale markers)\n- `/cc-view diff` - before/after flow-state diff map\n\nOperational work is handled by `/cc`, `/cc-next`, `/cc-ideate`, `/cc-view`, and `node .cclaw/hooks/stage-complete.mjs <stage>` inside the installed harness runtime. `npx cclaw-cli` is the installer/support surface for init, sync, upgrade, doctor, and explicit/manual archive; the normal stage flow must not depend on a runtime `cclaw` binary in PATH.\n\nCritical-path stage order remains canonical:\n`brainstorm -> scope -> design -> spec -> plan -> tdd -> review -> ship`\n\nEvery track then closes out through:\n`retro -> compound -> archive`\n\n## Stage -> skill folder mapping\n\n| Stage | Skill folder |\n|---|---|\n| `brainstorm` | `brainstorming` |\n| `scope` | `scope-shaping` |\n| `design` | `engineering-design-lock` |\n| `spec` | `specification-authoring` |\n| `plan` | `planning-and-task-breakdown` |\n| `tdd` | `test-driven-development` |\n| `review` | `two-layer-review` |\n| `ship` | `shipping-and-handoff` |\n\nThis map is generated from `src/constants.ts::STAGE_TO_SKILL_FOLDER` so\nskill-path naming stays explicit and stable even when stage ids differ from\nfolder names.\n\n## Install surfaces\n\nAlways generated:\n\n- `.cclaw/commands/*.md`\n- `.cclaw/skills/*/SKILL.md`\n- `.cclaw/state/*.json|*.jsonl`\n- `AGENTS.md` managed block\n\nHarness-specific additions:\n\n- `claude`: `.claude/commands/cc*.md`, `.claude/hooks/hooks.json`\n- `cursor`: `.cursor/commands/cc*.md`, `.cursor/hooks.json`, `.cursor/rules/cclaw-workflow.mdc`\n- `opencode`: `.opencode/commands/cc*.md`, `.opencode/plugins/cclaw-plugin.mjs`, opencode plugin registration with `permission.question: \"allow\"`; set `OPENCODE_ENABLE_QUESTION_TOOL=1` for ACP clients so structured asks can route through question tooling. Doctor validates the config permission and warns when the environment hint is absent.\n- `codex`: `.agents/skills/cc/SKILL.md`, `.agents/skills/cc-next/SKILL.md`, `.agents/skills/cc-ideate/SKILL.md`, `.agents/skills/cc-view/SKILL.md`, `.codex/hooks.json` (Codex CLI reads `.agents/skills/` for custom skills and consumes `.codex/hooks.json` on v0.114+ when `[features] codex_hooks = true` is set in `~/.codex/config.toml`. `.codex/commands/` and the legacy `.agents/skills/cclaw-cc*/` layout from v0.39.x are auto-cleaned on sync.)\n\n## Runtime observability\n\n- `npx cclaw-cli doctor` validates shim, hook, and lifecycle surfaces against this capability model.\n- `/cc-view status` and `/cc-view tree` surface the same harness tier/fallback facts from the generated runtime metadata.\n\n## Delegation Proof Model\n\nRuntime state is split deliberately:\n\n- `.cclaw/state/delegation-log.json` is the compact current ledger used by stage gates and `/cc-view` summaries.\n- `.cclaw/state/delegation-events.jsonl` is append-only audit proof for `scheduled`, `launched`, `acknowledged`, `completed`, `failed`, `waived`, and `stale` lifecycle transitions.\n- `.cclaw/state/subagents.json` is a lightweight active-worker tracker for status/tree/doctor surfaces.\n- `.cclaw/hooks/delegation-record.mjs` is the generated helper for lifecycle rows/events. It validates required fields and emits JSON diagnostics with `--json`.\n\nIsolated completion requires `spanId`, `dispatchId` or `workerRunId`, `dispatchSurface`, `agentDefinitionPath`, `ackTs`, `launchedTs`, and `completedTs`. Cursor/generic dispatch and role-switch also require evidence refs when artifact evidence is the proof source. Legacy inferred completions remain readable, but doctor reports them as warnings because they predate event-log proof.\n\n## Reference Audit Appendix\n\nStatus meanings: `deep` = read for transferable implementation contract; `targeted` = inspected the relevant files only; `skimmed` = searched/read enough to classify; `not relevant` = intentionally excluded from implementation influence.\n\n| Reference path under `/Users/zuevrs/Downloads/references` | Status | Findings preserved |\n|---|---|---|\n| `evanklem-evanflow/skills/evanflow-coder-overseer/SKILL.md` | deep | Contract-first coder/overseer loop, reviewer reads code rather than worker narrative, and integration overseer pattern map cleanly onto cclaw subagent guidance. |\n| `evanklem-evanflow/agents/evanflow-coder.md` | targeted | Worker role is narrow: implement the pasted contract, avoid broad orchestration, and return evidence for overseer verification. |\n| `evanklem-evanflow/agents/evanflow-overseer.md` | targeted | Overseer validates actual code and acceptance evidence before controller marks work complete. |\n| `oh-my-codex/src/agents/native-config.ts` | deep | Native agent config shape supports explicit metadata/model/tool posture; cclaw should validate generated `.codex/agents/*.toml` shape instead of trusting file presence. |\n| `oh-my-codex/src/team/state/events.ts` and `src/team/state/workers.ts` | targeted | Append-only events plus worker state are useful as separate audit/current-state layers; cclaw mirrors that with `delegation-events.jsonl` and `subagents.json`. |\n| `oh-my-openagent/src/tools/delegate-task/tools.ts` | deep | Delegation should have an explicit dispatch surface and mode instead of relying on a prose claim that an agent was launched. |\n| `oh-my-openagent/src/tools/delegate-task/subagent-resolver.ts` | targeted | Agent discovery should be checked by doctor so missing/corrupt generated agent definitions are visible before dispatch. |\n| `oh-my-openagent/src/tools/delegate-task/prompt-builder.ts` | targeted | Prompt builders should include exact invocation/return contracts; cclaw generated worker prompts now carry ACK/result schemas. |\n| `giancarloerra-socraticode/**` | skimmed | Useful for workflow/e2e and graph-oriented contract testing, but not a subagent dispatch implementation reference; no runtime pattern imported. |\n| unrelated large reference trees not named above | not relevant | Searched/skipped because they did not contain flow/subagent/harness dispatch patterns relevant to this plan. |\n";
+}

package/dist/content/hooks.d.ts

@@ -1,5 +1,6 @@
 export declare function startFlowScript(): string;
 export declare function stageCompleteScript(): string;
+export declare function delegationRecordScript(): string;
 export declare function runHookCmdScript(): string;
 export { claudeHooksJsonWithObservation as claudeHooksJson } from "./observe.js";
 export { cursorHooksJsonWithObservation as cursorHooksJson } from "./observe.js";

package/dist/content/hooks.js

@@ -260,6 +260,195 @@ async function main() {
   });
 }
 
+void main();
+`;
+}
+export function delegationRecordScript() {
+    return `#!/usr/bin/env node
+import fs from "node:fs/promises";
+import path from "node:path";
+import process from "node:process";
+
+const RUNTIME_ROOT = ${JSON.stringify(RUNTIME_ROOT)};
+const VALID_STATUSES = new Set(["scheduled", "launched", "acknowledged", "completed", "failed", "waived", "stale"]);
+const TERMINAL = new Set(["completed", "failed", "waived", "stale"]);
+
+function parseArgs(argv) {
+  const args = {};
+  for (const raw of argv) {
+    const valueMatch = /^--([^=]+)=(.*)$/u.exec(raw);
+    if (valueMatch) {
+      args[valueMatch[1]] = valueMatch[2];
+      continue;
+    }
+    const flagMatch = /^--([^=]+)$/u.exec(raw);
+    if (flagMatch) args[flagMatch[1]] = true;
+  }
+  return args;
+}
+
+async function exists(filePath) {
+  try {
+    await fs.access(filePath);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function detectRoot() {
+  const candidates = [
+    process.env.CCLAW_PROJECT_ROOT,
+    process.env.CLAUDE_PROJECT_DIR,
+    process.env.CURSOR_PROJECT_DIR,
+    process.env.CURSOR_PROJECT_ROOT,
+    process.env.OPENCODE_PROJECT_DIR,
+    process.env.OPENCODE_PROJECT_ROOT,
+    process.cwd()
+  ].filter((value) => typeof value === "string" && value.length > 0);
+  for (const candidate of candidates) {
+    if (await exists(path.join(candidate, RUNTIME_ROOT))) return candidate;
+  }
+  return candidates[0] || process.cwd();
+}
+
+async function readRunId(root) {
+  try {
+    const raw = await fs.readFile(path.join(root, RUNTIME_ROOT, "state", "flow-state.json"), "utf8");
+    const parsed = JSON.parse(raw);
+    return typeof parsed.activeRunId === "string" ? parsed.activeRunId : "unknown-run";
+  } catch {
+    return "unknown-run";
+  }
+}
+
+async function readDelegationEvents(root) {
+  try {
+    const raw = await fs.readFile(path.join(root, RUNTIME_ROOT, "state", "delegation-events.jsonl"), "utf8");
+    return raw
+      .split(/\\r?\\n/u)
+      .filter((line) => line.trim().length > 0)
+      .map((line) => {
+        try {
+          return JSON.parse(line);
+        } catch {
+          return null;
+        }
+      })
+      .filter((event) => event && typeof event === "object");
+  } catch {
+    return [];
+  }
+}
+
+function hasPriorAck(events, args, runId) {
+  return events.some((event) =>
+    event.runId === runId &&
+    event.stage === args.stage &&
+    event.agent === args.agent &&
+    event.spanId === args["span-id"] &&
+    event.event === "acknowledged" &&
+    typeof event.ackTs === "string" &&
+    event.ackTs.length > 0
+  );
+}
+
+function usage() {
+  process.stderr.write("Usage: node .cclaw/hooks/delegation-record.mjs --stage=<stage> --agent=<agent> --mode=<mandatory|proactive> --status=<scheduled|launched|acknowledged|completed|failed|waived|stale> --span-id=<id> [--dispatch-id=<id>] [--worker-run-id=<id>] [--dispatch-surface=<surface>] [--agent-definition-path=<path>] [--ack-ts=<iso>] [--launched-ts=<iso>] [--completed-ts=<iso>] [--evidence-ref=<ref>] [--waiver-reason=<text>] [--json]\\n");
+}
+
+async function main() {
+  const args = parseArgs(process.argv.slice(2));
+  const json = args.json !== undefined;
+  const problems = [];
+  if (!args.stage) problems.push("missing --stage");
+  if (!args.agent) problems.push("missing --agent");
+  if (args.mode !== "mandatory" && args.mode !== "proactive") problems.push("--mode must be mandatory or proactive");
+  if (!VALID_STATUSES.has(args.status)) problems.push("invalid --status");
+  if (!args["span-id"]) problems.push("missing --span-id");
+  if (args.status === "waived" && !args["waiver-reason"]) problems.push("waived status requires --waiver-reason");
+  if (args.status === "completed" && args["dispatch-surface"] !== "role-switch") {
+    for (const key of ["dispatch-id", "dispatch-surface", "agent-definition-path"]) {
+      if (!args[key]) problems.push("completed isolated/generic status requires --" + key);
+    }
+  }
+  if (args.status === "completed" && args["dispatch-surface"] === "role-switch" && !args["evidence-ref"]) {
+    problems.push("completed role-switch status requires --evidence-ref");
+  }
+  if (problems.length > 0) {
+    if (json) process.stdout.write(JSON.stringify({ ok: false, problems }, null, 2) + "\\n");
+    else {
+      usage();
+      process.stderr.write("[cclaw] delegation-record: " + problems.join("; ") + "\\n");
+    }
+    process.exitCode = 1;
+    return;
+  }
+
+  const root = await detectRoot();
+  const now = new Date().toISOString();
+  const runId = await readRunId(root);
+  if (args.status === "completed" && args["dispatch-surface"] !== "role-switch" && !args["ack-ts"]) {
+    const priorEvents = await readDelegationEvents(root);
+    if (!hasPriorAck(priorEvents, args, runId)) {
+      const ackProblem = "completed isolated/generic status requires prior acknowledged event for same span or --ack-ts";
+      if (json) process.stdout.write(JSON.stringify({ ok: false, problems: [ackProblem] }, null, 2) + "\\n");
+      else {
+        usage();
+        process.stderr.write("[cclaw] delegation-record: " + ackProblem + "\\n");
+      }
+      process.exitCode = 1;
+      return;
+    }
+  }
+  const status = args.status;
+  const row = {
+    stage: args.stage,
+    agent: args.agent,
+    mode: args.mode,
+    status,
+    spanId: args["span-id"],
+    dispatchId: args["dispatch-id"],
+    workerRunId: args["worker-run-id"],
+    dispatchSurface: args["dispatch-surface"],
+    agentDefinitionPath: args["agent-definition-path"],
+    fulfillmentMode: args["dispatch-surface"] === "role-switch" ? "role-switch" : args["dispatch-surface"] === "cursor-task" || args["dispatch-surface"] === "generic-task" ? "generic-dispatch" : "isolated",
+    waiverReason: args["waiver-reason"],
+    evidenceRefs: args["evidence-ref"] ? [args["evidence-ref"]] : [],
+    runId,
+    startTs: now,
+    ts: now,
+    launchedTs: args["launched-ts"] || (status === "launched" ? now : undefined),
+    ackTs: args["ack-ts"] || (status === "acknowledged" ? now : undefined),
+    completedTs: args["completed-ts"] || (status === "completed" ? now : undefined),
+    endTs: TERMINAL.has(status) ? now : undefined,
+    schemaVersion: 1
+  };
+  const clean = Object.fromEntries(Object.entries(row).filter(([, value]) => value !== undefined));
+  const event = { ...clean, event: status, eventTs: now };
+  const stateDir = path.join(root, RUNTIME_ROOT, "state");
+  await fs.mkdir(stateDir, { recursive: true });
+  await fs.appendFile(path.join(stateDir, "delegation-events.jsonl"), JSON.stringify(event) + "\\n", { encoding: "utf8", mode: 0o600 });
+
+  const ledgerPath = path.join(stateDir, "delegation-log.json");
+  let ledger = { runId, entries: [] };
+  try {
+    ledger = JSON.parse(await fs.readFile(ledgerPath, "utf8"));
+    if (!Array.isArray(ledger.entries)) ledger.entries = [];
+  } catch {
+    ledger = { runId, entries: [] };
+  }
+  if (!ledger.entries.some((entry) => entry.spanId === clean.spanId && entry.status === clean.status)) {
+    ledger.entries.push(clean);
+    ledger.runId = runId;
+    await fs.writeFile(ledgerPath, JSON.stringify(ledger, null, 2) + "\\n", { encoding: "utf8", mode: 0o600 });
+  }
+
+  const active = ledger.entries.filter((entry) => ["scheduled", "launched", "acknowledged"].includes(entry.status));
+  await fs.writeFile(path.join(stateDir, "subagents.json"), JSON.stringify({ active, updatedAt: now }, null, 2) + "\\n", { encoding: "utf8", mode: 0o600 });
+  process.stdout.write(JSON.stringify({ ok: true, event }, null, 2) + "\\n");
+}
+
 void main();
 `;
 }

package/dist/content/next-command.js

@@ -76,7 +76,7 @@ ${conversationLanguagePolicyMarkdown()}
 
 1. Read **\`${flowPath}\`**. If missing → **BLOCKED** (state missing).
 2. Parse JSON. Capture \`currentStage\` and \`stageGateCatalog[currentStage]\`.
-3. If \`staleStages[currentStage]\` exists, do not advance automatically. Re-run the stage artifact work, then clear the marker with \`cclaw internal rewind --ack <currentStage>\`.
+3. If \`staleStages[currentStage]\` exists, do not advance automatically. Report the stale marker reason/rewindId, re-run the stage artifact work, then clear only the current stage marker with \`cclaw internal rewind --ack <currentStage>\`.
 4. Read **\`${reconciliationNoticesPath}\`** when present. If it contains entries for \`activeRunId + currentStage\` and the listed gate is still blocked in \`stageGateCatalog[currentStage].blocked\`, emit a structured warning before any stage-advance decision.
 5. Let \`G\` = \`requiredGates\` for **\`currentStage\`** from the stage schema.
 6. Let \`catalog\` = \`stageGateCatalog[currentStage]\` from flow state.
@@ -85,7 +85,7 @@ ${conversationLanguagePolicyMarkdown()}
 9. If \`M\` is non-empty, inspect **\`${delegationPath}\`**. Treat as satisfied only if each mandatory agent is **completed** or **waived**.
 10. For each satisfied mandatory delegation row, verify \`evidenceRefs\` is a non-empty array (unless status is \`waived\` with rationale). Missing evidenceRefs means delegation is unresolved.
 11. If any mandatory delegation is missing and no waiver exists: **STOP** and ask the user whether to dispatch now or waive with rationale. Do not mark gates passed while delegation is unresolved.
-12. If \`currentStage === "review"\` and \`catalog.blocked\` includes \`review_criticals_resolved\`, treat this as a hard remediation branch: recommend \`cclaw internal rewind tdd "review_blocked_by_critical"\` with the blocking finding IDs, and do not attempt to advance toward ship.
+12. If \`currentStage === "review"\` and \`catalog.blocked\` includes \`review_criticals_resolved\`, treat this as a hard remediation branch: recommend the managed command \`cclaw internal rewind tdd "review_blocked_by_critical <finding-ids>"\`, and do not attempt to advance toward ship. After TDD rework, require \`cclaw internal rewind --ack tdd\` before continuing.
 
 ### Path A: Current stage is NOT complete (any gate unmet or delegation missing)
 
@@ -186,11 +186,13 @@ ${conversationLanguagePolicyMarkdown()}
 Default output should be compact, like OMC/OMX operator surfaces:
 
 \`\`\`
-Stage: <currentStage> (<track>)
+Current: <currentStage or closeout.shipSubstate> (<track>)
+Stage: <currentStage>
 Gates: <passed>/<required> passed, <blocked> blocked
 Delegations: <done>/<mandatory> done
-Blockers: <none | gate/delegation/reconciliation ids>
+Blocked by: <none | gate/delegation/reconciliation/stale/TDD/review ids>
 Next: <exact next action, usually /cc-next or one named remediation>
+Evidence needed: <artifact/test/review/delegation evidence required to unblock>
 \`\`\`
 
 Only expand beyond this when blocked, when asking a structured question, or when
@@ -214,7 +216,7 @@ Do **not** mark gates satisfied from memory alone. Cite **artifact evidence** (p
 
 1. Open **\`${flowPath}\`**.
 2. Record \`currentStage\` and \`stageGateCatalog[currentStage]\`.
-3. If \`staleStages[currentStage]\` exists, re-run the stage and clear marker via \`cclaw internal rewind --ack <currentStage>\` before advancing.
+3. If \`staleStages[currentStage]\` exists, show the marker reason/rewindId, re-run the stage, and clear only the current marker via \`cclaw internal rewind --ack <currentStage>\` before advancing.
 4. If the file is missing or invalid JSON → **BLOCKED** (report and stop).
 5. Read \`${reconciliationNoticesPath}\` when present. For entries matching \`activeRunId + currentStage\` whose gate is still in \`stageGateCatalog[currentStage].blocked\`, show a warning with gate id + reason before proceeding.
 
@@ -242,7 +244,9 @@ Execute the stage protocol. The stage skill handles interaction, STOP points, ga
 
 ${ralphLoopContractSnippet()}
 
-Special-case for review: if \`review_criticals_resolved\` is in \`blocked\`, route to rework instead of looping review forever — recommend \`cclaw internal rewind tdd "review_blocked_by_critical"\`.
+Special-case for review: if \`review_criticals_resolved\` is in \`blocked\`, route to rework instead of looping review forever - recommend \`cclaw internal rewind tdd "review_blocked_by_critical <finding-ids>"\`, then \`cclaw internal rewind --ack tdd\` after TDD rework.
+
+Special-case for TDD blockers: when \`06-tdd.md\` records \`NO_SOURCE_CONTEXT\`, \`NO_TEST_SURFACE\`, \`NO_IMPLEMENTABLE_SLICE\`, \`RED_NOT_EXPRESSIBLE\`, or \`NO_VCS_MODE\`, keep status BLOCKED and print \`Current\`, \`Blocked by\`, \`Next\`, and \`Evidence needed\` instead of retrying speculative RED/GREEN work.
 
 **Path B — stage IS complete (all gates met, all delegations done):**
 

package/dist/content/reference-patterns.d.ts

@@ -0,0 +1,18 @@
+import type { FlowStage } from "../types.js";
+export interface ReferencePatternContract {
+    stage: FlowStage;
+    guidance: string[];
+    artifactSections: string[];
+}
+export interface ReferencePattern {
+    id: string;
+    title: string;
+    intent: string;
+    useWhen: string;
+    policyNeedles: string[];
+    contracts: ReferencePatternContract[];
+}
+export declare const REFERENCE_PATTERNS: ReferencePattern[];
+export declare function referencePatternsForStage(stage: FlowStage): ReferencePattern[];
+export declare function referencePatternContractsForStage(stage: FlowStage): ReferencePatternContract[];
+export declare function referencePatternPolicyNeedles(stage: FlowStage): string[];