@interf/compiler 0.33.0 → 0.50.0

package/dist/packages/runtime/build/stage-manifest.js

@@ -0,0 +1,1125 @@
+import { createHash } from "node:crypto";
+import { existsSync, mkdirSync, readdirSync, readFileSync, statSync } from "node:fs";
+import { basename, extname, join, relative } from "node:path";
+import { ExpectedInputsFileSchema, GraphManifestSchema, MetricCountSchema, ReviewedInputSchema, ReviewedInputsFileSchema, ResourceRefSchema, StageManifestSchema, } from "../../contracts/lib/schema.js";
+import { graphRelativePathPattern, knowledgeNoteKind, layerForPath, normalizeLayerPath, roleForLayerPath, roleForWritePath, } from "../../contracts/lib/context-graph-layer.js";
+import { isFilesystemArtifact, listFilesRecursive } from "../../contracts/utils/filesystem.js";
+import { parseJsonFrontmatter, readJsonFileWithSchema } from "../../contracts/utils/parse.js";
+import { findBuildPlanContextArtifact, readBuildPlanContextFile, } from "./context-graph-schema.js";
+import { buildPlanPackagePathForContextGraph, contextGraphRuntimeGraphManifestPath, contextGraphRuntimeStageExpectedInputsPath, contextGraphRuntimeStageManifestPath, contextGraphRuntimeStageReviewedInputsPath, contextGraphRuntimeStageRoot, } from "./context-graph-paths.js";
+import { loadBuildStageInputs, loadContextGraphSourceManifest, } from "./source-manifest.js";
+import { writeJsonAtomic, } from "./atomic-fs.js";
+import { readExecutionStageLedgerHistory, } from "../runtime-persistence.js";
+const WIKILINK_PATTERN = /\[\[([^\]\n]+)\]\]/g;
+const MARKDOWN_LINK_PATTERN = /!?\[[^\]\n]*\]\(([^)\n]+)\)/g;
+// Shared marker for the per-summary orphaned-summary `missing` reason a
+// knowledge-role stage emits. The GraphManifest readiness rollup keys off it to
+// collapse those per-summary entries into the single FINAL-state
+// `knowledge:summary-backlinks` gate, so one logical orphan gap is counted once
+// in readiness instead of twice (per-summary entry + metric gate).
+const ORPHANED_SUMMARY_REASON = "is cited by a knowledge note's source_refs but never wikilinked; the summary is an orphaned island.";
+// Single source for the "N knowledge note(s) link no summary" message shared by
+// the `knowledge_summary_connectivity` metric detail (no trailing period, metric
+// style) and the readiness `knowledge:summary-connectivity` gate reason (trailing
+// period, sentence style). One formatter so the singular/plural agreement and
+// wording can never drift between the two surfaces.
+function formatDisconnectedNotesMessage(count, includePeriod) {
+    return `${count} knowledge note${count === 1 ? " links" : "s link"} no summary (disconnected from the source-backed layer)${includePeriod ? "." : ""}`;
+}
+// Path normalization + the graph-relative link pattern come from the central
+// Context Graph layer model so this scanner and every other consumer share one
+// canonical layer set. `normalizeRelativePath` is kept as a local alias so the
+// many existing call sites below read unchanged.
+const normalizeRelativePath = normalizeLayerPath;
+function relativeToGraph(contextGraphPath, filePath) {
+    return normalizeRelativePath(relative(contextGraphPath, filePath));
+}
+function slug(value) {
+    const clean = value
+        .toLowerCase()
+        .replace(/['"]/g, "")
+        .replace(/[^a-z0-9]+/g, "-")
+        .replace(/^-+|-+$/g, "");
+    return clean.length > 0 ? clean : "resource";
+}
+// Resource ids stay <=90 slug chars, but the slug alone is NOT injective: two
+// distinct keys whose first 90 slug chars are identical (e.g. sibling files
+// `.../msg-XXXX-<long>/summary.md` and `.../manifest.md`, which only diverge
+// after char ~90) would collapse to the same id. A non-unique id makes the
+// StageManifest dedup guard reject an otherwise-valid manifest, failing the
+// stage on every retry. When (and only when) the slug must be truncated, append
+// a short stable hash of the FULL key so the id is collision-proof and still
+// deterministic across runs (same path -> same id).
+function resourceId(role, key) {
+    const full = slug(key);
+    if (full.length <= 90)
+        return `${role}:${full}`;
+    const hash = createHash("sha1").update(key).digest("hex").slice(0, 8);
+    return `${role}:${full.slice(0, 81)}-${hash}`;
+}
+function markdownTitle(path, frontmatter, body) {
+    const title = stringField(frontmatter.title) ?? stringField(frontmatter.label);
+    if (title)
+        return title;
+    const heading = body.split("\n").find((line) => /^#{1,3}\s+\S/.test(line));
+    if (heading)
+        return heading.replace(/^#{1,3}\s+/, "").trim();
+    return basename(path, extname(path));
+}
+function markdownSummary(frontmatter, body) {
+    const explicit = stringField(frontmatter.summary)
+        ?? stringField(frontmatter.abstract)
+        ?? stringField(frontmatter.description);
+    if (explicit)
+        return explicit.length > 240 ? `${explicit.slice(0, 237)}...` : explicit;
+    const paragraph = body
+        .split(/\n\s*\n/)
+        .map((block) => block.replace(/\s+/g, " ").trim())
+        .find((block) => block.length > 0 && !block.startsWith("#"));
+    if (!paragraph)
+        return null;
+    return paragraph.length > 240 ? `${paragraph.slice(0, 237)}...` : paragraph;
+}
+function stringField(value) {
+    return typeof value === "string" && value.trim().length > 0 ? value.trim() : null;
+}
+function stringValues(value) {
+    if (Array.isArray(value))
+        return value.flatMap((item) => stringValues(item));
+    if (typeof value === "string")
+        return value.trim().length > 0 ? [value.trim()] : [];
+    if (value && typeof value === "object") {
+        const record = value;
+        return [
+            stringField(record.path),
+            stringField(record.locator),
+            stringField(record.source_path),
+            stringField(record.ref),
+            stringField(record.summary),
+        ].filter((item) => Boolean(item));
+    }
+    return [];
+}
+function sourceRefsFromFrontmatter(frontmatter) {
+    return Array.from(new Set([
+        ...stringValues(frontmatter.source_refs),
+        ...stringValues(frontmatter.source_ref),
+        ...stringValues(frontmatter.source_path),
+        ...stringValues(frontmatter.source),
+    ]));
+}
+function sourceRefsFromContent(content, frontmatter, knownSourceRefs) {
+    const refs = new Set(sourceRefsFromFrontmatter(frontmatter));
+    for (const sourceRef of knownSourceRefs) {
+        if (content.includes(sourceRef))
+            refs.add(sourceRef);
+    }
+    return [...refs];
+}
+function graphLinksFromFrontmatter(frontmatter) {
+    return [
+        ...stringValues(frontmatter.links),
+        ...stringValues(frontmatter.linked_notes),
+        ...stringValues(frontmatter.related),
+        ...stringValues(frontmatter.upstream),
+        ...stringValues(frontmatter.upstream_refs),
+    ];
+}
+function parseLinks(content, frontmatter) {
+    const links = [];
+    links.push(...graphLinksFromFrontmatter(frontmatter));
+    for (const match of content.matchAll(WIKILINK_PATTERN)) {
+        const raw = match[1]?.split("|")[0]?.split("#")[0]?.trim();
+        if (raw)
+            links.push(raw);
+    }
+    for (const match of content.matchAll(MARKDOWN_LINK_PATTERN)) {
+        const raw = match[1]?.split("#")[0]?.trim();
+        if (!raw || /^https?:\/\//i.test(raw))
+            continue;
+        links.push(raw);
+    }
+    for (const match of content.matchAll(graphRelativePathPattern())) {
+        const raw = match[1]?.split("#")[0]?.trim().replace(/[),.;:]+$/g, "");
+        if (raw)
+            links.push(raw);
+    }
+    return Array.from(new Set(links));
+}
+function collectMarkdownFiles(rootPath, relativeDir) {
+    const absoluteDir = join(rootPath, relativeDir);
+    if (!existsSync(absoluteDir))
+        return [];
+    const stat = statSync(absoluteDir);
+    if (stat.isFile()) {
+        return relativeDir.toLowerCase().endsWith(".md") ? [normalizeRelativePath(relativeDir)] : [];
+    }
+    if (!stat.isDirectory())
+        return [];
+    const files = [];
+    for (const entry of readdirSync(absoluteDir, { withFileTypes: true }).sort((left, right) => left.name.localeCompare(right.name))) {
+        if (entry.name.startsWith("."))
+            continue;
+        const childPath = normalizeRelativePath(join(relativeDir, entry.name));
+        if (entry.isDirectory()) {
+            files.push(...collectMarkdownFiles(rootPath, childPath));
+        }
+        else if (entry.isFile() && childPath.toLowerCase().endsWith(".md")) {
+            files.push(childPath);
+        }
+    }
+    return files;
+}
+// Note-kind label for a StageManifest ResourceRef. The layer (home / artifact /
+// summary / knowledge / other) and the knowledge claim·entity sub-kind both come
+// from the central `context-graph-layer` module so the `knowledge/claims/` /
+// `claim-` conventions can never drift from the semantic-graph classifier. The
+// dotted label vocabulary is this module's own; only the classification is
+// shared. Precedence matches the original chain exactly: layer wins for
+// home/artifact/summary, then claim/entity (recognized by leaf prefix even at
+// the root), then any other knowledge note, then a plain markdown note.
+function noteKindForPath(path) {
+    const layer = layerForPath(path);
+    if (layer === "home")
+        return "entrypoint.home";
+    if (layer === "artifacts")
+        return "entrypoint.artifact";
+    if (layer === "summaries")
+        return "summary.note";
+    const knowledgeKind = knowledgeNoteKind(path);
+    if (knowledgeKind === "claim")
+        return "knowledge.claim";
+    if (knowledgeKind === "entity")
+        return "knowledge.entity";
+    if (layer === "knowledge")
+        return "knowledge.note";
+    return "note.markdown";
+}
+// `roleForPath` and `layerRoleForWritePath` are the central Context Graph layer
+// classifiers, imported as `roleForLayerPath` / `roleForWritePath`. They are the
+// SINGLE source of truth every consumer (note role, stage role, disconnected /
+// web checks, metrics) routes through — case-insensitive policing of where a
+// note or artifact lands on disk, never derived from a stringly id. Local
+// aliases keep the many call sites below reading unchanged.
+const roleForPath = roleForLayerPath;
+const layerRoleForWritePath = roleForWritePath;
+/**
+ * Resolve a stage's artifact-id references (its `writes` or `reads`) to the set
+ * of layer roles they touch, by looking up each artifact's write *path* in the
+ * Build Plan schema. When a referenced token has no schema artifact (e.g. a
+ * plan that lists a bare layer path directly), the token is treated as a path
+ * so the layer is still recognized. Returns roles derived from disk location,
+ * with no reliance on stringly stage ids or artifact ids.
+ */
+function stageArtifactRoles(contextGraphPath, artifactIds) {
+    const schema = readBuildPlanContextFile(buildPlanPackagePathForContextGraph(contextGraphPath));
+    const roles = new Set();
+    for (const artifactId of artifactIds) {
+        const artifact = schema ? findBuildPlanContextArtifact(schema, artifactId) : null;
+        roles.add(layerRoleForWritePath(artifact?.path ?? artifactId));
+    }
+    return roles;
+}
+function noteResource(contextGraphPath, path, stageId, knownSourceRefs = []) {
+    const content = readFileSync(join(contextGraphPath, path), "utf8");
+    const parsed = parseJsonFrontmatter(content);
+    const frontmatter = parsed?.frontmatter ?? {};
+    const body = parsed?.body ?? content;
+    const role = roleForPath(path);
+    const links = parseLinks(content, frontmatter)
+        .filter((link) => normalizeRelativePath(link).replace(/\.md$/i, "") !== normalizeRelativePath(path).replace(/\.md$/i, ""));
+    return ResourceRefSchema.parse({
+        id: resourceId(role, path),
+        role,
+        kind: noteKindForPath(path),
+        label: markdownTitle(path, frontmatter, body),
+        path,
+        ...(stageId ? { stage_id: stageId } : {}),
+        source_refs: sourceRefsFromContent(content, frontmatter, knownSourceRefs),
+        links,
+        metadata: {
+            ...(markdownSummary(frontmatter, body) ? { summary: markdownSummary(frontmatter, body) } : {}),
+        },
+    });
+}
+function knownSourceRefsForGraph(contextGraphPath) {
+    return loadContextGraphSourceManifest(contextGraphPath)?.files.map((file) => file.path) ?? [];
+}
+function listSummaryResources(contextGraphPath) {
+    const knownSourceRefs = knownSourceRefsForGraph(contextGraphPath);
+    return collectMarkdownFiles(contextGraphPath, "summaries")
+        .map((path) => noteResource(contextGraphPath, path, undefined, knownSourceRefs));
+}
+function listKnowledgeResources(contextGraphPath) {
+    const knownSourceRefs = knownSourceRefsForGraph(contextGraphPath);
+    return collectMarkdownFiles(contextGraphPath, "knowledge")
+        .map((path) => noteResource(contextGraphPath, path, undefined, knownSourceRefs));
+}
+function listEntrypointResources(contextGraphPath) {
+    const knownSourceRefs = knownSourceRefsForGraph(contextGraphPath);
+    const home = existsSync(join(contextGraphPath, "home.md")) ? ["home.md"] : [];
+    return [...home, ...collectMarkdownFiles(contextGraphPath, "artifacts")]
+        .map((path) => noteResource(contextGraphPath, path, undefined, knownSourceRefs));
+}
+function sourceFileResource(file) {
+    return ResourceRefSchema.parse({
+        id: resourceId("source", file.id),
+        role: "source",
+        kind: "source.file",
+        label: file.path,
+        locator: file.locator,
+        source_refs: [file.path],
+        required: true,
+        metadata: {
+            source_file_id: file.id,
+            path: file.path,
+            kind: file.kind,
+            ...(typeof file.page_count === "number" ? { page_count: file.page_count } : {}),
+        },
+    });
+}
+function sourceUnitResources(manifest) {
+    const resources = [];
+    for (const file of manifest.files) {
+        const units = file.inspectable_units.length > 0
+            ? file.inspectable_units
+            : [{ kind: "file", index: 1, label: "whole file" }];
+        for (const [index, unit] of units.entries()) {
+            const label = unit.label ?? `${unit.kind} ${unit.index ?? index + 1}`;
+            resources.push(ResourceRefSchema.parse({
+                id: resourceId("source-unit", `${file.id}-${unit.kind}-${unit.index ?? index + 1}`),
+                role: "source",
+                kind: `source.${unit.kind}`,
+                label: `${file.path} · ${label}`,
+                locator: file.locator,
+                source_refs: [file.path],
+                required: true,
+                metadata: {
+                    source_file_id: file.id,
+                    source_path: file.path,
+                    expected_summary_folder: `summaries/${file.path}`,
+                    expected_summary_path: `summaries/${file.path}/summary.md`,
+                    unit_kind: unit.kind,
+                    unit_index: unit.index ?? index + 1,
+                },
+            }));
+        }
+    }
+    return resources;
+}
+function loadExpectedInputs(contextGraphPath, stageId) {
+    const path = contextGraphRuntimeStageExpectedInputsPath(contextGraphPath, stageId);
+    const file = existsSync(path)
+        ? readJsonFileWithSchema(path, "stage expected inputs", ExpectedInputsFileSchema)
+        : null;
+    return file?.expected ?? [];
+}
+function loadReviewedInputs(contextGraphPath, stageId) {
+    const path = contextGraphRuntimeStageReviewedInputsPath(contextGraphPath, stageId);
+    if (!existsSync(path))
+        return null;
+    const file = readJsonFileWithSchema(path, "stage reviewed inputs", ReviewedInputsFileSchema);
+    return file?.reviewed ?? null;
+}
+export function persistStageReviewedInputsFromShell(options) {
+    const shellPath = join(options.shellRoot, "runtime", "reviewed-inputs.json");
+    if (!existsSync(shellPath)) {
+        return {
+            ok: false,
+            summary: `${options.stageId} did not write runtime/reviewed-inputs.json.`,
+        };
+    }
+    let file;
+    try {
+        file = readJsonFileWithSchema(shellPath, `${options.stageId} reviewed inputs`, ReviewedInputsFileSchema);
+    }
+    catch (error) {
+        return {
+            ok: false,
+            summary: `Invalid runtime/reviewed-inputs.json for ${options.stageId}: ${error instanceof Error ? error.message : String(error)}`,
+        };
+    }
+    if (!file || file.stage_id !== options.stageId) {
+        return {
+            ok: false,
+            summary: `runtime/reviewed-inputs.json stage_id must be ${options.stageId}.`,
+        };
+    }
+    mkdirSync(contextGraphRuntimeStageRoot(options.contextGraphPath, options.stageId), { recursive: true });
+    writeJsonAtomic(contextGraphRuntimeStageReviewedInputsPath(options.contextGraphPath, options.stageId), file);
+    return {
+        ok: true,
+        summary: `${options.stageId} reviewed ${file.reviewed.length} expected input${file.reviewed.length === 1 ? "" : "s"}.`,
+    };
+}
+function expectedInputsForStage(options) {
+    if (options.stage.id === "source") {
+        return options.manifest.files.map(sourceFileResource);
+    }
+    // Roles are derived from the artifact write/read *paths*, not from artifact
+    // ids or stage ids, so a custom plan cannot dodge layer policy by renaming.
+    const writeRoles = stageArtifactRoles(options.contextGraphPath, options.stage.writes);
+    const readRoles = stageArtifactRoles(options.contextGraphPath, options.stage.reads);
+    if (writeRoles.has("summary") || options.stage.contractType === "build-file-evidence") {
+        return sourceUnitResources(options.manifest);
+    }
+    if (writeRoles.has("entrypoint")) {
+        const knowledge = listKnowledgeResources(options.contextGraphPath);
+        return (knowledge.length > 0 ? knowledge : listSummaryResources(options.contextGraphPath))
+            .map((resource) => ({ ...resource, required: true }));
+    }
+    if (writeRoles.has("knowledge")) {
+        return listSummaryResources(options.contextGraphPath).map((resource) => ({
+            ...resource,
+            required: true,
+        }));
+    }
+    const expected = [];
+    if (options.stage.reads.includes("source"))
+        expected.push(...options.manifest.files.map(sourceFileResource));
+    if (readRoles.has("summary"))
+        expected.push(...listSummaryResources(options.contextGraphPath));
+    if (readRoles.has("knowledge"))
+        expected.push(...listKnowledgeResources(options.contextGraphPath));
+    return expected.map((resource) => ({ ...resource, required: true }));
+}
+export function writeStageExpectedInputs(options) {
+    const manifest = loadContextGraphSourceManifest(options.contextGraphPath);
+    if (!manifest)
+        return null;
+    const generatedAt = options.generatedAt ?? new Date().toISOString();
+    const expected = expectedInputsForStage({
+        contextGraphPath: options.contextGraphPath,
+        manifest,
+        stage: options.stage,
+    });
+    const file = ExpectedInputsFileSchema.parse({
+        kind: "interf-stage-expected-inputs",
+        version: 1,
+        generated_at: generatedAt,
+        stage_id: options.stage.id,
+        expected,
+    });
+    mkdirSync(contextGraphRuntimeStageRoot(options.contextGraphPath, options.stage.id), { recursive: true });
+    writeJsonAtomic(contextGraphRuntimeStageExpectedInputsPath(options.contextGraphPath, options.stage.id), file);
+    return file;
+}
+function metric(key, label, value, total, unit, detail, 
+// Optional honest-guarantee tag rendered into MetricCount.metadata.guarantee.
+// "coverage" = every Source file read/summarized (file-level, provable).
+// "traceability" = every claim/summary/knowledge node linked (provable). Plain
+// counts pass no guarantee. Verification (qa_match) is never a metric guarantee.
+guarantee) {
+    return MetricCountSchema.parse({
+        key,
+        label,
+        value,
+        ...(typeof total === "number" ? { total } : {}),
+        ...(unit ? { unit } : {}),
+        primary: true,
+        ...(typeof total === "number" ? { issue_state: value >= total ? "pass" : "missing" } : {}),
+        ...(detail ? { detail } : {}),
+        ...(guarantee ? { metadata: { guarantee } } : {}),
+    });
+}
+function producedResourcesForStage(options) {
+    const schema = readBuildPlanContextFile(buildPlanPackagePathForContextGraph(options.contextGraphPath));
+    const resources = [];
+    for (const artifactId of options.stage.writes) {
+        const artifact = schema ? findBuildPlanContextArtifact(schema, artifactId) : null;
+        if (!artifact)
+            continue;
+        if (artifact.kind === "file") {
+            if (existsSync(join(options.contextGraphPath, artifact.path))) {
+                resources.push(noteResource(options.contextGraphPath, artifact.path, options.stage.id, knownSourceRefsForGraph(options.contextGraphPath)));
+            }
+            continue;
+        }
+        const root = join(options.contextGraphPath, artifact.path);
+        if (!existsSync(root))
+            continue;
+        for (const filePath of listFilesRecursive(root)) {
+            if (!filePath.toLowerCase().endsWith(".md"))
+                continue;
+            resources.push(noteResource(options.contextGraphPath, relativeToGraph(options.contextGraphPath, filePath), options.stage.id, knownSourceRefsForGraph(options.contextGraphPath)));
+        }
+    }
+    return Array.from(new Map(resources.map((resource) => [resource.id, resource])).values());
+}
+function readLatestStageEvidence(contextGraphPath, stageId) {
+    const history = readExecutionStageLedgerHistory(contextGraphPath)
+        .filter((entry) => entry.stage === stageId && entry.evidence)
+        .sort((left, right) => right.updated_at.localeCompare(left.updated_at));
+    return history[0]?.evidence ?? null;
+}
+function synthesizeReviewedInputs(options) {
+    const evidence = readLatestStageEvidence(options.contextGraphPath, options.stageId);
+    const producedBySourceRef = new Map();
+    for (const item of evidence?.accepted.items ?? []) {
+        for (const sourceRef of item.source_refs) {
+            const paths = item.output_refs.map((ref) => ref.path);
+            producedBySourceRef.set(sourceRef.path, [...(producedBySourceRef.get(sourceRef.path) ?? []), ...paths]);
+        }
+    }
+    const producedIdsByPath = new Map(options.produced.map((resource) => [resource.path ?? resource.id, resource.id]));
+    return options.expected.map((input) => {
+        const sourcePath = stringField(input.metadata?.source_path) ?? input.source_refs[0] ?? "";
+        const outputPaths = sourcePath ? producedBySourceRef.get(sourcePath) ?? [] : [];
+        const outputResourceIds = outputPaths
+            .map((path) => producedIdsByPath.get(path))
+            .filter((id) => Boolean(id));
+        if (outputResourceIds.length > 0) {
+            return ReviewedInputSchema.parse({
+                resource_id: input.id,
+                decision: "used",
+                output_resource_ids: outputResourceIds,
+                source_refs: input.source_refs,
+            });
+        }
+        return ReviewedInputSchema.parse({
+            resource_id: input.id,
+            decision: "missing",
+            reason: "Stage did not write reviewed-inputs.json for this expected input.",
+            source_refs: input.source_refs,
+        });
+    });
+}
+function missingInputs(reviewed) {
+    return reviewed
+        .filter((entry) => entry.decision === "missing" || entry.decision === "blocked" || entry.decision === "not-relevant")
+        .map((entry) => ({
+        resource_id: entry.resource_id,
+        status: entry.decision === "blocked" ? "blocked" : entry.decision === "not-relevant" ? "not-relevant" : "missing",
+        reason: entry.reason ?? `${entry.resource_id} was not used by this stage.`,
+    }));
+}
+/**
+ * The Source path an expected ResourceRef points at, if any. Source-file and
+ * source-unit resources carry it on `metadata.path` / `metadata.source_path`,
+ * and always on `source_refs[0]` / `label`.
+ */
+function expectedResourcePath(resource) {
+    return stringField(resource.metadata?.path)
+        ?? stringField(resource.metadata?.source_path)
+        ?? resource.source_refs[0]
+        ?? resource.path
+        ?? resource.label;
+}
+/**
+ * Backstop: drop `missing` entries that point at OS-generated filesystem junk
+ * (`.DS_Store`, AppleDouble forks, `Thumbs.db`, …). Inventory already filters
+ * these out before they become expected inputs, but a pre-existing on-disk
+ * manifest (or any future inventory path) could still surface one. Matched by
+ * the expected resource's filename only — provable, never by an agent's
+ * `not-relevant` label — so a real skipped content file still counts as missing.
+ */
+function dropFilesystemArtifactMissing(missing, expected) {
+    if (missing.length === 0)
+        return missing;
+    const artifactIds = new Set(expected
+        .filter((resource) => {
+        const path = expectedResourcePath(resource);
+        return Boolean(path) && isFilesystemArtifact(path);
+    })
+        .map((resource) => resource.id));
+    if (artifactIds.size === 0)
+        return missing;
+    return missing.filter((entry) => !artifactIds.has(entry.resource_id));
+}
+function dedupeMissing(missing) {
+    const byId = new Map();
+    for (const entry of missing) {
+        if (!byId.has(entry.resource_id))
+            byId.set(entry.resource_id, entry);
+    }
+    return [...byId.values()];
+}
+function resourceMatchesLink(resource, link) {
+    const cleanLink = normalizeRelativePath(link).replace(/\.md$/i, "");
+    const path = resource.path ? normalizeRelativePath(resource.path).replace(/\.md$/i, "") : "";
+    if (path && (cleanLink === path || cleanLink.endsWith(`/${basename(path)}`)))
+        return true;
+    return slug(resource.label) === slug(link) || (path ? slug(basename(path)) === slug(link) : false);
+}
+function referencedInputs(expected, produced) {
+    const refs = new Map();
+    for (const output of produced) {
+        for (const link of output.links) {
+            const match = expected.find((resource) => resourceMatchesLink(resource, link));
+            if (match)
+                refs.set(match.id, match);
+        }
+        for (const sourceRef of output.source_refs) {
+            const match = expected.find((resource) => resource.source_refs.some((ref) => sourceRef.includes(ref) || ref.includes(sourceRef)));
+            if (match)
+                refs.set(match.id, match);
+        }
+    }
+    return [...refs.values()];
+}
+/**
+ * Summary-backlink coverage for the knowledge layer, computed in memory from the
+ * resources the manifest already holds. A summary is "cited" when a produced note
+ * shares a source ref with it; "linked" when a produced note wikilinks the summary
+ * note. Orphaned = cited but not linked. Source-agnostic: no task taxonomy, no
+ * project-specific input — it reuses the same link/source-ref matching the
+ * referenced-inputs rollup uses.
+ */
+function summaryBacklinkCoverage(expectedSummaries, producedNotes) {
+    const cited = [];
+    const linkedCited = [];
+    const orphaned = [];
+    for (const summary of expectedSummaries) {
+        const isCited = producedNotes.some((note) => note.source_refs.some((noteRef) => summary.source_refs.some((summaryRef) => noteRef.includes(summaryRef) || summaryRef.includes(noteRef))));
+        if (!isCited)
+            continue;
+        cited.push(summary);
+        const isLinked = producedNotes.some((note) => note.links.some((link) => resourceMatchesLink(summary, link)));
+        if (isLinked)
+            linkedCited.push(summary);
+        else
+            orphaned.push(summary);
+    }
+    return { cited, linkedCited, orphaned };
+}
+/**
+ * Does a produced note connect to the summary layer? It connects when it
+ * wikilinks at least one of the expected summary notes. This is the note-side
+ * complement to the orphaned-summary check: it closes the bypass where a
+ * knowledge note cites nothing (no source_refs) — so no summary is "cited" and
+ * the orphan rollup is vacuously empty — or uses a single global link that
+ * doesn't resolve to any summary. Source-agnostic: it reuses the same
+ * link-matching the referenced-inputs rollup uses, with no task taxonomy.
+ */
+function noteConnectsToSummaryLayer(note, expectedSummaries) {
+    return note.links.some((link) => expectedSummaries.some((summary) => resourceMatchesLink(summary, link)));
+}
+/**
+ * Knowledge-layer notes that link no summary at all. A knowledge note's purpose
+ * is to connect prepared knowledge back to the source-backed summary layer; a
+ * note that links nothing in `summaries/` is a disconnected island that must not
+ * pass coverage silently. Scoped to notes that actually live in the knowledge
+ * layer (by write path, via `roleForPath`), so home/artifacts entrypoint notes
+ * produced by the same stage are not falsely flagged.
+ */
+/**
+ * Does a produced note land in the knowledge layer? A note is knowledge-layer
+ * when it carries the `knowledge` role OR its on-disk write path normalizes into
+ * the knowledge layer (via the central `roleForPath` classifier). Single
+ * definition of the predicate every knowledge-layer rollup routes through, so the
+ * note→layer test can never drift between the disconnected-notes, web, and
+ * knowledge-notes paths.
+ */
+function isKnowledgeNote(note) {
+    return note.role === "knowledge"
+        || (note.path ? roleForPath(normalizeRelativePath(note.path)) === "knowledge" : false);
+}
+function disconnectedKnowledgeNotes(expectedSummaries, producedNotes) {
+    if (expectedSummaries.length === 0)
+        return [];
+    return producedNotes.filter((note) => {
+        if (!isKnowledgeNote(note))
+            return false;
+        return !noteConnectsToSummaryLayer(note, expectedSummaries);
+    });
+}
+/**
+ * Knowledge-web connectivity for the produced notes — the manifest-side mirror of
+ * the `knowledge_web_connectivity` Check. Distinct from `disconnectedKnowledgeNotes`
+ * (notes → summaries, the DOWN-link): this is notes ↔ notes (the WEB). A knowledge
+ * note is web-connected when it links another knowledge note OR another knowledge
+ * note links it (UNDIRECTED), reusing the in-memory `ResourceRef.links` graph and
+ * `resourceMatchesLink` the referenced-inputs rollup already uses. Connectedness,
+ * not a count: degree ≥ 1 passes, degree 0 is a disconnected island. Vacuous pass:
+ * ≤1 knowledge note cannot form a web (connected = all, no islands). Both this and
+ * the Check derive connectedness from the same link graph, so they agree.
+ */
+function knowledgeWebConnectivity(producedNotes) {
+    const knowledgeNotes = producedNotes.filter(isKnowledgeNote);
+    if (knowledgeNotes.length <= 1) {
+        return { knowledgeNotes, connected: knowledgeNotes.length, islands: [] };
+    }
+    // A directed edge A→B exists when A links a DIFFERENT knowledge note B. Undirected
+    // connectivity: a node has degree ≥ 1 when it is the source of any edge (outbound)
+    // or the target of any edge from another knowledge note (inbound).
+    const hasOutbound = new Set();
+    const hasInbound = new Set();
+    for (const from of knowledgeNotes) {
+        for (const link of from.links) {
+            for (const to of knowledgeNotes) {
+                if (to.id === from.id)
+                    continue;
+                if (resourceMatchesLink(to, link)) {
+                    hasOutbound.add(from.id);
+                    hasInbound.add(to.id);
+                }
+            }
+        }
+    }
+    const islands = knowledgeNotes.filter((note) => !hasOutbound.has(note.id) && !hasInbound.has(note.id));
+    return { knowledgeNotes, connected: knowledgeNotes.length - islands.length, islands };
+}
+function stageRole(contextGraphPath, stage) {
+    if (stage.id === "source")
+        return "source";
+    // Role is decided by where the stage's artifacts are written on disk, resolved
+    // through the Build Plan schema — never by a stringly stage id or artifact id.
+    // A custom plan that writes artifact id "claims" into path `knowledge/` via
+    // stage "extract-claims" is still the knowledge layer and is still policed.
+    const writeRoles = stageArtifactRoles(contextGraphPath, stage.writes);
+    if (writeRoles.has("summary") || stage.contractType === "build-file-evidence")
+        return "summary";
+    if (writeRoles.has("entrypoint"))
+        return "entrypoint";
+    if (writeRoles.has("knowledge"))
+        return "knowledge";
+    return "other";
+}
+/** Produced notes that land in the knowledge layer, by their on-disk path. */
+function knowledgeNotesIn(produced) {
+    return produced.filter(isKnowledgeNote);
+}
+/**
+ * Knowledge-layer metrics for the notes a stage produced into `knowledge/`. Emitted
+ * whenever a stage produces ANY knowledge note — not gated on the stage's single
+ * primary role — so a multi-layer stage (e.g. an entrypoint stage that ALSO writes
+ * route/index notes into `knowledge/`) still reports knowledge coverage,
+ * backlinks, summary-connectivity, and web connectivity for the notes it added.
+ * This is what lets the GraphManifest roll up FINAL knowledge state from whichever
+ * stage last mutated the layer.
+ *
+ * The backlink / summary-connectivity analyses compare produced knowledge notes
+ * against the ACTUAL summary layer on disk (`summaries`), NOT against the stage's
+ * role-specific `expected` inputs — the entrypoint stage's expected inputs are
+ * knowledge notes, not summaries, so reusing `expected` here would compare the
+ * wrong layer.
+ *
+ * `includeCoverageMetric` adds the `knowledge_coverage` traceability count
+ * (summaries this stage reviewed/used). It is emitted ONLY for a knowledge-role
+ * stage, because only that stage's expected inputs ARE the summaries — emitting
+ * it from a multi-layer stage (e.g. the entrypoint stage) would put a confusing
+ * "knowledge notes reviewed / summary total" denominator mismatch on the primary
+ * metric. The LINK-QUALITY metrics below are emitted for ANY stage that produced
+ * knowledge notes, so the GraphManifest rolls up FINAL link state from whichever
+ * stage last mutated the layer.
+ */
+function knowledgeLayerMetrics(options) {
+    const reviewedCount = options.reviewed.filter((entry) => entry.decision === "used" || entry.decision === "reviewed").length;
+    const usedCount = options.reviewed.filter((entry) => entry.decision === "used").length || options.referenced.length;
+    const backlinks = summaryBacklinkCoverage(options.expectedSummaries, options.produced);
+    const knowledgeNotes = knowledgeNotesIn(options.produced);
+    const disconnected = disconnectedKnowledgeNotes(options.expectedSummaries, options.produced);
+    const connectedNotes = knowledgeNotes.length - disconnected.length;
+    const web = knowledgeWebConnectivity(options.produced);
+    return [
+        // knowledge_coverage counts summaries the knowledge stage reviewed/used — a
+        // TRACEABILITY signal (knowledge linked back to the coverage layer), NOT the
+        // provable file-level "every Source file was read" COVERAGE guarantee. Tagged
+        // traceability so nothing derived/judgment is mislabeled coverage.
+        ...(options.includeCoverageMetric
+            ? [metric("knowledge_coverage", "Knowledge coverage", reviewedCount, options.reviewedTotal, "summaries", `${reviewedCount} / ${options.reviewedTotal} reviewed, ${usedCount} used`, "traceability")]
+            : []),
+        metric("knowledge_notes", "Knowledge notes", knowledgeNotes.length, undefined, "notes"),
+        metric("knowledge_summary_backlinks", "Summaries wikilinked", backlinks.linkedCited.length, backlinks.cited.length, "summaries", backlinks.orphaned.length === 0
+            ? `${backlinks.linkedCited.length} / ${backlinks.cited.length} cited summaries wikilinked`
+            : `${backlinks.orphaned.length} cited summar${backlinks.orphaned.length === 1 ? "y" : "ies"} orphaned (cited but never wikilinked)`, "traceability"),
+        metric("knowledge_summary_connectivity", "Knowledge notes linked to summaries", connectedNotes, knowledgeNotes.length, "notes", disconnected.length === 0
+            ? `${connectedNotes} / ${knowledgeNotes.length} knowledge notes wikilink a summary`
+            : formatDisconnectedNotesMessage(disconnected.length, false), "traceability"),
+        // notes ↔ notes (the WEB), distinct from knowledge_summary_connectivity
+        // (notes → summaries, the DOWN-link). A star (every note links only summaries,
+        // none link each other) reads as islands here; a web reads as connected.
+        metric("knowledge_web_connectivity", "Knowledge notes linked into the web", web.connected, web.knowledgeNotes.length, "notes", web.islands.length === 0
+            ? `${web.connected} / ${web.knowledgeNotes.length} knowledge notes link another knowledge note`
+            : `${web.islands.length} knowledge note${web.islands.length === 1 ? "" : "s"} link no other knowledge note (disconnected island${web.islands.length === 1 ? "" : "s"})`, "traceability"),
+    ];
+}
+/** Entrypoint-layer metric for the home spine + entrypoint notes a stage produced. */
+function entrypointLayerMetrics(produced) {
+    const homeReady = produced.some((resource) => resource.path === "home.md") ? 1 : 0;
+    const entrypointCount = produced.filter((resource) => resource.role === "entrypoint").length;
+    return [
+        metric("entrypoints", "Entrypoints", homeReady, 1, "entrypoints", `${entrypointCount} entrypoint file${entrypointCount === 1 ? "" : "s"} produced`),
+    ];
+}
+function stageMetrics(options) {
+    if (options.role === "source") {
+        return [
+            metric("files_processed", "Files processed", options.produced.length, options.manifest.source_total, "files", undefined, "coverage"),
+        ];
+    }
+    if (options.role === "summary") {
+        const summarizedCount = options.reviewed.filter((entry) => entry.decision === "used" || entry.decision === "reviewed").length;
+        return [
+            metric("source_units_summarized", "Source units summarized", summarizedCount, options.expected.length, "source units", undefined, "coverage"),
+        ];
+    }
+    // Knowledge + entrypoint metrics are LAYER-keyed, not role-keyed: a stage emits
+    // the metrics for every canonical layer its produced resources actually touch.
+    // The default entrypoint stage writes `home`, `artifacts`, AND `knowledge` (route
+    // notes), so it emits BOTH entrypoint and knowledge metrics — the knowledge
+    // branch no longer hides behind an "entrypoint vs knowledge" role precedence.
+    // The GraphManifest then rolls up the FINAL per-layer metric across stages.
+    const metrics = [];
+    const producesKnowledge = knowledgeNotesIn(options.produced).length > 0;
+    const producesEntrypoint = options.role === "entrypoint"
+        || options.produced.some((resource) => resource.role === "entrypoint");
+    if (producesKnowledge) {
+        // Compare produced knowledge notes against the ACTUAL summary layer on disk,
+        // not this stage's role-specific expected inputs (which, for an entrypoint
+        // stage, are knowledge notes — the wrong layer). For a knowledge-role stage
+        // these are the same set. Only the knowledge-role stage emits the
+        // knowledge_coverage traceability count (summaries reviewed), with its
+        // original expected-input denominator.
+        const isKnowledgeRole = options.role === "knowledge";
+        const expectedSummaries = isKnowledgeRole
+            ? options.expected
+            : listSummaryResources(options.contextGraphPath);
+        metrics.push(...knowledgeLayerMetrics({
+            expectedSummaries,
+            reviewedTotal: options.expected.length,
+            produced: options.produced,
+            referenced: options.referenced,
+            reviewed: options.reviewed,
+            includeCoverageMetric: isKnowledgeRole,
+        }));
+    }
+    if (producesEntrypoint) {
+        metrics.push(...entrypointLayerMetrics(options.produced));
+    }
+    if (metrics.length > 0)
+        return metrics;
+    return [
+        metric("outputs_produced", "Outputs produced", options.produced.length, undefined, "outputs"),
+    ];
+}
+export function writeSourceStageManifest(options) {
+    const generatedAt = options.generatedAt ?? new Date().toISOString();
+    const expected = options.sourceManifest.files.map(sourceFileResource);
+    const reviewed = expected.map((resource) => ReviewedInputSchema.parse({
+        resource_id: resource.id,
+        decision: "used",
+        source_refs: resource.source_refs,
+        output_resource_ids: [resource.id],
+    }));
+    const manifest = StageManifestSchema.parse({
+        kind: "interf-stage-manifest",
+        version: 1,
+        generated_at: generatedAt,
+        project: options.sourceManifest.project,
+        run_id: options.runId ?? options.sourceManifest.run_id,
+        build_plan: options.buildPlanId,
+        stage_id: "source",
+        stage_label: "Prepare Source",
+        role: "source",
+        summary: `Source Manifest captured ${options.sourceManifest.source_total} file(s).`,
+        input_manifests: [],
+        expected,
+        reviewed,
+        referenced: expected,
+        missing: [],
+        produced: expected,
+        metrics: [
+            metric("files_processed", "Files processed", expected.length, options.sourceManifest.source_total, "files", undefined, "coverage"),
+        ],
+    });
+    mkdirSync(contextGraphRuntimeStageRoot(options.contextGraphPath, "source"), { recursive: true });
+    writeJsonAtomic(contextGraphRuntimeStageManifestPath(options.contextGraphPath, "source"), manifest);
+    return manifest;
+}
+export function loadStageManifest(contextGraphPath, stageId) {
+    const path = contextGraphRuntimeStageManifestPath(contextGraphPath, stageId);
+    if (!existsSync(path))
+        return null;
+    return readJsonFileWithSchema(path, `stage manifest ${stageId}`, StageManifestSchema);
+}
+export function listStageManifests(contextGraphPath) {
+    const stagesRoot = join(contextGraphPath, ".interf", "runtime", "stages");
+    if (!existsSync(stagesRoot))
+        return [];
+    return readdirSync(stagesRoot, { withFileTypes: true })
+        .filter((entry) => entry.isDirectory())
+        .map((entry) => loadStageManifest(contextGraphPath, entry.name))
+        .filter((entry) => entry !== null)
+        .sort((left, right) => {
+        const order = ["source", "summarize", "knowledge", "entrypoint"];
+        const leftOrder = order.indexOf(left.stage_id);
+        const rightOrder = order.indexOf(right.stage_id);
+        return (leftOrder === -1 ? 99 : leftOrder) - (rightOrder === -1 ? 99 : rightOrder);
+    });
+}
+export function writeStageManifestFromOutputs(options) {
+    const sourceManifest = loadContextGraphSourceManifest(options.contextGraphPath);
+    if (!sourceManifest)
+        return null;
+    const generatedAt = options.generatedAt ?? new Date().toISOString();
+    const expected = loadExpectedInputs(options.contextGraphPath, options.stage.id);
+    const produced = producedResourcesForStage({
+        contextGraphPath: options.contextGraphPath,
+        stage: options.stage,
+    });
+    const explicitReviewed = loadReviewedInputs(options.contextGraphPath, options.stage.id);
+    const reviewed = explicitReviewed ?? synthesizeReviewedInputs({
+        contextGraphPath: options.contextGraphPath,
+        expected,
+        produced,
+        stageId: options.stage.id,
+    });
+    const referenced = referencedInputs(expected, produced);
+    const role = stageRole(options.contextGraphPath, options.stage);
+    // Orphaned summaries (cited via a note's source_refs but never wikilinked) are
+    // missing coverage for the knowledge layer, even when otherwise reviewed. On a
+    // knowledge-role stage the summaries ARE this stage's expected inputs, so the
+    // orphan is an expected-input gap and belongs in `missing` (the StageManifest
+    // schema requires every `missing.resource_id` to be an expected input, so this
+    // is scoped to that case). When a DIFFERENT stage (e.g. the entrypoint stage)
+    // also mutates `knowledge/`, its summaries are not its expected inputs, so the
+    // orphan cannot live in that stage's `missing`; it instead surfaces as the
+    // failing `knowledge_summary_backlinks` metric — which `writeGraphManifest`
+    // rolls into graph readiness from FINAL per-layer state, alongside the
+    // summary-connectivity and web gaps. So no orphan escapes readiness regardless
+    // of which stage last touched the knowledge layer.
+    const orphanMissing = role === "knowledge"
+        ? summaryBacklinkCoverage(expected, produced).orphaned.map((summary) => ({
+            resource_id: summary.id,
+            status: "missing",
+            reason: `${summary.path ?? summary.label} ${ORPHANED_SUMMARY_REASON}`,
+        }))
+        : [];
+    const missing = dropFilesystemArtifactMissing(dedupeMissing([...missingInputs(reviewed), ...orphanMissing]), expected);
+    const manifest = StageManifestSchema.parse({
+        kind: "interf-stage-manifest",
+        version: 1,
+        generated_at: generatedAt,
+        project: options.projectId,
+        run_id: options.runId ?? null,
+        build_plan: options.buildPlanId,
+        stage_id: options.stage.id,
+        stage_label: options.stage.label,
+        role,
+        summary: `${options.stage.label} produced ${produced.length} resource${produced.length === 1 ? "" : "s"}.`,
+        input_manifests: [
+            ResourceRefSchema.parse({
+                id: `manifest:${sourceManifest.manifest_id}`,
+                role: "diagnostic",
+                kind: "source.manifest",
+                label: "Source Manifest",
+                path: ".interf/runtime/source-manifest.json",
+            }),
+        ],
+        expected,
+        reviewed,
+        referenced,
+        missing,
+        produced,
+        metrics: stageMetrics({
+            contextGraphPath: options.contextGraphPath,
+            expected,
+            manifest: sourceManifest,
+            produced,
+            referenced,
+            reviewed,
+            role,
+        }),
+    });
+    mkdirSync(contextGraphRuntimeStageRoot(options.contextGraphPath, options.stage.id), { recursive: true });
+    writeJsonAtomic(contextGraphRuntimeStageManifestPath(options.contextGraphPath, options.stage.id), manifest);
+    return manifest;
+}
+/**
+ * The FINAL value of a metric across the stage manifests, in execution order.
+ * `listStageManifests` returns manifests ordered source → summarize → knowledge →
+ * entrypoint, so the LAST manifest that emitted a given metric key reflects the
+ * final on-disk state of that layer. Taking the last (not the first) match is
+ * what makes the GraphManifest final-state-correct: when the entrypoint stage
+ * mutates `knowledge/` after the knowledge stage, its (later) knowledge metrics
+ * win over the earlier, now-stale knowledge-stage values.
+ */
+function metricByKey(manifests, key) {
+    let latest = null;
+    for (const manifest of manifests) {
+        const found = manifest.metrics.find((entry) => entry.key === key);
+        if (found)
+            latest = found;
+    }
+    return latest;
+}
+function countByKind(resources, kind) {
+    return resources.filter((resource) => resource.kind === kind || resource.kind.startsWith(`${kind}.`)).length;
+}
+function graphResourceCounts(resources, links, sourceRefs) {
+    return {
+        nodes: resources.length,
+        edges: links + sourceRefs,
+        notes: resources.filter((resource) => resource.path?.endsWith(".md")).length,
+        links,
+        source_refs: sourceRefs,
+        claims: countByKind(resources, "knowledge.claim"),
+        entities: countByKind(resources, "knowledge.entity"),
+    };
+}
+export function loadGraphManifest(contextGraphPath) {
+    const path = contextGraphRuntimeGraphManifestPath(contextGraphPath);
+    if (!existsSync(path))
+        return null;
+    return readJsonFileWithSchema(path, "graph manifest", GraphManifestSchema);
+}
+export function writeGraphManifest(options) {
+    const generatedAt = options.generatedAt ?? new Date().toISOString();
+    const manifests = listStageManifests(options.contextGraphPath);
+    // FINAL on-disk state per resource: last-write-wins by id, in execution order.
+    // A note in `knowledge/` that the knowledge stage produced and the entrypoint
+    // stage then re-read (now carrying the route links the entrypoint stage added)
+    // must roll up in its FINAL form, not the earlier knowledge-stage snapshot. The
+    // previous first-by-id kept the stale copy and could mask links/refs added by a
+    // later stage. `set` already overwrites, so iterating in order yields the latest.
+    const resourcesById = new Map();
+    for (const manifest of manifests) {
+        for (const resource of manifest.produced) {
+            resourcesById.set(resource.id, resource);
+        }
+    }
+    const resources = [...resourcesById.values()];
+    const entrypoints = resources.filter((resource) => resource.role === "entrypoint");
+    // Readiness-feeding missing inputs. The per-summary orphaned-summary entries a
+    // knowledge stage records are collapsed here into the single FINAL-state
+    // `knowledge:summary-backlinks` gate (added below from the metric), so one
+    // orphan gap counts once in readiness — not once per summary AND again via the
+    // metric gate. The full, unfiltered stage `missing` is still preserved on each
+    // GraphManifest stage summary (`missing_required_total`).
+    const missing = manifests
+        .flatMap((manifest) => manifest.missing)
+        .filter((entry) => !entry.reason.endsWith(ORPHANED_SUMMARY_REASON));
+    const links = resources.reduce((total, resource) => total + resource.links.length, 0);
+    const sourceRefs = resources.reduce((total, resource) => total + resource.source_refs.length, 0);
+    const sourceMetric = metricByKey(manifests, "files_processed");
+    const summaryMetric = metricByKey(manifests, "source_units_summarized");
+    const knowledgeMetric = metricByKey(manifests, "knowledge_coverage");
+    const entrypointMetric = metricByKey(manifests, "entrypoints");
+    const graphOutputs = graphResourceCounts(resources, links, sourceRefs);
+    const graphOutputMetric = MetricCountSchema.parse({
+        key: "graph_outputs",
+        label: "Graph outputs",
+        value: graphOutputs.notes,
+        unit: "notes",
+        primary: true,
+        detail: `${graphOutputs.notes} notes, ${graphOutputs.links} links, ${graphOutputs.source_refs} source refs`,
+        metadata: graphOutputs,
+    });
+    const primaryMetrics = [
+        sourceMetric,
+        summaryMetric,
+        knowledgeMetric,
+        graphOutputMetric,
+        entrypointMetric,
+    ].filter((entry) => entry !== null);
+    // The three knowledge-layer link-quality gates (summary-orphan, summary
+    // down-connectivity, and notes↔notes web) are derived HERE from the FINAL
+    // on-disk resources, not read off any single stage manifest. Stage manifests
+    // are per-stage snapshots; whichever stage ran last is not guaranteed to be the
+    // one that holds the final knowledge layer (the entrypoint stage adds route
+    // notes after the knowledge stage). Computing from `resources` — the
+    // last-write-wins union of every stage's produced notes — makes readiness
+    // final-state-correct by construction, independent of stage ordering or a
+    // stale per-stage metric. These reuse the SAME in-memory analyses the stage
+    // metrics use, so the gate and the displayed metric agree.
+    const finalSummaries = resources.filter((resource) => resource.role === "summary");
+    const finalKnowledgeNotes = knowledgeNotesIn(resources);
+    const finalBacklinks = summaryBacklinkCoverage(finalSummaries, finalKnowledgeNotes);
+    const finalDisconnected = disconnectedKnowledgeNotes(finalSummaries, finalKnowledgeNotes);
+    const finalWeb = knowledgeWebConnectivity(finalKnowledgeNotes);
+    // Orphaned summaries: cited via a note's source_refs but never wikilinked. A
+    // disconnected coverage layer is not ready. (Per-summary detail still lives on
+    // each knowledge-role stage's `missing`; here it is one collapsed gate.)
+    const backlinkMissing = finalBacklinks.orphaned.length > 0
+        ? [{
+                resource_id: "knowledge:summary-backlinks",
+                status: "missing",
+                reason: `${finalBacklinks.orphaned.length} cited summar${finalBacklinks.orphaned.length === 1 ? "y is" : "ies are"} orphaned (cited by a knowledge note but never wikilinked).`,
+            }]
+        : [];
+    // Down-connectivity: knowledge notes that wikilink no summary at all — the
+    // no-cite / single-global-link bypass. notes → summaries.
+    const connectivityMissing = finalDisconnected.length > 0
+        ? [{
+                resource_id: "knowledge:summary-connectivity",
+                status: "missing",
+                reason: formatDisconnectedNotesMessage(finalDisconnected.length, true),
+            }]
+        : [];
+    // No-orphan knowledge WEB: notes ↔ notes. A disconnected island (a knowledge
+    // note that links no OTHER knowledge note) is not ready. Honest sparsity (≤1
+    // note, or a genuinely connected web) yields no islands and no gap.
+    const webMissing = finalWeb.islands.length > 0
+        ? [{
+                resource_id: "knowledge:web-connectivity",
+                status: "missing",
+                reason: `${finalWeb.islands.length} knowledge note${finalWeb.islands.length === 1 ? "" : "s"} link no other knowledge note (disconnected island${finalWeb.islands.length === 1 ? "" : "s"}).`,
+            }]
+        : [];
+    const entrypointMissing = entrypoints.length > 0
+        ? []
+        : [{
+                resource_id: "entrypoint:home",
+                status: "missing",
+                reason: "Context Graph has no generated entrypoint.",
+            }];
+    // not-relevant is *not* a free pass for a required input. Required inputs that
+    // are skipped without a substitute still count toward the missing-required
+    // rollup, otherwise readiness can flip ready by tagging real gaps not-relevant.
+    const readinessMissing = [
+        ...missing,
+        ...backlinkMissing,
+        ...connectivityMissing,
+        ...webMissing,
+        ...entrypointMissing,
+    ];
+    const missingRequiredTotal = readinessMissing.length;
+    const readiness = {
+        status: missingRequiredTotal === 0 ? "ready" : "not-ready",
+        ready: missingRequiredTotal === 0,
+        summary: missingRequiredTotal === 0
+            ? "Context Graph has complete required coverage metrics."
+            : `${missingRequiredTotal} required coverage item${missingRequiredTotal === 1 ? "" : "s"} missing.`,
+        context_graph_path: options.contextGraphPath,
+        missing_required_total: missingRequiredTotal,
+        missing: readinessMissing,
+    };
+    const graphManifest = GraphManifestSchema.parse({
+        kind: "interf-graph-manifest",
+        version: 1,
+        generated_at: generatedAt,
+        project: options.projectId,
+        graph_id: options.graphId ?? options.runId ?? `${options.projectId}-latest`,
+        run_id: options.runId ?? null,
+        build_plan: options.buildPlanId,
+        intent: options.intent ?? null,
+        graph_path: options.contextGraphPath,
+        primary_metrics: primaryMetrics,
+        stages: manifests.map((manifest) => ({
+            stage_id: manifest.stage_id,
+            stage_label: manifest.stage_label,
+            role: manifest.role,
+            manifest_path: relativeToGraph(options.contextGraphPath, contextGraphRuntimeStageManifestPath(options.contextGraphPath, manifest.stage_id)),
+            summary: manifest.summary,
+            produced_total: manifest.produced.length,
+            missing_required_total: manifest.missing.length,
+            metrics: manifest.metrics,
+        })),
+        entrypoints,
+        resources,
+        graph_outputs: graphOutputs,
+        readiness,
+    });
+    writeJsonAtomic(contextGraphRuntimeGraphManifestPath(options.contextGraphPath), graphManifest);
+    return graphManifest;
+}
+export function reviewedInputsFilePath(contextGraphPath, stageId) {
+    return contextGraphRuntimeStageReviewedInputsPath(contextGraphPath, stageId);
+}
+export function expectedInputsFilePath(contextGraphPath, stageId) {
+    return contextGraphRuntimeStageExpectedInputsPath(contextGraphPath, stageId);
+}
+export function loadStageInputsForManifest(contextGraphPath, stageId) {
+    return loadBuildStageInputs(contextGraphPath, stageId);
+}