cclaw-cli 7.4.0 → 7.5.0

package/dist/artifact-linter/plan.js

@@ -1,4 +1,4 @@
-import { evaluateInvestigationTrace, evaluateLayeredDocumentReviewStatus, extractAuthoredBody, headingPresent, sectionBodyByName, collectPatternHits, PLACEHOLDER_PATTERNS, extractDecisionIds, SCOPE_REDUCTION_PATTERNS } from "./shared.js";
+import { evaluateInvestigationTrace, evaluateLayeredDocumentReviewStatus, extractAcceptanceCriterionIdsFromMarkdown, extractAuthoredBody, extractH2Sections, headingPresent, sectionBodyByName, collectPatternHits, PLACEHOLDER_PATTERNS, extractDecisionIds, SCOPE_REDUCTION_PATTERNS } from "./shared.js";
 import { resolveArtifactPath as resolveStageArtifactPath } from "../artifact-paths.js";
 import { exists } from "../fs-utils.js";
 import { FORBIDDEN_PLACEHOLDER_TOKENS, CONFIDENCE_FINDING_REGEX_SOURCE } from "../content/skills.js";
@@ -8,6 +8,7 @@ import { PLAN_SPLIT_SMALL_PLAN_THRESHOLD, parseImplementationUnits, parseImpleme
 const PARALLEL_EXEC_MANAGED_START = "<!-- parallel-exec-managed-start -->";
 const PARALLEL_EXEC_MANAGED_END = "<!-- parallel-exec-managed-end -->";
 const TASK_ID_PATTERN = /\bT-\d{3}[a-z]?(?:\.\d{1,3})?\b/giu;
+const ACCEPTANCE_ID_PATTERN = /\bAC-\d+\b/giu;
 const PLAN_LANE_WHITELIST = new Set([
     "production",
     "test",
@@ -30,6 +31,21 @@ function extractTaskIds(body) {
     }
     return ids;
 }
+function extractAcceptanceTaskLinks(body) {
+    const links = [];
+    for (const line of body.split(/\r?\n/u)) {
+        const acIds = [...line.matchAll(ACCEPTANCE_ID_PATTERN)].map((match) => match[0].toUpperCase());
+        const taskIds = [...line.matchAll(TASK_ID_PATTERN)].map((match) => match[0]);
+        if (acIds.length === 0 || taskIds.length === 0)
+            continue;
+        for (const acId of acIds) {
+            for (const taskId of taskIds) {
+                links.push({ acId, taskId });
+            }
+        }
+    }
+    return links;
+}
 /**
  * Return the body between the parallel-exec managed comment markers, or
  * an empty string if the block is absent. The TDD wave parser uses the
@@ -190,6 +206,59 @@ export async function lintPlanStage(ctx) {
                 ? "No scope-reduction phrases detected in Task List."
                 : `Detected scope-reduction phrase(s) in Task List: ${reductionHits.join(", ")}.`
     });
+    const authoredTaskIds = extractTaskIds(taskListBody);
+    const acceptanceMappingBody = sectionBodyByName(sections, "Acceptance Mapping") ?? "";
+    const acTaskLinks = [
+        ...extractAcceptanceTaskLinks(taskListBody),
+        ...extractAcceptanceTaskLinks(acceptanceMappingBody)
+    ];
+    const mappedTaskToAcs = new Map();
+    const mappedAcToTasks = new Map();
+    for (const link of acTaskLinks) {
+        const taskSet = mappedTaskToAcs.get(link.taskId) ?? new Set();
+        taskSet.add(link.acId);
+        mappedTaskToAcs.set(link.taskId, taskSet);
+        const acSet = mappedAcToTasks.get(link.acId) ?? new Set();
+        acSet.add(link.taskId);
+        mappedAcToTasks.set(link.acId, acSet);
+    }
+    const tasksMissingAc = [...authoredTaskIds].filter((taskId) => !mappedTaskToAcs.has(taskId));
+    let specAcIds = [];
+    const specArtifact = await resolveStageArtifactPath("spec", {
+        projectRoot,
+        track,
+        intent: "read"
+    });
+    if (await exists(specArtifact.absPath)) {
+        try {
+            const specRaw = await fs.readFile(specArtifact.absPath, "utf8");
+            const specSections = extractH2Sections(specRaw);
+            const acceptanceBody = sectionBodyByName(specSections, "Acceptance Criteria") ?? specRaw;
+            specAcIds = extractAcceptanceCriterionIdsFromMarkdown(acceptanceBody);
+        }
+        catch {
+            specAcIds = [];
+        }
+    }
+    const acsMissingTask = specAcIds.filter((acId) => !mappedAcToTasks.has(acId));
+    const mappingFound = authoredTaskIds.size > 0 &&
+        tasksMissingAc.length === 0 &&
+        acsMissingTask.length === 0;
+    findings.push({
+        section: "plan_acceptance_mapped",
+        required: authoredTaskIds.size > 0,
+        rule: "Every T-NNN task must reference >=1 AC-N, and every AC-N from spec must be referenced by >=1 plan task.",
+        found: mappingFound,
+        details: authoredTaskIds.size === 0
+            ? "Task List has no T-NNN ids; acceptance mapping check skipped."
+            : tasksMissingAc.length > 0
+                ? `Task(s) missing AC mapping: ${tasksMissingAc.join(", ")}. Add AC-N references in Task List or Acceptance Mapping.`
+                : acsMissingTask.length > 0
+                    ? `Spec AC(s) missing task coverage: ${acsMissingTask.join(", ")}.`
+                    : specAcIds.length === 0
+                        ? `Mapped ${authoredTaskIds.size} task(s) to AC ids; spec artifact AC list is empty or unavailable.`
+                        : `Mapped ${authoredTaskIds.size} task(s) across ${specAcIds.length} spec AC(s).`
+    });
     // Universal Layer 2.5 structural checks (superpowers writing-plans + ce-plan).
     // Plan-wide placeholder scan (broader than Task List) using the
     // FORBIDDEN_PLACEHOLDER_TOKENS list shared with the cross-cutting block.

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

@@ -560,6 +560,7 @@ export declare const SCOPE_REDUCTION_PATTERNS: Array<{
 export declare function parseFrontmatter(markdown: string): ParsedFrontmatter;
 export declare function extractDecisionIds(text: string): string[];
 export declare function extractRequirementIdsFromMarkdown(text: string): string[];
+export declare function extractAcceptanceCriterionIdsFromMarkdown(text: string): string[];
 export declare function collectPatternHits(text: string, patterns: Array<{
     label: string;
     regex: RegExp;

package/dist/artifact-linter/shared.js

@@ -2002,6 +2002,11 @@ export function extractRequirementIdsFromMarkdown(text) {
     const ids = text.match(/\bR\d+\b/gu) ?? [];
     return [...new Set(ids)];
 }
+export function extractAcceptanceCriterionIdsFromMarkdown(text) {
+    const ids = text.match(/\bAC-\d+\b/giu) ?? [];
+    const normalized = ids.map((id) => id.toUpperCase());
+    return [...new Set(normalized)];
+}
 // Cross-stage decision traceability uses stable D-XX IDs which the
 // agent can edit safely without recomputing content hashes.
 export function collectPatternHits(text, patterns) {

package/dist/artifact-linter/ship.js

@@ -1,5 +1,121 @@
+import { execFile } from "node:child_process";
+import fs from "node:fs/promises";
+import path from "node:path";
+import { promisify } from "node:util";
 import { readDelegationLedger } from "../delegation.js";
-import { sectionBodyByName } from "./shared.js";
+import { resolveArtifactPath as resolveStageArtifactPath } from "../artifact-paths.js";
+import { exists } from "../fs-utils.js";
+import { extractAcceptanceCriterionIdsFromMarkdown, extractH2Sections, sectionBodyByName } from "./shared.js";
+import { readFlowState } from "../run-persistence.js";
+const execFileAsync = promisify(execFile);
+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];
+}
+function escapeForRegex(value) {
+    return value.replace(/[.*+?^${}()|[\]\\]/gu, "\\$&");
+}
+function entryTimestamp(entry) {
+    return entry.startTs ?? entry.ts ?? entry.launchedTs ?? entry.ackTs ?? entry.completedTs ?? entry.endTs ?? "";
+}
+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 sections = extractH2Sections(specRaw);
+        const acceptanceBody = sectionBodyByName(sections, "Acceptance Criteria") ?? specRaw;
+        return extractAcceptanceCriterionIdsFromMarkdown(acceptanceBody);
+    }
+    catch {
+        return [];
+    }
+}
+async function collectAcceptanceSlicesMap(tddSlicesDir) {
+    const map = new Map();
+    let names = [];
+    try {
+        names = await fs.readdir(tddSlicesDir);
+    }
+    catch {
+        return map;
+    }
+    for (const name of names) {
+        const match = /^(S-[A-Za-z0-9._-]+)\.md$/u.exec(name);
+        if (!match)
+            continue;
+        const sliceId = match[1];
+        let content = "";
+        try {
+            content = await fs.readFile(path.join(tddSlicesDir, name), "utf8");
+        }
+        catch {
+            continue;
+        }
+        const acIds = extractSliceCardClosedAcceptanceCriteria(content);
+        for (const acId of acIds) {
+            const set = map.get(acId) ?? new Set();
+            set.add(sliceId);
+            map.set(acId, set);
+        }
+    }
+    return map;
+}
+async function sliceHasManagedCommit(projectRoot, sliceId, sinceTs) {
+    const grepPattern = `^${escapeForRegex(sliceId)}/`;
+    const args = ["log", "--extended-regexp", "--grep", grepPattern, "--pretty=%H"];
+    if (sinceTs && sinceTs.length > 0) {
+        args.push(`--since=${sinceTs}`);
+    }
+    try {
+        const { stdout } = await execFileAsync("git", args, { cwd: projectRoot });
+        return stdout.trim().length > 0;
+    }
+    catch {
+        return false;
+    }
+}
+async function resolveActiveRunStartTs(projectRoot, runId) {
+    const ledger = await readDelegationLedger(projectRoot).catch(() => null);
+    const runRows = ledger
+        ? ledger.entries.filter((entry) => entry.runId === runId)
+        : [];
+    const stamps = runRows
+        .map((entry) => entryTimestamp(entry))
+        .filter((value) => typeof value === "string" && value.length > 0)
+        .sort();
+    if (stamps.length > 0) {
+        return stamps[0];
+    }
+    try {
+        const state = await readFlowState(projectRoot);
+        if (state.activeRunId === runId) {
+            const completed = Object.values(state.completedStageMeta ?? {})
+                .map((meta) => meta?.completedAt)
+                .filter((value) => typeof value === "string" && value.length > 0)
+                .sort();
+            if (completed.length > 0) {
+                return completed[0];
+            }
+        }
+    }
+    catch {
+        // no-op fallback
+    }
+    return null;
+}
 export async function lintShipStage(ctx) {
     const { projectRoot, track, raw, absFile, sections, findings, parsedFrontmatter, brainstormShortCircuitBody, brainstormShortCircuitActivated, staleDiagramAuditEnabled, isTrivialOverride } = ctx;
     // Universal Layer 2.8 structural checks (superpowers finishing-a-development-branch).
@@ -79,4 +195,56 @@ export async function lintShipStage(ctx) {
             ? "Architect cross-stage verification reported DRIFT_DETECTED; ship must not proceed."
             : "No DRIFT_DETECTED signal found in ship artifact or architect delegation evidence."
     });
+    const specAcceptanceIds = await readSpecAcceptanceCriteriaIds(projectRoot, track);
+    const tddSlicesDir = path.join(path.dirname(absFile), "tdd-slices");
+    const acceptanceSlices = await collectAcceptanceSlicesMap(tddSlicesDir);
+    const gitPresent = await exists(path.join(projectRoot, ".git"));
+    const runStartTs = gitPresent
+        ? await resolveActiveRunStartTs(projectRoot, delegationLedger.runId)
+        : null;
+    const uncoveredCriteria = [];
+    if (specAcceptanceIds.length > 0 && gitPresent && runStartTs !== null) {
+        for (const acId of specAcceptanceIds) {
+            const slices = [...(acceptanceSlices.get(acId) ?? new Set())];
+            let covered = false;
+            if (slices.length > 0) {
+                for (const sliceId of slices) {
+                    if (await sliceHasManagedCommit(projectRoot, sliceId, runStartTs)) {
+                        covered = true;
+                        break;
+                    }
+                }
+            }
+            if (!covered) {
+                const reason = slices.length === 0
+                    ? `${acId} has no \`Closes: ${acId}\` slice mapping`
+                    : `${acId} mapped slices ${slices.join(", ")} have no managed commit since run start`;
+                uncoveredCriteria.push(reason);
+                findings.push({
+                    section: `acceptance_criterion_${acId}_uncovered`,
+                    required: true,
+                    rule: "Every acceptance criterion must map to at least one slice card and at least one managed slice commit.",
+                    found: false,
+                    details: reason
+                });
+            }
+        }
+    }
+    const allAcceptanceCovered = specAcceptanceIds.length === 0 ||
+        ((!gitPresent || runStartTs !== null) && uncoveredCriteria.length === 0);
+    findings.push({
+        section: "ship_all_acceptance_criteria_have_commits",
+        required: true,
+        rule: "For every spec AC-N, at least one `tdd-slices/S-*.md` card must declare `Closes: AC-N` and at least one managed slice commit (`^S-<id>/`) must exist since run start.",
+        found: allAcceptanceCovered,
+        details: specAcceptanceIds.length === 0
+            ? "Spec acceptance criteria list is empty or unreadable; AC commit coverage check is idle."
+            : !gitPresent
+                ? "No .git directory detected; AC-to-commit coverage check is skipped for no-VCS mode."
+                : runStartTs === null
+                    ? "Unable to resolve active run start timestamp from delegation ledger/flow-state."
+                    : uncoveredCriteria.length > 0
+                        ? `Uncovered acceptance criteria: ${uncoveredCriteria.join(" | ")}.`
+                        : `All ${specAcceptanceIds.length} acceptance criteria map to slice cards and managed commits since ${runStartTs}.`
+    });
 }

package/dist/artifact-linter/spec.js

@@ -1,4 +1,4 @@
-import { evaluateLayeredDocumentReviewStatus, sectionBodyByName, SPEC_MAX_MODULES } from "./shared.js";
+import { getMarkdownTableRows, evaluateLayeredDocumentReviewStatus, extractAcceptanceCriterionIdsFromMarkdown, sectionBodyByName, SPEC_MAX_MODULES } from "./shared.js";
 import { CONFIDENCE_FINDING_REGEX_SOURCE } from "../content/skills.js";
 export async function lintSpecStage(ctx) {
     const { projectRoot, track, raw, absFile, sections, findings, parsedFrontmatter, brainstormShortCircuitBody, brainstormShortCircuitActivated, staleDiagramAuditEnabled, isTrivialOverride } = ctx;
@@ -128,6 +128,38 @@ export async function lintSpecStage(ctx) {
         });
     }
     const acceptanceCriteriaBody = sectionBodyByName(sections, "Acceptance Criteria");
+    if (acceptanceCriteriaBody === null) {
+        findings.push({
+            section: "spec_ac_ids_present",
+            required: true,
+            rule: "Acceptance Criteria must assign stable IDs in `AC-N` format for every criterion row.",
+            found: false,
+            details: "No ## heading matching required section \"Acceptance Criteria\"."
+        });
+    }
+    else {
+        const tableRows = getMarkdownTableRows(acceptanceCriteriaBody);
+        const bulletRows = acceptanceCriteriaBody
+            .split("\n")
+            .map((line) => line.trim())
+            .filter((line) => /^[-*]\s+/u.test(line));
+        const candidateRows = tableRows.length > 0
+            ? tableRows.map((row) => row.join(" | ").trim()).filter((row) => row.length > 0)
+            : bulletRows;
+        const missingIds = candidateRows.filter((row) => extractAcceptanceCriterionIdsFromMarkdown(row).length === 0);
+        const found = candidateRows.length > 0 && missingIds.length === 0;
+        findings.push({
+            section: "spec_ac_ids_present",
+            required: true,
+            rule: "Acceptance Criteria must assign stable IDs in `AC-N` format for every criterion row.",
+            found,
+            details: candidateRows.length === 0
+                ? "Acceptance Criteria has no populated criterion rows."
+                : missingIds.length === 0
+                    ? `All ${candidateRows.length} acceptance criterion row(s) include AC-N identifiers.`
+                    : `${missingIds.length} acceptance criterion row(s) are missing AC-N identifiers.`
+        });
+    }
     if (acceptanceCriteriaBody !== null && /\|/u.test(acceptanceCriteriaBody)) {
         const hasParallel = /\bparallelSafe\b/iu.test(acceptanceCriteriaBody);
         const hasTouch = /\btouchSurface\b/iu.test(acceptanceCriteriaBody);

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

@@ -23,6 +23,11 @@ interface SliceFileInfo {
     sliceId: string;
     absPath: string;
 }
+interface SliceNoOrphanChangesResult {
+    ok: boolean;
+    details: string;
+}
+export declare function evaluateSliceNoOrphanChanges(projectRoot: string, rows: DelegationEntry[]): Promise<SliceNoOrphanChangesResult>;
 interface ParsedSliceCycleResult {
     ok: boolean;
     details: string;

package/dist/artifact-linter/tdd.js

@@ -1,12 +1,17 @@
 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 { 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 +356,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 +386,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 +407,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
@@ -466,6 +515,156 @@ async function listSliceFiles(slicesDir) {
 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/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",
@@ -283,6 +284,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 +300,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 +345,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/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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cclaw-cli",
-  "version": "7.4.0",
+  "version": "7.5.0",
   "description": "Installer-first flow toolkit for coding agents",
   "type": "module",
   "bin": {