cclaw-cli 6.10.0 → 6.11.0

package/dist/artifact-linter/tdd.js

@@ -1,14 +1,39 @@
 import fs from "node:fs/promises";
 import path from "node:path";
 import { readDelegationLedger } from "../delegation.js";
-import { foldTddSliceLedger, readTddSliceLedger } from "../tdd-slices.js";
 import { 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 -->";
+/**
+ * v6.11.0 — TDD stage linter.
+ *
+ * Source-of-truth ladder, in order of precedence:
+ *
+ * 1. **Phase events** in `delegation-events.jsonl` for the active run
+ *    (`stage=tdd`, `sliceId=S-N`, `phase=red|green|refactor|refactor-deferred|doc`).
+ *    When at least one slice carries any phase event, the linter
+ *    auto-derives Watched-RED / Vertical Slice Cycle from the events
+ *    and writes a rendered summary block between auto-render markers
+ *    in `06-tdd.md`. Markdown table content is no longer required.
+ * 2. **Legacy markdown tables** (Watched-RED Proof + Vertical Slice
+ *    Cycle) — used as a fallback when the events ledger has no slice
+ *    phase rows for the active run. Existing v6.10 and earlier
+ *    artifacts continue to validate via this path.
+ * 3. **Sharded slice files** under `<artifacts-dir>/tdd-slices/S-*.md`.
+ *    Per-slice prose lives there. The main `06-tdd.md` is auto-indexed
+ *    via `## Slices Index`.
+ */
 export async function lintTddStage(ctx) {
-    const { projectRoot, track, raw, absFile, sections, findings, parsedFrontmatter, brainstormShortCircuitBody, brainstormShortCircuitActivated, staleDiagramAuditEnabled, isTrivialOverride } = ctx;
-    const sliceLedger = await readTddSliceLedger(projectRoot);
-    const sidecarActive = sliceLedger.entries.length > 0;
+    const { projectRoot, discoveryMode, raw, absFile, sections, findings, parsedFrontmatter } = ctx;
+    void projectRoot;
+    void parsedFrontmatter;
     evaluateInvestigationTrace(ctx, "Watched-RED Proof");
-    // Universal Layer 2.6 structural checks (superpowers TDD + evanflow vertical slices).
+    const delegationLedger = await readDelegationLedger(ctx.projectRoot);
+    const activeRunEntries = delegationLedger.entries.filter((entry) => entry.stage === "tdd" && entry.runId === delegationLedger.runId);
+    const slicesByEvents = groupBySlice(activeRunEntries);
+    const eventsActive = slicesByEvents.size > 0;
     const ironLawBody = sectionBodyByName(sections, "Iron Law Acknowledgement");
     if (ironLawBody === null) {
         findings.push({
@@ -32,18 +57,14 @@ export async function lintTddStage(ctx) {
         });
     }
     const watchedRedBody = sectionBodyByName(sections, "Watched-RED Proof");
-    if (sidecarActive) {
-        // v6.10.0 (T2): when 06-tdd-slices.jsonl carries rows, the sidecar is
-        // the source of truth for RED observation evidence; the markdown
-        // table is auto-derived (or left as a template stub) and must not
-        // block stage advance.
-        const sidecarResult = evaluateSidecarWatchedRed(sliceLedger.entries);
+    if (eventsActive) {
+        const redResult = evaluateEventsWatchedRed(slicesByEvents);
         findings.push({
             section: "Watched-RED Proof Shape",
             required: true,
-            rule: "Watched-RED Proof: when 06-tdd-slices.jsonl is present, every slice row with status >= red must include redObservedAt, testFile, testCommand, and claimedPaths.",
-            found: sidecarResult.ok,
-            details: sidecarResult.details
+            rule: "Watched-RED Proof: when delegation-events.jsonl carries slice phase events, every slice with a phase=red row must include a non-empty evidenceRefs[] (test path, span ref, or pasted-output pointer) and a completedTs.",
+            found: redResult.ok,
+            details: redResult.details
         });
     }
     else if (watchedRedBody === null) {
@@ -61,9 +82,8 @@ export async function lintTddStage(ctx) {
         const populatedRows = dataRows.filter((row) => row
             .split("|")
             .slice(1, -1)
-            .filter((_, idx) => idx !== 0) // skip slice column
+            .filter((_, idx) => idx !== 0)
             .some((cell) => cell.trim().length > 0));
-        // Each populated row must include an ISO timestamp in column 3.
         const isoRegex = /\d{4}-\d{2}-\d{2}T\d{2}:\d{2}/u;
         const validProofRows = populatedRows.filter((row) => isoRegex.test(row));
         const hasPopulatedRows = populatedRows.length > 0;
@@ -80,15 +100,18 @@ export async function lintTddStage(ctx) {
                     : `${populatedRows.length - validProofRows.length} watched-RED proof row(s) lack an ISO timestamp.`
         });
     }
-    if (sidecarActive) {
-        const cycleResult = evaluateSidecarSliceCycle(sliceLedger.entries);
+    if (eventsActive) {
+        const cycleResult = evaluateEventsSliceCycle(slicesByEvents);
         findings.push({
             section: "Vertical Slice Cycle Coverage",
             required: true,
-            rule: "Vertical Slice Cycle: 06-tdd-slices.jsonl rows must show RED -> GREEN monotonic progression per slice; REFACTOR is satisfied by `refactor-done` (with refactorAt > greenAt) or `refactor-deferred` (with non-empty refactorRationale).",
+            rule: "Vertical Slice Cycle: every slice with phase events must show RED before GREEN (completedTs monotonic), and a REFACTOR phase event (`refactor` with completedTs OR `refactor-deferred` with non-empty refactorRationale or evidenceRefs).",
             found: cycleResult.ok,
             details: cycleResult.details
         });
+        for (const finding of cycleResult.findings) {
+            findings.push(finding);
+        }
     }
     else {
         const sliceCycleBody = sectionBodyByName(sections, "Vertical Slice Cycle");
@@ -112,21 +135,19 @@ export async function lintTddStage(ctx) {
             });
         }
     }
-    if (!sidecarActive) {
-        // Advisory nudge: stage finished without ever migrating to the sidecar.
-        // Detect "filled markdown" by checking whether the Watched-RED Proof
-        // table or Vertical Slice Cycle has any populated rows.
-        const sliceCycleBodyAdvisory = sectionBodyByName(sections, "Vertical Slice Cycle");
-        const watchedRedBodyAdvisory = sectionBodyByName(sections, "Watched-RED Proof");
-        const markdownIsAuthored = hasPopulatedTableRows(watchedRedBodyAdvisory) ||
-            hasPopulatedTableRows(sliceCycleBodyAdvisory);
-        if (markdownIsAuthored) {
+    // Phase C — slice-documenter coverage. When discoveryMode=deep, every
+    // slice with a green phase event must also carry a phase=doc event with
+    // non-empty evidenceRefs pointing at `tdd-slices/S-<id>.md`.
+    if (eventsActive) {
+        const docResult = evaluateSliceDocumenterCoverage(slicesByEvents);
+        if (docResult.missing.length > 0) {
+            const isDeep = discoveryMode === "deep";
             findings.push({
-                section: "tdd_slice_ledger_missing",
-                required: false,
-                rule: "When markdown TDD tables are filled, prefer recording slice events via `cclaw-cli internal tdd-slice-record` so 06-tdd-slices.jsonl becomes the source of truth.",
+                section: "tdd_slice_documenter_missing_for_deep",
+                required: isDeep,
+                rule: "On discoveryMode=deep, every TDD slice with a phase=green event must also carry a slice-documenter `phase=doc` event whose evidenceRefs reference `<artifacts-dir>/tdd-slices/S-<id>.md`. On other discovery modes the requirement is advisory.",
                 found: false,
-                details: "06-tdd-slices.jsonl is empty even though the markdown tables are populated. Migrate this stage's slices to the sidecar with `cclaw-cli internal tdd-slice-record --slice <id> --status <red|green|refactor-done|refactor-deferred> ...`."
+                details: `Slices missing slice-documenter coverage: ${docResult.missing.join(", ")}.`
             });
         }
     }
@@ -169,8 +190,6 @@ export async function lintTddStage(ctx) {
                     : "Mocks/spies detected without boundary justification; add explicit trust-boundary rationale or replace with real/fake/stub coverage."
         });
     }
-    const delegationLedger = await readDelegationLedger(projectRoot);
-    const activeRunEntries = delegationLedger.entries.filter((entry) => entry.stage === "tdd" && entry.runId === delegationLedger.runId);
     const completedSliceImplementers = activeRunEntries.filter((entry) => entry.agent === "slice-implementer" && entry.status === "completed");
     const fanOutDetected = completedSliceImplementers.length > 1;
     if (fanOutDetected) {
@@ -240,145 +259,276 @@ 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);
+    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
+    });
+    // Phase S — sharded slice files. Validate per-slice file presence
+    // and required headings. `tdd-slices/` is optional; missing folder
+    // simply means main-only mode (legacy fallback).
+    const artifactsDir = path.dirname(absFile);
+    const slicesDir = path.join(artifactsDir, "tdd-slices");
+    const sliceFiles = await listSliceFiles(slicesDir);
+    for (const sliceFile of sliceFiles) {
+        const sliceId = sliceFile.sliceId;
+        const requiredForSlice = slicesByEvents.has(sliceId) &&
+            slicesByEvents.get(sliceId).some((entry) => entry.phase === "doc");
+        let content = "";
+        try {
+            content = await fs.readFile(sliceFile.absPath, "utf8");
+        }
+        catch {
+            content = "";
+        }
+        const issues = [];
+        if (!new RegExp(`^#\\s+Slice\\s+${escapeForRegex(sliceId)}\\b`, "mu").test(content) &&
+            !/^#\s+Slice\b/mu.test(content)) {
+            issues.push("missing `# Slice <id>` heading");
+        }
+        if (!/^##\s+Plan unit\b/imu.test(content)) {
+            issues.push("missing `## Plan unit` section");
+        }
+        if (!/^##\s+REFACTOR notes\b/imu.test(content)) {
+            issues.push("missing `## REFACTOR notes` section");
+        }
+        if (!/^##\s+Learnings\b/imu.test(content)) {
+            issues.push("missing `## Learnings` section");
+        }
         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
+            section: `tdd_slice_file:${sliceId}`,
+            required: requiredForSlice,
+            rule: "Sharded slice file must include `# Slice <id>`, `## Plan unit`, `## REFACTOR notes`, and `## Learnings` headings.",
+            found: issues.length === 0,
+            details: issues.length === 0
+                ? `tdd-slices/${path.basename(sliceFile.absPath)} has all required headings.`
+                : `tdd-slices/${path.basename(sliceFile.absPath)}: ${issues.join(", ")}.`
         });
     }
+    // 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
+    // phase events, no sharded files) stay byte-for-byte unchanged.
+    if (eventsActive || sliceFiles.length > 0) {
+        try {
+            await renderTddSliceSummary({
+                mainArtifactPath: absFile,
+                slicesByEvents,
+                sliceFiles,
+                renderSummary: eventsActive,
+                renderIndex: sliceFiles.length > 0
+            });
+        }
+        catch {
+            // best-effort render — never block the gate.
+        }
+    }
 }
-/**
- * v6.10.0 (T2) — sidecar-aware Watched-RED check. Validates that every
- * slice currently recorded in `06-tdd-slices.jsonl` (folded latest-row
- * per `sliceId`) has the structural evidence the markdown table would
- * have required: RED observation timestamp, test file, test command,
- * and at least one claimed path.
- */
-export function evaluateSidecarWatchedRed(rawEntries) {
-    if (rawEntries.length === 0) {
-        return {
-            ok: false,
-            details: "Sidecar 06-tdd-slices.jsonl is empty; record at least one slice via `cclaw-cli internal tdd-slice-record`."
-        };
+async function listSliceFiles(slicesDir) {
+    let entries = [];
+    try {
+        entries = await fs.readdir(slicesDir);
+    }
+    catch {
+        return [];
+    }
+    const files = [];
+    for (const name of entries) {
+        const match = /^(S-[A-Za-z0-9._-]+)\.md$/u.exec(name);
+        if (!match)
+            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));
+    return files;
+}
+function escapeForRegex(value) {
+    return value.replace(/[.*+?^${}()|[\]\\]/gu, "\\$&");
+}
+function groupBySlice(entries) {
+    const grouped = new Map();
+    for (const entry of entries) {
+        if (typeof entry.sliceId !== "string" || entry.sliceId.length === 0)
+            continue;
+        if (typeof entry.phase !== "string" || entry.phase.length === 0)
+            continue;
+        if (entry.status !== "completed")
+            continue;
+        const list = grouped.get(entry.sliceId) ?? [];
+        list.push(entry);
+        grouped.set(entry.sliceId, list);
     }
-    const folded = foldTddSliceLedger(rawEntries);
+    return grouped;
+}
+export function evaluateEventsWatchedRed(slices) {
     const errors = [];
-    for (const entry of folded) {
+    let redCount = 0;
+    for (const [sliceId, rows] of slices.entries()) {
+        const reds = rows.filter((entry) => entry.phase === "red");
+        if (reds.length === 0)
+            continue;
+        redCount += 1;
         const issues = [];
-        if (!entry.redObservedAt || entry.redObservedAt.trim().length === 0) {
-            issues.push("missing redObservedAt");
-        }
-        else if (!/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}/u.test(entry.redObservedAt)) {
-            issues.push("redObservedAt is not an ISO timestamp");
-        }
-        if (!entry.testFile || entry.testFile.length === 0) {
-            issues.push("missing testFile");
-        }
-        if (!entry.testCommand || entry.testCommand.length === 0) {
-            issues.push("missing testCommand");
-        }
-        if (!Array.isArray(entry.claimedPaths) || entry.claimedPaths.length === 0) {
-            issues.push("missing claimedPaths");
+        for (const red of reds) {
+            const ts = red.completedTs ?? red.endTs ?? red.ts ?? "";
+            if (!/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}/u.test(ts)) {
+                issues.push("phase=red row missing ISO completedTs");
+            }
+            if (!Array.isArray(red.evidenceRefs) ||
+                red.evidenceRefs.filter((ref) => typeof ref === "string" && ref.trim().length > 0).length === 0) {
+                issues.push("phase=red row has empty evidenceRefs");
+            }
         }
         if (issues.length > 0) {
-            errors.push(`${entry.sliceId}: ${issues.join(", ")}`);
+            errors.push(`${sliceId}: ${issues.join(", ")}`);
         }
     }
+    if (redCount === 0) {
+        return {
+            ok: false,
+            details: "Watched-RED Proof: events ledger has slice phase rows but none with phase=red. Dispatch test-author --slice <id> --phase red so RED is observable in delegation-events.jsonl."
+        };
+    }
     if (errors.length > 0) {
         return {
             ok: false,
-            details: `Sidecar slice rows missing RED evidence fields: ${errors.join(" | ")}.`
+            details: `Watched-RED slice events missing required fields: ${errors.join(" | ")}.`
         };
     }
     return {
         ok: true,
-        details: `Sidecar 06-tdd-slices.jsonl has ${folded.length} slice row(s) with required RED evidence fields.`
+        details: `${redCount} slice(s) carry phase=red events with ISO completedTs and evidenceRefs.`
     };
 }
-/**
- * v6.10.0 (T2) — sidecar-aware Vertical Slice Cycle check. Each slice
- * must have a row whose effective status (latest by sliceId) implies a
- * monotonic progression. Once a slice carries `greenAt`, the linter
- * requires `greenAt >= redObservedAt`. `refactor-deferred` requires a
- * non-empty `refactorRationale`. `refactor-done` requires a `refactorAt`
- * that is `>= greenAt`. Slices stuck at `red` are tolerated only when
- * the run is still in TDD; the linter surfaces them as advisory through
- * the watched-RED check above.
- */
-export function evaluateSidecarSliceCycle(rawEntries) {
-    if (rawEntries.length === 0) {
-        return {
-            ok: false,
-            details: "Sidecar 06-tdd-slices.jsonl is empty; the vertical slice cycle has no rows."
-        };
-    }
-    const folded = foldTddSliceLedger(rawEntries);
+export function evaluateEventsSliceCycle(slices) {
     const errors = [];
-    for (const entry of folded) {
-        if (entry.greenAt) {
-            const redIso = parseTimestampCell(entry.redObservedAt ?? "");
-            const greenIso = parseTimestampCell(entry.greenAt);
-            if (greenIso === null) {
-                errors.push(`${entry.sliceId}: greenAt is not an ISO timestamp.`);
-                continue;
-            }
-            if (redIso !== null && greenIso < redIso) {
-                errors.push(`${entry.sliceId}: greenAt (${entry.greenAt}) precedes redObservedAt (${entry.redObservedAt}) — order must be monotonic.`);
-                continue;
-            }
+    const findings = [];
+    for (const [sliceId, rows] of slices.entries()) {
+        const reds = rows.filter((entry) => entry.phase === "red");
+        const greens = rows.filter((entry) => entry.phase === "green");
+        const refactors = rows.filter((entry) => entry.phase === "refactor" || entry.phase === "refactor-deferred");
+        const redTs = pickEventTs(reds);
+        const greenTs = pickEventTs(greens);
+        if (reds.length === 0) {
+            errors.push(`${sliceId}: phase=red event missing.`);
+            findings.push({
+                section: `tdd_slice_red_missing:${sliceId}`,
+                required: true,
+                rule: "Each TDD slice with phase events must include a `phase=red` row.",
+                found: false,
+                details: `${sliceId}: no phase=red event recorded for the active run.`
+            });
+            continue;
         }
-        if (entry.status === "refactor-deferred") {
-            if (!entry.refactorRationale || entry.refactorRationale.trim().length === 0) {
-                errors.push(`${entry.sliceId}: status=refactor-deferred requires a non-empty refactorRationale.`);
-                continue;
-            }
+        if (greens.length === 0) {
+            errors.push(`${sliceId}: phase=green event missing.`);
+            findings.push({
+                section: `tdd_slice_green_missing:${sliceId}`,
+                required: true,
+                rule: "Each TDD slice with a phase=red event must reach a `phase=green` row before stage-complete.",
+                found: false,
+                details: `${sliceId}: no phase=green event recorded; RED has no matching GREEN.`
+            });
+            continue;
         }
-        if (entry.status === "refactor-done") {
-            const greenIso = parseTimestampCell(entry.greenAt ?? "");
-            const refactorIso = parseTimestampCell(entry.refactorAt ?? "");
-            if (refactorIso === null) {
-                errors.push(`${entry.sliceId}: status=refactor-done requires a refactorAt ISO timestamp.`);
-                continue;
-            }
-            if (greenIso !== null && refactorIso < greenIso) {
-                errors.push(`${entry.sliceId}: refactorAt (${entry.refactorAt}) precedes greenAt (${entry.greenAt}) — order must be monotonic.`);
+        if (greenTs && redTs && greenTs < redTs) {
+            errors.push(`${sliceId}: phase=green completedTs (${greenTs}) precedes phase=red (${redTs}).`);
+            findings.push({
+                section: `tdd_slice_phase_order_invalid:${sliceId}`,
+                required: true,
+                rule: "Phase events must be monotonic: phase=green completedTs >= phase=red completedTs.",
+                found: false,
+                details: `${sliceId}: green at ${greenTs} precedes red at ${redTs}.`
+            });
+            continue;
+        }
+        const greenEvidenceRef = greens
+            .flatMap((entry) => Array.isArray(entry.evidenceRefs) ? entry.evidenceRefs : [])
+            .find((ref) => typeof ref === "string" && ref.trim().length > 0);
+        if (!greenEvidenceRef) {
+            errors.push(`${sliceId}: phase=green row has empty evidenceRefs.`);
+            findings.push({
+                section: `tdd_slice_evidence_missing:${sliceId}`,
+                required: true,
+                rule: "Each `phase=green` event must record at least one evidenceRef (path to test artifact, span id, or pasted-output pointer).",
+                found: false,
+                details: `${sliceId}: phase=green event missing evidenceRefs.`
+            });
+            continue;
+        }
+        if (refactors.length === 0) {
+            errors.push(`${sliceId}: phase=refactor or phase=refactor-deferred event missing.`);
+            findings.push({
+                section: `tdd_slice_refactor_missing:${sliceId}`,
+                required: true,
+                rule: "Each TDD slice must close with a `phase=refactor` event or a `phase=refactor-deferred` event whose evidenceRefs / refactorRationale captures why refactor was deferred.",
+                found: false,
+                details: `${sliceId}: no phase=refactor or phase=refactor-deferred event.`
+            });
+            continue;
+        }
+        const deferred = refactors.find((entry) => entry.phase === "refactor-deferred");
+        if (deferred && refactors.every((entry) => entry.phase === "refactor-deferred")) {
+            const refs = Array.isArray(deferred.evidenceRefs) ? deferred.evidenceRefs : [];
+            const hasRationale = refs.some((ref) => typeof ref === "string" && ref.trim().length > 0);
+            if (!hasRationale) {
+                errors.push(`${sliceId}: phase=refactor-deferred row needs evidenceRefs containing a rationale.`);
+                findings.push({
+                    section: `tdd_slice_refactor_missing:${sliceId}`,
+                    required: true,
+                    rule: "phase=refactor-deferred must record a rationale via --refactor-rationale or via --evidence-ref pointing at the rationale text.",
+                    found: false,
+                    details: `${sliceId}: phase=refactor-deferred recorded without rationale evidenceRefs.`
+                });
                 continue;
             }
         }
     }
     if (errors.length > 0) {
-        return { ok: false, details: errors.join(" ") };
+        return {
+            ok: false,
+            details: errors.join(" "),
+            findings
+        };
     }
     return {
         ok: true,
-        details: `${folded.length} sidecar slice row(s) show monotonic RED -> GREEN -> REFACTOR (deferred-with-rationale accepted).`
+        details: `${slices.size} slice(s) show monotonic phase=red -> phase=green -> phase=refactor (deferred-with-rationale accepted).`,
+        findings: []
     };
 }
-function hasPopulatedTableRows(body) {
-    if (body === null)
-        return false;
-    const tableLines = body.split("\n").filter((line) => /^\|/u.test(line));
-    if (tableLines.length < 3)
-        return false;
-    const dataRows = tableLines.slice(2);
-    for (const row of dataRows) {
-        const cells = row
-            .split("|")
-            .slice(1, -1)
-            .map((cell) => cell.trim());
-        // Skip cells that are entirely placeholder slice IDs (S-1 default).
-        const meaningful = cells.filter((cell, idx) => idx !== 0 && cell.length > 0);
-        if (meaningful.length > 0)
-            return true;
+export function evaluateSliceDocumenterCoverage(slices) {
+    const missing = [];
+    for (const [sliceId, rows] of slices.entries()) {
+        const hasGreen = rows.some((entry) => entry.phase === "green");
+        if (!hasGreen)
+            continue;
+        const docRow = rows.find((entry) => entry.phase === "doc");
+        if (!docRow) {
+            missing.push(sliceId);
+            continue;
+        }
+        const refs = Array.isArray(docRow.evidenceRefs) ? docRow.evidenceRefs : [];
+        const hasSliceFileRef = refs.some((ref) => typeof ref === "string" && /tdd-slices\/S-[^/]+\.md/u.test(ref));
+        if (!hasSliceFileRef) {
+            missing.push(sliceId);
+        }
+    }
+    return { missing };
+}
+function pickEventTs(rows) {
+    for (const entry of rows) {
+        const ts = entry.completedTs ?? entry.endTs ?? entry.ts;
+        if (typeof ts === "string" && ts.length > 0)
+            return ts;
     }
-    return false;
+    return undefined;
 }
 export function parseVerticalSliceCycle(body) {
     const tableLines = body.split("\n").filter((line) => /^\|/u.test(line));
@@ -490,7 +640,6 @@ function extractDeferRationale(cell) {
     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;
 }
@@ -537,3 +686,93 @@ export function evaluateVerificationLadder(body) {
             "Promote each to `passed`, `n/a`, `failed`, `skipped`, or `deferred` (with rationale) before stage-complete."
     };
 }
+export async function renderTddSliceSummary(input) {
+    let raw;
+    try {
+        raw = await fs.readFile(input.mainArtifactPath, "utf8");
+    }
+    catch {
+        return;
+    }
+    let next = raw;
+    if (input.renderSummary !== false) {
+        const summaryBlock = renderSliceSummaryBlock(input.slicesByEvents);
+        next = upsertAutoBlock(next, SLICE_SUMMARY_START, SLICE_SUMMARY_END, summaryBlock);
+    }
+    if (input.renderIndex !== false) {
+        const indexBlock = renderSlicesIndexBlock(input.sliceFiles);
+        next = upsertAutoBlock(next, SLICES_INDEX_START, SLICES_INDEX_END, indexBlock);
+    }
+    if (next !== raw) {
+        try {
+            await fs.writeFile(input.mainArtifactPath, next, "utf8");
+        }
+        catch {
+            // best-effort render
+        }
+    }
+}
+function renderSliceSummaryBlock(slices) {
+    if (slices.size === 0) {
+        return "## Vertical Slice Cycle\n\n_No slice phase events recorded for the active run._";
+    }
+    const sortedIds = [...slices.keys()].sort();
+    const rows = [];
+    rows.push("## Vertical Slice Cycle");
+    rows.push("");
+    rows.push("| Slice | RED ts | GREEN ts | REFACTOR | Implementer | Test refs |");
+    rows.push("|---|---|---|---|---|---|");
+    for (const sliceId of sortedIds) {
+        const events = slices.get(sliceId);
+        const red = events.find((entry) => entry.phase === "red");
+        const green = events.find((entry) => entry.phase === "green");
+        const refactor = events.find((entry) => entry.phase === "refactor" || entry.phase === "refactor-deferred");
+        const redTs = red?.completedTs ?? red?.endTs ?? red?.ts ?? "";
+        const greenTs = green?.completedTs ?? green?.endTs ?? green?.ts ?? "";
+        let refactorCell;
+        if (!refactor) {
+            refactorCell = "";
+        }
+        else if (refactor.phase === "refactor-deferred") {
+            const refs = Array.isArray(refactor.evidenceRefs) ? refactor.evidenceRefs : [];
+            const rationale = refs.find((ref) => typeof ref === "string" && ref.trim().length > 0) ?? "";
+            refactorCell = `deferred because ${rationale}`.trim();
+        }
+        else {
+            refactorCell = refactor.completedTs ?? refactor.ts ?? "";
+        }
+        const implementer = green?.agent ?? red?.agent ?? "";
+        const refsList = green?.evidenceRefs ?? red?.evidenceRefs ?? [];
+        const testRefs = Array.isArray(refsList) ? refsList.join(", ") : "";
+        rows.push(`| ${sliceId} | ${redTs} | ${greenTs} | ${escapeTableCell(refactorCell)} | ${implementer} | ${escapeTableCell(testRefs)} |`);
+    }
+    return rows.join("\n");
+}
+function renderSlicesIndexBlock(sliceFiles) {
+    if (sliceFiles.length === 0) {
+        return "## Slices Index\n\n_No `tdd-slices/S-*.md` files present._";
+    }
+    const lines = [];
+    lines.push("## Slices Index");
+    lines.push("");
+    for (const file of sliceFiles) {
+        lines.push(`- [${file.sliceId}](tdd-slices/${path.basename(file.absPath)})`);
+    }
+    return lines.join("\n");
+}
+function escapeTableCell(value) {
+    return value.replace(/\|/gu, "\\|").replace(/\r?\n/gu, " ");
+}
+function upsertAutoBlock(raw, startMarker, endMarker, bodyContent) {
+    const startIdx = raw.indexOf(startMarker);
+    const endIdx = raw.indexOf(endMarker);
+    const replacement = `${startMarker}\n${bodyContent}\n${endMarker}`;
+    if (startIdx >= 0 && endIdx > startIdx) {
+        const before = raw.slice(0, startIdx);
+        const after = raw.slice(endIdx + endMarker.length);
+        return `${before}${replacement}${after}`;
+    }
+    // append to end
+    const sep = raw.endsWith("\n") ? "" : "\n";
+    return `${raw}${sep}\n${replacement}\n`;
+}