cclaw-cli 6.8.0 → 6.10.0

package/dist/artifact-linter.js

@@ -1,9 +1,11 @@
 import fs from "node:fs/promises";
+import path from "node:path";
 import { resolveArtifactPath as resolveStageArtifactPath } from "./artifact-paths.js";
 import { exists } from "./fs-utils.js";
 import { stageSchema } from "./content/stage-schema.js";
 import { readFlowState } from "./run-persistence.js";
-import { duplicateH2Headings, extractH2Sections, extractRequirementIdsFromMarkdown, isShortCircuitActivated, normalizeHeadingTitle, parseFrontmatter, parseLearningsSection, sectionBodyByAnyName, sectionBodyByHeadingPrefix, sectionBodyByName, validateSectionBody, formatLearningsErrorsBullets } from "./artifact-linter/shared.js";
+import { duplicateH2Headings, extractEvidencePointers, extractH2Sections, extractRequirementIdsFromMarkdown, isShortCircuitActivated, normalizeHeadingTitle, parseFrontmatter, parseLearningsSection, sectionBodyByAnyName, sectionBodyByHeadingPrefix, sectionBodyByName, validateSectionBody, formatLearningsErrorsBullets } from "./artifact-linter/shared.js";
+import { foldTddSliceLedger, readTddSliceLedger } from "./tdd-slices.js";
 import { shouldDemoteArtifactValidationByTrack } from "./content/stage-schema.js";
 import { readDelegationLedger, recordArtifactValidationDemotedByTrack } from "./delegation.js";
 import { classifyAndPersistFindings } from "./artifact-linter/findings-dedup.js";
@@ -145,6 +147,17 @@ export async function lintArtifact(projectRoot, stage, track = "standard", optio
         }
     }
     const liteTierForValidators = shouldDemoteArtifactValidationByTrack(track, taskClass);
+    // v6.10.0 (T3) — pre-resolve RED/GREEN Evidence pointers and sidecar
+    // auto-satisfy state once for the whole TDD loop, then thread the
+    // booleans through `validateSectionBody`. We do the async resolution
+    // here (path existence + delegation spanId match) so the validators
+    // themselves stay sync.
+    const tddEvidenceContext = stage === "tdd"
+        ? await resolveTddEvidencePointerContext({
+            projectRoot,
+            sections
+        })
+        : { red: {}, green: {} };
     for (const v of schema.artifactValidation) {
         const sectionKey = normalizeHeadingTitle(v.section).toLowerCase();
         const scopeBoundaryAlias = stage === "scope" && sectionKey === "in scope / out of scope";
@@ -164,7 +177,8 @@ export async function lintArtifact(projectRoot, stage, track = "standard", optio
             ? { ok: false, details: `No ## heading matching required section "${v.section}".` }
             : validateSectionBody(body, v.validationRule, v.section, {
                 sections,
-                liteTier: liteTierForValidators
+                liteTier: liteTierForValidators,
+                tddEvidence: stage === "tdd" ? tddEvidenceContext : undefined
             });
         const found = hasHeading && validation.ok;
         findings.push({
@@ -420,3 +434,74 @@ const ARTIFACT_VALIDATION_LITE_DEMOTE_SECTIONS = new Set([
     "Stale Diagram Drift Check",
     "Product Discovery Delegation (Strategist Mode)"
 ]);
+/**
+ * v6.10.0 (T3) — pre-resolve `Evidence:` pointers and sidecar
+ * auto-satisfy state for the TDD stage's RED/GREEN Evidence rows so
+ * `validateSectionBody` (sync) can short-circuit. A pointer of the form
+ * `<path>` is satisfied when the path exists on disk relative to the
+ * project root; `spanId:<id>` is satisfied when any delegation ledger
+ * row carries that span id. Sidecar auto-satisfy fires when
+ * `06-tdd-slices.jsonl` carries at least one slice with a non-empty
+ * `redOutputRef` / `greenOutputRef`.
+ */
+async function resolveTddEvidencePointerContext(input) {
+    const { projectRoot, sections } = input;
+    const redSection = sectionBodyByName(sections, "RED Evidence") ?? "";
+    const greenSection = sectionBodyByName(sections, "GREEN Evidence") ?? "";
+    const redPointers = extractEvidencePointers(redSection);
+    const greenPointers = extractEvidencePointers(greenSection);
+    let knownSpanIds = new Set();
+    if (redPointers.length > 0 || greenPointers.length > 0) {
+        try {
+            const ledger = await readDelegationLedger(projectRoot);
+            knownSpanIds = new Set(ledger.entries
+                .map((entry) => entry.spanId)
+                .filter((id) => typeof id === "string" && id.length > 0));
+        }
+        catch {
+            knownSpanIds = new Set();
+        }
+    }
+    async function pointerResolves(value) {
+        const trimmed = value.replace(/[`*_]/gu, "").trim();
+        if (trimmed.length === 0)
+            return false;
+        if (/^spanid\s*:/iu.test(trimmed)) {
+            const id = trimmed.replace(/^spanid\s*:\s*/iu, "").trim();
+            return id.length > 0 && knownSpanIds.has(id);
+        }
+        const candidate = path.isAbsolute(trimmed) ? trimmed : path.join(projectRoot, trimmed);
+        return exists(candidate);
+    }
+    async function anyResolved(values) {
+        for (const value of values) {
+            if (await pointerResolves(value))
+                return true;
+        }
+        return false;
+    }
+    let redSidecarAutoSatisfy = false;
+    let greenSidecarAutoSatisfy = false;
+    try {
+        const sidecar = await readTddSliceLedger(projectRoot);
+        if (sidecar.entries.length > 0) {
+            const folded = foldTddSliceLedger(sidecar.entries);
+            redSidecarAutoSatisfy = folded.some((entry) => typeof entry.redOutputRef === "string" && entry.redOutputRef.length > 0);
+            greenSidecarAutoSatisfy = folded.some((entry) => typeof entry.greenOutputRef === "string" && entry.greenOutputRef.length > 0);
+        }
+    }
+    catch {
+        redSidecarAutoSatisfy = false;
+        greenSidecarAutoSatisfy = false;
+    }
+    return {
+        red: {
+            pointerSatisfied: await anyResolved(redPointers),
+            sidecarAutoSatisfy: redSidecarAutoSatisfy
+        },
+        green: {
+            pointerSatisfied: await anyResolved(greenPointers),
+            sidecarAutoSatisfy: greenSidecarAutoSatisfy
+        }
+    };
+}

package/dist/content/examples.js

@@ -36,10 +36,10 @@ export const BEHAVIOR_ANCHORS = [
     },
     {
         stage: "tdd",
-        section: "RED Evidence",
-        bad: "RED: `expect(true).toBe(true)` then \"failing test observed\" — the assertion can never have caught the bug it claims to prove.",
-        good: "RED: `expect(api.fetchFeed()).rejects.toThrow(AuthError)`; the failure output names the missing guard and ties to AC-3.",
-        ruleHint: "Mental mutation test: name a plausible bug that would still pass the assertion. If you can, the assertion is too coarse."
+        section: "Watched-RED Proof",
+        bad: "Hand-edit `S-1 | 2026-04-15T10:00 | observed RED` into the markdown table; nothing lands in the JSONL sidecar, so retries silently overwrite the row.",
+        good: "Run `cclaw-cli internal tdd-slice-record --slice S-1 --status red --test-file tests/feed.spec.ts --command \"npm test\" --paths src/api/feed.ts --ac AC-3`; the linter reads the sidecar.",
+        ruleHint: "RED/GREEN/REFACTOR transitions are recorded by `cclaw-cli internal tdd-slice-record`; the markdown tables are an auto-derived view from v6.10.0 onward."
     },
     {
         stage: "review",
@@ -247,12 +247,12 @@ Plan is ready to execute after user confirmation.
 | S-1 feed window | expected 30d window, got 7d |
 | S-2 degraded banner | banner absent after forced disconnect |
 
-## Acceptance Mapping
+## Acceptance & Failure Map
 
-| Slice | AC IDs |
-| --- | --- |
-| S-1 | AC-1 |
-| S-2 | AC-3 |
+| Slice | Source ID | AC ID | Expected behavior | RED-link |
+| --- | --- | --- | --- | --- |
+| S-1 | SRC-1 | AC-1 | feed window honors 30d cap | spanId:tdd-feed-window-red |
+| S-2 | SRC-2 | AC-3 | degraded banner appears on disconnect | .cclaw/artifacts/06-tdd-slices.jsonl |
 
 ## GREEN
 

package/dist/content/harness-doc.js

@@ -60,6 +60,6 @@ export function harnessIntegrationDocMarkdown() {
         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(),
         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"
+        "\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\nRuntime Honesty 6.9.0 reduced the runtime to two dispatched handlers:\n`session-start` (rehydrate) and `stop-handoff` (clean handoff). Earlier\nreleases also generated `prompt-guard`, `workflow-guard`,\n`context-monitor`, `pre-compact`, and `verify-current-state` handlers, but\nthose entry points were unreachable via the dispatch table they shipped\nwith and have been removed.\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| `stop_handoff` | Stop -> stop-handoff | stop -> stop-handoff | plugin session.idle -> stop-handoff | Stop -> stop-handoff |\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`, and `session-rehydrate` routes to `session-start`. 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`, `Stop`) |\n| Cursor | `cursor` | camelCase (`sessionStart`, `stop`) |\n| OpenCode | `opencode` | camelCase (`sessionStart`, `stop`) |\n| OpenAI Codex | `codex` | PascalCase (`SessionStart`, `Stop`) |\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- Hook-level pre-tool blocking (prompt-guard / workflow-guard) was removed\n  in 6.9.0. Stage transitions are owned by the canonical CLI path\n  `node .cclaw/hooks/stage-complete.mjs <stage>`; harness sessions enforce\n  workflow discipline via the iron-laws block surfaced at session-start\n  rather than via per-tool hook interception.\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`post_ship_review -> 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/hooks.js

@@ -326,7 +326,7 @@ function hasPriorAck(events, args, runId) {
 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>] [--supersede=<prevSpanId>] [--allow-parallel] [--json]",
+    "  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>] [--supersede=<prevSpanId>] [--allow-parallel] [--paths=<comma-separated>] [--override-cap=<int>] [--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>] [--evidence-ref=<ref>] [--json]",
     "  node .cclaw/hooks/delegation-record.mjs --repair --span-id=<id> --repair-reason=\"<why>\" [--json]",
     "",
@@ -339,6 +339,10 @@ function usage() {
     "Dispatch dedup (v6.8.0):",
     "  --supersede=<prevSpanId>  close the previous active span on this (stage, agent) as 'stale' before recording the new scheduled row",
     "  --allow-parallel          record both spans as concurrent; new row is tagged allowParallel: true",
+    "",
+    "TDD parallel scheduler (v6.10.0):",
+    "  --paths=<a,b,c>           repo-relative paths the slice-implementer will edit; disjoint sets auto-promote to allowParallel, overlap throws DispatchOverlapError",
+    "  --override-cap=<int>      raise the slice-implementer fan-out cap once for this dispatch (default cap " + String(5) + ", env CCLAW_MAX_PARALLEL_SLICE_IMPLEMENTERS overrides globally)",
     ""
   ].join("\\n") + "\\n");
 }
@@ -440,6 +444,13 @@ function buildRow(args, status, runId, now, options) {
   // Inherit the span's startTs from prior rows so monotonic validation
   // can compare against the original schedule, not the row write time.
   const startTs = (options && options.spanStartTs) || now;
+  // v6.10.0 (P1): claimedPaths from --paths=<comma-separated>. Empty
+  // arrays are dropped so the row stays compatible with v6.9 readers.
+  const claimedPathsRaw = typeof args.paths === "string" ? args.paths : "";
+  const claimedPaths = claimedPathsRaw
+    .split(",")
+    .map((value) => value.trim())
+    .filter((value) => value.length > 0);
   return {
     stage: args.stage,
     agent: args.agent,
@@ -461,7 +472,8 @@ function buildRow(args, status, runId, now, options) {
     completedTs: args["completed-ts"] || (status === "completed" ? now : undefined),
     endTs: TERMINAL.has(status) ? now : undefined,
     schemaVersion: LEDGER_SCHEMA_VERSION,
-    allowParallel: args["allow-parallel"] === true ? true : undefined
+    allowParallel: args["allow-parallel"] === true ? true : undefined,
+    claimedPaths: claimedPaths.length > 0 ? claimedPaths : undefined
   };
 }
 
@@ -485,7 +497,11 @@ function findActiveSpanForPairInline(stage, agent, runId, entries) {
   for (const entry of entries) {
     if (!entry || typeof entry !== "object") continue;
     if (typeof entry.spanId !== "string" || entry.spanId.length === 0) continue;
-    if (entry.runId && entry.runId !== runId) continue;
+    // Strict run-scope (v6.9.0 R7 fix): legacy entries without a runId
+    // are treated as foreign so they cannot keep an old span "active"
+    // across runs and trip dispatch_duplicate on a fresh dispatch.
+    if (typeof entry.runId !== "string" || entry.runId.length === 0) continue;
+    if (entry.runId !== runId) continue;
     if (entry.stage !== stage || entry.agent !== agent) continue;
     const existing = latestBySpan.get(entry.spanId);
     if (!existing || effectiveTs(entry) >= effectiveTs(existing)) {
@@ -498,6 +514,102 @@ function findActiveSpanForPairInline(stage, agent, runId, entries) {
   return null;
 }
 
+// keep in sync with computeActiveSubagents in src/delegation.ts
+function computeActiveSubagentsInline(entries) {
+  const ACTIVE_STATUSES = new Set(["scheduled", "launched", "acknowledged"]);
+  const effectiveTs = (entry) =>
+    entry.completedTs || entry.ackTs || entry.launchedTs || entry.endTs || entry.startTs || entry.ts || "";
+  const latestBySpan = new Map();
+  for (const entry of entries) {
+    if (!entry || typeof entry !== "object") continue;
+    if (typeof entry.spanId !== "string" || entry.spanId.length === 0) continue;
+    const existing = latestBySpan.get(entry.spanId);
+    if (!existing || effectiveTs(entry) >= effectiveTs(existing)) {
+      latestBySpan.set(entry.spanId, entry);
+    }
+  }
+  const active = [];
+  for (const entry of latestBySpan.values()) {
+    if (ACTIVE_STATUSES.has(entry.status)) active.push(entry);
+  }
+  return active;
+}
+
+// keep in sync with validateFileOverlap in src/delegation.ts
+function validateFileOverlapInline(stamped, activeEntries) {
+  if (stamped.agent !== "slice-implementer" || stamped.stage !== "tdd") {
+    return { autoParallel: false, conflict: null };
+  }
+  const newPaths = Array.isArray(stamped.claimedPaths) ? stamped.claimedPaths : [];
+  if (newPaths.length === 0) {
+    return { autoParallel: false, conflict: null };
+  }
+  const sameLane = activeEntries.filter(
+    (entry) =>
+      entry.stage === stamped.stage &&
+      entry.agent === stamped.agent &&
+      entry.spanId !== stamped.spanId
+  );
+  if (sameLane.length === 0) {
+    return { autoParallel: true, conflict: null };
+  }
+  for (const existing of sameLane) {
+    const existingPaths = Array.isArray(existing.claimedPaths) ? existing.claimedPaths : [];
+    if (existingPaths.length === 0) {
+      return { autoParallel: false, conflict: null };
+    }
+    const overlap = newPaths.filter((p) => existingPaths.includes(p));
+    if (overlap.length > 0) {
+      return {
+        autoParallel: false,
+        conflict: {
+          existingSpanId: existing.spanId || "unknown",
+          newSpanId: stamped.spanId || "unknown",
+          pair: { stage: stamped.stage, agent: stamped.agent },
+          conflictingPaths: overlap
+        }
+      };
+    }
+  }
+  return { autoParallel: true, conflict: null };
+}
+
+const MAX_PARALLEL_SLICE_IMPLEMENTERS_INLINE = 5;
+
+function readMaxParallelOverrideFromEnvInline() {
+  const raw = process.env.CCLAW_MAX_PARALLEL_SLICE_IMPLEMENTERS;
+  if (typeof raw !== "string" || raw.trim().length === 0) return null;
+  const parsed = Number(raw);
+  if (!Number.isFinite(parsed) || !Number.isInteger(parsed) || parsed < 1) return null;
+  return parsed;
+}
+
+// keep in sync with validateFanOutCap in src/delegation.ts
+function validateFanOutCapInline(stamped, activeEntries, override) {
+  if (stamped.agent !== "slice-implementer" || stamped.stage !== "tdd") return null;
+  if (stamped.status !== "scheduled") return null;
+  let cap;
+  if (override !== null && override !== undefined && Number.isInteger(override) && override >= 1) {
+    cap = override;
+  } else {
+    cap = readMaxParallelOverrideFromEnvInline() || MAX_PARALLEL_SLICE_IMPLEMENTERS_INLINE;
+  }
+  const sameLaneActive = activeEntries.filter(
+    (entry) =>
+      entry.stage === stamped.stage &&
+      entry.agent === stamped.agent &&
+      entry.spanId !== stamped.spanId
+  );
+  if (sameLaneActive.length + 1 > cap) {
+    return {
+      cap,
+      active: sameLaneActive.length,
+      pair: { stage: stamped.stage, agent: stamped.agent }
+    };
+  }
+  return null;
+}
+
 function enforceDispatchDedupInline(stamped, priorEntries, args) {
   if (stamped.status !== "scheduled") return null;
   if (args["allow-parallel"] === true) return null;
@@ -988,6 +1100,31 @@ async function main() {
     emitErrorJson("delegation_timestamp_non_monotonic", violation, json);
     return;
   }
+
+  // v6.10.0 (P1+P2): file-overlap scheduler + fan-out cap. Run before
+  // the legacy dispatch dedup so disjoint claimedPaths can auto-promote
+  // to allowParallel and bypass the duplicate guard.
+  if (status === "scheduled") {
+    const sameRunPrior = priorLedger.filter((entry) => entry.runId === runId);
+    const activeForRun = computeActiveSubagentsInline(sameRunPrior);
+    const overlap = validateFileOverlapInline(clean, activeForRun);
+    if (overlap.conflict) {
+      emitErrorJson("dispatch_overlap", overlap.conflict, json);
+      return;
+    }
+    if (overlap.autoParallel && clean.allowParallel !== true) {
+      clean.allowParallel = true;
+      args["allow-parallel"] = true;
+      event.allowParallel = true;
+    }
+    const overrideRaw = typeof args["override-cap"] === "string" ? args["override-cap"] : null;
+    const override = overrideRaw !== null ? Number(overrideRaw) : null;
+    const capViolation = validateFanOutCapInline(clean, activeForRun, override);
+    if (capViolation) {
+      emitErrorJson("dispatch_cap", capViolation, json);
+      return;
+    }
+  }
   const dedupViolation = enforceDispatchDedupInline(clean, priorLedger, args);
   if (dedupViolation) {
     if (dedupViolation.kind === "supersede") {

package/dist/content/iron-laws.js

@@ -158,9 +158,13 @@ function hardGateReference(law) {
         .join(", ");
 }
 export function ironLawsSkillMarkdown() {
+    // v6.9.0: Phase A purged the `PreToolUse` / `PostToolUse` / pre-tool
+    // pipeline handlers, so `review-coverage-complete-before-ship` is no
+    // longer hook-enforced — it now lives in the ship stage HARD-GATE.
+    // Only `stop-clean-or-handoff` (Stop hook) is still hook-enforced;
+    // everything else is stage-owned advisory.
     const enforcedLawIds = new Set([
-        "stop-clean-or-handoff",
-        "review-coverage-complete-before-ship"
+        "stop-clean-or-handoff"
     ]);
     const enforced = IRON_LAWS.filter((law) => enforcedLawIds.has(law.id));
     const advisory = IRON_LAWS.filter((law) => !enforcedLawIds.has(law.id));