cclaw-cli 7.7.1 → 8.1.0

package/dist/content/review-loop.js

@@ -1,734 +1,32 @@
-import fs from "node:fs/promises";
-import os from "node:os";
-import path from "node:path";
-export const REVIEW_LOOP_STAGES = ["scope", "design"];
-export const REVIEW_LOOP_DEFAULT_MAX_ITERATIONS = 3;
-export const REVIEW_LOOP_DEFAULT_TARGET_SCORE = 0.8;
-const REVIEW_LOOP_RESPONSE_SCHEMA = `{
-  "findings": [
+export const FIVE_FAILURE_MODES = [
     {
-      "id": "F-1",
-      "dimensionId": "<one checklist id>",
-      "severity": "critical|important|suggestion",
-      "summary": "what is wrong",
-      "evidence": "artifact quote/path",
-      "recommendation": "concrete fix"
-    }
-  ],
-  "dimensionScores": [
+        id: "hallucinated-actions",
+        name: "Hallucinated actions",
+        description: "File paths, env vars, ids, or function names that do not exist in the repository. Cross-check every reference before reporting it as done."
+    },
     {
-      "dimensionId": "<one checklist id>",
-      "score": 0.0
-    }
-  ]
-}`;
-export function reviewLoopPolicySummary(stage) {
-    const checklist = REVIEW_LOOP_CHECKLISTS[stage];
-    const ids = checklist.map((dimension) => `\`${dimension.id}\``).join(", ");
-    return `outside-voice review loop policy: use checklist dimensions ${ids}; stop at quality score >= ${REVIEW_LOOP_DEFAULT_TARGET_SCORE} or max ${REVIEW_LOOP_DEFAULT_MAX_ITERATIONS} iterations.`;
-}
-export function reviewLoopSecondOpinionSummary(stage) {
-    return `when \`.cclaw/config.yaml::reviewLoop.externalSecondOpinion.enabled\` is true, run an extra external-model pass for ${stage} and explicitly reconcile score/finding disagreements.`;
-}
-export const REVIEW_LOOP_CHECKLISTS = {
-    scope: [
-        {
-            id: "premise_fit",
-            label: "Premise fit",
-            weight: 1,
-            guidance: "Does the scope contract solve the actual user/problem framing without drifting into adjacent asks?"
-        },
-        {
-            id: "alternatives_coverage",
-            label: "Alternatives coverage",
-            weight: 1,
-            guidance: "Are meaningful alternatives compared with explicit trade-offs and one clear recommendation?"
-        },
-        {
-            id: "error_rescue_registry",
-            label: "Error and rescue coverage",
-            weight: 1,
-            guidance: "Does each scoped capability define failure mode, detection signal, and fallback/rescue behavior?"
-        },
-        {
-            id: "scope_creep_risk",
-            label: "Scope-creep risk",
-            weight: 1,
-            guidance: "Are in/out boundaries explicit and protected against silent expansion/reduction language?"
-        },
-        {
-            id: "completion_status_fidelity",
-            label: "Completion status fidelity",
-            weight: 1,
-            guidance: "Does the completion dashboard honestly report unresolved risks, decision count, and stop reason?"
-        }
-    ],
-    design: [
-        {
-            id: "architecture_fit",
-            label: "Architecture fit",
-            weight: 1,
-            guidance: "Do architecture boundaries and diagrams align with scope and real blast-radius code?"
-        },
-        {
-            id: "failure_mode_coverage",
-            label: "Failure-mode coverage",
-            weight: 1,
-            guidance: "Does the failure-mode table capture method/exception/rescue/user-visible impact for critical paths?"
-        },
-        {
-            id: "test_coverage_realism",
-            label: "Test coverage realism",
-            weight: 1,
-            guidance: "Is the proposed test split realistic (unit/integration/e2e) with explicit gap handling?"
-        },
-        {
-            id: "performance_budget",
-            label: "Performance budget",
-            weight: 1,
-            guidance: "Are critical metrics, thresholds, and measurement methods concrete and enforceable?"
-        },
-        {
-            id: "observability_adequacy",
-            label: "Observability adequacy",
-            weight: 1,
-            guidance: "Can on-call trace a failure from user symptom to root cause via logs/metrics/traces/alerts?"
-        }
-    ]
-};
-function clampScore(value) {
-    if (Number.isNaN(value))
-        return 0;
-    if (value < 0)
-        return 0;
-    if (value > 1)
-        return 1;
-    return value;
-}
-function normalizeBudget(budget) {
-    const maxIterations = typeof budget?.maxIterations === "number" && Number.isInteger(budget.maxIterations)
-        ? Math.min(Math.max(budget.maxIterations, 1), 10)
-        : REVIEW_LOOP_DEFAULT_MAX_ITERATIONS;
-    const targetScore = typeof budget?.targetScore === "number"
-        ? clampScore(budget.targetScore)
-        : REVIEW_LOOP_DEFAULT_TARGET_SCORE;
-    return { maxIterations, targetScore };
-}
-function formatChecklistForPrompt(checklist) {
-    return checklist
-        .map((dimension, index) => {
-        return `${index + 1}. [${dimension.id}] ${dimension.label} (weight=${dimension.weight})\n   - ${dimension.guidance}`;
-    })
-        .join("\n");
-}
-function formatPriorIterationsForPrompt(priorIterations) {
-    if (priorIterations.length === 0) {
-        return "- none";
-    }
-    return priorIterations
-        .map((row) => {
-        return `- iteration ${row.iteration}: score=${row.qualityScore.toFixed(3)}, findings=${row.findingsCount}`;
-    })
-        .join("\n");
-}
-export function buildOutsideVoiceReviewPrompt(request) {
-    return [
-        "You are the Outside Voice adversarial reviewer.",
-        "Review ONLY the provided artifact markdown and return strict JSON (no prose).",
-        "",
-        `Stage: ${request.stage}`,
-        `Iteration: ${request.iteration}/${request.budget.maxIterations}`,
-        `Target quality score: ${request.budget.targetScore}`,
-        "",
-        "Checklist dimensions:",
-        formatChecklistForPrompt(request.checklist),
-        "",
-        "Prior iterations:",
-        formatPriorIterationsForPrompt(request.priorIterations),
-        "",
-        "Return JSON schema:",
-        REVIEW_LOOP_RESPONSE_SCHEMA
-    ].join("\n");
-}
-export function createOutsideVoiceDispatcher(adapter) {
-    return async (request) => {
-        return adapter({
-            request,
-            prompt: buildOutsideVoiceReviewPrompt(request),
-            responseSchema: REVIEW_LOOP_RESPONSE_SCHEMA
-        });
-    };
-}
-function normalizeSeverity(value) {
-    if (typeof value !== "string")
-        return "important";
-    const normalized = value.trim().toLowerCase();
-    if (normalized === "critical")
-        return "critical";
-    if (normalized === "suggestion")
-        return "suggestion";
-    return "important";
-}
-function asRecord(value) {
-    if (!value || typeof value !== "object" || Array.isArray(value))
-        return null;
-    return value;
-}
-function parseFindings(value, checklist) {
-    if (!Array.isArray(value))
-        return [];
-    const fallbackDimension = checklist[0]?.id ?? "general";
-    const allowedDimensions = new Set(checklist.map((item) => item.id));
-    const findings = [];
-    value.forEach((raw, index) => {
-        const row = asRecord(raw);
-        if (!row)
-            return;
-        const summary = typeof row.summary === "string"
-            ? row.summary.trim()
-            : typeof row.finding === "string"
-                ? row.finding.trim()
-                : "";
-        if (summary.length === 0)
-            return;
-        const requestedDimension = typeof row.dimensionId === "string"
-            ? row.dimensionId
-            : typeof row.dimension === "string"
-                ? row.dimension
-                : fallbackDimension;
-        const dimensionId = allowedDimensions.has(requestedDimension)
-            ? requestedDimension
-            : fallbackDimension;
-        findings.push({
-            id: typeof row.id === "string" && row.id.trim().length > 0
-                ? row.id.trim()
-                : `F-${index + 1}`,
-            dimensionId,
-            severity: normalizeSeverity(row.severity),
-            summary,
-            evidence: typeof row.evidence === "string" ? row.evidence : undefined,
-            recommendation: typeof row.recommendation === "string" ? row.recommendation : undefined
-        });
-    });
-    return findings;
-}
-function inferDimensionScoresFromFindings(checklist, findings) {
-    const byDimension = new Map(checklist.map((dimension) => [dimension.id, 1]));
-    for (const finding of findings) {
-        const current = byDimension.get(finding.dimensionId) ?? 1;
-        const penalty = finding.severity === "critical"
-            ? 0.4
-            : finding.severity === "important"
-                ? 0.2
-                : 0.1;
-        byDimension.set(finding.dimensionId, clampScore(current - penalty));
-    }
-    return checklist.map((dimension) => ({
-        dimensionId: dimension.id,
-        score: byDimension.get(dimension.id) ?? 0,
-        weight: dimension.weight
-    }));
-}
-function parseDimensionScores(value, checklist, findings) {
-    if (!Array.isArray(value)) {
-        return inferDimensionScoresFromFindings(checklist, findings);
-    }
-    const allowedDimensions = new Set(checklist.map((item) => item.id));
-    const parsed = [];
-    value.forEach((raw) => {
-        const row = asRecord(raw);
-        if (!row)
-            return;
-        const rawDimension = typeof row.dimensionId === "string"
-            ? row.dimensionId
-            : typeof row.dimension === "string"
-                ? row.dimension
-                : "";
-        if (!allowedDimensions.has(rawDimension))
-            return;
-        if (typeof row.score !== "number" || Number.isNaN(row.score))
-            return;
-        parsed.push({
-            dimensionId: rawDimension,
-            score: clampScore(row.score),
-            weight: typeof row.weight === "number" ? row.weight : undefined,
-            rationale: typeof row.rationale === "string" ? row.rationale : undefined
-        });
-    });
-    if (parsed.length === 0) {
-        return inferDimensionScoresFromFindings(checklist, findings);
-    }
-    return parsed;
-}
-function unwrapDispatcherPayload(raw) {
-    if (typeof raw === "string") {
-        try {
-            return JSON.parse(raw);
-        }
-        catch {
-            return {
-                findings: [{ summary: raw, severity: "important" }]
-            };
-        }
-    }
-    const record = asRecord(raw);
-    if (!record) {
-        return raw;
-    }
-    const payload = asRecord(record.payload);
-    if (payload && (Array.isArray(payload.findings) || Array.isArray(payload.dimensionScores))) {
-        return payload;
-    }
-    if (typeof record.output === "string") {
-        try {
-            return JSON.parse(record.output);
-        }
-        catch {
-            return { findings: [{ summary: record.output, severity: "important" }] };
-        }
-    }
-    if (typeof record.text === "string") {
-        try {
-            return JSON.parse(record.text);
-        }
-        catch {
-            return { findings: [{ summary: record.text, severity: "important" }] };
-        }
-    }
-    return raw;
-}
-export function parseReviewLoopDispatcherResult(raw, checklist) {
-    const payload = unwrapDispatcherPayload(raw);
-    const record = asRecord(payload);
-    const findings = parseFindings(record?.findings, checklist);
-    const dimensionScores = parseDimensionScores(record?.dimensionScores, checklist, findings);
-    return { findings, dimensionScores };
-}
-function normalizeSecondOpinionPolicy(policy) {
-    const enabled = policy?.enabled === true;
-    const scoreDeltaThreshold = typeof policy?.scoreDeltaThreshold === "number"
-        ? clampScore(policy.scoreDeltaThreshold)
-        : 0.2;
-    const modelLabel = typeof policy?.modelLabel === "string" && policy.modelLabel.trim().length > 0
-        ? policy.modelLabel.trim()
-        : undefined;
-    return { enabled, scoreDeltaThreshold, modelLabel };
-}
-function dedupeFindings(findings) {
-    const seen = new Set();
-    const out = [];
-    for (const finding of findings) {
-        const key = `${finding.dimensionId}:${finding.severity}:${finding.summary.trim().toLowerCase()}`;
-        if (seen.has(key))
-            continue;
-        seen.add(key);
-        out.push(finding);
-    }
-    return out;
-}
-export function mergeSecondOpinionResults(primaryRaw, secondOpinionRaw, checklist, policy) {
-    const normalizedPolicy = normalizeSecondOpinionPolicy(policy);
-    const primary = parseReviewLoopDispatcherResult(primaryRaw, checklist);
-    const secondOpinion = parseReviewLoopDispatcherResult(secondOpinionRaw, checklist);
-    const primaryScore = aggregateQualityScore(primary.dimensionScores, checklist);
-    const secondOpinionScore = aggregateQualityScore(secondOpinion.dimensionScores, checklist);
-    const scoreDelta = Math.abs(primaryScore - secondOpinionScore);
-    const byDimension = new Map();
-    for (const dimension of checklist) {
-        byDimension.set(dimension.id, []);
-    }
-    for (const row of [...primary.dimensionScores, ...secondOpinion.dimensionScores]) {
-        const bucket = byDimension.get(row.dimensionId);
-        if (!bucket)
-            continue;
-        bucket.push(clampScore(row.score));
-    }
-    const dimensionScores = checklist.map((dimension) => {
-        const bucket = byDimension.get(dimension.id) ?? [];
-        const average = bucket.length > 0 ? bucket.reduce((sum, score) => sum + score, 0) / bucket.length : 0;
-        return {
-            dimensionId: dimension.id,
-            score: clampScore(average),
-            weight: dimension.weight
-        };
-    });
-    const findings = dedupeFindings([...primary.findings, ...secondOpinion.findings]);
-    if (scoreDelta >= normalizedPolicy.scoreDeltaThreshold) {
-        findings.push({
-            id: "F-cross-model-disagreement",
-            dimensionId: checklist[0]?.id ?? "general",
-            severity: "important",
-            summary: "Cross-model second opinion found a meaningful quality-score disagreement that needs explicit disposition.",
-            evidence: `primary=${primaryScore.toFixed(3)} secondOpinion=${secondOpinionScore.toFixed(3)} threshold=${normalizedPolicy.scoreDeltaThreshold.toFixed(3)}`,
-            recommendation: "Record why the team accepts one view or synthesize both findings before closing the review loop."
-        });
-    }
-    return {
-        findings,
-        dimensionScores,
-        secondOpinion: {
-            enabled: true,
-            modelLabel: normalizedPolicy.modelLabel,
-            primaryScore,
-            secondOpinionScore,
-            scoreDelta,
-            threshold: normalizedPolicy.scoreDeltaThreshold
-        }
-    };
-}
-export function createSecondOpinionDispatcher(args) {
-    const normalizedPolicy = normalizeSecondOpinionPolicy(args.policy);
-    return async (request) => {
-        const primaryRaw = await args.primary(request);
-        if (!normalizedPolicy.enabled || !args.secondOpinion) {
-            return primaryRaw;
-        }
-        const secondOpinionRaw = await args.secondOpinion(request);
-        return mergeSecondOpinionResults(primaryRaw, secondOpinionRaw, request.checklist, normalizedPolicy);
-    };
-}
-export function aggregateQualityScore(scores, checklist) {
-    if (checklist.length === 0)
-        return 0;
-    const byDimension = new Map(scores.map((row) => [row.dimensionId, row]));
-    let weightedScore = 0;
-    let totalWeight = 0;
-    for (const dimension of checklist) {
-        const scoreRow = byDimension.get(dimension.id);
-        const score = clampScore(scoreRow?.score ?? 0);
-        const weight = typeof scoreRow?.weight === "number" && scoreRow.weight > 0
-            ? scoreRow.weight
-            : dimension.weight;
-        totalWeight += weight;
-        weightedScore += score * weight;
-    }
-    if (totalWeight <= 0)
-        return 0;
-    return clampScore(weightedScore / totalWeight);
-}
-async function materializeArtifactForDispatch(artifactPath, stage, iteration) {
-    const markdown = await fs.readFile(artifactPath, "utf8");
-    const tempDir = await fs.mkdtemp(path.join(os.tmpdir(), `cclaw-review-loop-${stage}-`));
-    const tempArtifactPath = path.join(tempDir, `artifact-iteration-${iteration}.md`);
-    await fs.writeFile(tempArtifactPath, markdown, "utf8");
-    return { tempDir, tempArtifactPath };
-}
-export async function runReviewLoopIteration(input, dispatcher) {
-    const checklist = input.checklist ?? REVIEW_LOOP_CHECKLISTS[input.stage];
-    const budget = normalizeBudget(input.budget);
-    const priorIterations = input.priorIterations ?? [];
-    const { tempDir, tempArtifactPath } = await materializeArtifactForDispatch(input.artifactPath, input.stage, input.iteration);
-    try {
-        const raw = await dispatcher({
-            stage: input.stage,
-            artifactPath: tempArtifactPath,
-            checklist,
-            priorIterations,
-            iteration: input.iteration,
-            budget
-        });
-        const { findings, dimensionScores } = parseReviewLoopDispatcherResult(raw, checklist);
-        const qualityScore = aggregateQualityScore(dimensionScores, checklist);
-        return {
-            qualityScore,
-            findings,
-            iteration: input.iteration,
-            shouldContinue: qualityScore < budget.targetScore && input.iteration < budget.maxIterations,
-            dimensionScores
-        };
-    }
-    finally {
-        await fs.rm(tempDir, { recursive: true, force: true });
-    }
-}
-export function buildReviewLoopEnvelope(args) {
-    return {
-        type: "review-loop",
-        version: "1",
-        stage: args.stage,
-        artifactPath: args.artifactPath,
-        targetScore: args.targetScore,
-        maxIterations: args.maxIterations,
-        stopReason: args.stopReason,
-        iterations: [...args.iterations]
-    };
-}
-function formatScore(value) {
-    return clampScore(value).toFixed(3);
-}
-function reviewLoopHeading(stage) {
-    return stage === "scope" ? "Scope Outside Voice Loop" : "Design Outside Voice Loop";
-}
-function finalEnvelopeScore(envelope) {
-    if (envelope.iterations.length === 0)
-        return 0;
-    return envelope.iterations[envelope.iterations.length - 1].qualityScore;
-}
-export function renderReviewLoopHeader(envelope) {
-    return `> Review Loop Quality: ${formatScore(finalEnvelopeScore(envelope))} | stop: ${envelope.stopReason} | iterations: ${envelope.iterations.length}/${envelope.maxIterations}`;
-}
-export function upsertReviewLoopHeader(markdown, envelope) {
-    const header = renderReviewLoopHeader(envelope);
-    const existingHeader = /^>\s+Review Loop Quality:.*$/m;
-    if (existingHeader.test(markdown)) {
-        return markdown.replace(existingHeader, header);
-    }
-    const firstHeading = /^# .+$/m.exec(markdown);
-    if (!firstHeading || firstHeading.index < 0) {
-        const prefix = markdown.length > 0 ? `${header}\n\n` : `${header}\n`;
-        return `${prefix}${markdown}`;
-    }
-    const headingEnd = firstHeading.index + firstHeading[0].length;
-    return `${markdown.slice(0, headingEnd)}\n\n${header}${markdown.slice(headingEnd)}`;
-}
-export function renderReviewLoopSummarySection(envelope) {
-    const rows = envelope.iterations.length > 0
-        ? envelope.iterations
-            .map((row) => {
-            return `| ${row.iteration} | ${formatScore(row.qualityScore)} | ${row.findingsCount} |`;
-        })
-            .join("\n")
-        : "| 0 | 0.000 | 0 |";
-    const heading = reviewLoopHeading(envelope.stage);
-    return `## ${heading}
-| Iteration | Quality Score | Findings |
-|---|---|---|
-${rows}
-
-- Stop reason: ${envelope.stopReason}
-- Target score: ${formatScore(envelope.targetScore)}
-- Max iterations: ${envelope.maxIterations}`;
-}
-export function upsertReviewLoopSummary(markdown, envelope) {
-    const withHeader = upsertReviewLoopHeader(markdown, envelope);
-    const section = renderReviewLoopSummarySection(envelope);
-    const headingCandidates = [reviewLoopHeading(envelope.stage), "Spec Review Loop"];
-    const match = headingCandidates
-        .map((heading) => {
-        const escapedHeading = heading.replace(/[.*+?^${}()|[\]\\]/gu, "\\$&");
-        return new RegExp(`^##\\s+${escapedHeading}\\s*$`, "m").exec(withHeader);
-    })
-        .find((candidate) => candidate !== null && candidate.index >= 0);
-    if (!match) {
-        const needsBreak = withHeader.endsWith("\n") ? "" : "\n";
-        return `${withHeader}${needsBreak}\n${section}\n`;
-    }
-    const start = match.index;
-    const afterStart = withHeader.slice(start + match[0].length);
-    const nextHeading = /\n##\s+/m.exec(afterStart);
-    const end = nextHeading ? start + match[0].length + nextHeading.index + 1 : withHeader.length;
-    return `${withHeader.slice(0, start)}${section}\n${withHeader.slice(end)}`.replace(/\n{3,}/g, "\n\n");
-}
-function extractH2Section(markdown, heading) {
-    const escaped = heading.replace(/[.*+?^${}()|[\]\\]/gu, "\\$&");
-    const sectionStartRe = new RegExp(`^##\\s+${escaped}\\s*$`, "mi");
-    const startMatch = sectionStartRe.exec(markdown);
-    if (!startMatch || startMatch.index < 0) {
-        return null;
-    }
-    const start = startMatch.index + startMatch[0].length;
-    const rest = markdown.slice(start);
-    const nextHeading = /\n##\s+/m.exec(rest);
-    const end = nextHeading ? start + nextHeading.index + 1 : markdown.length;
-    return markdown.slice(start, end).trim();
-}
-function normalizeStopReason(value) {
-    if (typeof value !== "string")
-        return null;
-    const normalized = value.trim();
-    if (normalized === "quality_threshold_met")
-        return "quality_threshold_met";
-    if (normalized === "max_iterations_reached")
-        return "max_iterations_reached";
-    if (normalized === "user_opt_out")
-        return "user_opt_out";
-    return null;
-}
-function parseScoreCell(value) {
-    const percent = /([0-9]*\.?[0-9]+)\s*%/u.exec(value)?.[1];
-    if (percent !== undefined) {
-        const score = Number(percent) / 100;
-        return Number.isFinite(score) ? clampScore(score) : null;
-    }
-    const direct = Number(value.trim());
-    if (Number.isFinite(direct)) {
-        return clampScore(direct > 1 ? direct / 100 : direct);
-    }
-    const embedded = /([0-9]*\.?[0-9]+)/u.exec(value)?.[1];
-    if (embedded === undefined)
-        return null;
-    const score = Number(embedded);
-    if (!Number.isFinite(score))
-        return null;
-    return clampScore(score > 1 ? score / 100 : score);
-}
-function parseFindingsCountCell(value) {
-    if (/\b(?:none|zero|clear|no findings?|0)\b/iu.test(value))
-        return 0;
-    const match = /(\d+)/u.exec(value);
-    if (!match)
-        return null;
-    const count = Number(match[1]);
-    return Number.isInteger(count) && count >= 0 ? count : null;
-}
-function parseIterationsTable(sectionBody) {
-    const rows = [];
-    const lines = sectionBody.split(/\r?\n/gu);
-    for (const line of lines) {
-        const trimmed = line.trim();
-        if (!trimmed.startsWith("|"))
-            continue;
-        const cells = trimmed
-            .split("|")
-            .slice(1, -1)
-            .map((cell) => cell.trim());
-        if (cells.length < 3)
-            continue;
-        if (/^iteration$/iu.test(cells[0] ?? ""))
-            continue;
-        if (/^-+$/u.test((cells[0] ?? "").replace(/:/gu, "")))
-            continue;
-        const iteration = Number(/(\d+)/u.exec(cells[0] ?? "")?.[1] ?? "");
-        const qualityScore = parseScoreCell(cells[1] ?? "");
-        const findingsCount = parseFindingsCountCell(cells[2] ?? "");
-        if (!Number.isInteger(iteration) || iteration < 1)
-            continue;
-        if (qualityScore === null)
-            continue;
-        if (findingsCount === null)
-            continue;
-        rows.push({
-            iteration,
-            qualityScore,
-            findingsCount
-        });
-    }
-    rows.sort((a, b) => a.iteration - b.iteration);
-    return rows;
-}
-function parseHeaderMeta(markdown) {
-    const match = /^>\s*Review Loop Quality:\s*([0-9]*\.?[0-9]+)\s*\|\s*stop:\s*([a-z_]+)\s*\|\s*iterations:\s*(\d+)\s*\/\s*(\d+)\s*$/mi.exec(markdown);
-    if (!match)
-        return {};
-    const score = Number(match[1]);
-    const stopReason = normalizeStopReason(match[2] ?? "");
-    const iterations = Number(match[3]);
-    const maxIterations = Number(match[4]);
-    return {
-        score: Number.isFinite(score) ? clampScore(score) : undefined,
-        stopReason: stopReason ?? undefined,
-        iterations: Number.isInteger(iterations) ? iterations : undefined,
-        maxIterations: Number.isInteger(maxIterations) ? maxIterations : undefined
-    };
-}
-export function extractReviewLoopEnvelopeFromArtifact(markdown, stage, artifactPath) {
-    const sectionBody = extractH2Section(markdown, reviewLoopHeading(stage))
-        ?? extractH2Section(markdown, "Spec Review Loop");
-    if (!sectionBody)
-        return null;
-    const iterations = parseIterationsTable(sectionBody);
-    if (iterations.length === 0)
-        return null;
-    const stopReasonFromSection = normalizeStopReason(/-\s*Stop reason:\s*([a-z_]+)/iu.exec(sectionBody)?.[1]);
-    const targetFromSection = parseScoreCell(/-\s*Target score:\s*([^\n]+)/iu.exec(sectionBody)?.[1] ?? "");
-    const maxFromSection = Number(/-\s*Max iterations:\s*(\d+)/iu.exec(sectionBody)?.[1] ?? "");
-    const header = parseHeaderMeta(markdown);
-    const targetScore = targetFromSection !== null
-        ? targetFromSection
-        : REVIEW_LOOP_DEFAULT_TARGET_SCORE;
-    const maxIterationsCandidate = Number.isInteger(maxFromSection) && maxFromSection > 0
-        ? maxFromSection
-        : Number.isInteger(header.maxIterations) && (header.maxIterations ?? 0) > 0
-            ? header.maxIterations
-            : REVIEW_LOOP_DEFAULT_MAX_ITERATIONS;
-    const maxIterations = Math.max(maxIterationsCandidate, iterations.length);
-    const stopReason = stopReasonFromSection
-        ?? header.stopReason
-        ?? (iterations[iterations.length - 1].qualityScore >= targetScore
-            ? "quality_threshold_met"
-            : iterations.length >= maxIterations
-                ? "max_iterations_reached"
-                : "user_opt_out");
-    return {
-        type: "review-loop",
-        version: "1",
-        stage,
-        artifactPath,
-        targetScore,
-        maxIterations,
-        stopReason,
-        iterations
-    };
-}
-export function toSkillEnvelope(envelope, emittedAt = new Date().toISOString(), agent) {
-    return {
-        version: "1",
-        kind: "stage-output",
-        stage: envelope.stage,
-        payload: envelope,
-        emittedAt,
-        ...(agent ? { agent } : {})
-    };
-}
-export async function runReviewLoop(input, options) {
-    const budget = normalizeBudget(input.budget);
-    const prior = [...(input.priorIterations ?? [])];
-    const iterations = [];
-    let stopReason = "max_iterations_reached";
-    while (iterations.length < budget.maxIterations) {
-        if (options.shouldOptOut?.()) {
-            stopReason = "user_opt_out";
-            break;
-        }
-        const iteration = prior.length + iterations.length + 1;
-        const result = await runReviewLoopIteration({
-            ...input,
-            iteration,
-            priorIterations: [
-                ...prior,
-                ...iterations.map((row) => ({
-                    iteration: row.iteration,
-                    qualityScore: row.qualityScore,
-                    findingsCount: row.findings.length
-                }))
-            ]
-        }, options.dispatcher);
-        iterations.push(result);
-        await options.applyFindings(result);
-        if (result.qualityScore >= budget.targetScore) {
-            stopReason = "quality_threshold_met";
-            break;
-        }
-        if (iterations.length >= budget.maxIterations) {
-            stopReason = "max_iterations_reached";
-            break;
-        }
-    }
-    const summaryRows = [
-        ...prior,
-        ...iterations.map((row) => ({
-            iteration: row.iteration,
-            qualityScore: row.qualityScore,
-            findingsCount: row.findings.length
-        }))
-    ];
-    const finalQualityScore = summaryRows.length > 0 ? summaryRows[summaryRows.length - 1].qualityScore : 0;
-    const envelope = buildReviewLoopEnvelope({
-        stage: input.stage,
-        artifactPath: input.artifactPath,
-        targetScore: budget.targetScore,
-        maxIterations: budget.maxIterations,
-        stopReason,
-        iterations: summaryRows
-    });
-    options.emitEnvelope?.(envelope);
-    return {
-        iterations,
-        qualityScore: finalQualityScore,
-        stopReason,
-        envelope
-    };
-}
-export function isReviewLoopStage(stage) {
-    return REVIEW_LOOP_STAGES.includes(stage);
+        id: "scope-creep",
+        name: "Scope creep",
+        description: "Changes outside the declared AC. If the diff touches files no AC mentions, surface the question instead of proceeding."
+    },
+    {
+        id: "cascading-errors",
+        name: "Cascading errors",
+        description: "One fix introduces new failures (typecheck, runtime, tests). Verify build/typecheck/test is green for the affected files after each change."
+    },
+    {
+        id: "context-loss",
+        name: "Context loss",
+        description: "Earlier decisions, constraints, or AC text are forgotten. Re-read plan.md frontmatter and AC list before each iteration."
+    },
+    {
+        id: "tool-misuse",
+        name: "Tool misuse",
+        description: "Tool used in the wrong mode or without understanding effects (force pushes, destructive deletes, ambiguous patches). Pause and ask."
+    }
+];
+export const REVIEW_ITERATION_HARD_CAP = 5;
+export function failureModesChecklist() {
+    const items = FIVE_FAILURE_MODES.map((mode, index) => `${index + 1}. **${mode.name}** — ${mode.description}`).join("\n");
+    return `### Review checklist — Five Failure Modes\n\n${items}\n\nHard cap: stop after ${REVIEW_ITERATION_HARD_CAP} review/fix iterations and report what remains.`;
 }