@bridge_gpt/mcp-server 0.2.60 → 0.2.65

package/build/epic-coherence-input.js

@@ -0,0 +1,920 @@
+/**
+ * BAPI-1320: build and structurally check the normalized epic-coherence input
+ * document (`epic-coherence-input.json`) that `review-epic-coherence.md` reviews.
+ *
+ * Why this lives in the packaged MCP server: the procedure ships to consumer
+ * repositories, where `mcp_server/src/` does not exist. A repository script
+ * would only exist here, so the packaged `epic-coherence-input` subcommand is
+ * the reachable surface for authors who draft an epic as local markdown files.
+ *
+ * Two rules the first real run (BAPI-1316) showed are load-bearing:
+ *  - epic ACs are matched by their explicit id (`AC-3:`), never by position or
+ *    keyword;
+ *  - files a child only reads (`reads` -> `read_files`) are kept apart from the
+ *    files it edits (`edits` -> `touched_files`).
+ *
+ * The checker is structural only. It never judges coverage — that stays the
+ * reviewer's job. All I/O goes through an injectable seam so tests never touch
+ * a real disk.
+ */
+import { createHash } from "node:crypto";
+import path from "node:path";
+import { writeJsonAtomically, } from "./conductor-bundle-artifacts.js";
+// ===========================================================================
+// Constants
+// ===========================================================================
+/**
+ * The high-risk edit prefixes from the procedure's "Escalation rule". An
+ * unclassified backticked path under one of these is a build error, because
+ * whether a child edits or only reads it decides the epic's risk tier.
+ */
+export const HIGH_RISK_PATH_PREFIXES = [
+    "db/migrations/",
+    "db/alembic/",
+    "api/library/billing/",
+    "api/routes/setup/auth.py",
+    "api/library/auth/",
+    "mcp_server/src/executor/",
+    "mcp_server/src/agent-launchers/",
+    "mcp_server/src/claude-settings.ts",
+    ".github/workflows/",
+    "tests/integration/conductor_harness/",
+    "api/library/db/",
+];
+const EPIC_KEY_PATTERN = /^[A-Z][A-Z0-9]+-\d+$/;
+const EPIC_SLUG_PATTERN = /^[a-z0-9][a-z0-9-]*$/;
+const AC_ID_PATTERN = /^AC-\d+$/;
+const EPIC_AC_BULLET = /^[-*]\s+(?:\*\*)?(AC-\d+):(?:\*\*)?(?:\s+(.*))?$/;
+const TOP_LEVEL_BULLET = /^[-*]\s+(.*)$/;
+const VERIFICATION_LABEL = /(?:\*\*)?Verification:(?:\*\*)?/;
+const BACKTICK_SPAN = /`([^`\n]+)`/g;
+const REPO_PATH_SHAPE = /^[A-Za-z0-9_.@-]+(?:\/[A-Za-z0-9_.@-]+)*\/?$/;
+// ===========================================================================
+// Canonical encoding and digests
+// ===========================================================================
+/** Raised when a value has no encoding identical to the procedure's Python one. */
+export class CanonicalEncodingError extends Error {
+}
+const PY_ESCAPES = {
+    '"': '\\"',
+    "\\": "\\\\",
+    "\b": "\\b",
+    "\f": "\\f",
+    "\n": "\\n",
+    "\r": "\\r",
+    "\t": "\\t",
+};
+/** `json.dumps(s, ensure_ascii=False)` for one string; lone surrogates are rejected. */
+function encodeString(value) {
+    let out = '"';
+    for (let i = 0; i < value.length; i++) {
+        const code = value.charCodeAt(i);
+        if (code >= 0xd800 && code <= 0xdbff) {
+            const next = value.charCodeAt(i + 1);
+            if (!(next >= 0xdc00 && next <= 0xdfff)) {
+                throw new CanonicalEncodingError("A string contains a lone surrogate.");
+            }
+            out += value[i] + value[i + 1];
+            i++;
+            continue;
+        }
+        if (code >= 0xdc00 && code <= 0xdfff) {
+            throw new CanonicalEncodingError("A string contains a lone surrogate.");
+        }
+        const ch = value[i];
+        const escape = PY_ESCAPES[ch];
+        if (escape !== undefined)
+            out += escape;
+        else if (code < 0x20)
+            out += "\\u" + code.toString(16).padStart(4, "0");
+        else
+            out += ch;
+    }
+    return out + '"';
+}
+/** Python's `sort_keys` orders by code point, not by UTF-16 code unit. */
+function compareCodePoints(a, b) {
+    const left = Array.from(a);
+    const right = Array.from(b);
+    const length = Math.min(left.length, right.length);
+    for (let i = 0; i < length; i++) {
+        const diff = left[i].codePointAt(0) - right[i].codePointAt(0);
+        if (diff !== 0)
+            return diff;
+    }
+    return left.length - right.length;
+}
+/**
+ * The one canonical serializer behind all three digests: sorted keys, compact
+ * separators, and raw UTF-8 — identical to
+ * `json.dumps(v, sort_keys=True, separators=(",", ":"), ensure_ascii=False)`.
+ * Floats, unsafe integers, and anything else Python would encode differently
+ * are rejected rather than silently diverging.
+ */
+export function canonicalJson(value) {
+    if (value === null)
+        return "null";
+    if (value === true)
+        return "true";
+    if (value === false)
+        return "false";
+    if (typeof value === "string")
+        return encodeString(value);
+    if (typeof value === "number") {
+        if (!Number.isSafeInteger(value)) {
+            throw new CanonicalEncodingError(`The number ${String(value)} is not a safe integer; floats and unsafe integers have no identical encoding.`);
+        }
+        return Object.is(value, -0) ? "0" : String(value);
+    }
+    if (Array.isArray(value)) {
+        return "[" + value.map((item) => canonicalJson(item)).join(",") + "]";
+    }
+    if (typeof value === "object") {
+        const record = value;
+        const keys = Object.keys(record).sort(compareCodePoints);
+        return ("{" +
+            keys.map((key) => encodeString(key) + ":" + canonicalJson(record[key])).join(",") +
+            "}");
+    }
+    throw new CanonicalEncodingError(`Unsupported value of type ${typeof value}.`);
+}
+/** SHA-256 hex digest of the canonical encoding. */
+export function canonicalSha256(value) {
+    return createHash("sha256").update(Buffer.from(canonicalJson(value), "utf8")).digest("hex");
+}
+/**
+ * The procedure's three identities. An absent `child_evidence` or
+ * `non_child_owners` array hashes as an empty array.
+ */
+export function computeEpicCoherenceDigests(document) {
+    return {
+        manifest_sha256: canonicalSha256(document.manifest),
+        child_evidence_sha256: canonicalSha256(document.child_evidence ?? []),
+        non_child_owners_sha256: canonicalSha256(document.non_child_owners ?? []),
+    };
+}
+/**
+ * Reject number tokens JavaScript would silently reinterpret. `JSON.parse`
+ * reads `1.0` and `1e2` as integers, but Python reads them as floats and
+ * encodes them differently, so the digests would diverge.
+ */
+export function findUnsupportedNumberTokens(raw) {
+    const problems = [];
+    let inString = false;
+    for (let i = 0; i < raw.length; i++) {
+        const ch = raw[i];
+        if (inString) {
+            if (ch === "\\")
+                i++;
+            else if (ch === '"')
+                inString = false;
+            continue;
+        }
+        if (ch === '"') {
+            inString = true;
+            continue;
+        }
+        if (ch === "-" || (ch >= "0" && ch <= "9")) {
+            let j = i + 1;
+            while (j < raw.length && /[0-9.eE+-]/.test(raw[j]))
+                j++;
+            const token = raw.slice(i, j);
+            if (/[.eE]/.test(token)) {
+                problems.push(`number ${token} is not an integer`);
+            }
+            else if (!Number.isSafeInteger(Number(token))) {
+                problems.push(`integer ${token} is outside the safe integer range`);
+            }
+            i = j - 1;
+        }
+    }
+    return problems;
+}
+/** Parse JSON text and reject number tokens with no identical canonical encoding. */
+function parseCanonicalJson(raw, label) {
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch (err) {
+        return {
+            ok: false,
+            errors: [`${label} is not valid JSON: ${err instanceof Error ? err.message : String(err)}`],
+            warnings: [],
+        };
+    }
+    const numberProblems = findUnsupportedNumberTokens(raw);
+    if (numberProblems.length > 0) {
+        return {
+            ok: false,
+            errors: numberProblems.map((problem) => `${label}: ${problem}.`),
+            warnings: [],
+        };
+    }
+    return { ok: true, value: parsed, warnings: [] };
+}
+// ===========================================================================
+// Path containment
+// ===========================================================================
+function isInside(target, dir) {
+    if (target === dir)
+        return true;
+    return target.startsWith(dir.endsWith(path.sep) ? dir : dir + path.sep);
+}
+/** A syntactic check: repository-relative, never absolute, never upward. */
+export function repositoryRelativePathProblem(candidate, label) {
+    if (typeof candidate !== "string" || candidate.trim().length === 0) {
+        return `${label} must be a non-empty path.`;
+    }
+    if (path.isAbsolute(candidate) || /^[A-Za-z]:[\\/]/.test(candidate) || candidate.startsWith("\\")) {
+        return `${label} must be repository-relative, not absolute: ${candidate}`;
+    }
+    if (candidate.replace(/\\/g, "/").split("/").some((segment) => segment === "..")) {
+        return `${label} must not traverse upward: ${candidate}`;
+    }
+    return null;
+}
+function isMissing(err) {
+    const code = err?.code;
+    return code === "ENOENT" || code === "ENOTDIR";
+}
+/**
+ * Resolve a repository-relative path and prove it stays inside the repository.
+ * An existing target is checked by its real path. A missing target is checked
+ * through its nearest existing ancestor, so a symlinked ancestor cannot escape.
+ */
+async function locateInsideRepository(relative, repoRoot, deps, label) {
+    const syntactic = repositoryRelativePathProblem(relative, label);
+    if (syntactic)
+        return { ok: false, error: syntactic };
+    const resolved = path.resolve(deps.cwd, relative);
+    let probe = resolved;
+    let exists = true;
+    for (;;) {
+        try {
+            const canonical = await deps.fs.realpath(probe);
+            if (!isInside(canonical, repoRoot)) {
+                return { ok: false, error: `${label} resolves outside the repository: ${relative}` };
+            }
+            return { ok: true, value: { exists, canonical: exists ? canonical : resolved } };
+        }
+        catch (err) {
+            if (!isMissing(err)) {
+                return {
+                    ok: false,
+                    error: `${label} cannot be resolved: ${err instanceof Error ? err.message : String(err)}`,
+                };
+            }
+            const parent = path.dirname(probe);
+            if (parent === probe) {
+                return { ok: false, error: `${label} has no existing ancestor: ${relative}` };
+            }
+            exists = false;
+            probe = parent;
+        }
+    }
+}
+/** Read a contained, existing file. */
+async function readContainedFile(relative, repoRoot, deps, label) {
+    const located = await locateInsideRepository(relative, repoRoot, deps, label);
+    if (!located.ok)
+        return located;
+    if (!located.value.exists)
+        return { ok: false, error: `${label} does not exist: ${relative}` };
+    try {
+        return { ok: true, value: await deps.fs.readFile(located.value.canonical) };
+    }
+    catch (err) {
+        return {
+            ok: false,
+            error: `${label} is unreadable: ${relative}: ${err instanceof Error ? err.message : String(err)}`,
+        };
+    }
+}
+async function resolveRepositoryRoot(deps) {
+    try {
+        return { ok: true, value: await deps.fs.realpath(deps.cwd) };
+    }
+    catch (err) {
+        return {
+            ok: false,
+            error: `Cannot resolve the repository root ${deps.cwd}: ${err instanceof Error ? err.message : String(err)}`,
+        };
+    }
+}
+/** Split a draft into its H1, preamble, and H2 sections. Fenced code is not a heading. */
+function parseDraft(text) {
+    const lines = text.replace(/\r\n/g, "\n").split("\n");
+    let title = null;
+    const preamble = [];
+    const sections = [];
+    let inFence = false;
+    for (const line of lines) {
+        if (/^\s*(```|~~~)/.test(line))
+            inFence = !inFence;
+        if (!inFence && title === null && sections.length === 0 && /^# /.test(line)) {
+            title = line.slice(2).trim();
+            continue;
+        }
+        if (!inFence && /^## /.test(line)) {
+            sections.push({ heading: line.slice(3).trim(), lines: [] });
+            continue;
+        }
+        if (sections.length === 0)
+            preamble.push(line);
+        else
+            sections[sections.length - 1].lines.push(line);
+    }
+    return {
+        title,
+        preamble: preamble.join("\n").trim(),
+        sections: sections.map((s) => ({ heading: s.heading, body: s.lines.join("\n").trim() })),
+    };
+}
+function sameHeading(a, b) {
+    return a.trim().toLowerCase() === b.trim().toLowerCase();
+}
+function findSections(draft, heading) {
+    return draft.sections.filter((s) => sameHeading(s.heading, heading));
+}
+/** Collapse whitespace runs to single spaces: the only normalization allowed. */
+function normalizeWhitespace(text) {
+    return text.replace(/\s+/g, " ").trim();
+}
+/**
+ * Split an Acceptance Criteria section into top-level bullets, joining indented
+ * continuation lines with single spaces. Prose before the first bullet is an
+ * introduction; an unindented non-bullet line after one is ambiguous.
+ */
+function parseTopLevelBullets(body, label) {
+    const bullets = [];
+    const errors = [];
+    for (const line of body.split("\n")) {
+        if (line.trim().length === 0)
+            continue;
+        const bullet = TOP_LEVEL_BULLET.exec(line);
+        if (bullet) {
+            bullets.push([bullet[1]]);
+        }
+        else if (/^\s/.test(line) && bullets.length > 0) {
+            bullets[bullets.length - 1].push(line.trim());
+        }
+        else if (bullets.length > 0) {
+            errors.push(`${label}: an unindented line after a bullet is ambiguous: "${line.trim()}"`);
+        }
+    }
+    return { bullets: bullets.map((parts) => normalizeWhitespace(parts.join(" "))), errors };
+}
+function parseEpicAcceptanceCriteria(body, label) {
+    const { bullets, errors } = parseTopLevelBullets(body, label);
+    const criteria = [];
+    for (const bullet of bullets) {
+        const match = EPIC_AC_BULLET.exec(`- ${bullet}`);
+        if (!match) {
+            errors.push(`${label}: every epic AC bullet must start with an explicit id such as "AC-3:"; ` +
+                `ids are never assigned by position or keyword: "${bullet}"`);
+            continue;
+        }
+        const rest = match[2] ?? "";
+        const labelMatch = VERIFICATION_LABEL.exec(rest);
+        const text = normalizeWhitespace(labelMatch ? rest.slice(0, labelMatch.index) : rest);
+        const verification = labelMatch
+            ? normalizeWhitespace(rest.slice(labelMatch.index + labelMatch[0].length))
+            : "";
+        criteria.push({ id: match[1], text, verification });
+    }
+    if (criteria.length === 0 && errors.length === 0) {
+        errors.push(`${label}: the Acceptance Criteria section holds no AC bullets.`);
+    }
+    return { criteria, errors };
+}
+/** Backticked spans in a draft that look like repository paths. */
+function backtickedRepositoryPaths(text) {
+    const found = new Set();
+    for (const match of text.matchAll(BACKTICK_SPAN)) {
+        const candidate = match[1].trim();
+        if (!candidate.includes("/") || candidate.includes("://"))
+            continue;
+        if (!REPO_PATH_SHAPE.test(candidate))
+            continue;
+        if (repositoryRelativePathProblem(candidate, "path"))
+            continue;
+        found.add(candidate);
+    }
+    return [...found];
+}
+/** A mention is classified when a listed path equals it or one contains the other as a directory. */
+function isClassified(mention, listed) {
+    return listed.some((entry) => entry === mention ||
+        (mention.endsWith("/") && entry.startsWith(mention)) ||
+        (entry.endsWith("/") && mention.startsWith(entry)));
+}
+function isHighRiskPath(candidate) {
+    return HIGH_RISK_PATH_PREFIXES.some((prefix) => candidate.startsWith(prefix) || (candidate.endsWith("/") && prefix.startsWith(candidate)));
+}
+// ===========================================================================
+// Structural validation
+// ===========================================================================
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function isNonEmptyString(value) {
+    return typeof value === "string" && value.trim().length > 0;
+}
+function isStringArray(value) {
+    return Array.isArray(value) && value.every((item) => typeof item === "string");
+}
+function duplicates(values) {
+    const seen = new Set();
+    const dupes = new Set();
+    for (const value of values) {
+        if (seen.has(value))
+            dupes.add(value);
+        seen.add(value);
+    }
+    return [...dupes];
+}
+function validateClaims(claims, acIds, label, errors) {
+    if (claims === undefined)
+        return;
+    if (!Array.isArray(claims)) {
+        errors.push(`${label}: owns_verifications must be an array.`);
+        return;
+    }
+    claims.forEach((claim, index) => {
+        const where = `${label}: owns_verifications[${index}]`;
+        if (!isRecord(claim)) {
+            errors.push(`${where} must be an object.`);
+            return;
+        }
+        if (!isNonEmptyString(claim.epic_ac) || !acIds.has(claim.epic_ac)) {
+            errors.push(`${where}: epic_ac ${JSON.stringify(claim.epic_ac)} names no real epic AC.`);
+        }
+        if (!isNonEmptyString(claim.obligation)) {
+            errors.push(`${where}: obligation must be a non-empty string.`);
+        }
+    });
+}
+function validatePathList(value, label, errors) {
+    if (value === undefined)
+        return [];
+    if (!isStringArray(value)) {
+        errors.push(`${label} must be an array of strings.`);
+        return [];
+    }
+    for (const entry of value) {
+        const problem = repositoryRelativePathProblem(entry, label);
+        if (problem)
+            errors.push(problem);
+    }
+    return value;
+}
+/**
+ * The procedure's structural "Validation" rules, in memory. It never judges
+ * coverage. Returns every problem found, not just the first.
+ */
+export function validateEpicCoherenceDocumentShape(document) {
+    const errors = [];
+    if (!isRecord(document))
+        return ["The input document must be a JSON object."];
+    const epic = document.epic;
+    const acIds = new Set();
+    if (!isRecord(epic)) {
+        errors.push("epic must be an object.");
+    }
+    else {
+        const hasKey = epic.key !== undefined;
+        const hasSlug = epic.slug !== undefined;
+        if (!hasKey && !hasSlug)
+            errors.push("epic must carry a key or a slug.");
+        if (hasKey && (typeof epic.key !== "string" || !EPIC_KEY_PATTERN.test(epic.key))) {
+            errors.push(`epic.key ${JSON.stringify(epic.key)} is not a valid ticket key.`);
+        }
+        if (hasSlug && (typeof epic.slug !== "string" || !EPIC_SLUG_PATTERN.test(epic.slug))) {
+            errors.push(`epic.slug ${JSON.stringify(epic.slug)} is not a valid slug.`);
+        }
+        if (!isNonEmptyString(epic.title))
+            errors.push("epic.title must be a non-empty string.");
+        if (!Array.isArray(epic.acceptance_criteria) || epic.acceptance_criteria.length === 0) {
+            errors.push("epic.acceptance_criteria must be a non-empty array.");
+        }
+        else {
+            const ids = [];
+            epic.acceptance_criteria.forEach((ac, index) => {
+                if (!isRecord(ac)) {
+                    errors.push(`epic.acceptance_criteria[${index}] must be an object.`);
+                    return;
+                }
+                if (!isNonEmptyString(ac.id) || !AC_ID_PATTERN.test(ac.id)) {
+                    errors.push(`epic.acceptance_criteria[${index}].id must be an explicit id such as "AC-1".`);
+                }
+                else {
+                    ids.push(ac.id);
+                }
+                if (typeof ac.text !== "string") {
+                    errors.push(`epic.acceptance_criteria[${index}].text must be a string.`);
+                }
+                if (typeof ac.verification !== "string") {
+                    errors.push(`epic.acceptance_criteria[${index}].verification must be a string.`);
+                }
+            });
+            for (const dupe of duplicates(ids))
+                errors.push(`Epic AC id ${dupe} is not unique.`);
+            ids.forEach((id) => acIds.add(id));
+        }
+    }
+    if (typeof document.design_text !== "string")
+        errors.push("design_text must be a string.");
+    const childIds = [];
+    if (!Array.isArray(document.manifest) || document.manifest.length === 0) {
+        errors.push("manifest must be a non-empty array.");
+    }
+    else {
+        for (const entry of document.manifest) {
+            if (isRecord(entry) && isNonEmptyString(entry.id))
+                childIds.push(entry.id);
+        }
+        const childIdSet = new Set(childIds);
+        document.manifest.forEach((entry, index) => {
+            const label = `manifest[${index}]`;
+            if (!isRecord(entry)) {
+                errors.push(`${label} must be an object.`);
+                return;
+            }
+            for (const field of ["id", "title", "scope", "size_band"]) {
+                if (!isNonEmptyString(entry[field]))
+                    errors.push(`${label}.${field} must be a non-empty string.`);
+            }
+            for (const field of ["depends_on", "recommended_after"]) {
+                const value = entry[field];
+                if (!isStringArray(value)) {
+                    errors.push(`${label}.${field} must be an array of child ids.`);
+                }
+                else {
+                    for (const ref of value) {
+                        if (!childIdSet.has(ref))
+                            errors.push(`${label}.${field} names unknown child ${ref}.`);
+                    }
+                }
+            }
+            const edits = validatePathList(entry.touched_files, `${label}.touched_files`, errors);
+            const reads = validatePathList(entry.read_files, `${label}.read_files`, errors);
+            for (const both of edits.filter((p) => reads.includes(p))) {
+                errors.push(`${label}: ${both} is in both touched_files and read_files.`);
+            }
+            validateClaims(entry.owns_verifications, acIds, label, errors);
+        });
+        for (const dupe of duplicates(childIds))
+            errors.push(`Child id ${dupe} is not unique.`);
+    }
+    const childIdSet = new Set(childIds);
+    if (document.child_evidence !== undefined) {
+        if (!Array.isArray(document.child_evidence)) {
+            errors.push("child_evidence must be an array.");
+        }
+        else {
+            document.child_evidence.forEach((evidence, index) => {
+                const label = `child_evidence[${index}]`;
+                if (!isRecord(evidence)) {
+                    errors.push(`${label} must be an object.`);
+                    return;
+                }
+                if (!isNonEmptyString(evidence.id) || !childIdSet.has(evidence.id)) {
+                    errors.push(`${label}.id ${JSON.stringify(evidence.id)} names no manifest child.`);
+                }
+                if (evidence.acceptance_criteria !== undefined && !isStringArray(evidence.acceptance_criteria)) {
+                    errors.push(`${label}.acceptance_criteria must be an array of strings.`);
+                }
+                if (evidence.body !== undefined && typeof evidence.body !== "string") {
+                    errors.push(`${label}.body must be a string.`);
+                }
+            });
+        }
+    }
+    if (document.non_child_owners !== undefined) {
+        if (!Array.isArray(document.non_child_owners)) {
+            errors.push("non_child_owners must be an array.");
+        }
+        else {
+            const ownerIds = [];
+            document.non_child_owners.forEach((owner, index) => {
+                const label = `non_child_owners[${index}]`;
+                if (!isRecord(owner)) {
+                    errors.push(`${label} must be an object.`);
+                    return;
+                }
+                if (!isNonEmptyString(owner.id)) {
+                    errors.push(`${label}.id must be a non-empty string.`);
+                }
+                else {
+                    ownerIds.push(owner.id);
+                    if (childIdSet.has(owner.id)) {
+                        errors.push(`${label}.id ${owner.id} collides with a child id.`);
+                    }
+                }
+                if (owner.kind !== "owner_run") {
+                    errors.push(`${label}.kind must be "owner_run", not ${JSON.stringify(owner.kind)}.`);
+                }
+                for (const field of ["who", "step_ref", "step_text", "records_result_in"]) {
+                    if (!isNonEmptyString(owner[field]))
+                        errors.push(`${label}.${field} must be a non-empty string.`);
+                }
+                if (!Array.isArray(owner.owns_verifications) || owner.owns_verifications.length === 0) {
+                    errors.push(`${label}.owns_verifications must be a non-empty array.`);
+                }
+                else {
+                    validateClaims(owner.owns_verifications, acIds, label, errors);
+                }
+            });
+            for (const dupe of duplicates(ownerIds))
+                errors.push(`Non-child owner id ${dupe} is not unique.`);
+        }
+    }
+    try {
+        computeEpicCoherenceDigests(document);
+    }
+    catch (err) {
+        errors.push(`The document has no canonical encoding: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    return errors;
+}
+/**
+ * Named-file checks: every `touched_files` path stays inside the repository (a
+ * missing one may be a planned creation); every `read_files` path must exist,
+ * stay inside the repository, and be readable.
+ */
+async function validateNamedFiles(document, repoRoot, deps) {
+    const errors = [];
+    for (const entry of document.manifest) {
+        for (const edit of entry.touched_files ?? []) {
+            const located = await locateInsideRepository(edit, repoRoot, deps, `child ${entry.id} touched_files`);
+            if (!located.ok)
+                errors.push(located.error);
+        }
+        for (const read of entry.read_files ?? []) {
+            const readable = await readContainedFile(read, repoRoot, deps, `child ${entry.id} read_files`);
+            if (!readable.ok)
+                errors.push(readable.error);
+        }
+    }
+    return errors;
+}
+// ===========================================================================
+// Check mode
+// ===========================================================================
+/** Structurally validate an in-memory document, including its named files. */
+async function checkDocument(document, repoRoot, deps) {
+    const errors = validateEpicCoherenceDocumentShape(document);
+    if (errors.length > 0)
+        return { ok: false, errors, warnings: [] };
+    const typed = document;
+    const fileErrors = await validateNamedFiles(typed, repoRoot, deps);
+    if (fileErrors.length > 0)
+        return { ok: false, errors: fileErrors, warnings: [] };
+    return { ok: true, value: { digests: computeEpicCoherenceDigests(typed) }, warnings: [] };
+}
+/** `epic-coherence-input check <path>`: validate an existing document. Writes nothing. */
+export async function checkEpicCoherenceInput(inputPath, deps) {
+    const root = await resolveRepositoryRoot(deps);
+    if (!root.ok)
+        return { ok: false, errors: [root.error], warnings: [] };
+    const raw = await readContainedFile(inputPath, root.value, deps, "Input document");
+    if (!raw.ok)
+        return { ok: false, errors: [raw.error], warnings: [] };
+    const parsed = parseCanonicalJson(raw.value, "Input document");
+    if (!parsed.ok)
+        return parsed;
+    return checkDocument(parsed.value, root.value, deps);
+}
+// ===========================================================================
+// Build mode
+// ===========================================================================
+function validateOutlineShape(outline) {
+    const errors = [];
+    if (!isRecord(outline))
+        return ["The outline must be a JSON object."];
+    if (!isRecord(outline.epic)) {
+        errors.push("outline.epic must be an object.");
+    }
+    else {
+        if (outline.epic.key === undefined && outline.epic.slug === undefined) {
+            errors.push("outline.epic must carry a key or a slug.");
+        }
+        if (!isNonEmptyString(outline.epic.draft))
+            errors.push("outline.epic.draft must be a path.");
+    }
+    if (!Array.isArray(outline.children) || outline.children.length === 0) {
+        errors.push("outline.children must be a non-empty array.");
+    }
+    else {
+        outline.children.forEach((child, index) => {
+            const label = `outline.children[${index}]`;
+            if (!isRecord(child)) {
+                errors.push(`${label} must be an object.`);
+                return;
+            }
+            for (const field of ["id", "draft", "size_band"]) {
+                if (!isNonEmptyString(child[field]))
+                    errors.push(`${label}.${field} must be a non-empty string.`);
+            }
+            for (const field of ["depends_on", "recommended_after", "edits", "reads"]) {
+                if (child[field] !== undefined && !isStringArray(child[field])) {
+                    errors.push(`${label}.${field} must be an array of strings.`);
+                }
+            }
+            if (child.owns_verifications !== undefined && !Array.isArray(child.owns_verifications)) {
+                errors.push(`${label}.owns_verifications must be an array.`);
+            }
+        });
+    }
+    if (outline.non_child_owners !== undefined && !Array.isArray(outline.non_child_owners)) {
+        errors.push("outline.non_child_owners must be an array.");
+    }
+    return errors;
+}
+function composeDesignText(draft) {
+    const parts = [];
+    if (draft.preamble)
+        parts.push(draft.preamble);
+    for (const section of draft.sections) {
+        if (sameHeading(section.heading, "Acceptance Criteria"))
+            continue;
+        if (sameHeading(section.heading, "Materials & Access"))
+            continue;
+        parts.push(`## ${section.heading}\n\n${section.body}`.trim());
+    }
+    return parts.join("\n\n");
+}
+/**
+ * `epic-coherence-input build --outline <path> --out <path>`. Parses the drafts,
+ * builds the normalized document, runs the same structural checker check mode
+ * uses, computes the three digests, and writes only when everything passed.
+ */
+export async function buildEpicCoherenceInput(options, deps) {
+    const errors = [];
+    const warnings = [];
+    const failed = () => ({
+        ok: false,
+        errors,
+        warnings,
+    });
+    const root = await resolveRepositoryRoot(deps);
+    if (!root.ok)
+        return { ok: false, errors: [root.error], warnings };
+    const repoRoot = root.value;
+    // Contain the output before reading anything, so an escaping --out fails first.
+    const out = await locateInsideRepository(options.outPath, repoRoot, deps, "--out");
+    if (!out.ok)
+        return { ok: false, errors: [out.error], warnings };
+    const rawOutline = await readContainedFile(options.outlinePath, repoRoot, deps, "Outline");
+    if (!rawOutline.ok)
+        return { ok: false, errors: [rawOutline.error], warnings };
+    const parsedOutline = parseCanonicalJson(rawOutline.value, "Outline");
+    if (!parsedOutline.ok)
+        return parsedOutline;
+    errors.push(...validateOutlineShape(parsedOutline.value));
+    if (errors.length > 0)
+        return failed();
+    const outline = parsedOutline.value;
+    // ---- epic draft --------------------------------------------------------
+    const epicRaw = await readContainedFile(outline.epic.draft, repoRoot, deps, "Epic draft");
+    if (!epicRaw.ok)
+        return { ok: false, errors: [epicRaw.error], warnings };
+    const epicDraft = parseDraft(epicRaw.value);
+    if (!epicDraft.title)
+        errors.push("Epic draft: no H1 title.");
+    const epicAcSections = findSections(epicDraft, "Acceptance Criteria");
+    let epicCriteria = [];
+    if (epicAcSections.length !== 1) {
+        errors.push(`Epic draft: expected exactly one "## Acceptance Criteria" section, found ${epicAcSections.length}.`);
+    }
+    else {
+        const parsed = parseEpicAcceptanceCriteria(epicAcSections[0].body, "Epic draft");
+        epicCriteria = parsed.criteria;
+        errors.push(...parsed.errors);
+    }
+    // ---- child drafts ------------------------------------------------------
+    const manifest = [];
+    const childEvidence = [];
+    for (const child of outline.children) {
+        const label = `Child ${child.id}`;
+        const edits = child.edits ?? [];
+        const reads = child.reads ?? [];
+        for (const both of edits.filter((p) => reads.includes(p))) {
+            errors.push(`${label}: ${both} is in both edits and reads.`);
+        }
+        const draftRaw = await readContainedFile(child.draft, repoRoot, deps, `${label} draft`);
+        if (!draftRaw.ok) {
+            errors.push(draftRaw.error);
+            continue;
+        }
+        const draft = parseDraft(draftRaw.value);
+        if (!draft.title)
+            errors.push(`${label} draft: no H1 title.`);
+        const summaries = findSections(draft, "Summary");
+        if (summaries.length !== 1) {
+            errors.push(`${label} draft: expected exactly one "## Summary" section, found ${summaries.length}.`);
+        }
+        const acSections = findSections(draft, "Acceptance Criteria");
+        let childCriteria = [];
+        if (acSections.length !== 1) {
+            errors.push(`${label} draft: expected exactly one "## Acceptance Criteria" section, found ${acSections.length}.`);
+        }
+        else {
+            const parsed = parseTopLevelBullets(acSections[0].body, `${label} draft`);
+            childCriteria = parsed.bullets;
+            errors.push(...parsed.errors);
+        }
+        // Every declared obligation must name a real epic AC and appear verbatim,
+        // prefixed by its AC id.
+        const epicAcIds = new Set(epicCriteria.map((ac) => ac.id));
+        const claims = child.owns_verifications ?? [];
+        for (const claim of claims) {
+            if (!isRecord(claim) || !isNonEmptyString(claim.epic_ac) || !isNonEmptyString(claim.obligation)) {
+                continue; // Reported by the structural checker below.
+            }
+            if (epicAcSections.length === 1 && !epicAcIds.has(claim.epic_ac)) {
+                errors.push(`${label}: owns_verifications epic_ac ${claim.epic_ac} names no real epic AC.`);
+                continue;
+            }
+            const expected = normalizeWhitespace(`${claim.epic_ac}: ${claim.obligation}`);
+            if (acSections.length === 1 && !childCriteria.includes(expected)) {
+                errors.push(`${label}: the obligation for ${claim.epic_ac} is not found verbatim in the draft's ` +
+                    `Acceptance Criteria as "${expected}".`);
+            }
+        }
+        // Every backticked repository path must be classified as an edit or a read.
+        const listed = [...edits, ...reads];
+        for (const mention of backtickedRepositoryPaths(draftRaw.value)) {
+            if (isClassified(mention, listed))
+                continue;
+            if (isHighRiskPath(mention)) {
+                errors.push(`${label}: \`${mention}\` is under a high-risk path but is in neither edits nor reads; ` +
+                    "classify it, because only edits decide the risk tier.");
+            }
+            else {
+                warnings.push(`${label}: \`${mention}\` is named in the draft but is in neither edits nor reads.`);
+            }
+        }
+        manifest.push({
+            id: child.id,
+            title: draft.title ?? "",
+            scope: summaries[0]?.body ?? "",
+            size_band: child.size_band,
+            depends_on: child.depends_on ?? [],
+            recommended_after: child.recommended_after ?? [],
+            touched_files: edits,
+            read_files: reads,
+            owns_verifications: claims,
+        });
+        childEvidence.push({
+            id: child.id,
+            acceptance_criteria: childCriteria,
+            body: draftRaw.value.replace(/\r\n/g, "\n"),
+        });
+    }
+    if (errors.length > 0)
+        return failed();
+    const epic = {
+        ...(outline.epic.key !== undefined ? { key: outline.epic.key } : {}),
+        ...(outline.epic.slug !== undefined ? { slug: outline.epic.slug } : {}),
+        title: epicDraft.title ?? "",
+        acceptance_criteria: epicCriteria,
+    };
+    const document = {
+        epic,
+        design_text: composeDesignText(epicDraft),
+        manifest,
+        child_evidence: childEvidence,
+        ...(outline.non_child_owners !== undefined ? { non_child_owners: outline.non_child_owners } : {}),
+    };
+    // The same structural checker check mode runs; nothing is written on failure.
+    const checked = await checkDocument(document, repoRoot, deps);
+    if (!checked.ok)
+        return { ok: false, errors: checked.errors, warnings };
+    const destination = path.resolve(deps.cwd, options.outPath);
+    if (!out.value.exists) {
+        try {
+            await deps.fs.mkdir(path.dirname(destination));
+        }
+        catch (err) {
+            return {
+                ok: false,
+                errors: [`Could not create the directory for --out: ${err instanceof Error ? err.message : String(err)}`],
+                warnings,
+            };
+        }
+        // Re-contain after creating directories, in case an ancestor changed underneath.
+        const recheck = await locateInsideRepository(options.outPath, repoRoot, deps, "--out");
+        if (!recheck.ok)
+            return { ok: false, errors: [recheck.error], warnings };
+    }
+    const written = await writeJsonAtomically(destination, document, deps.fs);
+    if (!written.ok)
+        return { ok: false, errors: [written.error], warnings };
+    return {
+        ok: true,
+        value: { output_path: options.outPath, document, digests: checked.value.digests },
+        warnings,
+    };
+}