@tea-agent/loop-agent 0.38.2 → 0.38.4

package/dist/workflows/dag/structured-output-repair.js

@@ -0,0 +1,712 @@
+import { createHash } from "node:crypto";
+import { readFile, realpath, stat, open } from "node:fs/promises";
+import path from "node:path";
+import { z } from "zod";
+import { writeTextArtifactFile } from "../../infrastructure/harness/artifact-store.js";
+function sha256Hex(input) {
+    return createHash("sha256").update(input, "utf8").digest("hex");
+}
+function sortKeysDeep(value) {
+    if (Array.isArray(value))
+        return value.map(sortKeysDeep);
+    if (value && typeof value === "object") {
+        const record = value;
+        const sorted = {};
+        for (const key of Object.keys(record).sort()) {
+            sorted[key] = sortKeysDeep(record[key]);
+        }
+        return sorted;
+    }
+    return value;
+}
+function serializeDeterministicJson(value) {
+    return JSON.stringify(sortKeysDeep(value), null, 2);
+}
+async function writeDeterministicJsonArtifact(runDir, relativePath, value) {
+    const json = `${serializeDeterministicJson(value)}\n`;
+    const targetPath = path.join(runDir, relativePath);
+    await writeTextArtifactFile(targetPath, json);
+    return { path: targetPath, sha256: sha256Hex(json) };
+}
+export const STRUCTURED_OUTPUT_REPAIR_CONTEXT_SCHEMA_ID = "frontend-structured-output-repair-context-v1";
+export const FRONTEND_STRUCTURED_REPAIR_SCHEMA_IDS = [
+    "frontend-implementation-contract-plan-patch-v1",
+    "frontend-implementation-contract-revision-patch-v1",
+];
+export const STRUCTURED_REPAIR_EXHAUSTED_CATEGORY = "structured-repair-exhausted";
+export const GOVERNANCE_BLOCKED_CATEGORY = "governance-blocked";
+export const STRUCTURED_REPAIR_MAX_INLINE_BYTES = 65_536;
+export const STRUCTURED_REPAIR_MAX_CANDIDATE_BYTES = 65_536;
+const sha256Schema = z.string().regex(/^[a-f0-9]{64}$/);
+export const structuredOutputRepairContextSchema = z
+    .object({
+    schemaVersion: z.literal(1),
+    schemaId: z.literal(STRUCTURED_OUTPUT_REPAIR_CONTEXT_SCHEMA_ID),
+    taskId: z.string().min(1),
+    runId: z.string().min(1),
+    nodeId: z.string().min(1),
+    nodeAttempt: z.number().int().positive(),
+    targetSchemaId: z.string().min(1),
+    originalPrompt: z
+        .object({
+        path: z.string().min(1),
+        sha256: sha256Schema,
+    })
+        .strict()
+        .optional(),
+    runtimeSkeleton: z
+        .object({
+        path: z.string().min(1),
+        sha256: sha256Schema,
+    })
+        .strict(),
+    previousOutputs: z.array(z
+        .object({
+        attempt: z.number().int().positive(),
+        path: z.string().min(1),
+        sha256: sha256Schema,
+        stopReason: z.string().min(1).optional(),
+        inlinePolicy: z.enum(["inline", "head-tail", "digest"]),
+    })
+        .strict()),
+    validationHistory: z.array(z
+        .object({
+        attempt: z.number().int().positive(),
+        classification: z.string().min(1),
+        errors: z.array(z
+            .object({
+            path: z.string().min(1),
+            code: z.string().min(1),
+            message: z.string().min(1),
+        })
+            .strict()),
+    })
+        .strict()),
+    conversationEvidence: z
+        .object({
+        successfulReadPaths: z.array(z.string()),
+        appliedCitations: z.array(z.string()),
+    })
+        .strict(),
+    budget: z
+        .object({
+        maxInlineBytes: z.number().int().positive(),
+        maxCandidateBytes: z.number().int().positive(),
+    })
+        .strict(),
+    instructions: z
+        .object({
+        repairOnly: z.literal(true),
+        reemitCompleteOutput: z.literal(true),
+        preserveValidDecisions: z.literal(true),
+        doNotRepeatRepositoryResearch: z.literal(true),
+    })
+        .strict(),
+})
+    .strict();
+export function isFrontendStructuredRepairSchemaId(schemaId) {
+    return (schemaId !== undefined &&
+        FRONTEND_STRUCTURED_REPAIR_SCHEMA_IDS.includes(schemaId));
+}
+export function isStructuredRepairableFailureCategory(category) {
+    return (category === "invalid-output" ||
+        category === "structured-output-truncated" ||
+        category === "output-too-large" ||
+        category === "empty-output");
+}
+export function formatStructuredArtifactPointer(input) {
+    return [
+        "Frontend structured artifact (canonical contract). Read the JSON file with the read tool; do not parse this pointer as the contract body.",
+        `path: ${input.path}`,
+        `schema: ${input.schemaId}`,
+        `sha256: ${input.sha256}`,
+    ].join("\n");
+}
+export function stripStructuredOutputBom(text) {
+    return text.charCodeAt(0) === 0xfeff ? text.slice(1) : text;
+}
+export function classifyStructuredContractFailure(input) {
+    const reason = input.reason;
+    const errors = [
+        { path: "$", code: "invalid-output", message: reason },
+    ];
+    if (input.kind === "blocked") {
+        return { classification: "governance-blocked", errors };
+    }
+    if (input.stopReason === "length") {
+        return { classification: "truncated", errors };
+    }
+    const lower = reason.toLowerCase();
+    if (lower.includes("runtime-protected paths")) {
+        return { classification: "schema", errors };
+    }
+    if (lower.includes("sourcebinding") ||
+        lower.includes("runtime skeleton") ||
+        lower.includes("blocking evidence gap") ||
+        lower.includes("does not cover") ||
+        lower.includes("absolute frontend contract path") ||
+        lower.includes("escapes") ||
+        lower.includes("secret")) {
+        return { classification: "governance-blocked", errors };
+    }
+    if (lower.includes("unterminated") ||
+        lower.includes("unexpected end") ||
+        lower.includes("end of data") ||
+        lower.includes("truncated")) {
+        return { classification: "truncated", errors };
+    }
+    if (lower.includes("openspec-citations") ||
+        lower.includes("fenced json") ||
+        lower.includes("exactly one") ||
+        lower.includes("must extract") ||
+        lower.includes("must contain exactly one")) {
+        return { classification: "format", errors };
+    }
+    if (lower.includes("contradict") ||
+        lower.includes("incompatible") ||
+        lower.includes("mutually")) {
+        return { classification: "semantic-repair", errors };
+    }
+    return { classification: "schema", errors };
+}
+export function candidateDirRel(nodeId) {
+    return path.posix.join("contracts", "candidates", nodeId);
+}
+export function attemptRawRel(nodeId, attempt) {
+    return path.posix.join(candidateDirRel(nodeId), `attempt-${attempt}.raw.md`);
+}
+export function repairContextRel(nodeId, attempt) {
+    return path.posix.join(candidateDirRel(nodeId), `attempt-${attempt}.repair-context.json`);
+}
+export function runtimeSkeletonRel(nodeId) {
+    return path.posix.join(candidateDirRel(nodeId), "runtime-skeleton.json");
+}
+export function canonicalContractRel(nodeId) {
+    return path.posix.join(candidateDirRel(nodeId), "canonical-contract.json");
+}
+export function openspecCitationsRel(nodeId) {
+    return path.posix.join(candidateDirRel(nodeId), "openspec-citations.json");
+}
+export async function persistRuntimeSkeleton(input) {
+    const relativePath = runtimeSkeletonRel(input.nodeId);
+    const written = await writeDeterministicJsonArtifact(input.runDir, relativePath, input.skeleton);
+    return { path: written.path, sha256: written.sha256, relativePath };
+}
+export async function persistStructuredAttemptRaw(input) {
+    const relativePath = attemptRawRel(input.nodeId, input.attempt);
+    await writeTextArtifactFile(path.join(input.runDir, relativePath), input.text.endsWith("\n") ? input.text : `${input.text}\n`);
+    return relativePath;
+}
+export async function hasNonEmptyStructuredCandidate(input) {
+    for (let attempt = 1; attempt < input.beforeAttempt; attempt += 1) {
+        const rawPath = path.join(input.runDir, attemptRawRel(input.nodeId, attempt));
+        try {
+            const text = await readFile(rawPath, "utf8");
+            if (text.trim().length > 0)
+                return true;
+        }
+        catch (error) {
+            if (error.code !== "ENOENT")
+                throw error;
+        }
+    }
+    return false;
+}
+export async function assertRunOwnedPath(runDir, candidate) {
+    const resolvedRun = await realpath(runDir).catch(async () => path.resolve(runDir));
+    const resolved = path.resolve(resolvedRun, candidate);
+    const relative = path.relative(resolvedRun, resolved);
+    if (!relative || relative.startsWith("..") || path.isAbsolute(relative)) {
+        throw new Error(`repair context path escapes runDir: ${candidate}`);
+    }
+    try {
+        const real = await realpath(resolved);
+        const realRel = path.relative(resolvedRun, real);
+        if (!realRel || realRel.startsWith("..") || path.isAbsolute(realRel)) {
+            throw new Error(`repair context path escapes runDir via symlink: ${candidate}`);
+        }
+        return real;
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return resolved;
+        throw error;
+    }
+}
+function headTailExcerpt(text, budget) {
+    if (text.length <= budget)
+        return text;
+    const half = Math.max(256, Math.floor(budget / 2) - 20);
+    return `${text.slice(0, half)}\n…[truncated]…\n${text.slice(-half)}`;
+}
+async function sha256File(absPath) {
+    const bytes = await readFile(absPath);
+    return createHash("sha256").update(bytes).digest("hex");
+}
+async function readOptionalText(absPath) {
+    try {
+        return await readFile(absPath, "utf8");
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return undefined;
+        throw error;
+    }
+}
+function eventArgs(event) {
+    return event.args ?? event.toolInput ?? event.input ?? {};
+}
+/**
+ * Current byte length of a node's session-events.jsonl (0 when missing).
+ * Captured before an executor attempt appends its events so audits can be
+ * scoped to that attempt's segment only.
+ */
+export async function sessionEventsByteLength(runDir, nodeId) {
+    try {
+        return (await stat(path.join(runDir, nodeId, "session-events.jsonl")))
+            .size;
+    }
+    catch {
+        return 0;
+    }
+}
+export async function collectSuccessfulReadPaths(input) {
+    const eventsPath = path.join(input.runDir, input.nodeId, "session-events.jsonl");
+    const raw = await readOptionalText(eventsPath);
+    if (!raw)
+        return [];
+    const matched = new Set();
+    const started = new Map();
+    for (const line of raw.split(/\r?\n/)) {
+        const trimmed = line.trim();
+        if (!trimmed)
+            continue;
+        let event;
+        try {
+            event = JSON.parse(trimmed);
+        }
+        catch {
+            continue;
+        }
+        if (event.type === "tool_execution_start" && event.toolName === "read") {
+            const readPath = eventArgs(event).path;
+            if (typeof readPath === "string" && event.toolCallId) {
+                started.set(event.toolCallId, readPath);
+            }
+        }
+        else if (event.type === "tool_execution_end" &&
+            event.toolName === "read" &&
+            event.toolCallId) {
+            const readPath = started.get(event.toolCallId);
+            if (readPath)
+                matched.add(readPath);
+            started.delete(event.toolCallId);
+        }
+    }
+    return [...matched];
+}
+export async function auditRepairAttemptToolUse(input) {
+    const eventsPath = path.join(input.runDir, input.nodeId, "session-events.jsonl");
+    let raw;
+    if (input.eventText !== undefined) {
+        raw = input.eventText;
+    }
+    else {
+        raw = await readSessionEventsFromOffset(eventsPath, input.fromByteOffset);
+    }
+    if (!raw)
+        return { ok: true };
+    const allowed = new Set(input.allowedPaths.map((entry) => path.resolve(input.runDir, entry)));
+    const isAllowed = (candidate) => {
+        const resolved = path.resolve(input.runDir, candidate);
+        if (allowed.has(resolved))
+            return true;
+        for (const entry of allowed) {
+            const rel = path.relative(entry, resolved);
+            if (rel === "" || (!rel.startsWith("..") && !path.isAbsolute(rel))) {
+                return true;
+            }
+        }
+        return false;
+    };
+    for (const line of raw.split(/\r?\n/)) {
+        const trimmed = line.trim();
+        if (!trimmed)
+            continue;
+        let event;
+        try {
+            event = JSON.parse(trimmed);
+        }
+        catch {
+            continue;
+        }
+        if (event.type !== "tool_execution_start" || !event.toolName)
+            continue;
+        if (event.toolName !== "read") {
+            return {
+                ok: false,
+                reason: `repair attempt used disallowed tool ${event.toolName}`,
+            };
+        }
+        const readPath = eventArgs(event).path;
+        if (typeof readPath === "string" && !isAllowed(readPath)) {
+            return {
+                ok: false,
+                reason: `repair attempt read path is outside the frozen allowlist: ${readPath}`,
+            };
+        }
+    }
+    return { ok: true };
+}
+/**
+ * Read session-events.jsonl from a byte offset, tolerating a mid-character
+ * cut by aligning to the next newline boundary. Returns undefined when the
+ * file is missing or the offset is at/after EOF (nothing new to audit).
+ */
+async function readSessionEventsFromOffset(eventsPath, fromByteOffset) {
+    if (!fromByteOffset || fromByteOffset <= 0) {
+        return readOptionalText(eventsPath);
+    }
+    let handle;
+    try {
+        handle = await open(eventsPath, "r");
+    }
+    catch {
+        return undefined;
+    }
+    try {
+        const size = (await handle.stat()).size;
+        if (fromByteOffset >= size)
+            return undefined;
+        // The offset is captured after the previous attempt's fully drained
+        // appends, so it normally lands at a line start. Verify by reading one
+        // byte before the offset: when it is not a newline the offset lands
+        // mid-line (or mid-UTF-8) and the partial first line must be dropped by
+        // aligning to the next newline; otherwise audit from the offset itself.
+        const before = Buffer.alloc(1);
+        await handle.read(before, 0, 1, fromByteOffset - 1);
+        const aligned = before[0] === 0x0a ? fromByteOffset : -1;
+        const start = aligned >= 0 ? aligned : await findNextNewlineOffset(handle, fromByteOffset, size);
+        if (start < 0 || start >= size)
+            return undefined;
+        const length = size - start;
+        const buffer = Buffer.alloc(length);
+        await handle.read(buffer, 0, length, start);
+        return buffer.toString("utf8");
+    }
+    finally {
+        await handle.close();
+    }
+}
+/**
+ * Scan forward from an arbitrary offset for the next newline boundary when
+ * the captured offset lands mid-line. Bounded by file size.
+ */
+async function findNextNewlineOffset(handle, fromByteOffset, size) {
+    const chunk = Buffer.alloc(4096);
+    let position = fromByteOffset;
+    while (position < size) {
+        const readLength = Math.min(chunk.byteLength, size - position);
+        const { bytesRead } = await handle.read(chunk, 0, readLength, position);
+        if (bytesRead <= 0)
+            return -1;
+        const newlineIndex = chunk.subarray(0, bytesRead).indexOf(0x0a);
+        if (newlineIndex !== -1)
+            return position + newlineIndex + 1;
+        position += bytesRead;
+    }
+    return -1;
+}
+async function loadValidationHistory(input) {
+    const history = [];
+    for (let attempt = 1; attempt < input.beforeAttempt; attempt += 1) {
+        const reportPath = path.join(input.runDir, candidateDirRel(input.nodeId), `attempt-${attempt}.validation.json`);
+        const raw = await readOptionalText(reportPath);
+        if (!raw)
+            continue;
+        try {
+            const parsed = JSON.parse(raw);
+            history.push({
+                attempt,
+                classification: parsed.classification ?? "schema",
+                errors: (parsed.errors ?? []).map((error) => ({
+                    path: error.path ?? "$",
+                    code: error.code ?? "invalid-output",
+                    message: error.message ?? "invalid structured output",
+                })),
+            });
+        }
+        catch {
+            history.push({
+                attempt,
+                classification: "schema",
+                errors: [{ path: "$", code: "invalid-output", message: "unreadable validation report" }],
+            });
+        }
+    }
+    return history;
+}
+export async function freezeStructuredOutputRepairContext(input) {
+    if (input.nodeAttempt <= 1) {
+        throw new Error("repair context is only frozen for attempt>1");
+    }
+    const skeletonSource = input.skeleton ??
+        input.originalCanonical ??
+        undefined;
+    if (!skeletonSource) {
+        throw new Error("repair context requires a runtime skeleton or original canonical contract");
+    }
+    const skeleton = await persistRuntimeSkeleton({
+        runDir: input.runDir,
+        nodeId: input.nodeId,
+        skeleton: skeletonSource,
+    });
+    await assertRunOwnedPath(input.runDir, skeleton.relativePath);
+    const previousOutputs = [];
+    for (let attempt = 1; attempt < input.nodeAttempt; attempt += 1) {
+        const relativePath = attemptRawRel(input.nodeId, attempt);
+        const absPath = path.join(input.runDir, relativePath);
+        try {
+            await stat(absPath);
+        }
+        catch (error) {
+            if (error.code === "ENOENT")
+                continue;
+            throw error;
+        }
+        await assertRunOwnedPath(input.runDir, relativePath);
+        const digest = await sha256File(absPath);
+        const isLatest = attempt === input.nodeAttempt - 1;
+        previousOutputs.push({
+            attempt,
+            path: relativePath,
+            sha256: digest,
+            ...(isLatest && input.latestStopReason
+                ? { stopReason: input.latestStopReason }
+                : {}),
+            inlinePolicy: isLatest ? "inline" : "digest",
+        });
+    }
+    const originalPromptPath = path.posix.join(input.nodeId, "prompt.redacted.md");
+    let originalPrompt;
+    const originalAbs = path.join(input.runDir, originalPromptPath);
+    if (await readOptionalText(originalAbs)) {
+        await assertRunOwnedPath(input.runDir, originalPromptPath);
+        originalPrompt = {
+            path: originalPromptPath,
+            sha256: await sha256File(originalAbs),
+        };
+    }
+    const successfulReadPaths = await collectSuccessfulReadPaths({
+        runDir: input.runDir,
+        nodeId: input.nodeId,
+    });
+    const citationsPath = path.join(input.runDir, openspecCitationsRel(input.nodeId));
+    const citationsRaw = await readOptionalText(citationsPath);
+    const appliedCitations = [];
+    if (citationsRaw) {
+        try {
+            const parsed = JSON.parse(citationsRaw);
+            for (const citation of parsed.citations ?? []) {
+                if (typeof citation.path === "string" && citation.path.trim()) {
+                    appliedCitations.push(citation.path);
+                }
+            }
+        }
+        catch {
+            // Citations are evidence, not a blocker for repair.
+        }
+    }
+    const context = {
+        schemaVersion: 1,
+        schemaId: STRUCTURED_OUTPUT_REPAIR_CONTEXT_SCHEMA_ID,
+        taskId: input.taskId,
+        runId: input.runId,
+        nodeId: input.nodeId,
+        nodeAttempt: input.nodeAttempt,
+        targetSchemaId: input.targetSchemaId,
+        ...(originalPrompt ? { originalPrompt } : {}),
+        runtimeSkeleton: {
+            path: skeleton.relativePath,
+            sha256: skeleton.sha256,
+        },
+        previousOutputs,
+        validationHistory: await loadValidationHistory({
+            runDir: input.runDir,
+            nodeId: input.nodeId,
+            beforeAttempt: input.nodeAttempt,
+        }),
+        conversationEvidence: {
+            successfulReadPaths,
+            appliedCitations,
+        },
+        budget: {
+            maxInlineBytes: STRUCTURED_REPAIR_MAX_INLINE_BYTES,
+            maxCandidateBytes: STRUCTURED_REPAIR_MAX_CANDIDATE_BYTES,
+        },
+        instructions: {
+            repairOnly: true,
+            reemitCompleteOutput: true,
+            preserveValidDecisions: true,
+            doNotRepeatRepositoryResearch: true,
+        },
+    };
+    const parsed = structuredOutputRepairContextSchema.parse(context);
+    const relativePath = repairContextRel(input.nodeId, input.nodeAttempt);
+    const written = await writeDeterministicJsonArtifact(input.runDir, relativePath, parsed);
+    await assertRunOwnedPath(input.runDir, relativePath);
+    return {
+        context: parsed,
+        relativePath,
+        sha256: written.sha256,
+        absolutePath: written.path,
+    };
+}
+async function loadInlineCandidate(input) {
+    const absPath = await assertRunOwnedPath(input.runDir, input.entry.path);
+    const digest = await sha256File(absPath);
+    if (digest !== input.entry.sha256) {
+        throw new Error(`repair context previous output hash mismatch: ${input.entry.path}`);
+    }
+    const text = await readFile(absPath, "utf8");
+    if (input.entry.inlinePolicy === "digest") {
+        return `(attempt ${input.entry.attempt} digest ${digest})`;
+    }
+    if (input.entry.inlinePolicy === "head-tail" || text.length > input.budget) {
+        return headTailExcerpt(text, Math.min(input.budget, STRUCTURED_REPAIR_MAX_CANDIDATE_BYTES));
+    }
+    return text;
+}
+export async function buildStructuredOutputRepairPrompt(input) {
+    const skeletonAbs = await assertRunOwnedPath(input.runDir, input.context.runtimeSkeleton.path);
+    const skeletonDigest = await sha256File(skeletonAbs);
+    if (skeletonDigest !== input.context.runtimeSkeleton.sha256) {
+        throw new Error("repair context runtime skeleton hash mismatch");
+    }
+    const skeletonText = await readFile(skeletonAbs, "utf8");
+    const latest = [...input.context.previousOutputs].sort((left, right) => right.attempt - left.attempt)[0];
+    const excerpts = [];
+    let remaining = input.context.budget.maxInlineBytes -
+        Buffer.byteLength(skeletonText, "utf8");
+    if (latest) {
+        const latestText = await loadInlineCandidate({
+            runDir: input.runDir,
+            entry: latest,
+            budget: Math.min(remaining, input.context.budget.maxCandidateBytes),
+        });
+        excerpts.push(`### Latest failed candidate (attempt ${latest.attempt}${latest.stopReason ? `, stopReason=${latest.stopReason}` : ""})\n${latestText}`);
+        remaining -= Buffer.byteLength(latestText, "utf8");
+    }
+    for (const entry of input.context.previousOutputs) {
+        if (latest && entry.attempt === latest.attempt)
+            continue;
+        if (remaining <= 0)
+            break;
+        const digestLine = `attempt ${entry.attempt} ${entry.path} sha256=${entry.sha256}`;
+        excerpts.push(`### Earlier candidate\n${digestLine}`);
+        remaining -= Buffer.byteLength(digestLine, "utf8");
+    }
+    const errorLines = input.context.validationHistory.flatMap((entry) => entry.errors.map((error) => `- attempt ${entry.attempt} [${entry.classification}] ${error.path}: ${error.message}`));
+    const clippedErrors = Buffer.byteLength(errorLines.join("\n"), "utf8") > 8_192
+        ? errorLines.slice(0, 24)
+        : errorLines;
+    return [
+        `STRUCTURED_OUTPUT_REPAIR attempt=${input.context.nodeAttempt}/${input.maxAttempts}`,
+        "",
+        "Repair the existing structured result using the frozen repair context attached",
+        "to this session. Do not re-plan, repeat repository research, or add unsupported",
+        "requirements. Preserve all valid decisions from previous attempts.",
+        "",
+        "Review the latest candidate and the cumulative validation history. When an",
+        "earlier output was truncated, recover missing content from the runtime",
+        "skeleton, successful read/citation evidence, and compact previous-output",
+        "excerpts. Do not reread the full original planner prompt.",
+        "",
+        "Return one complete standalone replacement from the beginning. Never return",
+        "only a suffix and never rely on concatenation with a previous output.",
+        "",
+        "## Tool contract (hard requirement)",
+        "This repair attempt allows ONLY the `read` tool, and only on paths listed",
+        "in the frozen repair context (the context file itself, the runtime skeleton,",
+        "the original prompt reference, previous output candidates, and the",
+        "successful read / citation evidence below). Every other tool — grep, find,",
+        "ls, bash, or any write — is forbidden this attempt and fails the node as",
+        "governance-blocked. Reading any path outside the allowlist fails the same",
+        "way. Do not open repository files, templates, or docs to answer format",
+        "questions: use the schema guidance in this prompt instead.",
+        "",
+        "## Frozen repair context",
+        `- path: ${input.contextPath}`,
+        `- sha256: ${input.contextSha256}`,
+        `- targetSchemaId: ${input.context.targetSchemaId}`,
+        "",
+        "## Runtime skeleton (never trimmed)",
+        "```json",
+        skeletonText.trimEnd(),
+        "```",
+        "",
+        "## Previous outputs",
+        excerpts.join("\n\n") || "(none)",
+        "",
+        "## Validation history",
+        clippedErrors.join("\n") || "(none)",
+        "",
+        "## Successful read / citation evidence",
+        input.context.conversationEvidence.successfulReadPaths
+            .map((entry) => `- read: ${entry}`)
+            .join("\n") || "(none)",
+        input.context.conversationEvidence.appliedCitations
+            .map((entry) => `- citation: ${entry}`)
+            .join("\n"),
+        "",
+        "## Schema-specific guidance",
+        ...input.schemaGuidance,
+        ...(input.previousReason
+            ? ["", "## Previous validator reason", input.previousReason]
+            : []),
+        "",
+        "Fix every reported field violation: do not emit null for optional fields, do not misspell field names, and match the required types exactly.",
+    ]
+        .filter((line) => line !== undefined)
+        .join("\n");
+}
+export function allowedRepairReadPaths(input) {
+    return [
+        input.contextPath,
+        input.context.runtimeSkeleton.path,
+        input.context.originalPrompt?.path,
+        ...input.context.previousOutputs.map((entry) => entry.path),
+        ...input.context.conversationEvidence.successfulReadPaths,
+        ...input.context.conversationEvidence.appliedCitations,
+    ]
+        .filter((entry) => Boolean(entry))
+        .map((entry) => path.resolve(input.runDir, entry));
+}
+export function parseOpenspecCitationsBlock(text) {
+    const match = text.match(/```openspec-citations[ \t]*\r?\n([\s\S]*?)\r?\n```/);
+    if (!match) {
+        return { block: "", citations: [] };
+    }
+    const citations = [];
+    for (const rawLine of (match[1] ?? "").split(/\r?\n/)) {
+        const line = rawLine.trim();
+        if (!line)
+            continue;
+        try {
+            const parsed = JSON.parse(line);
+            if (typeof parsed.path !== "string" || !parsed.path.trim())
+                continue;
+            citations.push({
+                path: parsed.path,
+                section: typeof parsed.section === "string" ? parsed.section : "",
+                line: typeof parsed.line === "number" && Number.isInteger(parsed.line)
+                    ? parsed.line
+                    : null,
+            });
+        }
+        catch {
+            // Keep the raw block even when a row is unparseable.
+        }
+    }
+    return { block: match[0], citations };
+}