cclaw-cli 0.51.25 → 0.51.27

package/dist/content/examples.js

@@ -7,15 +7,16 @@ const STAGE_EXAMPLES = {
 ## Problem Decision Record
 
 - **Depth:** standard
-- **Frame type:** technical-maintenance
+- **Frame type:** \`technical-maintenance\` (free-form label; pick whatever fits — see commentary in the template for example labels)
 
-### Technical-maintenance framing
+### Framing fields (universal — keep field names; fill in whatever is meaningful for this work)
 
-- **Affected operator/developer:** release operator and package maintainer.
-- **Current failure mode:** release checks are fragile and inconsistent between CI and local runs; invalid metadata sometimes reaches npm publish.
-- **Expected operational improvement:** invalid release preconditions are caught before publish with explicit operator feedback in CI and local workflows.
-- **Verification signal:** shared release validation tests and CI release-check command fail on invalid metadata.
-- **Do-nothing cost:** continued publish risk and duplicated local/CI fixes.
+- **Affected user / role / operator:** release operator and package maintainer.
+- **Current state / failure mode / opportunity:** release checks are fragile and inconsistent between CI and local runs; invalid metadata sometimes reaches npm publish.
+- **Desired outcome (observable):** invalid release preconditions are caught before publish; \`pnpm release:check\` exits non-zero with explicit operator feedback in CI and local workflows.
+- **Evidence / signal supporting this framing:** prior incident postmortems referencing release-metadata drift; \`scripts/pre-publish.sh\` already partially encodes the rules.
+- **Why now (urgency / cost of waiting):** every additional release reinforces the divergent CI/local behavior and burns operator trust.
+- **Do-nothing consequence:** continued publish risk and duplicated local/CI fixes.
 - **Non-goals:** no new runtime dependencies; no release-framework rewrite.
 
 ## Clarifying Questions
@@ -675,7 +676,7 @@ function exampleSummaryBullets(stage) {
 // sample in STAGE_EXAMPLES gains or loses a top-level section.
 const STAGE_EXAMPLE_SECTION_HEADINGS = {
     brainstorm: [
-        "Problem Decision Record (product or technical-maintenance framing)",
+        "Problem Decision Record (free-form Frame type label + universal framing fields)",
         "Reference Pattern Candidates and approaches with trade-offs",
         "Recommended direction + open questions",
         "Clarification log and decision record"

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

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

package/dist/content/harness-doc.js

@@ -0,0 +1,47 @@
+import { DELEGATION_DISPATCH_SURFACES, DELEGATION_DISPATCH_SURFACE_PATH_PREFIXES } from "../delegation.js";
+import { harnessDelegationRecipes } from "../harness-adapters.js";
+/**
+ * One-line description per `--dispatch-surface` enum value. Sourced from
+ * `src/delegation.ts::DELEGATION_DISPATCH_SURFACES` so the generated doc
+ * stays in lockstep with the runtime enum. Add a new key here whenever a
+ * new surface is introduced upstream — TypeScript's `Record` enforces it.
+ */
+const DISPATCH_SURFACE_DESCRIPTIONS = {
+    "claude-task": "Claude Code native Task launch against `.claude/agents/<agent-name>.md`; fulfillmentMode: `isolated`.",
+    "cursor-task": "Cursor generic Task/Subagent dispatch against `.cclaw/agents/<agent-name>.md` with a role prompt; fulfillmentMode: `generic-dispatch`. Requires non-empty `evidenceRefs` on completion.",
+    "opencode-agent": "OpenCode native subagent (`@<agent-name>` or Task) against `.opencode/agents/<agent-name>.md`; fulfillmentMode: `isolated`.",
+    "codex-agent": "OpenAI Codex CLI native custom agent against `.codex/agents/<agent-name>.toml`; fulfillmentMode: `isolated`.",
+    "generic-task": "Generic Task dispatch against `.cclaw/agents/<agent-name>.md` for harnesses without a vendor-specific surface; fulfillmentMode: `generic-dispatch`.",
+    "role-switch": "In-session role-switch fallback when no isolated dispatch surface is available. No agent-definition-path prefix is enforced; completion requires non-empty `evidenceRefs`. fulfillmentMode: `role-switch`.",
+    "manual": "Out-of-band manual dispatch (e.g. operator hand-off, external ticketing system). The agent-definition-path is intentionally free-form; recorded for audit only."
+};
+function dispatchSurfaceTableMarkdown() {
+    const rows = DELEGATION_DISPATCH_SURFACES
+        .map((surface) => {
+        const prefixes = DELEGATION_DISPATCH_SURFACE_PATH_PREFIXES[surface];
+        const prefixCell = prefixes.length === 0
+            ? "(any)"
+            : prefixes.map((prefix) => `\`${prefix}\``).join(", ");
+        return `| \`${surface}\` | ${DISPATCH_SURFACE_DESCRIPTIONS[surface]} | ${prefixCell} |`;
+    })
+        .join("\n");
+    return `### Dispatch surfaces (\`--dispatch-surface\` enum)\n\nGenerated from \`src/delegation.ts::DELEGATION_DISPATCH_SURFACES\` and \`DELEGATION_DISPATCH_SURFACE_PATH_PREFIXES\`. Any surface not in this table is rejected by \`.cclaw/hooks/delegation-record.mjs\` with a non-zero exit. The deprecated \`task\` surface is **not** in this enum.\n\n| Surface | Purpose | Allowed agent-definition-path prefixes |\n|---|---|---|\n${rows}\n`;
+}
+function perHarnessRecipeMarkdown() {
+    const recipes = harnessDelegationRecipes();
+    const rows = recipes
+        .map((recipe) => `| \`${recipe.harnessId}\` | \`${recipe.dispatchSurface}\` | \`${recipe.agentDefinitionExample}\` | ${recipe.fulfillmentMode} | scheduled -> launched -> acknowledged -> completed (reuse \`<span-id>\` + \`<dispatch-id>\`; \`--ack-ts=<iso-ts>\` for completed isolated/generic) |`)
+        .join("\n");
+    const examples = recipes
+        .map((recipe) => `**${recipe.harnessId}**:\n\n` + recipe.lifecycleCommands.map((cmd) => `    ${cmd}`).join("\n"))
+        .join("\n\n");
+    return `\n\n## Per-Harness Lifecycle Recipe\n\n| Harness | Surface | Agent definition path | fulfillmentMode | Lifecycle |\n|---|---|---|---|---|\n${rows}\n\nNeutral placeholder tokens only: \`<agent-name>\`, \`<stage>\`, \`<run-id>\`, \`<span-id>\`, \`<dispatch-id>\`, \`<agent-def-path>\`, \`<iso-ts>\`, \`<artifact-anchor>\`. See \`docs/quality-gates.md\` for stage-by-stage gate mapping.\n\nThe four shipped harnesses (\`claude\`, \`cursor\`, \`opencode\`, \`codex\`) each ship with a canonical primary surface in the table above. The remaining enum values \`generic-task\`, \`role-switch\`, and \`manual\` are documented in the dispatch-surface table below and are available to any harness as fallback paths when the primary surface is unavailable.\n\n${examples}\n\n${dispatchSurfaceTableMarkdown()}\n\n### Legacy ledger upgrade\n\nPre-v3 ledger entries that lack a recorded \`dispatchSurface\` are tagged \`fulfillmentMode: "legacy-inferred"\` on read. Stage-complete blocks completion until those rows are re-recorded with the v3 helper:\n\n    node .cclaw/hooks/delegation-record.mjs \\\n      --rerecord \\\n      --span-id=<span-id> \\\n      --dispatch-id=<dispatch-id> \\\n      --dispatch-surface=<surface> \\\n      --agent-definition-path=<agent-def-path> \\\n      --ack-ts=<iso-ts> \\\n      --completed-ts=<iso-ts> \\\n      --json\n\n\`--dispatch-surface\` must be one of the values listed in the dispatch-surface table above (the enum is generated verbatim from \`src/delegation.ts::DELEGATION_DISPATCH_SURFACES\`). Surfaces must align with the allowed agent-definition-path prefixes shown alongside each surface; \`role-switch\` and \`manual\` accept any path. The deprecated \`task\` surface is rejected.\n\n`;
+}
+export function harnessIntegrationDocMarkdown() {
+    const head = "# Harness Integration Matrix\n\nGenerated from `src/harness-adapters.ts` capabilities and hook event mappings.";
+    return [
+        head + " 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",
+        perHarnessRecipeMarkdown(),
+        "\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"
+    ].join("");
+}

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

@@ -2,6 +2,7 @@ import { existsSync } from "node:fs";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 import { RUNTIME_ROOT } from "../constants.js";
+import { DELEGATION_DISPATCH_SURFACES, DELEGATION_DISPATCH_SURFACE_PATH_PREFIXES } from "../delegation.js";
 function resolveCliEntrypointForGeneratedHook() {
     const here = fileURLToPath(import.meta.url);
     const candidates = [
@@ -260,6 +261,374 @@ 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"]);
+const VALID_DISPATCH_SURFACES = ${JSON.stringify([...DELEGATION_DISPATCH_SURFACES])};
+const VALID_DISPATCH_SURFACES_SET = new Set(VALID_DISPATCH_SURFACES);
+const SURFACE_PATH_PREFIXES = ${JSON.stringify(DELEGATION_DISPATCH_SURFACE_PATH_PREFIXES)};
+const LEDGER_SCHEMA_VERSION = 3;
+
+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]",
+    "  node .cclaw/hooks/delegation-record.mjs --rerecord --span-id=<id> --dispatch-id=<id> --dispatch-surface=<surface> --agent-definition-path=<path> [--ack-ts=<iso>] [--completed-ts=<iso>] [--json]",
+    "",
+    "Allowed --dispatch-surface values:",
+    "  " + VALID_DISPATCH_SURFACES.join(", "),
+    "",
+    "Per-surface allowed --agent-definition-path prefixes:",
+    ...VALID_DISPATCH_SURFACES.map((surface) => "  " + surface + ": " + (SURFACE_PATH_PREFIXES[surface].length === 0 ? "(any)" : SURFACE_PATH_PREFIXES[surface].join(", "))),
+    ""
+  ].join("\\n") + "\\n");
+}
+
+function emitProblems(problems, json, code) {
+  const exitCode = typeof code === "number" ? code : 1;
+  if (json) {
+    process.stdout.write(JSON.stringify({ ok: false, problems, allowedDispatchSurfaces: VALID_DISPATCH_SURFACES }, null, 2) + "\\n");
+  } else {
+    usage();
+    process.stderr.write("[cclaw] delegation-record: " + problems.join("; ") + "\\n");
+  }
+  process.exitCode = exitCode;
+}
+
+function normalizeRelPath(value) {
+  return String(value || "").replace(/\\\\/gu, "/").replace(/^\\.\\//u, "");
+}
+
+function dispatchSurfaceMatchesPath(surface, agentDefinitionPath) {
+  const allowed = SURFACE_PATH_PREFIXES[surface] || [];
+  if (allowed.length === 0) return true;
+  const normalized = normalizeRelPath(agentDefinitionPath);
+  return allowed.some((prefix) => normalized === prefix.replace(/\\/$/u, "") || normalized.startsWith(prefix));
+}
+
+async function pathExists(filePath) {
+  try {
+    const stat = await fs.stat(filePath);
+    return stat.isFile() || stat.isDirectory();
+  } catch {
+    return false;
+  }
+}
+
+function buildRow(args, status, runId, now) {
+  const fulfillmentMode = args["dispatch-surface"] === "role-switch"
+    ? "role-switch"
+    : args["dispatch-surface"] === "cursor-task" || args["dispatch-surface"] === "generic-task"
+      ? "generic-dispatch"
+      : "isolated";
+  return {
+    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,
+    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: LEDGER_SCHEMA_VERSION
+  };
+}
+
+async function persistEntry(root, runId, clean, event, options = {}) {
+  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: [], schemaVersion: LEDGER_SCHEMA_VERSION };
+  try {
+    ledger = JSON.parse(await fs.readFile(ledgerPath, "utf8"));
+    if (!Array.isArray(ledger.entries)) ledger.entries = [];
+  } catch {
+    ledger = { runId, entries: [], schemaVersion: LEDGER_SCHEMA_VERSION };
+  }
+
+  // Rerecord semantics: replace any pre-existing row with the same spanId
+  // (regardless of its status) so the legacy v1/v2 row is upgraded to v3
+  // shape on disk. The append path keeps the historical dedup semantics:
+  // an exact (spanId, status) duplicate is dropped to keep retried hooks
+  // idempotent.
+  if (options.replaceBySpanId) {
+    ledger.entries = ledger.entries.filter((entry) => entry.spanId !== clean.spanId);
+    ledger.entries.push(clean);
+    ledger.runId = runId;
+    ledger.schemaVersion = LEDGER_SCHEMA_VERSION;
+    await fs.writeFile(ledgerPath, JSON.stringify(ledger, null, 2) + "\\n", { encoding: "utf8", mode: 0o600 });
+  } else if (!ledger.entries.some((entry) => entry.spanId === clean.spanId && entry.status === clean.status)) {
+    ledger.entries.push(clean);
+    ledger.runId = runId;
+    ledger.schemaVersion = LEDGER_SCHEMA_VERSION;
+    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: event.eventTs }, null, 2) + "\\n", { encoding: "utf8", mode: 0o600 });
+}
+
+async function findLegacyEntry(root, spanId) {
+  const ledgerPath = path.join(root, RUNTIME_ROOT, "state", "delegation-log.json");
+  let ledger;
+  try {
+    ledger = JSON.parse(await fs.readFile(ledgerPath, "utf8"));
+  } catch {
+    return null;
+  }
+  if (!ledger || !Array.isArray(ledger.entries)) return null;
+  return ledger.entries.find((entry) => entry && entry.spanId === spanId) || null;
+}
+
+async function runRerecord(args, json) {
+  const problems = [];
+  for (const key of ["span-id", "dispatch-id", "dispatch-surface", "agent-definition-path"]) {
+    if (!args[key]) problems.push("missing --" + key);
+  }
+  if (args["dispatch-surface"] && !VALID_DISPATCH_SURFACES_SET.has(args["dispatch-surface"])) {
+    problems.push("invalid --dispatch-surface (allowed: " + VALID_DISPATCH_SURFACES.join(", ") + ")");
+  }
+  if (problems.length > 0) {
+    emitProblems(problems, json, 2);
+    return;
+  }
+  const root = await detectRoot();
+  const now = new Date().toISOString();
+  const runId = await readRunId(root);
+  const legacyEntry = await findLegacyEntry(root, args["span-id"]);
+  if (!legacyEntry) {
+    emitProblems(["no legacy ledger entry found for --span-id=" + args["span-id"]], json, 1);
+    return;
+  }
+  if (args["dispatch-surface"] !== "role-switch") {
+    if (!dispatchSurfaceMatchesPath(args["dispatch-surface"], args["agent-definition-path"])) {
+      const allowedPrefixes = SURFACE_PATH_PREFIXES[args["dispatch-surface"]];
+      emitProblems([
+        "--agent-definition-path does not lie under any allowed prefix for --dispatch-surface=" + args["dispatch-surface"] + " (expected one of: " + (allowedPrefixes.join(", ") || "(any)") + ")"
+      ], json, 2);
+      return;
+    }
+    const exists = await pathExists(path.join(root, args["agent-definition-path"]));
+    if (!exists) {
+      emitProblems(["--agent-definition-path does not exist on disk: " + args["agent-definition-path"]], json, 2);
+      return;
+    }
+  }
+  const merged = {
+    stage: legacyEntry.stage,
+    agent: legacyEntry.agent,
+    mode: legacyEntry.mode || "mandatory",
+    "span-id": args["span-id"],
+    "dispatch-id": args["dispatch-id"],
+    "worker-run-id": args["worker-run-id"] || legacyEntry.workerRunId,
+    "dispatch-surface": args["dispatch-surface"],
+    "agent-definition-path": args["agent-definition-path"],
+    "ack-ts": args["ack-ts"] || legacyEntry.ackTs || now,
+    "completed-ts": args["completed-ts"] || legacyEntry.completedTs || now,
+    "launched-ts": args["launched-ts"] || legacyEntry.launchedTs || now
+  };
+  const status = "completed";
+  const clean = Object.fromEntries(Object.entries(buildRow(merged, status, runId, now)).filter(([, value]) => value !== undefined));
+  clean.fulfillmentMode = clean.dispatchSurface === "role-switch" ? "role-switch" : (clean.dispatchSurface === "cursor-task" || clean.dispatchSurface === "generic-task" ? "generic-dispatch" : "isolated");
+  const event = { ...clean, event: status, eventTs: now, rerecord: true };
+  await persistEntry(root, runId, clean, event, { replaceBySpanId: true });
+  process.stdout.write(JSON.stringify({ ok: true, event, rerecord: true }, null, 2) + "\\n");
+}
+
+async function main() {
+  const args = parseArgs(process.argv.slice(2));
+  const json = args.json !== undefined;
+
+  if (args.rerecord) {
+    await runRerecord(args, json);
+    return;
+  }
+
+  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");
+
+  // Strict --dispatch-surface enum validation: any provided surface must be
+  // in the canonical allow-list. Do this BEFORE we use the value to gate
+  // completed/role-switch fields.
+  if (args["dispatch-surface"] !== undefined && !VALID_DISPATCH_SURFACES_SET.has(args["dispatch-surface"])) {
+    problems.push("invalid --dispatch-surface (allowed: " + VALID_DISPATCH_SURFACES.join(", ") + ")");
+    emitProblems(problems, json, 2);
+    return;
+  }
+
+  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");
+  }
+
+  // Validate --agent-definition-path against the surface and on-disk
+  // existence whenever both are provided.
+  if (args["dispatch-surface"] && args["agent-definition-path"] && args["dispatch-surface"] !== "role-switch" && args["dispatch-surface"] !== "manual") {
+    if (!dispatchSurfaceMatchesPath(args["dispatch-surface"], args["agent-definition-path"])) {
+      const allowedPrefixes = SURFACE_PATH_PREFIXES[args["dispatch-surface"]];
+      problems.push("--agent-definition-path does not lie under any allowed prefix for --dispatch-surface=" + args["dispatch-surface"] + " (expected one of: " + (allowedPrefixes.join(", ") || "(any)") + ")");
+    }
+  }
+
+  if (problems.length > 0) {
+    emitProblems(problems, json, 2);
+    return;
+  }
+
+  const root = await detectRoot();
+  const now = new Date().toISOString();
+  const runId = await readRunId(root);
+
+  // For completed isolated/generic rows, --agent-definition-path must
+  // resolve to an existing file or directory inside the project. This
+  // catches typos and stale generated agent paths before they enter the
+  // ledger. Skipped for role-switch (no agent file is generated) and
+  // manual (intentionally free-form).
+  if (
+    args.status === "completed" &&
+    args["dispatch-surface"] &&
+    args["dispatch-surface"] !== "role-switch" &&
+    args["dispatch-surface"] !== "manual" &&
+    args["agent-definition-path"]
+  ) {
+    const exists = await pathExists(path.join(root, args["agent-definition-path"]));
+    if (!exists) {
+      emitProblems(["--agent-definition-path does not exist on disk: " + args["agent-definition-path"]], json, 2);
+      return;
+    }
+  }
+
+  // Completed isolated/generic rows require explicit --ack-ts OR a prior
+  // acknowledged event for the same span. fulfillmentMode=isolated cannot
+  // be claimed without an ACK timestamp anchor.
+  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";
+      emitProblems([ackProblem], json, 2);
+      return;
+    }
+  }
+
+  const status = args.status;
+  const row = buildRow(args, status, runId, now);
+  const clean = Object.fromEntries(Object.entries(row).filter(([, value]) => value !== undefined));
+  const event = { ...clean, event: status, eventTs: now };
+  await persistEntry(root, runId, clean, event);
+  process.stdout.write(JSON.stringify({ ok: true, event }, null, 2) + "\\n");
+}
+
 void main();
 `;
 }

package/dist/content/skills.d.ts

@@ -1,3 +1,12 @@
 import { type FlowStage, type FlowTrack } from "../types.js";
+export declare const FORBIDDEN_SYCOPHANCY_PHRASES: string[];
+export declare const FORBIDDEN_PLACEHOLDER_TOKENS: string[];
+export declare const CONFIDENCE_FINDING_REGEX_SOURCE = "\\[P[123]\\]\\s*\\(confidence:\\s*\\d{1,2}/10\\)\\s+[^\\s]+(?::\\d+)?\\s+\u2014";
+export declare function stopPerIssueBlock(): string;
+export declare function confidenceCalibrationBlock(): string;
+export declare function outsideVoiceSlotBlock(): string;
+export declare function antiSycophancyBlock(): string;
+export declare function noPlaceholdersBlock(): string;
+export declare function watchedFailProofBlock(): string;
 export declare function stageSkillFolder(stage: FlowStage): string;
 export declare function stageSkillMarkdown(stage: FlowStage, track?: FlowTrack): string;