cclaw-cli 6.7.0 → 6.9.0

package/dist/artifact-linter/design.js

@@ -424,7 +424,7 @@ export async function lintDesignStage(ctx) {
     if (layeredDocumentReview !== null) {
         findings.push({
             section: "Document Reviewer Structured Findings",
-            required: false,
+            required: true,
             rule: "When Layered review references coherence-reviewer/scope-guardian-reviewer/feasibility-reviewer, include explicit reviewer status plus calibrated finding lines.",
             found: layeredDocumentReview.missingStructured.length === 0,
             details: layeredDocumentReview.missingStructured.length === 0

package/dist/artifact-linter/shared.js

@@ -1881,7 +1881,8 @@ export function checkInvestigationTrace(sectionBody) {
  */
 export function evaluateInvestigationTrace(ctx, sectionName) {
     const body = sectionBodyByName(ctx.sections, sectionName);
-    const result = checkInvestigationTrace(body);
+    const authoredBody = body === null ? null : extractAuthoredBody(body);
+    const result = checkInvestigationTrace(authoredBody);
     if (result === null)
         return;
     ctx.findings.push({

package/dist/artifact-linter/tdd.d.ts

@@ -1,2 +1,13 @@
 import { type StageLintContext } from "./shared.js";
 export declare function lintTddStage(ctx: StageLintContext): Promise<void>;
+interface ParsedSliceCycleResult {
+    ok: boolean;
+    details: string;
+}
+export declare function parseVerticalSliceCycle(body: string): ParsedSliceCycleResult;
+interface VerificationLadderResult {
+    ok: boolean;
+    details: string;
+}
+export declare function evaluateVerificationLadder(body: string | null): VerificationLadderResult;
+export {};

package/dist/artifact-linter/tdd.js

@@ -74,16 +74,13 @@ export async function lintTddStage(ctx) {
         });
     }
     else {
-        const required = ["RED", "GREEN", "REFACTOR"];
-        const missing = required.filter((token) => !new RegExp(token, "u").test(sliceCycleBody));
+        const cycleResult = parseVerticalSliceCycle(sliceCycleBody);
         findings.push({
             section: "Vertical Slice Cycle Coverage",
             required: true,
-            rule: "Vertical Slice Cycle must include RED, GREEN, and REFACTOR per slice (refactor may be deferred with rationale).",
-            found: missing.length === 0,
-            details: missing.length === 0
-                ? "Vertical Slice Cycle references RED/GREEN/REFACTOR."
-                : `Vertical Slice Cycle is missing phase token(s): ${missing.join(", ")}.`
+            rule: "Vertical Slice Cycle must show RED -> GREEN -> REFACTOR monotonic progression per slice (refactor may be deferred with one-line rationale, e.g. `deferred because <reason>`).",
+            found: cycleResult.ok,
+            details: cycleResult.details
         });
     }
     const assertionBody = sectionBodyByName(sections, "Assertion Correctness Notes");
@@ -196,4 +193,174 @@ export async function lintTddStage(ctx) {
                     : "integration-overseer completion exists, but PASS/PASS_WITH_GAPS evidence is missing in delegation evidenceRefs and artifact text."
         });
     }
+    {
+        const verificationBody = sectionBodyByName(sections, "Verification Ladder") ??
+            sectionBodyByName(sections, "Verification Status") ??
+            sectionBodyByName(sections, "Verification");
+        const ladderResult = evaluateVerificationLadder(verificationBody);
+        findings.push({
+            section: "tdd_verification_pending",
+            required: true,
+            rule: "Verification Ladder rows must not remain `pending`; promote each row to `passed`, `n/a`, `failed`, `skipped`, or `deferred` (with rationale) before stage-complete.",
+            found: ladderResult.ok,
+            details: ladderResult.details
+        });
+    }
+}
+export function parseVerticalSliceCycle(body) {
+    const tableLines = body.split("\n").filter((line) => /^\|/u.test(line));
+    if (tableLines.length < 3) {
+        return {
+            ok: false,
+            details: "Vertical Slice Cycle table must have a header, separator, and at least one slice row."
+        };
+    }
+    const headerCells = splitMarkdownRow(tableLines[0]).map((cell) => cell.toLowerCase());
+    const findIdx = (token) => headerCells.findIndex((cell) => cell.includes(token));
+    const sliceIdx = findIdx("slice");
+    const redIdx = findIdx("red");
+    const greenIdx = findIdx("green");
+    const refactorIdx = findIdx("refactor");
+    if (sliceIdx < 0 || redIdx < 0 || greenIdx < 0 || refactorIdx < 0) {
+        return {
+            ok: false,
+            details: "Vertical Slice Cycle header must include Slice, RED, GREEN, and REFACTOR columns."
+        };
+    }
+    const dataRows = tableLines.slice(2);
+    const populated = dataRows.filter((row) => splitMarkdownRow(row).some((cell) => cell.length > 0));
+    if (populated.length === 0) {
+        return {
+            ok: false,
+            details: "Vertical Slice Cycle has no populated slice rows."
+        };
+    }
+    const errors = [];
+    for (const row of populated) {
+        const cells = splitMarkdownRow(row);
+        const slice = cells[sliceIdx] ?? "";
+        const red = cells[redIdx] ?? "";
+        const green = cells[greenIdx] ?? "";
+        const refactor = cells[refactorIdx] ?? "";
+        const label = slice.length > 0 ? slice : `row ${populated.indexOf(row) + 1}`;
+        const redTs = parseTimestampCell(red);
+        const greenTs = parseTimestampCell(green);
+        if (red.length === 0) {
+            errors.push(`${label}: RED ts is empty.`);
+            continue;
+        }
+        if (green.length === 0) {
+            errors.push(`${label}: GREEN ts is empty.`);
+            continue;
+        }
+        if (redTs === null) {
+            errors.push(`${label}: RED ts \`${red}\` is not an ISO timestamp.`);
+            continue;
+        }
+        if (greenTs === null) {
+            errors.push(`${label}: GREEN ts \`${green}\` is not an ISO timestamp.`);
+            continue;
+        }
+        if (greenTs < redTs) {
+            errors.push(`${label}: GREEN (${green}) precedes RED (${red}) — order must be monotonic.`);
+            continue;
+        }
+        if (refactor.length === 0) {
+            errors.push(`${label}: REFACTOR cell is empty; provide a timestamp or \`deferred because <reason>\`.`);
+            continue;
+        }
+        if (isDeferredOrNotNeeded(refactor)) {
+            const rationale = extractDeferRationale(refactor);
+            if (rationale.length === 0) {
+                errors.push(`${label}: REFACTOR marked deferred/not-needed but rationale is missing — use \`deferred because <reason>\` or \`not needed because <reason>\`.`);
+            }
+            continue;
+        }
+        const refactorTs = parseTimestampCell(refactor);
+        if (refactorTs === null) {
+            errors.push(`${label}: REFACTOR cell \`${refactor}\` is not an ISO timestamp and not marked deferred/not-needed with rationale.`);
+            continue;
+        }
+        if (refactorTs < greenTs) {
+            errors.push(`${label}: REFACTOR (${refactor}) precedes GREEN (${green}) — order must be monotonic.`);
+            continue;
+        }
+    }
+    if (errors.length > 0) {
+        return { ok: false, details: errors.join(" ") };
+    }
+    return {
+        ok: true,
+        details: `${populated.length} slice row(s) show monotonic RED -> GREEN -> REFACTOR (deferred-with-rationale accepted).`
+    };
+}
+function splitMarkdownRow(line) {
+    const trimmed = line.trim();
+    if (!trimmed.startsWith("|"))
+        return [];
+    const inner = trimmed.replace(/^\|/u, "").replace(/\|$/u, "");
+    return inner.split("|").map((cell) => cell.trim());
+}
+function parseTimestampCell(cell) {
+    const trimmed = cell.replace(/^[`*_\s]+|[`*_\s]+$/gu, "");
+    if (!/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}/u.test(trimmed))
+        return null;
+    const t = Date.parse(trimmed);
+    return Number.isFinite(t) ? t : null;
+}
+function isDeferredOrNotNeeded(cell) {
+    return /\b(deferred|not[\s-]?needed|n\/?a|skipped)\b/iu.test(cell);
+}
+function extractDeferRationale(cell) {
+    const cleaned = cell.replace(/`/gu, "").trim();
+    const match = /(?:deferred|not[\s-]?needed|skipped)\s+(?:because|since|due to|—|-)\s*(.+)/iu.exec(cleaned);
+    if (match !== null && match[1] !== undefined && match[1].trim().length > 0) {
+        return match[1].trim();
+    }
+    // Accept any free-form rationale text following the deferral marker.
+    const fallback = cleaned.replace(/^\s*(deferred|not[\s-]?needed|skipped|n\/?a)\b[:\s-]*/iu, "").trim();
+    return fallback;
+}
+export function evaluateVerificationLadder(body) {
+    if (body === null) {
+        return {
+            ok: true,
+            details: "No Verification Ladder section present; rule advisory."
+        };
+    }
+    const tableLines = body.split("\n").filter((line) => /^\|/u.test(line));
+    if (tableLines.length < 3) {
+        return {
+            ok: true,
+            details: "Verification Ladder section has no table rows; rule advisory."
+        };
+    }
+    const dataRows = tableLines.slice(2);
+    const pendingRows = [];
+    for (const row of dataRows) {
+        const cells = splitMarkdownRow(row);
+        if (cells.length === 0)
+            continue;
+        if (cells.every((cell) => cell.length === 0))
+            continue;
+        const cellsLower = cells.map((cell) => cell.toLowerCase().replace(/`/gu, "").trim());
+        const hasPending = cellsLower.some((cell) => /\bpending\b/u.test(cell));
+        if (hasPending) {
+            const label = cells[0] !== undefined && cells[0].length > 0
+                ? cells[0]
+                : `row ${dataRows.indexOf(row) + 1}`;
+            pendingRows.push(label);
+        }
+    }
+    if (pendingRows.length === 0) {
+        return {
+            ok: true,
+            details: "Verification Ladder has no rows still marked `pending`."
+        };
+    }
+    return {
+        ok: false,
+        details: `Verification Ladder has ${pendingRows.length} row(s) still marked \`pending\`: ${pendingRows.join(", ")}. ` +
+            "Promote each to `passed`, `n/a`, `failed`, `skipped`, or `deferred` (with rationale) before stage-complete."
+    };
 }

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>] [--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] [--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]",
     "",
@@ -335,6 +335,10 @@ function usage() {
     "",
     "Per-surface allowed --agent-definition-path prefixes:",
     ...VALID_DISPATCH_SURFACES.map((surface) => "  " + surface + ": " + (SURFACE_PATH_PREFIXES[surface].length === 0 ? "(any)" : SURFACE_PATH_PREFIXES[surface].join(", "))),
+    "",
+    "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",
     ""
   ].join("\\n") + "\\n");
 }
@@ -350,6 +354,51 @@ function emitProblems(problems, json, code) {
   process.exitCode = exitCode;
 }
 
+function emitErrorJson(error, details, json) {
+  if (json) {
+    process.stdout.write(JSON.stringify({ ok: false, error, details }, null, 2) + "\\n");
+  } else {
+    process.stderr.write("[cclaw] delegation-record: error: " + error + " — " + JSON.stringify(details) + "\\n");
+  }
+  process.exit(2);
+}
+
+// keep in sync with validateMonotonicTimestamps in src/delegation.ts
+function validateMonotonicTimestampsInline(stamped, prior) {
+  const startTs = stamped.startTs;
+  if (stamped.launchedTs && startTs && stamped.launchedTs < startTs) {
+    return { field: "launchedTs", actual: stamped.launchedTs, bound: startTs };
+  }
+  if (stamped.ackTs) {
+    const ackBound = stamped.launchedTs || startTs;
+    if (ackBound && stamped.ackTs < ackBound) {
+      return { field: "ackTs", actual: stamped.ackTs, bound: ackBound };
+    }
+  }
+  if (stamped.completedTs) {
+    const completedBound = stamped.ackTs || stamped.launchedTs || startTs;
+    if (completedBound && stamped.completedTs < completedBound) {
+      return { field: "completedTs", actual: stamped.completedTs, bound: completedBound };
+    }
+  }
+  if (!stamped.spanId) return null;
+  const priorForSpan = (prior || []).filter((entry) => entry && entry.spanId === stamped.spanId);
+  if (priorForSpan.length === 0) return null;
+  const tsValues = priorForSpan
+    .map((entry) => entry.ts || entry.startTs || "")
+    .filter((ts) => ts.length > 0);
+  if (tsValues.length === 0) return null;
+  let latest = tsValues[0];
+  for (let i = 1; i < tsValues.length; i += 1) {
+    if (tsValues[i] > latest) latest = tsValues[i];
+  }
+  const stampedTs = stamped.ts || stamped.startTs || "";
+  if (stampedTs && stampedTs < latest) {
+    return { field: "ts", actual: stampedTs, bound: latest };
+  }
+  return null;
+}
+
 function normalizeRelPath(value) {
   return String(value || "").replace(/\\\\/gu, "/").replace(/^\\.\\//u, "");
 }
@@ -382,12 +431,15 @@ function normalizeEvidenceRefs(args) {
   return [];
 }
 
-function buildRow(args, status, runId, now) {
+function buildRow(args, status, runId, now, options) {
   const fulfillmentMode = args["dispatch-surface"] === "role-switch"
     ? "role-switch"
     : args["dispatch-surface"] === "cursor-task" || args["dispatch-surface"] === "generic-task"
       ? "generic-dispatch"
       : "isolated";
+  // 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;
   return {
     stage: args.stage,
     agent: args.agent,
@@ -402,13 +454,87 @@ function buildRow(args, status, runId, now) {
     waiverReason: args["waiver-reason"],
     evidenceRefs: normalizeEvidenceRefs(args),
     runId,
-    startTs: now,
+    startTs,
     ts: now,
     launchedTs: args["launched-ts"] || (status === "launched" ? now : undefined),
     ackTs: args["ack-ts"] || (status === "acknowledged" ? now : undefined),
     completedTs: args["completed-ts"] || (status === "completed" ? now : undefined),
     endTs: TERMINAL.has(status) ? now : undefined,
-    schemaVersion: LEDGER_SCHEMA_VERSION
+    schemaVersion: LEDGER_SCHEMA_VERSION,
+    allowParallel: args["allow-parallel"] === true ? true : undefined
+  };
+}
+
+async function readDelegationLedgerEntries(root) {
+  try {
+    const raw = await fs.readFile(path.join(root, RUNTIME_ROOT, "state", "delegation-log.json"), "utf8");
+    const parsed = JSON.parse(raw);
+    if (parsed && Array.isArray(parsed.entries)) return parsed.entries;
+  } catch {
+    // empty / missing ledger is fine for dedup + monotonicity checks
+  }
+  return [];
+}
+
+// keep in sync with findActiveSpanForPair / DispatchDuplicateError in src/delegation.ts
+function findActiveSpanForPairInline(stage, agent, runId, 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;
+    // 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)) {
+      latestBySpan.set(entry.spanId, entry);
+    }
+  }
+  for (const entry of latestBySpan.values()) {
+    if (ACTIVE_STATUSES.has(entry.status)) return entry;
+  }
+  return null;
+}
+
+function enforceDispatchDedupInline(stamped, priorEntries, args) {
+  if (stamped.status !== "scheduled") return null;
+  if (args["allow-parallel"] === true) return null;
+  const existing = findActiveSpanForPairInline(
+    stamped.stage,
+    stamped.agent,
+    stamped.runId,
+    priorEntries
+  );
+  if (!existing || existing.spanId === stamped.spanId) return null;
+  if (typeof args.supersede === "string" && args.supersede.length > 0) {
+    if (args.supersede !== existing.spanId) {
+      return {
+        kind: "supersede-mismatch",
+        details: {
+          requested: args.supersede,
+          actualActiveSpanId: existing.spanId,
+          stage: stamped.stage,
+          agent: stamped.agent
+        }
+      };
+    }
+    return { kind: "supersede", existing };
+  }
+  return {
+    kind: "error",
+    details: {
+      existingSpanId: existing.spanId,
+      existingStatus: existing.status,
+      newSpanId: stamped.spanId,
+      pair: { stage: stamped.stage, agent: stamped.agent },
+      hint: "pass --supersede=" + existing.spanId + " to close the previous span as stale, or --allow-parallel to record both as concurrent"
+    }
   };
 }
 
@@ -490,7 +616,32 @@ async function persistEntry(root, runId, clean, event, options = {}) {
     await releaseDelegationLogLock(lockDir);
   }
 
-  const active = ledger.entries.filter((entry) => ["scheduled", "launched", "acknowledged"].includes(entry.status));
+  // keep in sync with computeActiveSubagents in src/delegation.ts
+  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 ledger.entries) {
+    if (!entry || typeof entry !== "object" || typeof entry.spanId !== "string" || entry.spanId.length === 0) continue;
+    const existing = latestBySpan.get(entry.spanId);
+    if (!existing) {
+      latestBySpan.set(entry.spanId, entry);
+      continue;
+    }
+    if (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);
+  }
+  active.sort((a, b) => {
+    const aKey = a.startTs || a.ts || "";
+    const bKey = b.startTs || b.ts || "";
+    if (aKey === bKey) return 0;
+    return aKey < bKey ? -1 : 1;
+  });
   await fs.writeFile(path.join(stateDir, "subagents.json"), JSON.stringify({ active, updatedAt: event.eventTs }, null, 2) + "\\n", { encoding: "utf8", mode: 0o600 });
 }
 
@@ -814,9 +965,61 @@ async function main() {
   }
 
   const status = args.status;
-  const row = buildRow(args, status, runId, now);
+  const priorLedger = await readDelegationLedgerEntries(root);
+  const priorForSpan = priorLedger.filter((e) => e && e.spanId === args["span-id"]);
+  const inheritedStartTs = priorForSpan
+    .map((e) => e.startTs)
+    .filter((ts) => typeof ts === "string" && ts.length > 0)
+    .sort()[0];
+  // When no prior row exists, fall back to the earliest user-supplied
+  // event timestamp so the monotonic validator never sees the row write
+  // time overshoot the real event timestamps.
+  const lifecycleCandidates = [
+    inheritedStartTs,
+    args["launched-ts"],
+    args["ack-ts"],
+    args["completed-ts"],
+    now
+  ].filter((value) => typeof value === "string" && value.length > 0);
+  const spanStartTs = inheritedStartTs ||
+    lifecycleCandidates.reduce((min, candidate) => (candidate < min ? candidate : min), now);
+  const row = buildRow(args, status, runId, now, { spanStartTs });
   const clean = Object.fromEntries(Object.entries(row).filter(([, value]) => value !== undefined));
   const event = { ...clean, event: status, eventTs: now };
+
+  const violation = validateMonotonicTimestampsInline(clean, priorLedger);
+  if (violation) {
+    emitErrorJson("delegation_timestamp_non_monotonic", violation, json);
+    return;
+  }
+  const dedupViolation = enforceDispatchDedupInline(clean, priorLedger, args);
+  if (dedupViolation) {
+    if (dedupViolation.kind === "supersede") {
+      const stalenessTs = new Date(new Date(now).getTime() - 1).toISOString();
+      const staleRow = {
+        stage: dedupViolation.existing.stage,
+        agent: dedupViolation.existing.agent,
+        mode: dedupViolation.existing.mode,
+        status: "stale",
+        spanId: dedupViolation.existing.spanId,
+        runId,
+        startTs: dedupViolation.existing.startTs || stalenessTs,
+        ts: stalenessTs,
+        endTs: stalenessTs,
+        supersededBy: clean.spanId,
+        schemaVersion: LEDGER_SCHEMA_VERSION
+      };
+      const staleEvent = { ...staleRow, event: "stale", eventTs: stalenessTs };
+      await persistEntry(root, runId, staleRow, staleEvent);
+    } else if (dedupViolation.kind === "error") {
+      emitErrorJson("dispatch_duplicate", dedupViolation.details, json);
+      return;
+    } else if (dedupViolation.kind === "supersede-mismatch") {
+      emitErrorJson("dispatch_supersede_mismatch", dedupViolation.details, json);
+      return;
+    }
+  }
+
   await persistEntry(root, runId, clean, event);
   process.stdout.write(JSON.stringify({ ok: true, event }, null, 2) + "\\n");
 }

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));