cclaw-cli 6.9.0 → 6.11.0

package/dist/artifact-linter/tdd.js

@@ -2,10 +2,38 @@ import fs from "node:fs/promises";
 import path from "node:path";
 import { readDelegationLedger } from "../delegation.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 { 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({
@@ -29,7 +57,17 @@ export async function lintTddStage(ctx) {
         });
     }
     const watchedRedBody = sectionBodyByName(sections, "Watched-RED Proof");
-    if (watchedRedBody === null) {
+    if (eventsActive) {
+        const redResult = evaluateEventsWatchedRed(slicesByEvents);
+        findings.push({
+            section: "Watched-RED Proof Shape",
+            required: true,
+            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) {
         findings.push({
             section: "Watched-RED Proof Shape",
             required: true,
@@ -44,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;
@@ -63,25 +100,56 @@ export async function lintTddStage(ctx) {
                     : `${populatedRows.length - validProofRows.length} watched-RED proof row(s) lack an ISO timestamp.`
         });
     }
-    const sliceCycleBody = sectionBodyByName(sections, "Vertical Slice Cycle");
-    if (sliceCycleBody === null) {
+    if (eventsActive) {
+        const cycleResult = evaluateEventsSliceCycle(slicesByEvents);
         findings.push({
             section: "Vertical Slice Cycle Coverage",
             required: true,
-            rule: "Vertical Slice Cycle must include RED, GREEN, and REFACTOR per slice (refactor may be deferred with rationale).",
-            found: false,
-            details: "No ## heading matching required section \"Vertical Slice Cycle\"."
-        });
-    }
-    else {
-        const cycleResult = parseVerticalSliceCycle(sliceCycleBody);
-        findings.push({
-            section: "Vertical Slice Cycle Coverage",
-            required: true,
-            rule: "Vertical Slice Cycle must show RED -> GREEN -> REFACTOR monotonic progression per slice (refactor may be deferred with one-line rationale, e.g. `deferred because <reason>`).",
+            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");
+        if (sliceCycleBody === null) {
+            findings.push({
+                section: "Vertical Slice Cycle Coverage",
+                required: true,
+                rule: "Vertical Slice Cycle must include RED, GREEN, and REFACTOR per slice (refactor may be deferred with rationale).",
+                found: false,
+                details: "No ## heading matching required section \"Vertical Slice Cycle\"."
+            });
+        }
+        else {
+            const cycleResult = parseVerticalSliceCycle(sliceCycleBody);
+            findings.push({
+                section: "Vertical Slice Cycle Coverage",
+                required: true,
+                rule: "Vertical Slice Cycle must show RED -> GREEN -> REFACTOR monotonic progression per slice (refactor may be deferred with one-line rationale, e.g. `deferred because <reason>`).",
+                found: cycleResult.ok,
+                details: cycleResult.details
+            });
+        }
+    }
+    // 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_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: `Slices missing slice-documenter coverage: ${docResult.missing.join(", ")}.`
+            });
+        }
     }
     const assertionBody = sectionBodyByName(sections, "Assertion Correctness Notes");
     if (assertionBody !== null) {
@@ -122,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) {
@@ -193,19 +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.
+        }
+    }
+}
+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);
+    }
+    return grouped;
+}
+export function evaluateEventsWatchedRed(slices) {
+    const errors = [];
+    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 = [];
+        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(`${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: `Watched-RED slice events missing required fields: ${errors.join(" | ")}.`
+        };
+    }
+    return {
+        ok: true,
+        details: `${redCount} slice(s) carry phase=red events with ISO completedTs and evidenceRefs.`
+    };
+}
+export function evaluateEventsSliceCycle(slices) {
+    const errors = [];
+    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 (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 (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(" "),
+            findings
+        };
+    }
+    return {
+        ok: true,
+        details: `${slices.size} slice(s) show monotonic phase=red -> phase=green -> phase=refactor (deferred-with-rationale accepted).`,
+        findings: []
+    };
+}
+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 undefined;
 }
 export function parseVerticalSliceCycle(body) {
     const tableLines = body.split("\n").filter((line) => /^\|/u.test(line));
@@ -317,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;
 }
@@ -364,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`;
+}

package/dist/artifact-linter.js

@@ -1,9 +1,10 @@
 import fs from "node:fs/promises";
+import path from "node:path";
 import { resolveArtifactPath as resolveStageArtifactPath } from "./artifact-paths.js";
 import { exists } from "./fs-utils.js";
 import { stageSchema } from "./content/stage-schema.js";
 import { readFlowState } from "./run-persistence.js";
-import { duplicateH2Headings, extractH2Sections, extractRequirementIdsFromMarkdown, isShortCircuitActivated, normalizeHeadingTitle, parseFrontmatter, parseLearningsSection, sectionBodyByAnyName, sectionBodyByHeadingPrefix, sectionBodyByName, validateSectionBody, formatLearningsErrorsBullets } from "./artifact-linter/shared.js";
+import { duplicateH2Headings, extractEvidencePointers, extractH2Sections, extractRequirementIdsFromMarkdown, isShortCircuitActivated, normalizeHeadingTitle, parseFrontmatter, parseLearningsSection, sectionBodyByAnyName, sectionBodyByHeadingPrefix, sectionBodyByName, validateSectionBody, formatLearningsErrorsBullets } from "./artifact-linter/shared.js";
 import { shouldDemoteArtifactValidationByTrack } from "./content/stage-schema.js";
 import { readDelegationLedger, recordArtifactValidationDemotedByTrack } from "./delegation.js";
 import { classifyAndPersistFindings } from "./artifact-linter/findings-dedup.js";
@@ -145,6 +146,18 @@ export async function lintArtifact(projectRoot, stage, track = "standard", optio
         }
     }
     const liteTierForValidators = shouldDemoteArtifactValidationByTrack(track, taskClass);
+    // v6.11.0 (D5) — pre-resolve RED/GREEN Evidence pointers AND
+    // delegation phase events so `validateSectionBody` (sync) can
+    // short-circuit. The Evidence: pointer mode (v6.10.0 T3) stays as a
+    // fallback alongside legacy markdown content; phase events with a
+    // `phase=red`/`phase=green` row plus non-empty evidenceRefs auto-pass
+    // the corresponding markdown validator.
+    const tddEvidenceContext = stage === "tdd"
+        ? await resolveTddEvidencePointerContext({
+            projectRoot,
+            sections
+        })
+        : { red: {}, green: {} };
     for (const v of schema.artifactValidation) {
         const sectionKey = normalizeHeadingTitle(v.section).toLowerCase();
         const scopeBoundaryAlias = stage === "scope" && sectionKey === "in scope / out of scope";
@@ -164,7 +177,8 @@ export async function lintArtifact(projectRoot, stage, track = "standard", optio
             ? { ok: false, details: `No ## heading matching required section "${v.section}".` }
             : validateSectionBody(body, v.validationRule, v.section, {
                 sections,
-                liteTier: liteTierForValidators
+                liteTier: liteTierForValidators,
+                tddEvidence: stage === "tdd" ? tddEvidenceContext : undefined
             });
         const found = hasHeading && validation.ok;
         findings.push({
@@ -420,3 +434,80 @@ const ARTIFACT_VALIDATION_LITE_DEMOTE_SECTIONS = new Set([
     "Stale Diagram Drift Check",
     "Product Discovery Delegation (Strategist Mode)"
 ]);
+/**
+ * v6.11.0 (D5) — pre-resolve `Evidence:` pointers and delegation
+ * phase-event auto-satisfy state for the TDD stage's RED/GREEN
+ * Evidence rows so `validateSectionBody` (sync) can short-circuit.
+ *
+ * - `<path>` pointer is satisfied when the path exists on disk relative
+ *   to the project root.
+ * - `spanId:<id>` pointer is satisfied when any delegation ledger row
+ *   carries that span id.
+ * - Phase-event auto-satisfy fires when `delegation-events.jsonl`
+ *   carries at least one slice-tagged event for the active run with
+ *   `phase=red`/`phase=green` and non-empty `evidenceRefs`. This is the
+ *   v6.11.0 replacement for the v6.10.0 sidecar auto-satisfy hook —
+ *   slice events are now the source of truth, the RED/GREEN markdown
+ *   tables are auto-rendered from them, and the validators MUST NOT
+ *   demand pasted stdout when the events already prove RED/GREEN.
+ */
+async function resolveTddEvidencePointerContext(input) {
+    const { projectRoot, sections } = input;
+    const redSection = sectionBodyByName(sections, "RED Evidence") ?? "";
+    const greenSection = sectionBodyByName(sections, "GREEN Evidence") ?? "";
+    const redPointers = extractEvidencePointers(redSection);
+    const greenPointers = extractEvidencePointers(greenSection);
+    let knownSpanIds = new Set();
+    let phaseEventsAutoSatisfy = { red: false, green: false };
+    try {
+        const ledger = await readDelegationLedger(projectRoot);
+        knownSpanIds = new Set(ledger.entries
+            .map((entry) => entry.spanId)
+            .filter((id) => typeof id === "string" && id.length > 0));
+        const runId = ledger.runId;
+        const slicePhaseRows = ledger.entries.filter((entry) => entry.runId === runId &&
+            entry.stage === "tdd" &&
+            typeof entry.sliceId === "string" &&
+            entry.sliceId.length > 0 &&
+            typeof entry.phase === "string");
+        const redOk = slicePhaseRows.some((entry) => entry.phase === "red" &&
+            Array.isArray(entry.evidenceRefs) &&
+            entry.evidenceRefs.some((ref) => typeof ref === "string" && ref.trim().length > 0));
+        const greenOk = slicePhaseRows.some((entry) => entry.phase === "green" &&
+            Array.isArray(entry.evidenceRefs) &&
+            entry.evidenceRefs.some((ref) => typeof ref === "string" && ref.trim().length > 0));
+        phaseEventsAutoSatisfy = { red: redOk, green: greenOk };
+    }
+    catch {
+        knownSpanIds = new Set();
+        phaseEventsAutoSatisfy = { red: false, green: false };
+    }
+    async function pointerResolves(value) {
+        const trimmed = value.replace(/[`*_]/gu, "").trim();
+        if (trimmed.length === 0)
+            return false;
+        if (/^spanid\s*:/iu.test(trimmed)) {
+            const id = trimmed.replace(/^spanid\s*:\s*/iu, "").trim();
+            return id.length > 0 && knownSpanIds.has(id);
+        }
+        const candidate = path.isAbsolute(trimmed) ? trimmed : path.join(projectRoot, trimmed);
+        return exists(candidate);
+    }
+    async function anyResolved(values) {
+        for (const value of values) {
+            if (await pointerResolves(value))
+                return true;
+        }
+        return false;
+    }
+    return {
+        red: {
+            pointerSatisfied: await anyResolved(redPointers),
+            phaseEventsSatisfied: phaseEventsAutoSatisfy.red
+        },
+        green: {
+            pointerSatisfied: await anyResolved(greenPointers),
+            phaseEventsSatisfied: phaseEventsAutoSatisfy.green
+        }
+    };
+}