cclaw-cli 0.51.30 → 0.55.2

package/dist/content/examples.js

@@ -753,7 +753,7 @@ const STAGE_DOMAIN_SAMPLES = {
         {
             domain: "cli",
             label: "Direction",
-            body: "Problem: `cclaw archive` silently deletes 30+ day runs with no preview. Success: a `--dry-run` flag prints would-be-archived run IDs to stdout and exits 0; current behavior is unchanged without the flag. Anti-success: adding an interactive confirmation prompt that breaks CI scripts."
+            body: "Problem: `npx cclaw-cli archive` silently deletes 30+ day runs with no preview. Success: a `--dry-run` flag prints would-be-archived run IDs to stdout and exits 0; current behavior is unchanged without the flag. Anti-success: adding an interactive confirmation prompt that breaks CI scripts."
         },
         {
             domain: "library",
@@ -775,7 +775,7 @@ const STAGE_DOMAIN_SAMPLES = {
         {
             domain: "cli",
             label: "Scope line",
-            body: "In: add `--dry-run` to `cclaw archive`; out: redesigning archive formats, adding retention flags, or changing the default. Discretion: exact wording of stdout lines. NOT in scope: touching `init` / `sync` / `doctor` subcommands."
+            body: "In: add `--dry-run` to `npx cclaw-cli archive`; out: redesigning archive formats, adding retention flags, or changing the default. Discretion: exact wording of stdout lines. NOT in scope: touching `init` / `sync` / `sync` subcommands."
         },
         {
             domain: "library",
@@ -824,7 +824,7 @@ const STAGE_DOMAIN_SAMPLES = {
         {
             domain: "cli",
             label: "AC",
-            body: "AC-C1: Given `cclaw init --claude` run in an empty directory, exit code is `0`, `.cclaw/config.yaml` is created with `harnesses: [claude]`, and stderr contains no warnings (asserted by `tests/integration/init-sync-doctor.test.ts`)."
+            body: "AC-C1: Given `npx cclaw-cli init --harnesses=claude` run in an empty directory, exit code is `0`, `.cclaw/config.yaml` is created with `harnesses: [claude]`, and stderr contains no warnings (asserted by `tests/integration/init-sync-runtime.test.ts`)."
         },
         {
             domain: "library",
@@ -846,7 +846,7 @@ const STAGE_DOMAIN_SAMPLES = {
         {
             domain: "cli",
             label: "Task",
-            body: "T-C-2 `[~3m]`: Add `--dry-run` flag to `cclaw archive` that prints the would-be-archived run IDs to stdout and exits 0. AC-C3. Verify: `node dist/cli.js archive --dry-run` + `tests/unit/cli-parse.test.ts`."
+            body: "T-C-2 `[~3m]`: Add `--dry-run` flag to `npx cclaw-cli archive` that prints the would-be-archived run IDs to stdout and exits 0. AC-C3. Verify: `node dist/cli.js archive --dry-run` + `tests/unit/cli-parse.test.ts`."
         },
         {
             domain: "library",
@@ -890,7 +890,7 @@ const STAGE_DOMAIN_SAMPLES = {
         {
             domain: "cli",
             label: "Finding",
-            body: "R-C-2 (Suggestion, UX): `cclaw archive --dry-run` prints run IDs without a trailing newline, breaking downstream `xargs` pipelines. Evidence: `echo '' | xargs -I{} printf '%s\\n' {}` contrast. Fix owner: CLI; non-blocking."
+            body: "R-C-2 (Suggestion, UX): `npx cclaw-cli archive --dry-run` prints run IDs without a trailing newline, breaking downstream `xargs` pipelines. Evidence: `echo '' | xargs -I{} printf '%s\\n' {}` contrast. Fix owner: CLI; non-blocking."
         },
         {
             domain: "library",
@@ -912,7 +912,7 @@ const STAGE_DOMAIN_SAMPLES = {
         {
             domain: "cli",
             label: "Rollback",
-            body: "Trigger: `cclaw init --claude` exits non-zero on a fresh tmp dir, OR `cclaw doctor` regresses (FAIL count increases) on the smoke matrix. Steps: `npm unpublish cclaw-cli@<version>` (within the 72h window) or `npm deprecate cclaw-cli@<version> '<reason>'`; publish the previous patch. Verify: `npx cclaw-cli@latest --version` prints the previous version."
+            body: "Trigger: `npx cclaw-cli init --harnesses=claude` exits non-zero on a fresh tmp dir, OR `npx cclaw-cli sync` regresses (FAIL count increases) on the smoke matrix. Steps: `npm unpublish cclaw-cli@<version>` (within the 72h window) or `npm deprecate cclaw-cli@<version> '<reason>'`; publish the previous patch. Verify: `npx cclaw-cli@latest --version` prints the previous version."
         },
         {
             domain: "library",

package/dist/content/harness-doc.js

@@ -35,13 +35,31 @@ function perHarnessRecipeMarkdown() {
     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. Repair hints: \`cclaw sync\` safely regenerates shims/plugins/agents; Codex also needs \`[features] codex_hooks = true\`; OpenCode needs \`opencode.json(.c)\` plugin registration; role-switch completions require evidenceRefs. 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`;
+    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. Repair hints: \`npx cclaw-cli sync\` safely regenerates shims/plugins/agents; Codex also needs \`[features] codex_hooks = true\`; OpenCode needs \`opencode.json(.c)\` plugin registration; role-switch completions require evidenceRefs. 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`;
+}
+function hookLayeringSectionMarkdown() {
+    return `## Hook layering
+
+Hook behavior is intentionally split into three layers so docs, generation, and runtime checks stay in sync:
+
+| Layer | Source of truth | Responsibility |
+|---|---|---|
+| 1) Manifest projection | \`src/content/hook-manifest.ts\` | Canonical handler/event map per harness. This is the authoring surface for new handlers or reroutes. |
+| 2) JSON schema descriptors | \`src/hook-schemas/*.json\` + \`src/hook-schema.ts\` descriptor map | Declares required harness-native event arrays and schema version for each harness document. |
+| 3) Runtime TS validation | \`src/hook-schema.ts::validateHookDocument\` + sync hook checks | Validates generated hook JSON shape/required events and reports actionable diagnostics. |
+
+Flow:
+1. Manifest defines handler bindings.
+2. Hook documents are generated from manifest projections.
+3. Schema descriptors + TS validators enforce structure at sync time.
+`;
 }
 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"
+        hookLayeringSectionMarkdown(),
+        "\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; sync 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` - stage progression and post-ship closeout\n- `/cc-idea` - idea 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-idea`, `/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, 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` | `brainstorm` |\n| `scope` | `scope` |\n| `design` | `design` |\n| `spec` | `spec` |\n| `plan` | `plan` |\n| `tdd` | `tdd` |\n| `review` | `review` |\n| `ship` | `ship` |\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. Sync/runtime checks validate the config permission and warn when the environment hint is absent.\n- `codex`: `.agents/skills/cc/SKILL.md`, `.agents/skills/cc-idea/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 sync` 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/sync reports.\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 sync 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 `<repo-relative references dir>` | 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 sync 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/hook-inline-snippets.d.ts

@@ -10,6 +10,8 @@
  *    `src/knowledge-store.ts::computeCompoundReadiness`.
  * 2. `computeRalphLoopStatusInline` mirrors
  *    `src/tdd-cycle.ts::computeRalphLoopStatus`.
+ * 3. `computeEarlyLoopStatusInline` mirrors
+ *    `src/early-loop.ts::computeEarlyLoopStatus`.
  *
  * Previously those bodies lived inline in `src/content/node-hooks.ts` — a
  * ~2000-line file — next to unrelated hook-handler code. Any silent drift
@@ -25,11 +27,12 @@
  *   longer owns their source code.
  *
  * Parity with the TypeScript canonical implementations is enforced by
- * `tests/unit/ralph-loop-parity.test.ts`. Any structural change to the
+ * `tests/unit/ralph-loop-parity.test.ts` and
+ * `tests/unit/early-loop-parity.test.ts`. Any structural change to the
  * canonical TS code MUST:
  *
  * 1. Update the matching snippet below.
- * 2. Re-run `npm test tests/unit/ralph-loop-parity.test.ts`.
+ * 2. Re-run parity tests for the touched snippet.
  *
  * DO NOT inline tests here — keep the parity check in its dedicated test
  * file.
@@ -43,13 +46,13 @@
  *   timestamp so the hook-written `compound-readiness.json` is byte-equal
  *   to the CLI-written version for the same input.
  * - `countArchivedRunsInline` counts immediate subdirectories of
- *   `<root>/.cclaw/runs/` so both the hook and the CLI see the same
+ *   `<root>/.cclaw/archive/` so both the hook and the CLI see the same
  *   `archivedRunsCount` for the small-project relaxation.
  * - `formatCompoundReadinessLineInline` mirrors the one-line summary shape
  *   used by `src/internal/compound-readiness.ts::formatCompoundReadinessLine`
  *   so session-start and internal CLI command stay wording-compatible.
  */
-export declare const HOOK_INLINE_SHARED_HELPERS = "\nfunction normalizeCompoundLastUpdatedAt(date) {\n  return date.toISOString().replace(/\\.\\d{3}Z$/u, \"Z\");\n}\n\n// Count archived runs as sub-directories under `.cclaw/runs/`. Missing\n// dir returns 0; unexpected errors return undefined so the caller can\n// skip the small-project relaxation rather than guess.\nasync function countArchivedRunsInline(root) {\n  const dir = path.join(root, RUNTIME_ROOT, \"runs\");\n  try {\n    const entries = await fs.readdir(dir, { withFileTypes: true });\n    return entries.filter((entry) => entry.isDirectory()).length;\n  } catch (error) {\n    const code = error && typeof error === \"object\" && \"code\" in error ? error.code : null;\n    if (code === \"ENOENT\") return 0;\n    return undefined;\n  }\n}\n\nfunction formatCompoundReadinessLineInline(readiness) {\n  if (!readiness || typeof readiness !== \"object\") {\n    return \"\";\n  }\n  const ready = Array.isArray(readiness.ready) ? readiness.ready : [];\n  const readyCount =\n    typeof readiness.readyCount === \"number\" && Number.isFinite(readiness.readyCount)\n      ? Math.trunc(readiness.readyCount)\n      : ready.length;\n  const clusterCount =\n    typeof readiness.clusterCount === \"number\" && Number.isFinite(readiness.clusterCount)\n      ? Math.trunc(readiness.clusterCount)\n      : 0;\n  const threshold =\n    typeof readiness.threshold === \"number\" && Number.isFinite(readiness.threshold)\n      ? Math.trunc(readiness.threshold)\n      : COMPOUND_RECURRENCE_THRESHOLD;\n  if (readyCount === 0) {\n    return \"Compound readiness: no candidates (clusters=\" +\n      String(clusterCount) + \", threshold=\" + String(threshold) + \")\";\n  }\n  const critical = ready.filter(\n    (entry) => entry && typeof entry === \"object\" && entry.severity === \"critical\"\n  ).length;\n  const criticalSuffix = critical > 0 ? \" (critical=\" + String(critical) + \")\" : \"\";\n  return \"Compound readiness: clusters=\" + String(clusterCount) +\n    \", ready=\" + String(readyCount) + criticalSuffix;\n}\n";
+export declare const HOOK_INLINE_SHARED_HELPERS = "\nfunction normalizeCompoundLastUpdatedAt(date) {\n  return date.toISOString().replace(/\\.\\d{3}Z$/u, \"Z\");\n}\n\n// Count archived runs as sub-directories under `.cclaw/archive/`. Missing\n// dir returns 0; unexpected errors return undefined so the caller can\n// skip the small-project relaxation rather than guess.\nasync function countArchivedRunsInline(root) {\n  const dir = path.join(root, RUNTIME_ROOT, \"archive\");\n  try {\n    const entries = await fs.readdir(dir, { withFileTypes: true });\n    return entries.filter((entry) => entry.isDirectory()).length;\n  } catch (error) {\n    const code = error && typeof error === \"object\" && \"code\" in error ? error.code : null;\n    if (code === \"ENOENT\") return 0;\n    return undefined;\n  }\n}\n\nfunction formatCompoundReadinessLineInline(readiness) {\n  if (!readiness || typeof readiness !== \"object\") {\n    return \"\";\n  }\n  const ready = Array.isArray(readiness.ready) ? readiness.ready : [];\n  const readyCount =\n    typeof readiness.readyCount === \"number\" && Number.isFinite(readiness.readyCount)\n      ? Math.trunc(readiness.readyCount)\n      : ready.length;\n  const clusterCount =\n    typeof readiness.clusterCount === \"number\" && Number.isFinite(readiness.clusterCount)\n      ? Math.trunc(readiness.clusterCount)\n      : 0;\n  const threshold =\n    typeof readiness.threshold === \"number\" && Number.isFinite(readiness.threshold)\n      ? Math.trunc(readiness.threshold)\n      : COMPOUND_RECURRENCE_THRESHOLD;\n  if (readyCount === 0) {\n    return \"Compound readiness: no candidates (clusters=\" +\n      String(clusterCount) + \", threshold=\" + String(threshold) + \")\";\n  }\n  const critical = ready.filter(\n    (entry) => entry && typeof entry === \"object\" && entry.severity === \"critical\"\n  ).length;\n  const criticalSuffix = critical > 0 ? \" (critical=\" + String(critical) + \")\" : \"\";\n  return \"Compound readiness: clusters=\" + String(clusterCount) +\n    \", ready=\" + String(readyCount) + criticalSuffix;\n}\n";
 /**
  * Inline mirror of `src/knowledge-store.ts::computeCompoundReadiness`.
  *
@@ -81,3 +84,13 @@ export declare const COMPOUND_READINESS_INLINE_SOURCE = "\nasync function comput
  *   async function computeRalphLoopStatusInline(stateDir, runId) -> RalphLoopStatus
  */
 export declare const RALPH_LOOP_INLINE_SOURCE = "\nasync function computeRalphLoopStatusInline(stateDir, runId) {\n  const filePath = path.join(stateDir, \"tdd-cycle-log.jsonl\");\n  const raw = await readTextFile(filePath, \"\");\n  const sliceMap = new Map();\n  const acClosed = new Set();\n  const redOpenSlices = [];\n  let loopIteration = 0;\n  for (const rawLine of raw.split(/\\r?\\n/gu)) {\n    const line = rawLine.trim();\n    if (line.length === 0) continue;\n    let row;\n    try { row = JSON.parse(line); } catch { continue; }\n    if (!row || typeof row !== \"object\" || Array.isArray(row)) continue;\n    const rowRun = typeof row.runId === \"string\" && row.runId.length > 0 ? row.runId : runId;\n    if (rowRun !== runId) continue;\n    const slice = typeof row.slice === \"string\" && row.slice.length > 0 ? row.slice : \"S-unknown\";\n    let state = sliceMap.get(slice);\n    if (!state) {\n      state = { slice, redCount: 0, greenCount: 0, refactorCount: 0, redOpen: false, acIds: [] };\n      sliceMap.set(slice, state);\n    }\n    const exitCode = typeof row.exitCode === \"number\" ? row.exitCode : undefined;\n    if (row.phase === \"red\") {\n      state.redCount += 1;\n      if (exitCode !== undefined && exitCode !== 0) state.redOpen = true;\n    } else if (row.phase === \"green\") {\n      state.greenCount += 1;\n      state.redOpen = false;\n      loopIteration += 1;\n      if (Array.isArray(row.acIds)) {\n        for (const acId of row.acIds) {\n          if (typeof acId !== \"string\" || acId.length === 0) continue;\n          acClosed.add(acId);\n          if (!state.acIds.includes(acId)) state.acIds.push(acId);\n        }\n      }\n    } else if (row.phase === \"refactor\") {\n      state.refactorCount += 1;\n    }\n  }\n  for (const state of sliceMap.values()) {\n    if (state.redOpen) redOpenSlices.push(state.slice);\n  }\n  const slices = Array.from(sliceMap.values()).sort((a, b) => a.slice.localeCompare(b.slice, \"en\"));\n  return {\n    schemaVersion: 1,\n    runId,\n    loopIteration,\n    redOpen: redOpenSlices.length > 0,\n    redOpenSlices,\n    acClosed: Array.from(acClosed).sort(),\n    sliceCount: slices.length,\n    slices,\n    lastUpdatedAt: new Date().toISOString()\n  };\n}\n";
+/**
+ * Inline mirror of `src/early-loop.ts::computeEarlyLoopStatus`.
+ *
+ * Parity enforced by
+ * `tests/unit/early-loop-parity.test.ts::early-loop parity`.
+ *
+ * Signature contract:
+ *   async function computeEarlyLoopStatusInline(stateDir, stageId, runId, maxIterations) -> EarlyLoopStatus
+ */
+export declare const EARLY_LOOP_INLINE_SOURCE = "\nfunction normalizeEarlyLoopSeverityInline(value) {\n  if (value === \"critical\" || value === \"important\" || value === \"suggestion\") {\n    return value;\n  }\n  return \"important\";\n}\n\nfunction normalizeEarlyLoopTextInline(value, fallback) {\n  if (typeof value !== \"string\") return fallback;\n  const trimmed = value.trim();\n  return trimmed.length > 0 ? trimmed : fallback;\n}\n\nfunction stableConcernFallbackIdInline(locator, summary) {\n  const seed = (String(locator) + \"::\" + String(summary)).trim().toLowerCase();\n  let hash = 0;\n  for (let index = 0; index < seed.length; index += 1) {\n    hash = (Math.imul(31, hash) + seed.charCodeAt(index)) >>> 0;\n  }\n  return \"C-\" + hash.toString(16).padStart(8, \"0\");\n}\n\nfunction normalizeEarlyLoopConcernInline(row) {\n  if (!row || typeof row !== \"object\" || Array.isArray(row)) return null;\n  const locator = normalizeEarlyLoopTextInline(row.locator, \"unknown-location\");\n  const summary = normalizeEarlyLoopTextInline(row.summary, \"missing-summary\");\n  const id = typeof row.id === \"string\" && row.id.trim().length > 0\n    ? row.id.trim()\n    : stableConcernFallbackIdInline(locator, summary);\n  return {\n    id,\n    severity: normalizeEarlyLoopSeverityInline(row.severity),\n    locator,\n    summary\n  };\n}\n\nfunction normalizeEarlyLoopMaxIterationsInline(value) {\n  return Number.isInteger(value) && value >= 1 ? value : 3;\n}\n\nfunction earlyLoopSeverityWeightInline(value) {\n  if (value === \"critical\") return 3;\n  if (value === \"important\") return 2;\n  return 1;\n}\n\nfunction sortEarlyLoopConcernsInline(a, b) {\n  const severityDiff = earlyLoopSeverityWeightInline(b.severity) - earlyLoopSeverityWeightInline(a.severity);\n  if (severityDiff !== 0) return severityDiff;\n  if (a.firstSeenIteration !== b.firstSeenIteration) {\n    return a.firstSeenIteration - b.firstSeenIteration;\n  }\n  if (a.lastSeenIteration !== b.lastSeenIteration) {\n    return a.lastSeenIteration - b.lastSeenIteration;\n  }\n  return String(a.id).localeCompare(String(b.id), \"en\");\n}\n\nfunction formatEarlyLoopStatusLineInline(status) {\n  if (!status || typeof status !== \"object\") return \"\";\n  const convergence = status.convergenceTripped ? \"tripped\" : \"clear\";\n  return \"Early Loop: stage=\" + String(status.stage) +\n    \", iter=\" + String(status.iteration) + \"/\" + String(status.maxIterations) +\n    \", open=\" + String(Array.isArray(status.openConcerns) ? status.openConcerns.length : 0) +\n    \", convergence=\" + convergence;\n}\n\nasync function computeEarlyLoopStatusInline(stateDir, stageId, runId, maxIterations) {\n  const filePath = path.join(stateDir, \"early-loop-log.jsonl\");\n  const raw = await readTextFile(filePath, \"\");\n  const maxIters = normalizeEarlyLoopMaxIterationsInline(maxIterations);\n  const concernsMap = new Map();\n  let previousSnapshotKey = \"\";\n  let sameConcernStreak = 0;\n  let convergenceTripped = false;\n  let escalationReason = undefined;\n  let currentIteration = 0;\n  let lastSeenConcernIds = [];\n\n  for (const rawLine of raw.split(/\\r?\\n/gu)) {\n    const line = rawLine.trim();\n    if (line.length === 0) continue;\n    let parsed;\n    try {\n      parsed = JSON.parse(line);\n    } catch {\n      continue;\n    }\n    if (!parsed || typeof parsed !== \"object\" || Array.isArray(parsed)) continue;\n    const rowRunId = typeof parsed.runId === \"string\" && parsed.runId.trim().length > 0\n      ? parsed.runId.trim()\n      : \"active\";\n    const rowStage = typeof parsed.stage === \"string\" && parsed.stage.trim().length > 0\n      ? parsed.stage.trim()\n      : \"brainstorm\";\n    if (rowRunId !== runId || rowStage !== stageId) continue;\n\n    currentIteration += 1;\n    const iteration = Number.isInteger(parsed.iteration) && parsed.iteration >= 1\n      ? parsed.iteration\n      : currentIteration;\n    const seenThisIteration = new Set();\n    const concerns = Array.isArray(parsed.concerns) ? parsed.concerns : [];\n    for (const rawConcern of concerns) {\n      const concern = normalizeEarlyLoopConcernInline(rawConcern);\n      if (!concern) continue;\n      seenThisIteration.add(concern.id);\n      const existing = concernsMap.get(concern.id);\n      if (!existing) {\n        concernsMap.set(concern.id, {\n          id: concern.id,\n          severity: concern.severity,\n          locator: concern.locator,\n          summary: concern.summary,\n          firstSeenIteration: iteration,\n          lastSeenIteration: iteration\n        });\n        continue;\n      }\n      existing.lastSeenIteration = iteration;\n      existing.locator = concern.locator;\n      existing.summary = concern.summary;\n      if (earlyLoopSeverityWeightInline(concern.severity) >= earlyLoopSeverityWeightInline(existing.severity)) {\n        existing.severity = concern.severity;\n      }\n      delete existing.resolvedAtIteration;\n    }\n\n    const resolvedConcernIds = Array.isArray(parsed.resolvedConcernIds)\n      ? parsed.resolvedConcernIds\n          .filter((entry) => typeof entry === \"string\" && entry.trim().length > 0)\n          .map((entry) => entry.trim())\n      : [];\n    for (const concernId of resolvedConcernIds) {\n      const existing = concernsMap.get(concernId);\n      if (!existing) continue;\n      if (seenThisIteration.has(concernId)) continue;\n      if (existing.resolvedAtIteration === undefined) {\n        existing.resolvedAtIteration = iteration;\n      }\n    }\n\n    for (const concern of concernsMap.values()) {\n      if (concern.resolvedAtIteration !== undefined) continue;\n      if (seenThisIteration.has(concern.id)) continue;\n      concern.resolvedAtIteration = iteration;\n    }\n\n    const openConcernIds = Array.from(concernsMap.values())\n      .filter((concern) => concern.resolvedAtIteration === undefined)\n      .map((concern) => concern.id)\n      .sort((a, b) => String(a).localeCompare(String(b), \"en\"));\n    lastSeenConcernIds = openConcernIds;\n    const snapshotKey = openConcernIds.join(\"|\");\n    if (snapshotKey.length > 0 && snapshotKey === previousSnapshotKey) {\n      sameConcernStreak += 1;\n      if (!convergenceTripped && sameConcernStreak >= 2) {\n        convergenceTripped = true;\n        escalationReason = \"same concerns \" + String(sameConcernStreak) + \" iterations in a row\";\n      }\n    } else {\n      sameConcernStreak = snapshotKey.length > 0 ? 1 : 0;\n    }\n    previousSnapshotKey = snapshotKey;\n  }\n\n  const openConcerns = Array.from(concernsMap.values())\n    .filter((concern) => concern.resolvedAtIteration === undefined)\n    .sort(sortEarlyLoopConcernsInline);\n  const resolvedConcerns = Array.from(concernsMap.values())\n    .filter((concern) => concern.resolvedAtIteration !== undefined)\n    .sort((a, b) => {\n      if (a.resolvedAtIteration !== b.resolvedAtIteration) {\n        return a.resolvedAtIteration - b.resolvedAtIteration;\n      }\n      return sortEarlyLoopConcernsInline(a, b);\n    });\n\n  if (!convergenceTripped && openConcerns.length > 0 && currentIteration >= maxIters) {\n    convergenceTripped = true;\n    escalationReason = \"max iterations \" + String(maxIters) +\n      \" reached with \" + String(openConcerns.length) + \" open concern(s)\";\n  }\n\n  return {\n    schemaVersion: 1,\n    stage: stageId,\n    runId,\n    iteration: currentIteration,\n    maxIterations: maxIters,\n    openConcerns,\n    resolvedConcerns,\n    lastSeenConcernIds,\n    convergenceTripped,\n    ...(escalationReason ? { escalationReason } : {}),\n    lastUpdatedAt: new Date().toISOString()\n  };\n}\n";

package/dist/content/hook-inline-snippets.js

@@ -10,6 +10,8 @@
  *    `src/knowledge-store.ts::computeCompoundReadiness`.
  * 2. `computeRalphLoopStatusInline` mirrors
  *    `src/tdd-cycle.ts::computeRalphLoopStatus`.
+ * 3. `computeEarlyLoopStatusInline` mirrors
+ *    `src/early-loop.ts::computeEarlyLoopStatus`.
  *
  * Previously those bodies lived inline in `src/content/node-hooks.ts` — a
  * ~2000-line file — next to unrelated hook-handler code. Any silent drift
@@ -25,11 +27,12 @@
  *   longer owns their source code.
  *
  * Parity with the TypeScript canonical implementations is enforced by
- * `tests/unit/ralph-loop-parity.test.ts`. Any structural change to the
+ * `tests/unit/ralph-loop-parity.test.ts` and
+ * `tests/unit/early-loop-parity.test.ts`. Any structural change to the
  * canonical TS code MUST:
  *
  * 1. Update the matching snippet below.
- * 2. Re-run `npm test tests/unit/ralph-loop-parity.test.ts`.
+ * 2. Re-run parity tests for the touched snippet.
  *
  * DO NOT inline tests here — keep the parity check in its dedicated test
  * file.
@@ -43,7 +46,7 @@
  *   timestamp so the hook-written `compound-readiness.json` is byte-equal
  *   to the CLI-written version for the same input.
  * - `countArchivedRunsInline` counts immediate subdirectories of
- *   `<root>/.cclaw/runs/` so both the hook and the CLI see the same
+ *   `<root>/.cclaw/archive/` so both the hook and the CLI see the same
  *   `archivedRunsCount` for the small-project relaxation.
  * - `formatCompoundReadinessLineInline` mirrors the one-line summary shape
  *   used by `src/internal/compound-readiness.ts::formatCompoundReadinessLine`
@@ -54,11 +57,11 @@ function normalizeCompoundLastUpdatedAt(date) {
   return date.toISOString().replace(/\\.\\d{3}Z$/u, "Z");
 }
 
-// Count archived runs as sub-directories under \`.cclaw/runs/\`. Missing
+// Count archived runs as sub-directories under \`.cclaw/archive/\`. Missing
 // dir returns 0; unexpected errors return undefined so the caller can
 // skip the small-project relaxation rather than guess.
 async function countArchivedRunsInline(root) {
-  const dir = path.join(root, RUNTIME_ROOT, "runs");
+  const dir = path.join(root, RUNTIME_ROOT, "archive");
   try {
     const entries = await fs.readdir(dir, { withFileTypes: true });
     return entries.filter((entry) => entry.isDirectory()).length;
@@ -300,3 +303,213 @@ async function computeRalphLoopStatusInline(stateDir, runId) {
   };
 }
 `;
+/**
+ * Inline mirror of `src/early-loop.ts::computeEarlyLoopStatus`.
+ *
+ * Parity enforced by
+ * `tests/unit/early-loop-parity.test.ts::early-loop parity`.
+ *
+ * Signature contract:
+ *   async function computeEarlyLoopStatusInline(stateDir, stageId, runId, maxIterations) -> EarlyLoopStatus
+ */
+export const EARLY_LOOP_INLINE_SOURCE = `
+function normalizeEarlyLoopSeverityInline(value) {
+  if (value === "critical" || value === "important" || value === "suggestion") {
+    return value;
+  }
+  return "important";
+}
+
+function normalizeEarlyLoopTextInline(value, fallback) {
+  if (typeof value !== "string") return fallback;
+  const trimmed = value.trim();
+  return trimmed.length > 0 ? trimmed : fallback;
+}
+
+function stableConcernFallbackIdInline(locator, summary) {
+  const seed = (String(locator) + "::" + String(summary)).trim().toLowerCase();
+  let hash = 0;
+  for (let index = 0; index < seed.length; index += 1) {
+    hash = (Math.imul(31, hash) + seed.charCodeAt(index)) >>> 0;
+  }
+  return "C-" + hash.toString(16).padStart(8, "0");
+}
+
+function normalizeEarlyLoopConcernInline(row) {
+  if (!row || typeof row !== "object" || Array.isArray(row)) return null;
+  const locator = normalizeEarlyLoopTextInline(row.locator, "unknown-location");
+  const summary = normalizeEarlyLoopTextInline(row.summary, "missing-summary");
+  const id = typeof row.id === "string" && row.id.trim().length > 0
+    ? row.id.trim()
+    : stableConcernFallbackIdInline(locator, summary);
+  return {
+    id,
+    severity: normalizeEarlyLoopSeverityInline(row.severity),
+    locator,
+    summary
+  };
+}
+
+function normalizeEarlyLoopMaxIterationsInline(value) {
+  return Number.isInteger(value) && value >= 1 ? value : 3;
+}
+
+function earlyLoopSeverityWeightInline(value) {
+  if (value === "critical") return 3;
+  if (value === "important") return 2;
+  return 1;
+}
+
+function sortEarlyLoopConcernsInline(a, b) {
+  const severityDiff = earlyLoopSeverityWeightInline(b.severity) - earlyLoopSeverityWeightInline(a.severity);
+  if (severityDiff !== 0) return severityDiff;
+  if (a.firstSeenIteration !== b.firstSeenIteration) {
+    return a.firstSeenIteration - b.firstSeenIteration;
+  }
+  if (a.lastSeenIteration !== b.lastSeenIteration) {
+    return a.lastSeenIteration - b.lastSeenIteration;
+  }
+  return String(a.id).localeCompare(String(b.id), "en");
+}
+
+function formatEarlyLoopStatusLineInline(status) {
+  if (!status || typeof status !== "object") return "";
+  const convergence = status.convergenceTripped ? "tripped" : "clear";
+  return "Early Loop: stage=" + String(status.stage) +
+    ", iter=" + String(status.iteration) + "/" + String(status.maxIterations) +
+    ", open=" + String(Array.isArray(status.openConcerns) ? status.openConcerns.length : 0) +
+    ", convergence=" + convergence;
+}
+
+async function computeEarlyLoopStatusInline(stateDir, stageId, runId, maxIterations) {
+  const filePath = path.join(stateDir, "early-loop-log.jsonl");
+  const raw = await readTextFile(filePath, "");
+  const maxIters = normalizeEarlyLoopMaxIterationsInline(maxIterations);
+  const concernsMap = new Map();
+  let previousSnapshotKey = "";
+  let sameConcernStreak = 0;
+  let convergenceTripped = false;
+  let escalationReason = undefined;
+  let currentIteration = 0;
+  let lastSeenConcernIds = [];
+
+  for (const rawLine of raw.split(/\\r?\\n/gu)) {
+    const line = rawLine.trim();
+    if (line.length === 0) continue;
+    let parsed;
+    try {
+      parsed = JSON.parse(line);
+    } catch {
+      continue;
+    }
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) continue;
+    const rowRunId = typeof parsed.runId === "string" && parsed.runId.trim().length > 0
+      ? parsed.runId.trim()
+      : "active";
+    const rowStage = typeof parsed.stage === "string" && parsed.stage.trim().length > 0
+      ? parsed.stage.trim()
+      : "brainstorm";
+    if (rowRunId !== runId || rowStage !== stageId) continue;
+
+    currentIteration += 1;
+    const iteration = Number.isInteger(parsed.iteration) && parsed.iteration >= 1
+      ? parsed.iteration
+      : currentIteration;
+    const seenThisIteration = new Set();
+    const concerns = Array.isArray(parsed.concerns) ? parsed.concerns : [];
+    for (const rawConcern of concerns) {
+      const concern = normalizeEarlyLoopConcernInline(rawConcern);
+      if (!concern) continue;
+      seenThisIteration.add(concern.id);
+      const existing = concernsMap.get(concern.id);
+      if (!existing) {
+        concernsMap.set(concern.id, {
+          id: concern.id,
+          severity: concern.severity,
+          locator: concern.locator,
+          summary: concern.summary,
+          firstSeenIteration: iteration,
+          lastSeenIteration: iteration
+        });
+        continue;
+      }
+      existing.lastSeenIteration = iteration;
+      existing.locator = concern.locator;
+      existing.summary = concern.summary;
+      if (earlyLoopSeverityWeightInline(concern.severity) >= earlyLoopSeverityWeightInline(existing.severity)) {
+        existing.severity = concern.severity;
+      }
+      delete existing.resolvedAtIteration;
+    }
+
+    const resolvedConcernIds = Array.isArray(parsed.resolvedConcernIds)
+      ? parsed.resolvedConcernIds
+          .filter((entry) => typeof entry === "string" && entry.trim().length > 0)
+          .map((entry) => entry.trim())
+      : [];
+    for (const concernId of resolvedConcernIds) {
+      const existing = concernsMap.get(concernId);
+      if (!existing) continue;
+      if (seenThisIteration.has(concernId)) continue;
+      if (existing.resolvedAtIteration === undefined) {
+        existing.resolvedAtIteration = iteration;
+      }
+    }
+
+    for (const concern of concernsMap.values()) {
+      if (concern.resolvedAtIteration !== undefined) continue;
+      if (seenThisIteration.has(concern.id)) continue;
+      concern.resolvedAtIteration = iteration;
+    }
+
+    const openConcernIds = Array.from(concernsMap.values())
+      .filter((concern) => concern.resolvedAtIteration === undefined)
+      .map((concern) => concern.id)
+      .sort((a, b) => String(a).localeCompare(String(b), "en"));
+    lastSeenConcernIds = openConcernIds;
+    const snapshotKey = openConcernIds.join("|");
+    if (snapshotKey.length > 0 && snapshotKey === previousSnapshotKey) {
+      sameConcernStreak += 1;
+      if (!convergenceTripped && sameConcernStreak >= 2) {
+        convergenceTripped = true;
+        escalationReason = "same concerns " + String(sameConcernStreak) + " iterations in a row";
+      }
+    } else {
+      sameConcernStreak = snapshotKey.length > 0 ? 1 : 0;
+    }
+    previousSnapshotKey = snapshotKey;
+  }
+
+  const openConcerns = Array.from(concernsMap.values())
+    .filter((concern) => concern.resolvedAtIteration === undefined)
+    .sort(sortEarlyLoopConcernsInline);
+  const resolvedConcerns = Array.from(concernsMap.values())
+    .filter((concern) => concern.resolvedAtIteration !== undefined)
+    .sort((a, b) => {
+      if (a.resolvedAtIteration !== b.resolvedAtIteration) {
+        return a.resolvedAtIteration - b.resolvedAtIteration;
+      }
+      return sortEarlyLoopConcernsInline(a, b);
+    });
+
+  if (!convergenceTripped && openConcerns.length > 0 && currentIteration >= maxIters) {
+    convergenceTripped = true;
+    escalationReason = "max iterations " + String(maxIters) +
+      " reached with " + String(openConcerns.length) + " open concern(s)";
+  }
+
+  return {
+    schemaVersion: 1,
+    stage: stageId,
+    runId,
+    iteration: currentIteration,
+    maxIterations: maxIters,
+    openConcerns,
+    resolvedConcerns,
+    lastSeenConcernIds,
+    convergenceTripped,
+    ...(escalationReason ? { escalationReason } : {}),
+    lastUpdatedAt: new Date().toISOString()
+  };
+}
+`;

package/dist/content/hook-manifest.d.ts

@@ -5,7 +5,7 @@
  *
  *  - the per-harness JSON generators in `./observe.ts`
  *    (claude/cursor/codex hook documents),
- *  - the semantic coverage map in `./hook-events.ts` (docs + doctor),
+ *  - the semantic coverage map in `./hook-events.ts` (docs + sync/runtime checks),
  *  - the `requiredEvents` list embedded in `src/hook-schemas/*.v1.json`
  *    (enforced by a parity test).
  *
@@ -74,6 +74,6 @@ export declare function groupBindingsByEvent(harness: HookManifestHarness): Even
 /** Distinct harness-native event names covered by the manifest. */
 export declare function requiredEventsFor(harness: HookManifestHarness): string[];
 /**
- * Human-readable per-harness semantic coverage used by docs and doctor output.
+ * Human-readable per-harness semantic coverage used by docs and sync/runtime diagnostics.
  */
 export declare function semanticEventCoverage(harness: HookManifestHarness): Partial<Record<HookSemanticEvent, string>>;

package/dist/content/hook-manifest.js

@@ -5,7 +5,7 @@
  *
  *  - the per-harness JSON generators in `./observe.ts`
  *    (claude/cursor/codex hook documents),
- *  - the semantic coverage map in `./hook-events.ts` (docs + doctor),
+ *  - the semantic coverage map in `./hook-events.ts` (docs + sync/runtime checks),
  *  - the `requiredEvents` list embedded in `src/hook-schemas/*.v1.json`
  *    (enforced by a parity test).
  *
@@ -177,7 +177,7 @@ export function requiredEventsFor(harness) {
     return ordered;
 }
 /**
- * Human-readable per-harness semantic coverage used by docs and doctor output.
+ * Human-readable per-harness semantic coverage used by docs and sync/runtime diagnostics.
  */
 export function semanticEventCoverage(harness) {
     const out = {};

package/dist/content/hooks.d.ts

@@ -1,4 +1,5 @@
 export declare function startFlowScript(): string;
+export declare function cancelRunScript(): string;
 export declare function stageCompleteScript(): string;
 export declare function delegationRecordScript(): string;
 export declare function runHookCmdScript(): string;