cclaw-cli 7.4.0 → 7.6.0

package/dist/artifact-linter/tdd.js

@@ -1,12 +1,18 @@
 import fs from "node:fs/promises";
 import path from "node:path";
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
 import { loadTddReadySlicePool, readDelegationLedger, readDelegationEvents, selectReadySlices } from "../delegation.js";
+import { resolveArtifactPath as resolveStageArtifactPath } from "../artifact-paths.js";
+import { exists } from "../fs-utils.js";
 import { mergeParallelWaveDefinitions, parseParallelExecutionPlanWaves, parseWavePlanDirectory } from "../internal/plan-split-waves.js";
-import { evaluateInvestigationTrace, sectionBodyByName } from "./shared.js";
+import { compareSliceIds } from "../util/slice-id.js";
+import { extractAcceptanceCriterionIdsFromMarkdown, extractH2Sections, evaluateInvestigationTrace, sectionBodyByName } from "./shared.js";
 const SLICE_SUMMARY_START = "<!-- auto-start: tdd-slice-summary -->";
 const SLICE_SUMMARY_END = "<!-- auto-end: tdd-slice-summary -->";
 const SLICES_INDEX_START = "<!-- auto-start: slices-index -->";
 const SLICES_INDEX_END = "<!-- auto-end: slices-index -->";
+const execFileAsync = promisify(execFile);
 /**
  * TDD stage linter.
  *
@@ -351,6 +357,11 @@ export async function lintTddStage(ctx) {
     // simply means main-only mode (legacy fallback).
     const slicesDir = path.join(artifactsDir, "tdd-slices");
     const sliceFiles = await listSliceFiles(slicesDir);
+    const specAcceptanceIds = await readSpecAcceptanceCriteriaIds(projectRoot, ctx.track);
+    const specAcceptanceSet = new Set(specAcceptanceIds);
+    const slicesMissingCloses = [];
+    const slicesWithUnknownAcs = [];
+    let checkedSliceCards = 0;
     for (const sliceFile of sliceFiles) {
         const sliceId = sliceFile.sliceId;
         const requiredForSlice = slicesByEvents.has(sliceId) &&
@@ -376,6 +387,17 @@ export async function lintTddStage(ctx) {
         if (!/^##\s+Learnings\b/imu.test(content)) {
             issues.push("missing `## Learnings` section");
         }
+        checkedSliceCards += 1;
+        const closesIds = extractSliceCardClosedAcceptanceCriteria(content);
+        if (closesIds.length === 0) {
+            slicesMissingCloses.push(sliceId);
+        }
+        else if (specAcceptanceSet.size > 0) {
+            const unknown = closesIds.filter((acId) => !specAcceptanceSet.has(acId));
+            if (unknown.length > 0) {
+                slicesWithUnknownAcs.push(`${sliceId}: ${unknown.join(", ")}`);
+            }
+        }
         findings.push({
             section: `tdd_slice_file:${sliceId}`,
             required: requiredForSlice,
@@ -386,6 +408,34 @@ export async function lintTddStage(ctx) {
                 : `tdd-slices/${path.basename(sliceFile.absPath)}: ${issues.join(", ")}.`
         });
     }
+    const closesRequired = checkedSliceCards > 0;
+    const closesGatePassed = !closesRequired
+        ? true
+        : slicesMissingCloses.length === 0 &&
+            slicesWithUnknownAcs.length === 0;
+    findings.push({
+        section: "tdd_slice_closes_ac",
+        required: true,
+        rule: "Every `tdd-slices/S-<id>.md` card must include `Closes: AC-N` links (comma-separated allowed) that reference real spec AC ids.",
+        found: closesGatePassed,
+        details: !closesRequired
+            ? "No `tdd-slices/S-*.md` slice cards found yet; `Closes: AC-N` check is idle."
+            : slicesMissingCloses.length > 0
+                ? `Slice card(s) missing \`Closes: AC-N\`: ${slicesMissingCloses.join(", ")}.`
+                : slicesWithUnknownAcs.length > 0
+                    ? `Slice card(s) reference unknown AC ids: ${slicesWithUnknownAcs.join(" | ")}.`
+                    : specAcceptanceSet.size === 0
+                        ? `All ${checkedSliceCards} slice card(s) include Closes links; spec AC list unavailable for strict ID cross-check.`
+                        : `All ${checkedSliceCards} slice card(s) include valid Closes links to spec AC ids.`
+    });
+    const orphanCheck = await evaluateSliceNoOrphanChanges(projectRoot, activeRunEntries);
+    findings.push({
+        section: "slice_no_orphan_changes",
+        required: true,
+        rule: "On slice phase=doc, there must be no staged/unstaged changes outside the slice `claimedPaths` (worktree root when present, otherwise project root).",
+        found: orphanCheck.ok,
+        details: orphanCheck.details
+    });
     // Auto-render the slice summary inside `06-tdd.md` between markers.
     // Idempotent — content outside the markers is preserved. Skipped
     // entirely when there is nothing to render, so legacy artifacts (no
@@ -460,12 +510,162 @@ async function listSliceFiles(slicesDir) {
             continue;
         files.push({ sliceId: match[1], absPath: path.join(slicesDir, name) });
     }
-    files.sort((a, b) => (a.sliceId < b.sliceId ? -1 : a.sliceId > b.sliceId ? 1 : 0));
+    files.sort((a, b) => compareSliceIds(a.sliceId, b.sliceId));
     return files;
 }
 function escapeForRegex(value) {
     return value.replace(/[.*+?^${}()|[\]\\]/gu, "\\$&");
 }
+function normalizePathLike(value) {
+    const slashes = value.replace(/\\/gu, "/");
+    const withoutDot = slashes.replace(/^\.\//u, "");
+    return withoutDot.replace(/\/+$/u, "");
+}
+function parsePorcelainPaths(raw) {
+    const out = [];
+    for (const line of raw.split(/\r?\n/gu)) {
+        const trimmed = line.trimEnd();
+        if (trimmed.length < 4)
+            continue;
+        const status = trimmed.slice(0, 2);
+        if (status === "??") {
+            const p = normalizePathLike(trimmed.slice(3).trim());
+            if (p.length > 0)
+                out.push(p);
+            continue;
+        }
+        let p = trimmed.slice(3).trim();
+        const renameIdx = p.indexOf(" -> ");
+        if (renameIdx >= 0) {
+            p = p.slice(renameIdx + 4);
+        }
+        p = normalizePathLike(p.replace(/^"/u, "").replace(/"$/u, ""));
+        if (p.length > 0)
+            out.push(p);
+    }
+    return [...new Set(out)];
+}
+async function gitChangedPaths(cwd) {
+    const { stdout } = await execFileAsync("git", ["status", "--porcelain", "-uall"], { cwd });
+    return parsePorcelainPaths(stdout);
+}
+function matchesClaimedPath(changedPath, claimedPaths) {
+    const changed = normalizePathLike(changedPath);
+    return claimedPaths.some((rawClaimed) => {
+        const claimed = normalizePathLike(rawClaimed);
+        if (claimed.length === 0)
+            return false;
+        if (changed === claimed)
+            return true;
+        return changed.startsWith(`${claimed}/`);
+    });
+}
+function extractSliceCardClosedAcceptanceCriteria(content) {
+    const ids = new Set();
+    for (const match of content.matchAll(/^\s*(?:[-*]\s*)?closes\s*:\s*(.+)$/gimu)) {
+        const tail = match[1] ?? "";
+        for (const id of extractAcceptanceCriterionIdsFromMarkdown(tail)) {
+            ids.add(id);
+        }
+    }
+    return [...ids];
+}
+async function readSpecAcceptanceCriteriaIds(projectRoot, track) {
+    const specArtifact = await resolveStageArtifactPath("spec", {
+        projectRoot,
+        track,
+        intent: "read"
+    });
+    if (!(await exists(specArtifact.absPath))) {
+        return [];
+    }
+    try {
+        const specRaw = await fs.readFile(specArtifact.absPath, "utf8");
+        const specSections = extractH2Sections(specRaw);
+        const acceptanceBody = sectionBodyByName(specSections, "Acceptance Criteria") ?? specRaw;
+        return extractAcceptanceCriterionIdsFromMarkdown(acceptanceBody);
+    }
+    catch {
+        return [];
+    }
+}
+function resolveClaimedPathsForDocRow(row, allRows) {
+    const fromRow = Array.isArray(row.claimedPaths) ? row.claimedPaths : [];
+    if (fromRow.length > 0) {
+        return [...new Set(fromRow.map((value) => normalizePathLike(value)).filter((value) => value.length > 0))];
+    }
+    const fromSpan = allRows
+        .filter((entry) => entry.spanId === row.spanId &&
+        Array.isArray(entry.claimedPaths) &&
+        entry.claimedPaths.length > 0)
+        .flatMap((entry) => entry.claimedPaths);
+    return [...new Set(fromSpan.map((value) => normalizePathLike(value)).filter((value) => value.length > 0))];
+}
+async function resolveWorktreeCwdForDocRow(projectRoot, row, allRows) {
+    const candidates = [
+        typeof row.worktreePath === "string" ? row.worktreePath.trim() : "",
+        ...allRows
+            .filter((entry) => entry.spanId === row.spanId)
+            .map((entry) => (typeof entry.worktreePath === "string" ? entry.worktreePath.trim() : ""))
+    ].filter((value) => value.length > 0);
+    for (const candidateRaw of candidates) {
+        const candidateAbs = path.isAbsolute(candidateRaw)
+            ? candidateRaw
+            : path.join(projectRoot, candidateRaw);
+        if (await exists(candidateAbs)) {
+            return candidateAbs;
+        }
+    }
+    return projectRoot;
+}
+export async function evaluateSliceNoOrphanChanges(projectRoot, rows) {
+    if (!(await exists(path.join(projectRoot, ".git")))) {
+        return {
+            ok: true,
+            details: "No .git directory detected; orphan-change check skipped."
+        };
+    }
+    const docRows = rows.filter((entry) => entry.stage === "tdd" &&
+        entry.agent === "slice-builder" &&
+        entry.status === "completed" &&
+        entry.phase === "doc");
+    if (docRows.length === 0) {
+        return {
+            ok: true,
+            details: "No completed phase=doc rows found for the active run."
+        };
+    }
+    const missingClaimedPaths = [];
+    const driftRows = [];
+    for (const row of docRows) {
+        const claimedPaths = resolveClaimedPathsForDocRow(row, rows);
+        const rowKey = `${row.sliceId ?? "unknown-slice"}@${row.spanId ?? "unknown-span"}`;
+        if (claimedPaths.length === 0) {
+            missingClaimedPaths.push(rowKey);
+            continue;
+        }
+        const cwd = await resolveWorktreeCwdForDocRow(projectRoot, row, rows);
+        const changedPaths = await gitChangedPaths(cwd);
+        const driftPaths = changedPaths.filter((changedPath) => !matchesClaimedPath(changedPath, claimedPaths));
+        if (driftPaths.length > 0) {
+            driftRows.push(`${rowKey}: ${driftPaths.join(", ")}`);
+        }
+    }
+    if (missingClaimedPaths.length > 0 || driftRows.length > 0) {
+        const parts = [];
+        if (missingClaimedPaths.length > 0) {
+            parts.push(`doc row(s) missing claimedPaths: ${missingClaimedPaths.join(", ")}`);
+        }
+        if (driftRows.length > 0) {
+            parts.push(`orphan working-tree changes detected: ${driftRows.join(" | ")}`);
+        }
+        return { ok: false, details: parts.join(". ") };
+    }
+    return {
+        ok: true,
+        details: `Checked ${docRows.length} doc row(s); no orphan changes escaped claimedPaths.`
+    };
+}
 function groupBySlice(entries) {
     const grouped = new Map();
     for (const entry of entries) {

package/dist/config.d.ts

@@ -1,9 +1,11 @@
-import type { CclawConfig, FlowTrack, HarnessId, LanguageRulePack, TddCommitMode, TddIsolationMode } from "./types.js";
+import type { CclawConfig, FlowTrack, HarnessId, LanguageRulePack, LockfileTwinPolicy, TddCommitMode, TddIsolationMode } from "./types.js";
 export declare const TDD_COMMIT_MODES: readonly ["managed-per-slice", "agent-required", "checkpoint-only", "off"];
 export declare const DEFAULT_TDD_COMMIT_MODE: TddCommitMode;
 export declare const TDD_ISOLATION_MODES: readonly ["worktree", "in-place", "auto"];
 export declare const DEFAULT_TDD_ISOLATION_MODE: TddIsolationMode;
 export declare const DEFAULT_TDD_WORKTREE_ROOT = ".cclaw/worktrees";
+export declare const LOCKFILE_TWIN_POLICIES: readonly ["auto-include", "auto-revert", "strict-fence"];
+export declare const DEFAULT_LOCKFILE_TWIN_POLICY: LockfileTwinPolicy;
 export declare const DEFAULT_TDD_TEST_PATH_PATTERNS: readonly string[];
 export declare const DEFAULT_TDD_TEST_GLOBS: readonly string[];
 export declare const DEFAULT_TDD_PRODUCTION_PATH_PATTERNS: readonly string[];
@@ -24,6 +26,7 @@ export declare function createDefaultConfig(harnesses?: HarnessId[], _defaultTra
 export declare function resolveTddCommitMode(config: Pick<CclawConfig, "tdd"> | null | undefined): TddCommitMode;
 export declare function resolveTddIsolationMode(config: Pick<CclawConfig, "tdd"> | null | undefined): TddIsolationMode;
 export declare function resolveTddWorktreeRoot(config: Pick<CclawConfig, "tdd"> | null | undefined): string;
+export declare function resolveLockfileTwinPolicy(config: Pick<CclawConfig, "tdd"> | null | undefined): LockfileTwinPolicy;
 export declare function detectLanguageRulePacks(_projectRoot: string): Promise<LanguageRulePack[]>;
 export declare function readConfig(projectRoot: string, _options?: ReadConfigOptions): Promise<CclawConfig>;
 export interface WriteConfigOptions {

package/dist/config.js

@@ -20,6 +20,9 @@ export const TDD_ISOLATION_MODES = ["worktree", "in-place", "auto"];
 const TDD_ISOLATION_MODE_SET = new Set(TDD_ISOLATION_MODES);
 export const DEFAULT_TDD_ISOLATION_MODE = "worktree";
 export const DEFAULT_TDD_WORKTREE_ROOT = `${RUNTIME_ROOT}/worktrees`;
+export const LOCKFILE_TWIN_POLICIES = ["auto-include", "auto-revert", "strict-fence"];
+const LOCKFILE_TWIN_POLICY_SET = new Set(LOCKFILE_TWIN_POLICIES);
+export const DEFAULT_LOCKFILE_TWIN_POLICY = "auto-include";
 // Kept for runtime modules that use these defaults directly.
 export const DEFAULT_TDD_TEST_PATH_PATTERNS = [
     "**/*.test.*",
@@ -68,7 +71,8 @@ export function createDefaultConfig(harnesses = DEFAULT_HARNESSES, _defaultTrack
         tdd: {
             commitMode: DEFAULT_TDD_COMMIT_MODE,
             isolationMode: DEFAULT_TDD_ISOLATION_MODE,
-            worktreeRoot: DEFAULT_TDD_WORKTREE_ROOT
+            worktreeRoot: DEFAULT_TDD_WORKTREE_ROOT,
+            lockfileTwinPolicy: DEFAULT_LOCKFILE_TWIN_POLICY
         }
     };
 }
@@ -93,6 +97,13 @@ export function resolveTddWorktreeRoot(config) {
     }
     return DEFAULT_TDD_WORKTREE_ROOT;
 }
+export function resolveLockfileTwinPolicy(config) {
+    const raw = config?.tdd?.lockfileTwinPolicy;
+    if (typeof raw === "string" && LOCKFILE_TWIN_POLICY_SET.has(raw)) {
+        return raw;
+    }
+    return DEFAULT_LOCKFILE_TWIN_POLICY;
+}
 function assertOnlySupportedKeys(parsed, fullPath) {
     const unknownKeys = Object.keys(parsed).filter((key) => !ALLOWED_CONFIG_KEYS.has(key));
     if (unknownKeys.length === 0)
@@ -153,6 +164,7 @@ export async function readConfig(projectRoot, _options = {}) {
     const rawCommitMode = parsedTdd.commitMode;
     const rawIsolationMode = parsedTdd.isolationMode;
     const rawWorktreeRoot = parsedTdd.worktreeRoot;
+    const rawLockfileTwinPolicy = parsedTdd.lockfileTwinPolicy;
     if (rawCommitMode !== undefined &&
         (typeof rawCommitMode !== "string" || !TDD_COMMIT_MODE_SET.has(rawCommitMode))) {
         throw configValidationError(fullPath, `"tdd.commitMode" must be one of: ${TDD_COMMIT_MODES.join(", ")}`);
@@ -165,6 +177,10 @@ export async function readConfig(projectRoot, _options = {}) {
         (typeof rawWorktreeRoot !== "string" || rawWorktreeRoot.trim().length === 0)) {
         throw configValidationError(fullPath, `"tdd.worktreeRoot" must be a non-empty string when provided`);
     }
+    if (rawLockfileTwinPolicy !== undefined &&
+        (typeof rawLockfileTwinPolicy !== "string" || !LOCKFILE_TWIN_POLICY_SET.has(rawLockfileTwinPolicy))) {
+        throw configValidationError(fullPath, `"tdd.lockfileTwinPolicy" must be one of: ${LOCKFILE_TWIN_POLICIES.join(", ")}`);
+    }
     const commitMode = typeof rawCommitMode === "string"
         ? rawCommitMode
         : DEFAULT_TDD_COMMIT_MODE;
@@ -174,6 +190,9 @@ export async function readConfig(projectRoot, _options = {}) {
     const worktreeRoot = typeof rawWorktreeRoot === "string" && rawWorktreeRoot.trim().length > 0
         ? rawWorktreeRoot.trim()
         : DEFAULT_TDD_WORKTREE_ROOT;
+    const lockfileTwinPolicy = typeof rawLockfileTwinPolicy === "string"
+        ? rawLockfileTwinPolicy
+        : DEFAULT_LOCKFILE_TWIN_POLICY;
     return {
         version,
         flowVersion,
@@ -181,7 +200,8 @@ export async function readConfig(projectRoot, _options = {}) {
         tdd: {
             commitMode,
             isolationMode,
-            worktreeRoot
+            worktreeRoot,
+            lockfileTwinPolicy
         }
     };
 }
@@ -193,7 +213,8 @@ export async function writeConfig(projectRoot, config, _options = {}) {
         tdd: {
             commitMode: resolveTddCommitMode(config),
             isolationMode: resolveTddIsolationMode(config),
-            worktreeRoot: resolveTddWorktreeRoot(config)
+            worktreeRoot: resolveTddWorktreeRoot(config),
+            lockfileTwinPolicy: resolveLockfileTwinPolicy(config)
         }
     };
     await writeFileSafe(configPath(projectRoot), stringify(serialisable));

package/dist/content/core-agents.js

@@ -165,6 +165,21 @@ export function sliceBuilderProtocol() {
         "- Honor every `delegation-record`/`delegation-record.mjs` row shape the controller requests so artifact linters keep passing.",
         "- The umbrella `slice-completed` row ties RED/GREEN/REFACTOR/DOC timestamps to your builder span.",
         "",
+        "### Event → status flag table (7.6.0 — phase-event status validation)",
+        "",
+        "Phase-level granularity is only meaningful on terminal outcomes. The dispatch-level ack (no `--phase`) is the controller saying \"I see the dispatch surface back\" — it stays on `--status=acknowledged`. Phase events MUST use `--status=completed` or `--status=failed`. The hook rejects mismatches with `phase_event_requires_completed_or_failed_status` (exit 2) and prints a corrected-command hint.",
+        "",
+        "| event | --phase | --status |",
+        "|---|---|---|",
+        "| dispatch ack (controller-side) | (none) | `acknowledged` |",
+        "| RED watched-fail captured | `red` | `completed` |",
+        "| GREEN test passes | `green` | `completed` (with `--refactor-outcome=inline\\|deferred\\|...`) |",
+        "| REFACTOR landed | `refactor` | `completed` |",
+        "| DOC card landed (triggers slice-commit) | `doc` | `completed` |",
+        "| BLOCKED / unrecoverable | (any phase reached) | `failed` |",
+        "",
+        "Common slip: recording every phase event with `--status=acknowledged` (e.g. `--phase=doc --status=acknowledged`). The event row is silently dropped from terminal-phase aggregations, `slice-commit.mjs` never fires (it only triggers on `phase=doc status=completed`), and `wave-status` reports the slice as phantom-open. Recovery requires raw backfill commands. The 7.6.0 hook validator forbids this configuration up front.",
+        "",
         "### Streaming output contract",
         "- Emit one JSON line to stdout per completed phase: `{\"event\":\"phase-completed\",\"stage\":\"tdd\",\"sliceId\":\"S-<n>\",\"phase\":\"<red|green|refactor|refactor-deferred|doc>\",\"spanId\":\"<span>\",\"runId\":\"<run>\",\"ts\":\"<iso>\"}`.",
         "- For `phase=green` with inline/deferred refactor folding, include `refactorOutcome.mode` in the same JSON line so live controllers can close the slice without waiting for file sync.",

package/dist/content/hooks.js

@@ -1489,6 +1489,43 @@ async function main() {
     emitProblems(problems, json, 2);
     return;
   }
+  // 7.6.0 — phase-event status validation.
+  // \`--phase=<phase>\` carries phase-level granularity (RED/GREEN/REFACTOR/DOC
+  // outcomes). It is only meaningful on terminal statuses
+  // (\`completed\` or \`failed\`). The dispatch-level ack (no phase) keeps
+  // \`--status=acknowledged\`. Refuse acknowledged/launched/scheduled/waived/stale
+  // rows that carry a phase so phantom-open slices cannot be recorded.
+  if (
+    typeof args.phase === "string" &&
+    args.phase.length > 0 &&
+    args.status !== "completed" &&
+    args.status !== "failed"
+  ) {
+    const sliceFlag = typeof args.slice === "string" && args.slice.length > 0
+      ? "--slice=" + args.slice + " "
+      : "";
+    const spanFlag = typeof args["span-id"] === "string" && args["span-id"].length > 0
+      ? "--span-id=" + args["span-id"] + " "
+      : "";
+    const correctedCommandHint =
+      "node .cclaw/hooks/delegation-record.mjs --stage=" + (args.stage || "<stage>") +
+      " --agent=" + (args.agent || "<agent>") +
+      " --mode=" + (args.mode || "mandatory") +
+      " --status=completed --phase=" + args.phase +
+      " " + sliceFlag + spanFlag +
+      '--evidence-ref="<phase outcome>"';
+    emitErrorJson(
+      "phase_event_requires_completed_or_failed_status",
+      {
+        phase: args.phase,
+        status: args.status,
+        spanId: args["span-id"] || "unknown",
+        correctedCommandHint
+      },
+      json
+    );
+    return;
+  }
   if (args.phase === "refactor-deferred") {
     const rationaleQuality = validateDeferredRationaleInline(args["refactor-rationale"], args);
     if (rationaleQuality !== "ok") {

package/dist/content/stage-schema.js

@@ -258,6 +258,7 @@ const REQUIRED_GATE_IDS = {
         "design_test_and_perf_defined"
     ],
     spec: [
+        "spec_ac_ids_present",
         "spec_acceptance_measurable",
         "spec_testability_confirmed",
         "spec_assumptions_surfaced",
@@ -271,6 +272,7 @@ const REQUIRED_GATE_IDS = {
         "plan_execution_posture_recorded",
         "plan_parallel_exec_full_coverage",
         "plan_wave_paths_disjoint",
+        "plan_module_introducing_slice_wires_root",
         "plan_wait_for_confirm"
     ],
     tdd: (track) => [
@@ -283,6 +285,8 @@ const REQUIRED_GATE_IDS = {
         "tdd_iron_law_acknowledged",
         "tdd_watched_red_observed",
         "tdd_slice_cycle_complete",
+        "tdd_slice_closes_ac",
+        "slice_no_orphan_changes",
         "tdd_docs_drift_check",
         ...(track === "quick" ? [] : ["tdd_traceable_to_plan"])
     ],
@@ -297,6 +301,7 @@ const REQUIRED_GATE_IDS = {
         "ship_review_verdict_valid",
         "ship_preflight_passed",
         "ship_rollback_plan_ready",
+        "ship_all_acceptance_criteria_have_commits",
         "ship_finalization_executed"
     ]
 };
@@ -341,7 +346,7 @@ const REQUIRED_ARTIFACT_SECTIONS = {
         "Verification Ladder"
     ],
     review: ["Review Evidence Scope", "Changed-File Coverage", "Layer 1 Verdict", "Review Findings Contract", "Severity Summary", "Final Verdict"],
-    ship: ["Preflight Results", "Release Notes", "Rollback Plan", "Finalization"]
+    ship: ["Preflight Results", "Release Notes", "Traceability Matrix", "Rollback Plan", "Finalization"]
 };
 function resolveRequiredGateIds(stage, track) {
     const raw = REQUIRED_GATE_IDS[stage];

package/dist/content/stages/plan.js

@@ -85,6 +85,7 @@ export const PLAN = {
             { id: "plan_execution_posture_recorded", description: "Execution posture is recorded before implementation handoff." },
             { id: "plan_parallel_exec_full_coverage", description: "Every T-NNN task in `## Task List` (other than spikes/explicitly-deferred) is assigned to at least one slice inside the `<!-- parallel-exec-managed-start -->` block; TDD cannot fan out work that the plan never authored as waves." },
             { id: "plan_wave_paths_disjoint", description: "Within each authored wave, slice `claimedPaths` remain disjoint so `wave-fanout` can dispatch safely without overlap conflicts." },
+            { id: "plan_module_introducing_slice_wires_root", description: "When a slice introduces a new module file, the stack-adapter's wiring aggregator (Rust `lib.rs`, Python `__init__.py`, Node-TS barrel when present) must appear in the same slice's claim or a transitive predecessor's claim so RED can be expressed." },
             { id: "plan_wait_for_confirm", description: "Execution blocked until explicit user confirmation." }
         ],
         requiredEvidence: [

package/dist/content/stages/ship.js

@@ -45,6 +45,7 @@ export const SHIP = {
             "Merge-base detection (git only) — identify the correct base branch. Run `git merge-base HEAD <base>`. If the base has diverged significantly, flag for rebase-first.",
             "Re-run tests on merged result — if merging locally, run the full test suite AFTER the merge, not just before. Post-merge failures are common.",
             "Generate release notes — summarize what changed, why, and what it affects. Reference spec criteria. Include: breaking changes, new dependencies, migration steps if any.",
+            "Assemble acceptance traceability matrix — for each spec AC-N, list mapped slice IDs and at least one managed commit proving closure.",
             "Write rollback plan — trigger conditions (what tells you it is broken), rollback steps (exact commands/git operations), and verification (how to confirm rollback worked).",
             "Load utility skills — `verification-before-completion` for fresh evidence and `finishing-a-development-branch` for finalization workflow.",
             "Monitoring checklist — what should be watched after deploy? Error rates, latency, key business metrics. If no monitoring exists, flag it as a risk.",
@@ -74,11 +75,13 @@ export const SHIP = {
             { id: "ship_review_verdict_valid", description: "Review verdict is APPROVED or APPROVED_WITH_CONCERNS." },
             { id: "ship_preflight_passed", description: "Preflight checks passed or exceptions documented and approved." },
             { id: "ship_rollback_plan_ready", description: "Rollback trigger, steps, and verification are documented." },
+            { id: "ship_all_acceptance_criteria_have_commits", description: "Every spec AC-N has at least one `Closes: AC-N` slice mapping and a managed slice commit in the active run." },
             { id: "ship_finalization_executed", description: "Selected finalization action was executed and verified." }
         ],
         requiredEvidence: [
             "Artifact written to `.cclaw/artifacts/08-ship.md`.",
             "Release notes section is complete.",
+            "Traceability Matrix maps each spec AC-N to slice IDs and managed commit evidence.",
             "Rollback section includes trigger conditions, steps, and verification.",
             "Finalization section shows exactly one selected enum token.",
             "Victory Detector result documented: review verdict valid, preflight fresh, rollback ready, finalization enum selected, and execution result present."
@@ -115,6 +118,7 @@ export const SHIP = {
             { section: "Upstream Handoff", required: false, validationRule: "Summarizes review/tdd decisions, constraints, open questions, and explicit drift before finalization." },
             { section: "Preflight Results", required: true, validationRule: "Build, test, lint, type-check results captured with fresh output. Exceptions documented if any." },
             { section: "Release Notes", required: true, validationRule: "What changed, why, impact. References spec criteria. Breaking changes flagged." },
+            { section: "Traceability Matrix", required: true, validationRule: "One row per spec AC-N with mapped slice IDs (`S-<id>`), managed commit evidence (`^S-<id>/` subject), and coverage status." },
             { section: "Rollback Plan", required: true, validationRule: "Trigger conditions, rollback steps (exact commands), verification steps." },
             { section: "Monitoring", required: false, validationRule: "If applicable: what metrics/logs to watch post-deploy. Risk note if no monitoring." },
             { section: "Finalization", required: true, validationRule: "Exactly one finalization enum token selected (FINALIZE_MERGE_LOCAL | FINALIZE_OPEN_PR | FINALIZE_KEEP_BRANCH | FINALIZE_DISCARD_BRANCH | FINALIZE_NO_VCS). Execution result documented. Worktree cleaned if applicable." },

package/dist/content/stages/spec.js

@@ -68,6 +68,7 @@ export const SPEC = {
             "Write spec artifact and request approval."
         ],
         requiredGates: [
+            { id: "spec_ac_ids_present", description: "Acceptance Criteria rows include stable `AC-N` identifiers." },
             { id: "spec_acceptance_measurable", description: "Acceptance criteria are measurable and observable." },
             { id: "spec_testability_confirmed", description: "Each criterion has a described test method." },
             { id: "spec_assumptions_surfaced", description: "Assumptions were explicitly reviewed with source/confidence, validation path, and disposition before approval." },

package/dist/content/stages/tdd.js

@@ -76,6 +76,8 @@ export const TDD = {
             { id: "tdd_iron_law_acknowledged", description: "Iron Law acknowledgement is explicit (`Acknowledged: yes`) before implementation proceeds." },
             { id: "tdd_watched_red_observed", description: "Watched-RED Proof records at least one observed failing test with ISO timestamp evidence." },
             { id: "tdd_slice_cycle_complete", description: "Vertical Slice Cycle records RED, GREEN, and REFACTOR phases per active slice." },
+            { id: "tdd_slice_closes_ac", description: "Every `tdd-slices/S-<id>.md` card includes valid `Closes: AC-N` links to spec acceptance criteria." },
+            { id: "slice_no_orphan_changes", description: "After `phase=doc`, working tree changes remain inside the slice claimedPaths boundary (worktree root when present)." },
             { id: "tdd_traceable_to_plan", description: "Change traceability to plan slice is explicit." },
             { id: "tdd_docs_drift_check", description: "When public API/config/CLI surfaces change, docs drift is addressed via a completed doc-updater pass." }
         ],

package/dist/content/templates.js

@@ -1377,6 +1377,11 @@ ${renderBehaviorAnchorTemplateLine("ship")}
 ## Release Notes
 -
 
+## Traceability Matrix
+| AC ID | Slice ID(s) | Managed commit evidence | Coverage status |
+|---|---|---|---|
+| AC-1 | S-1 | \`abc1234 S-1/green: ...\` | covered |
+
 ## Structured PR Body
 > Required when selected option is \`OPEN_PR\`. The structure is universal — replace placeholder bullets with concrete content, do not introduce domain-specific subsections.
 

package/dist/delegation.d.ts

@@ -381,6 +381,45 @@ export declare class DispatchClaimedPathProtectedError extends Error {
  * offending path so the operator can fix the dispatch in one pass.
  */
 export declare function validateClaimedPathsNotProtected(stamped: DelegationEntry): void;
+/**
+ * Thrown by `appendDelegation` (and the inline `delegation-record.mjs`
+ * helper) when an event with a non-null `phase` is recorded with
+ * `status="acknowledged"`. Phase-level granularity only makes sense on
+ * terminal outcomes (`completed` or `failed`); the dispatch-level ACK
+ * (no phase) is the controller saying "I see the dispatch surface back".
+ *
+ * Motivated by hox W-08/S-41: the slice-builder agent recorded all four
+ * phase events with `--status=acknowledged`, which the helper silently
+ * accepted but `slice-commit.mjs` only fires on `phase=doc status=completed`.
+ * `wave-status` then saw the slice as phantom-open even though the
+ * worker had finished. Recovery required raw backfill commands.
+ *
+ * 7.6.0 makes the constraint explicit: pair `--phase=<phase>` with
+ * `--status=completed` (or `--status=failed`) and use
+ * `--status=acknowledged` only for the dispatch-level ack (no phase).
+ */
+export declare class PhaseEventRequiresTerminalStatusError extends Error {
+    readonly phase: string;
+    readonly status: DelegationStatus;
+    readonly spanId: string;
+    readonly correctedCommandHint: string;
+    constructor(params: {
+        phase: string;
+        status: DelegationStatus;
+        spanId: string;
+        correctedCommandHint: string;
+    });
+}
+/**
+ * Reject delegation rows where `phase` is set but `status` is not
+ * `completed` or `failed`. Acknowledged/launched/scheduled/waived/stale
+ * rows must NOT carry a phase — the phase-level lifecycle exists only
+ * to record terminal outcomes per phase (RED/GREEN/REFACTOR/DOC).
+ *
+ * Throws `PhaseEventRequiresTerminalStatusError`; the message includes
+ * an actionable corrected-command hint that the controller can paste.
+ */
+export declare function validatePhaseEventStatus(stamped: DelegationEntry): void;
 /**
  * Thrown by `appendDelegation` when a new `scheduled` span would open a
  * second TDD cycle for a slice that already has at least one closed span