@interf/compiler 0.22.2 → 0.50.0

package/dist/packages/runtime/build/check-evaluator.js

@@ -0,0 +1,1226 @@
+import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
+import { basename, dirname, join, relative, resolve } from "node:path";
+import { listFilesRecursive } from "../../contracts/utils/filesystem.js";
+import { parseJsonFrontmatter } from "../../contracts/utils/parse.js";
+import { CANONICAL_LAYER_DIRS, HOME_SPINE_FILE, graphRelativePathPattern, } from "../../contracts/lib/context-graph-layer.js";
+import { CheckKindSchema, SourceManifestSchema, } from "../../contracts/lib/schema.js";
+import { countBrokenWikilinks, isOutputMarkdownFile, validateSynthFiles, } from "./validate.js";
+/**
+ * Build a CheckResult envelope from an evaluator outcome. Centralizes the
+ * timestamp + required-flag plumbing so individual evaluators can
+ * focus on the pass/fail decision and a one-line summary.
+ */
+function makeCheckResult(check, passed, summary, details) {
+    return {
+        check_id: check.id,
+        kind: check.kind,
+        passed,
+        required: check.required,
+        summary,
+        ...(details !== undefined ? { details } : {}),
+        evaluated_at: new Date().toISOString(),
+    };
+}
+function resolveTargetPath(check, context) {
+    const target = context.targetPath;
+    if (!target)
+        return null;
+    const root = resolve(context.rootPath);
+    const absolute = resolve(root, target);
+    // Defense in depth — schema-level validation already rejects path
+    // traversal, but a hand-edited Build Plan or stale on-disk fixture could
+    // slip through. Reject anything that escapes the root.
+    if (absolute !== root && !absolute.startsWith(`${root}/`)) {
+        return null;
+    }
+    return absolute;
+}
+function listMarkdownFiles(absolutePath) {
+    if (!existsSync(absolutePath))
+        return [];
+    try {
+        const stats = statSync(absolutePath);
+        if (stats.isFile()) {
+            return isOutputMarkdownFile(absolutePath) ? [absolutePath] : [];
+        }
+        if (stats.isDirectory()) {
+            return listFilesRecursive(absolutePath, isOutputMarkdownFile);
+        }
+    }
+    catch {
+        return [];
+    }
+    return [];
+}
+function countFiles(absolutePath) {
+    if (!existsSync(absolutePath))
+        return 0;
+    try {
+        const stats = statSync(absolutePath);
+        if (stats.isFile())
+            return 1;
+        if (stats.isDirectory()) {
+            return listFilesRecursive(absolutePath, () => true).length;
+        }
+    }
+    catch {
+        return 0;
+    }
+    return 0;
+}
+function countSourceSummaryFolders(absolutePath, options) {
+    if (!existsSync(absolutePath))
+        return { actual: 0, missingSummary: [] };
+    try {
+        const stats = statSync(absolutePath);
+        if (!stats.isDirectory())
+            return { actual: 0, missingSummary: [] };
+        const missingSummary = [];
+        let actual = 0;
+        for (const entry of readdirSync(absolutePath, { withFileTypes: true })) {
+            if (!entry.isDirectory())
+                continue;
+            const dirPath = join(absolutePath, entry.name);
+            const hasSummary = existsSync(join(dirPath, options.summaryFile));
+            const hasManifest = existsSync(join(dirPath, options.manifestFile));
+            if (hasSummary || hasManifest) {
+                actual += 1;
+            }
+            else {
+                missingSummary.push(entry.name);
+            }
+        }
+        return { actual, missingSummary };
+    }
+    catch {
+        return { actual: 0, missingSummary: [] };
+    }
+}
+function summaryDirectoriesWithEvidence(absolutePath, options) {
+    const dirs = new Set();
+    if (!existsSync(absolutePath))
+        return dirs;
+    for (const file of listFilesRecursive(absolutePath, () => true)) {
+        const name = basename(file);
+        if (name !== options.summaryFile && name !== options.manifestFile)
+            continue;
+        dirs.add(relative(absolutePath, dirname(file)).replaceAll("\\", "/"));
+    }
+    return dirs;
+}
+function sourceSummaryFolderCandidates(sourcePath, sourceFileId, basenameCounts) {
+    const normalized = sourcePath.replaceAll("\\", "/");
+    const base = basename(normalized);
+    const candidates = [
+        normalized,
+        sourceFileId,
+        basenameCounts.get(base) === 1 ? base : "",
+    ].filter((candidate) => candidate.length > 0);
+    return [...new Set(candidates)];
+}
+function sourceSummaryCoverage(absolutePath, manifest, options) {
+    const evidenceDirs = summaryDirectoriesWithEvidence(absolutePath, options);
+    const matchedDirs = new Set();
+    const missingSourcePaths = [];
+    const basenameCounts = new Map();
+    for (const sourceFile of manifest.files) {
+        const base = basename(sourceFile.path.replaceAll("\\", "/"));
+        basenameCounts.set(base, (basenameCounts.get(base) ?? 0) + 1);
+    }
+    for (const sourceFile of manifest.files) {
+        const candidates = sourceSummaryFolderCandidates(sourceFile.path, sourceFile.id, basenameCounts);
+        const matched = candidates.find((candidate) => evidenceDirs.has(candidate));
+        if (matched) {
+            matchedDirs.add(matched);
+        }
+        else {
+            missingSourcePaths.push(sourceFile.path);
+        }
+    }
+    return {
+        actual: manifest.files.length - missingSourcePaths.length,
+        expected: manifest.source_total,
+        missingSourcePaths,
+        extraSummaryFolders: [...evidenceDirs].filter((dir) => !matchedDirs.has(dir)).sort((left, right) => left.localeCompare(right)),
+    };
+}
+const WIKILINK_TARGET_PATTERN = /\[\[([^[\]\n]+)\]\]/g;
+const MARKDOWN_LINK_TARGET_PATTERN = /!?\[[^\]\n]*\]\(([^)\n]+)\)/g;
+function normalizeGraphPath(value) {
+    return value.replaceAll("\\", "/").replace(/^\.\/+/, "").replace(/\.md$/i, "").replace(/\/+$/g, "");
+}
+/**
+ * Like normalizeGraphPath but preserves a trailing `.md` — summary folders are
+ * named after the source file and legitimately end in `.md` (e.g.
+ * `summaries/meeting-notes.md/`). Stripping it would split the folder identity.
+ */
+function normalizeFolderPath(value) {
+    return value.replaceAll("\\", "/").replace(/^\.\/+/, "").replace(/\/+$/g, "");
+}
+/**
+ * Wikilink targets referenced by a single note, normalized to graph-relative
+ * basenames (no `.md`, no `#anchor`, no `|alias`). Source-agnostic: reads only
+ * the `[[...]]` syntax, never a task taxonomy.
+ */
+function noteWikilinkTargets(content) {
+    const targets = [];
+    for (const match of content.matchAll(WIKILINK_TARGET_PATTERN)) {
+        const raw = match[1]?.split("|")[0]?.split("#")[0]?.trim();
+        if (raw)
+            targets.push(normalizeGraphPath(raw));
+    }
+    return targets;
+}
+/**
+ * Every link token a note references, across the three link forms the
+ * StageManifest's `parseLinks` reads: `[[wikilinks]]`, `[markdown](relative.md)`
+ * links (http(s) excluded), and bare graph-relative path mentions in body text
+ * (`knowledge/foo`, via the shared `graphRelativePathPattern` so the scanner and
+ * the layer model can never list different folders). Each token is normalized to
+ * a graph-relative path with no `.md`, anchor, or alias. Reusing the same link
+ * surface the manifest uses is what keeps the Check and the manifest rollup in
+ * lockstep on which notes are web-connected.
+ */
+function noteLinkTargets(content) {
+    const targets = new Set();
+    for (const target of noteWikilinkTargets(content))
+        targets.add(target);
+    for (const match of content.matchAll(MARKDOWN_LINK_TARGET_PATTERN)) {
+        const raw = match[1]?.split("#")[0]?.trim();
+        if (!raw || /^https?:\/\//i.test(raw))
+            continue;
+        targets.add(normalizeGraphPath(raw));
+    }
+    for (const match of content.matchAll(graphRelativePathPattern())) {
+        const raw = match[1]?.split("#")[0]?.trim().replace(/[),.;:]+$/g, "");
+        if (raw)
+            targets.add(normalizeGraphPath(raw));
+    }
+    return [...targets].filter((target) => target.length > 0);
+}
+/**
+ * Resolve a single link token to the knowledge note it names, or report that it
+ * is ambiguous. Mirrors the basename-aliasing discipline `existingSummaryFolderSet`
+ * already uses in this file: a full graph-path always resolves (paths are unique
+ * within the subtree); a token ending `/<basename>` resolves to the unique note
+ * with that path suffix; a BARE basename resolves ONLY when exactly one note
+ * carries it. A bare basename two or more notes share (e.g. `[[claim]]` for both
+ * `topics/claim` and `entities/claim`) is `ambiguous` — it must NOT credit a web
+ * edge to one arbitrarily, which would silently connect the linker and hide the
+ * other namesake's island. Returns the matched note, `ambiguous`, or `null`.
+ */
+function resolveLinkToNote(token, byGraphPath, byBasename, ambiguousBasenames) {
+    const clean = normalizeGraphPath(token);
+    if (clean.length === 0)
+        return null;
+    const exact = byGraphPath.get(clean);
+    if (exact)
+        return exact;
+    if (clean.includes("/")) {
+        // A path-shaped token: credit a note whose full path is the token's trailing
+        // segments. Unique by construction (graph paths are unique), so no ambiguity.
+        const suffix = basename(clean);
+        for (const note of byGraphPath.values()) {
+            if (clean.endsWith(`/${note.base}`) && note.base === suffix && clean.endsWith(note.graphPath)) {
+                return note;
+            }
+        }
+        return null;
+    }
+    // A bare basename: resolves only when unambiguous; a shared basename is a gap.
+    if (ambiguousBasenames.has(clean))
+        return "ambiguous";
+    return byBasename.get(clean) ?? null;
+}
+/**
+ * Resolve a note-relative link token (`./x`, `../x`) against the linking note's
+ * directory into an absolute graph path, so a relative wikilink credits a web
+ * edge the same way the wikilink validator resolves it. Without this, a note
+ * that links `[[../launch]]` is falsely scored a disconnected island. Non-relative
+ * tokens (full graph paths, bare basenames) are returned untouched for the global
+ * lookup.
+ */
+function resolveRelativeGraphPath(fromGraphPath, token) {
+    const lastSlash = fromGraphPath.lastIndexOf("/");
+    const segments = lastSlash >= 0 ? fromGraphPath.slice(0, lastSlash).split("/") : [];
+    for (const part of token.split("/")) {
+        if (part === "" || part === ".")
+            continue;
+        if (part === "..") {
+            segments.pop();
+            continue;
+        }
+        segments.push(part);
+    }
+    return normalizeGraphPath(segments.join("/"));
+}
+/**
+ * Markdown notes that form the CONTENT of a Context Graph — the canonical content
+ * layers (`summaries/`, `knowledge/`, `artifacts/`) plus the `home.md` spine —
+ * resolved to absolute file paths. Deliberately EXCLUDES the runtime scaffolding
+ * that also lives under the graph root (`.interf/`, `.claude/`, `.agents/`,
+ * skill `SKILL.md` docs, `CLAUDE.md`, `AGENTS.md`, view specs): those are not
+ * graph notes and must never be scored for web connectivity — they are always
+ * "islands" and several share the basename `SKILL`, which would inject false
+ * ambiguity. This mirrors the dot-entry skipping the semantic-graph builder
+ * already does, and keys off the central `CANONICAL_LAYER_DIRS` / `HOME_SPINE_FILE`
+ * so the connectivity floor and the layer model never list different folders.
+ */
+function collectGraphContentNotes(graphRoot) {
+    const files = [];
+    for (const layer of CANONICAL_LAYER_DIRS) {
+        files.push(...listMarkdownFiles(join(graphRoot, layer)));
+    }
+    const home = join(graphRoot, HOME_SPINE_FILE);
+    if (existsSync(home) && isOutputMarkdownFile(home))
+        files.push(home);
+    return files;
+}
+/**
+ * Note-web connectivity over a pre-collected note set — the filesystem-side
+ * mirror of the StageManifest's `knowledgeWebConnectivity`. Each file in `noteFiles`
+ * IS a note in the web (the caller chooses the scope and the file set: the
+ * knowledge layer for `knowledge_web_connectivity`, the canonical CONTENT layers
+ * for `graph_notes_connected`), so no layer re-derivation is needed here. A note
+ * is web-connected when it links a DIFFERENT note in the same set OR is linked
+ * by one (UNDIRECTED, degree ≥ 1); degree 0 is a disconnected island.
+ * Connectedness, not a count. Vacuous pass: ≤ 1 note cannot form a web, so it is
+ * reported connected with no islands. Edges and matching reuse the same link
+ * surface and basename-aliasing rule the manifest and the backlink check use, so
+ * the gates agree on islands.
+ */
+function analyzeNoteWeb(noteFiles, context) {
+    const root = resolve(context.rootPath);
+    const notes = noteFiles.map((file) => {
+        const graphPath = normalizeGraphPath(relative(root, file).replaceAll("\\", "/"));
+        return { file, graphPath, base: basename(graphPath) };
+    });
+    if (notes.length <= 1) {
+        return { notes: notes.length, connected: notes.length, islands: [], ambiguousLinkNotes: [] };
+    }
+    // Full path always keys a note; a basename keys a note only when unique. A
+    // basename two or more notes share is ambiguous and never resolves a bare link.
+    const byGraphPath = new Map();
+    const basenameCounts = new Map();
+    for (const note of notes) {
+        byGraphPath.set(note.graphPath, note);
+        basenameCounts.set(note.base, (basenameCounts.get(note.base) ?? 0) + 1);
+    }
+    const byBasename = new Map();
+    const ambiguousBasenames = new Set();
+    for (const note of notes) {
+        if ((basenameCounts.get(note.base) ?? 0) > 1) {
+            ambiguousBasenames.add(note.base);
+            continue;
+        }
+        byBasename.set(note.base, note);
+    }
+    const hasOutbound = new Set();
+    const hasInbound = new Set();
+    const ambiguousLinkNotes = new Set();
+    for (const from of notes) {
+        for (const token of noteLinkTargets(readFileSync(from.file, "utf8"))) {
+            const candidate = token.startsWith("../") || token.startsWith("./")
+                ? resolveRelativeGraphPath(from.graphPath, token)
+                : token;
+            const resolved = resolveLinkToNote(candidate, byGraphPath, byBasename, ambiguousBasenames);
+            if (resolved === "ambiguous") {
+                ambiguousLinkNotes.add(from.graphPath);
+                continue;
+            }
+            if (!resolved || resolved.graphPath === from.graphPath)
+                continue;
+            hasOutbound.add(from.graphPath);
+            hasInbound.add(resolved.graphPath);
+        }
+    }
+    const islands = notes
+        .filter((note) => !hasOutbound.has(note.graphPath) && !hasInbound.has(note.graphPath))
+        .map((note) => note.graphPath)
+        .sort((left, right) => left.localeCompare(right));
+    return {
+        notes: notes.length,
+        connected: notes.length - islands.length,
+        islands,
+        ambiguousLinkNotes: [...ambiguousLinkNotes].sort((left, right) => left.localeCompare(right)),
+    };
+}
+/**
+ * Source refs a note declares, drawn from frontmatter source keys and from any
+ * literal source path mentioned in the body. Mirrors the StageManifest reader so
+ * the check and the manifest agree on what a note "cites".
+ */
+function noteSourceRefs(content, frontmatter, knownSourcePaths) {
+    const refs = new Set();
+    for (const key of ["source_refs", "source_ref", "source_path", "source"]) {
+        const value = frontmatter[key];
+        if (typeof value === "string" && value.trim().length > 0)
+            refs.add(value.trim());
+        if (Array.isArray(value)) {
+            for (const entry of value) {
+                if (typeof entry === "string" && entry.trim().length > 0)
+                    refs.add(entry.trim());
+            }
+        }
+    }
+    for (const sourcePath of knownSourcePaths) {
+        if (content.includes(sourcePath))
+            refs.add(sourcePath);
+    }
+    return [...refs];
+}
+/**
+ * Resolve which summary folders actually exist on disk (folders under the
+ * summaries directory that hold a summary or manifest file). Returns a lookup
+ * from any reasonable reference form — the folder's graph-relative path and its
+ * basename — to the canonical folder path, plus the set of basenames that more
+ * than one folder carries. Reuses the same summary/manifest evidence convention
+ * the summary-coverage check uses.
+ *
+ * A basename alias is registered ONLY when that basename is unambiguous across
+ * summary folders. When two folders share a basename (e.g. `dept/report.pdf`
+ * and `legal/report.pdf` both basename `report.pdf`), aliasing one of them
+ * would silently resolve a basename-only ref to the wrong folder and HIDE a
+ * real orphan. Ambiguous basenames are left out of the `lookup` so a
+ * basename-only ref to them never resolves to one arbitrary folder; the
+ * `ambiguousBasenames` set lets the caller treat such a ref as an unresolved
+ * gap to surface rather than a silent pass. Full-path refs always resolve
+ * regardless of basename collisions.
+ */
+function existingSummaryFolderSet(summariesAbsolutePath, options) {
+    const lookup = new Map();
+    const evidenceDirs = summaryDirectoriesWithEvidence(summariesAbsolutePath, options);
+    const folders = [];
+    const basenameCounts = new Map();
+    for (const dir of evidenceDirs) {
+        const folder = normalizeFolderPath(dir);
+        if (folder.length === 0)
+            continue;
+        folders.push(folder);
+        // Full-path key always wins; it is unique per folder.
+        lookup.set(folder, folder);
+        const base = basename(folder);
+        if (base)
+            basenameCounts.set(base, (basenameCounts.get(base) ?? 0) + 1);
+    }
+    const ambiguousBasenames = new Set();
+    // Second pass: alias a basename to its folder only when exactly one folder
+    // carries that basename. Skip any basename that already collides with a
+    // full-path key (a folder literally named like another folder's basename) —
+    // the path key must not be shadowed.
+    for (const folder of folders) {
+        const base = basename(folder);
+        if (!base || base === folder)
+            continue;
+        if ((basenameCounts.get(base) ?? 0) > 1) {
+            ambiguousBasenames.add(base);
+            continue;
+        }
+        if (lookup.has(base))
+            continue;
+        lookup.set(base, folder);
+    }
+    return { lookup, ambiguousBasenames };
+}
+/**
+ * Whether one normalized graph path contains another at a path-segment (or
+ * trailing-delimiter) boundary, not mid-segment. `decks/q3.pptx` contains
+ * `decks/q3.pptx/pages/3` and `decks/q3.pptx#page=25`, but `decks/q3.pptx` does
+ * NOT contain `decks/q3.pptx-archive` — the suffix must begin at a `/` or `#`
+ * boundary. Source-agnostic: pure string-shape, no task taxonomy.
+ */
+function containsAtBoundary(container, inner) {
+    if (inner.length === 0 || container.length < inner.length)
+        return false;
+    const index = container.indexOf(inner);
+    if (index < 0)
+        return false;
+    // Inner must start at a segment boundary (path start or right after a "/").
+    if (index > 0 && container[index - 1] !== "/")
+        return false;
+    // Inner must end at a segment boundary (path end, or before a "/" / "#"
+    // anchor). Anything else (e.g. "q3.pptx" inside "q3.pptx-archive") is a
+    // mid-segment false match.
+    const after = container[index + inner.length];
+    return after === undefined || after === "/" || after === "#";
+}
+/**
+ * Map an arbitrary source ref to the summary-folder names that could hold its
+ * summary. Generic across any Source: a ref like `decks/q3.pptx` matches the
+ * `decks/q3.pptx` folder, the basename `q3.pptx` (when unambiguous), or the
+ * manifest file id. Never hardcodes a task or filename.
+ */
+function summaryFolderCandidatesForRef(ref, manifest, basenameCounts) {
+    const normalizedRef = ref.replaceAll("\\", "/");
+    const normalized = normalizeFolderPath(ref).replace(/^summaries\//, "");
+    const candidates = new Set();
+    candidates.add(normalized);
+    const base = basename(normalized);
+    if (base)
+        candidates.add(base);
+    // Resolve through the Source Manifest so a page-level or partial ref still
+    // points at the file-level summary folder. Match only at path-segment
+    // boundaries: a bare substring test over-matches (`q3` would hit
+    // `q3-archive`), crediting the wrong summary and hiding a real orphan.
+    for (const file of manifest?.files ?? []) {
+        const filePath = file.path.replaceAll("\\", "/");
+        if (containsAtBoundary(normalizedRef, filePath) ||
+            containsAtBoundary(filePath, normalized) ||
+            containsAtBoundary(normalized, filePath)) {
+            candidates.add(filePath);
+            if (basenameCounts.get(basename(filePath)) === 1)
+                candidates.add(basename(filePath));
+            candidates.add(file.id);
+        }
+    }
+    return [...candidates].filter((candidate) => candidate.length > 0);
+}
+/**
+ * Orphaned-summary analysis for a knowledge-style layer: a summary folder that is
+ * cited by some note's source_refs but is wikilinked by no note in the layer.
+ * Fully generic — derives expected backlinks from the notes' own refs and the
+ * Source Manifest, with no project-specific or task-specific input.
+ */
+function analyzeSummaryBacklinks(layerDir, context, options) {
+    const root = resolve(context.rootPath);
+    const manifest = loadSourceManifestForCheck(context).manifest;
+    const knownSourcePaths = manifest?.files.map((file) => file.path.replaceAll("\\", "/")) ?? [];
+    const basenameCounts = new Map();
+    for (const path of knownSourcePaths) {
+        const base = basename(path);
+        basenameCounts.set(base, (basenameCounts.get(base) ?? 0) + 1);
+    }
+    // Summary folders that actually exist on disk. You can only orphan a summary
+    // that exists — a note citing a source with no summary folder is not a
+    // backlink violation (there is nothing to link to). The lookup keys a folder
+    // by its full path and, only when unambiguous, its basename; ambiguousBasenames
+    // names the basenames carried by more than one folder.
+    const { lookup: existingSummaryFolders, ambiguousBasenames } = existingSummaryFolderSet(join(root, options.summariesDir), { summaryFile: options.summaryFile, manifestFile: options.manifestFile });
+    // Resolve a ref to a canonical summary folder. Three outcomes:
+    //   "resolved"  — a candidate matched an existing folder.
+    //   "ambiguous" — nothing matched, but a basename candidate collides with two
+    //                 or more existing folders, so we refuse to pick one. This is a
+    //                 gap to surface, not a clean miss.
+    //   "absent"    — nothing matched and no summary folder exists for the ref.
+    const resolveCitedFolder = (ref) => {
+        const candidates = summaryFolderCandidatesForRef(ref, manifest, basenameCounts);
+        for (const candidate of candidates) {
+            const folder = existingSummaryFolders.get(candidate);
+            if (folder)
+                return { kind: "resolved", folder };
+        }
+        if (candidates.some((candidate) => ambiguousBasenames.has(candidate))) {
+            return { kind: "ambiguous" };
+        }
+        return { kind: "absent" };
+    };
+    // Set of every summary-folder backlink wikilink target present anywhere in the
+    // layer, normalized to the folder name (drop the trailing summary/manifest leaf).
+    const linkedSummaries = new Set();
+    const summaryLeaf = normalizeGraphPath(options.summaryFile);
+    const manifestLeaf = normalizeGraphPath(options.manifestFile);
+    const citedSummaryToNotes = new Map();
+    const notesWithUnlinkedCitations = new Set();
+    const notesWithAmbiguousCitations = new Set();
+    let notesScanned = 0;
+    const notes = listMarkdownFiles(layerDir);
+    // First pass: every existing summary folder linked anywhere in the layer,
+    // resolved to its canonical folder name so basename and path links agree. A
+    // wikilink is a concrete graph path, so it credits a backlink ONLY when the
+    // target resolves to a real summary folder. `existingSummaryFolders` already
+    // keys both each folder's full path and its basename (the latter only when
+    // unambiguous), so a legitimate bare-basename link still resolves. We do NOT
+    // fall back to a separate basename(folderRef) lookup: that would let a broken
+    // wikilink — one whose folder path does not exist (e.g.
+    // `[[summaries/typo/q3.pptx/summary]]`) — launder through its basename and
+    // wrongly credit an unrelated namesake folder, hiding a real orphan.
+    for (const note of notes) {
+        const content = readFileSync(note, "utf8");
+        for (const target of noteWikilinkTargets(content)) {
+            const withinSummaries = target.startsWith(`${options.summariesDir}/`)
+                ? target.slice(options.summariesDir.length + 1)
+                : null;
+            if (withinSummaries === null)
+                continue;
+            const segments = withinSummaries.split("/");
+            const leaf = segments[segments.length - 1] ?? "";
+            const folderRef = leaf === summaryLeaf || leaf === manifestLeaf
+                ? segments.slice(0, -1).join("/")
+                : withinSummaries;
+            const folder = existingSummaryFolders.get(folderRef);
+            if (folder)
+                linkedSummaries.add(folder);
+        }
+    }
+    // Second pass: every existing summary a note cites, and whether it is linked.
+    for (const note of notes) {
+        notesScanned += 1;
+        const content = readFileSync(note, "utf8");
+        const parsed = parseJsonFrontmatter(content);
+        const frontmatter = parsed?.frontmatter ?? {};
+        const refs = noteSourceRefs(content, frontmatter, knownSourcePaths);
+        if (refs.length === 0)
+            continue;
+        const noteRel = relative(root, note).replaceAll("\\", "/");
+        let noteHasUnlinked = false;
+        let noteHasAmbiguous = false;
+        for (const ref of refs) {
+            const resolution = resolveCitedFolder(ref);
+            // An ambiguous basename-only citation cannot be proven backlinked; treat it
+            // as a surfaced gap rather than skipping it (which would hide the orphan).
+            if (resolution.kind === "ambiguous") {
+                noteHasAmbiguous = true;
+                continue;
+            }
+            // Only an existing summary folder can be orphaned; skip refs that point at
+            // a source with no summary in this graph.
+            if (resolution.kind === "absent")
+                continue;
+            const folder = resolution.folder;
+            const linked = linkedSummaries.has(folder);
+            const list = citedSummaryToNotes.get(folder) ?? [];
+            list.push(noteRel);
+            citedSummaryToNotes.set(folder, list);
+            if (!linked)
+                noteHasUnlinked = true;
+        }
+        if (noteHasUnlinked)
+            notesWithUnlinkedCitations.add(noteRel);
+        if (noteHasAmbiguous)
+            notesWithAmbiguousCitations.add(noteRel);
+    }
+    const citedSummaries = [...citedSummaryToNotes.keys()];
+    const orphanedSummaries = citedSummaries
+        .filter((summary) => !linkedSummaries.has(summary))
+        .sort((left, right) => left.localeCompare(right));
+    return {
+        citedSummaries,
+        linkedSummaries,
+        orphanedSummaries,
+        ambiguousCitations: [...notesWithAmbiguousCitations].sort((left, right) => left.localeCompare(right)),
+        notesWithUnlinkedCitations: [...notesWithUnlinkedCitations].sort((left, right) => left.localeCompare(right)),
+        notesScanned,
+    };
+}
+function checkPhrases(check) {
+    if (Array.isArray(check.params?.phrases)) {
+        return check.params.phrases.filter((phrase) => typeof phrase === "string");
+    }
+    if (typeof check.params?.text === "string") {
+        return [check.params.text];
+    }
+    return [];
+}
+function frontmatterKeys(check) {
+    return Array.isArray(check.params?.keys)
+        ? check.params.keys.filter((key) => typeof key === "string" && key.trim().length > 0)
+        : [];
+}
+function hasNonEmptyFrontmatterValue(value) {
+    if (typeof value === "string")
+        return value.trim().length > 0;
+    if (typeof value === "number" || typeof value === "boolean")
+        return true;
+    if (Array.isArray(value))
+        return value.some(hasNonEmptyFrontmatterValue);
+    if (value && typeof value === "object")
+        return Object.keys(value).length > 0;
+    return false;
+}
+function collectFrontmatterFailures(files, predicate) {
+    const invalid = [];
+    const missing = [];
+    for (const file of files) {
+        const parsed = parseJsonFrontmatter(readFileSync(file, "utf8"));
+        if (!parsed) {
+            invalid.push(file);
+            continue;
+        }
+        if (!predicate(parsed.frontmatter)) {
+            missing.push(file);
+        }
+    }
+    return { invalid, missing };
+}
+/**
+ * Declarative exemption clause for `source_refs_required`: `params.exempt_when`
+ * maps a frontmatter key to the values that exempt a note from the requirement
+ * (an empty value list means "any non-empty value exempts"). A note is exempt
+ * when it declares any matching signal — e.g. a pure index/navigation note that
+ * asserts nothing can opt out with `note_role: index` rather than being pushed
+ * to fabricate `source_refs`. This is config, not engine taxonomy: the keys and
+ * values live in the Build Plan, so no concept is hardcoded in the runtime.
+ */
+function exemptWhenClause(check) {
+    const raw = check.params?.exempt_when;
+    if (!raw || typeof raw !== "object" || Array.isArray(raw))
+        return {};
+    const out = {};
+    for (const [key, value] of Object.entries(raw)) {
+        if (typeof key !== "string" || key.trim().length === 0)
+            continue;
+        out[key] = Array.isArray(value)
+            ? value.filter((entry) => typeof entry === "string").map((entry) => entry.trim().toLowerCase())
+            : [];
+    }
+    return out;
+}
+function isExemptFromSourceRefs(frontmatter, exemptWhen) {
+    for (const [key, allowed] of Object.entries(exemptWhen)) {
+        const value = frontmatter[key];
+        if (!hasNonEmptyFrontmatterValue(value))
+            continue;
+        if (allowed.length === 0)
+            return true;
+        if (typeof value === "string" && allowed.includes(value.trim().toLowerCase()))
+            return true;
+        if (Array.isArray(value) && value.some((entry) => typeof entry === "string" && allowed.includes(entry.trim().toLowerCase()))) {
+            return true;
+        }
+    }
+    return false;
+}
+function loadSourceManifestForCheck(context, path = ".interf/runtime/source-manifest.json") {
+    const manifestPath = resolve(context.rootPath, path);
+    if (!existsSync(manifestPath))
+        return { manifest: null, error: `Source Manifest does not exist at ${path}.` };
+    try {
+        const manifest = SourceManifestSchema.parse(JSON.parse(readFileSync(manifestPath, "utf8")));
+        return { manifest, error: null };
+    }
+    catch (error) {
+        return {
+            manifest: null,
+            error: `Source Manifest is invalid: ${error instanceof Error ? error.message : String(error)}`,
+        };
+    }
+}
+function loadRequiredSourceManifestForCheck(check, context) {
+    const manifestPath = typeof check.params?.manifest_path === "string"
+        ? check.params.manifest_path
+        : ".interf/runtime/source-manifest.json";
+    const loaded = loadSourceManifestForCheck(context, manifestPath);
+    if (loaded.manifest)
+        return { manifest: loaded.manifest, failure: null };
+    return {
+        manifest: null,
+        failure: makeCheckResult(check, false, loaded.error ?? "Source Manifest is required for this source-bound check.", { manifest_path: manifestPath }),
+    };
+}
+function sourceManifestPageTotal(context) {
+    const loaded = loadSourceManifestForCheck(context);
+    if (!loaded.manifest)
+        return { total: 0, error: loaded.error };
+    let total = 0;
+    for (const file of loaded.manifest.files) {
+        const pageUnits = file.inspectable_units.filter((unit) => unit.kind === "page").length;
+        total += pageUnits > 0 ? pageUnits : file.page_count ?? 0;
+    }
+    return { total, error: null };
+}
+const EVALUATORS = {
+    file_exists(check, context) {
+        const target = resolveTargetPath(check, context);
+        if (!target) {
+            return makeCheckResult(check, false, "No target path provided for file_exists check.");
+        }
+        if (!existsSync(target)) {
+            return makeCheckResult(check, false, "File or directory does not exist.", { path: context.targetPath });
+        }
+        try {
+            const stats = statSync(target);
+            if (stats.isFile() && stats.size === 0) {
+                return makeCheckResult(check, false, "File exists but is empty.", { path: context.targetPath });
+            }
+            return makeCheckResult(check, true, `Path exists (${stats.isDirectory() ? "directory" : "file"}).`);
+        }
+        catch {
+            return makeCheckResult(check, false, "Could not stat target path.", { path: context.targetPath });
+        }
+    },
+    source_manifest_valid(check, context) {
+        const manifestPath = typeof check.params?.path === "string"
+            ? check.params.path
+            : ".interf/runtime/source-manifest.json";
+        const loaded = loadSourceManifestForCheck(context, manifestPath);
+        if (!loaded.manifest) {
+            return makeCheckResult(check, false, loaded.error ?? "Source Manifest is invalid.");
+        }
+        return makeCheckResult(check, true, `Source Manifest lists ${loaded.manifest.source_total} source file(s).`, { source_manifest_id: loaded.manifest.manifest_id, source_total: loaded.manifest.source_total });
+    },
+    min_file_count(check, context) {
+        const target = resolveTargetPath(check, context);
+        if (!target) {
+            return makeCheckResult(check, false, "No target path provided for min_file_count check.");
+        }
+        const min = typeof check.params?.min === "number" ? check.params.min : 1;
+        const actual = countFiles(target);
+        if (actual >= min) {
+            return makeCheckResult(check, true, `${actual} file(s) (≥ ${min}).`, { actual, min });
+        }
+        return makeCheckResult(check, false, `Found ${actual} file(s); expected at least ${min}.`, { actual, min });
+    },
+    min_file_count_matches_source(check, context) {
+        const target = resolveTargetPath(check, context);
+        if (!target) {
+            return makeCheckResult(check, false, "No target path provided for min_file_count_matches_source check.");
+        }
+        const sourceManifest = loadRequiredSourceManifestForCheck(check, context);
+        if (!sourceManifest.manifest)
+            return sourceManifest.failure ?? makeCheckResult(check, false, "Source Manifest is required.");
+        const matchKey = typeof check.params?.match === "string" ? check.params.match : "source_total";
+        const expected = matchKey === "source_total"
+            ? sourceManifest.manifest.source_total
+            : context.counts?.[matchKey];
+        if (typeof expected !== "number") {
+            return makeCheckResult(check, false, `Cannot evaluate: count "${matchKey}" not available in context.`, { matchKey });
+        }
+        if (expected <= 0) {
+            return makeCheckResult(check, false, `Cannot evaluate: count "${matchKey}" must be greater than zero.`, { matchKey, expected });
+        }
+        const actual = countFiles(target);
+        if (actual >= expected) {
+            return makeCheckResult(check, true, `${actual} of ${expected} source files covered.`, { actual, expected, source_manifest_id: sourceManifest.manifest.manifest_id });
+        }
+        return makeCheckResult(check, false, `Only ${actual} of ${expected} source files covered.`, { actual, expected, matchKey, source_manifest_id: sourceManifest.manifest.manifest_id });
+    },
+    source_summary_folders(check, context) {
+        const target = resolveTargetPath(check, context);
+        if (!target) {
+            return makeCheckResult(check, false, "No target path provided for source_summary_folders check.");
+        }
+        const sourceManifest = loadRequiredSourceManifestForCheck(check, context);
+        if (!sourceManifest.manifest)
+            return sourceManifest.failure ?? makeCheckResult(check, false, "Source Manifest is required.");
+        const matchKey = typeof check.params?.match === "string" ? check.params.match : "source_total";
+        const expected = matchKey === "source_total"
+            ? sourceManifest.manifest.source_total
+            : context.counts?.[matchKey];
+        if (typeof expected !== "number") {
+            return makeCheckResult(check, false, `Cannot evaluate: count "${matchKey}" not available in context.`, { matchKey });
+        }
+        if (expected <= 0) {
+            return makeCheckResult(check, false, `Cannot evaluate: count "${matchKey}" must be greater than zero.`, { matchKey, expected });
+        }
+        const summaryFile = typeof check.params?.summary_file === "string" ? check.params.summary_file : "summary.md";
+        const manifestFile = typeof check.params?.manifest_file === "string" ? check.params.manifest_file : "manifest.md";
+        const coverage = matchKey === "source_total"
+            ? sourceSummaryCoverage(target, sourceManifest.manifest, { summaryFile, manifestFile })
+            : {
+                ...countSourceSummaryFolders(target, { summaryFile, manifestFile }),
+                expected,
+                missingSourcePaths: [],
+                extraSummaryFolders: [],
+            };
+        if (coverage.actual >= expected) {
+            return makeCheckResult(check, true, `${coverage.actual} source summary folder(s) covered for ${expected} source file(s).`, {
+                actual: coverage.actual,
+                expected,
+                summaryFile,
+                manifestFile,
+                source_manifest_id: sourceManifest.manifest.manifest_id,
+                extraSummaryFolders: coverage.extraSummaryFolders,
+            });
+        }
+        return makeCheckResult(check, false, `Only ${coverage.actual} source summary folder(s) covered for ${expected} source file(s).`, {
+            actual: coverage.actual,
+            expected,
+            matchKey,
+            summaryFile,
+            manifestFile,
+            missingSourcePaths: coverage.missingSourcePaths,
+            extraSummaryFolders: coverage.extraSummaryFolders,
+        });
+    },
+    source_page_coverage(check, context) {
+        const target = resolveTargetPath(check, context);
+        if (!target) {
+            return makeCheckResult(check, false, "No target path provided for source_page_coverage check.");
+        }
+        const expected = sourceManifestPageTotal(context);
+        if (expected.error)
+            return makeCheckResult(check, false, expected.error);
+        if (expected.total <= 0) {
+            if (check.params?.allow_no_pages === true) {
+                return makeCheckResult(check, true, "Source Manifest does not declare page-level units.");
+            }
+            return makeCheckResult(check, false, "Source Manifest does not declare page-level units. Add page_count or page inspectable_units, or set params.allow_no_pages explicitly.");
+        }
+        const pagesDir = typeof check.params?.pages_dir === "string" ? check.params.pages_dir : "pages";
+        const summaryFile = typeof check.params?.summary_file === "string" ? check.params.summary_file : "summary.md";
+        const actual = listFilesRecursive(target)
+            .filter((file) => file.endsWith(`/${summaryFile}`) && file.includes(`/${pagesDir}/`))
+            .length;
+        if (actual >= expected.total) {
+            return makeCheckResult(check, true, `${actual} page summary file(s) cover ${expected.total} page unit(s).`, { actual, expected: expected.total });
+        }
+        return makeCheckResult(check, false, `Only ${actual} page summary file(s) cover ${expected.total} page unit(s).`, { actual, expected: expected.total, pagesDir, summaryFile });
+    },
+    frontmatter_valid(check, context) {
+        const target = resolveTargetPath(check, context);
+        if (!target) {
+            return makeCheckResult(check, false, "No target path provided for frontmatter_valid check.");
+        }
+        const files = listMarkdownFiles(target);
+        if (files.length === 0) {
+            return makeCheckResult(check, true, "No markdown files to validate.");
+        }
+        const validation = validateSynthFiles(files);
+        if (validation.invalid_frontmatter === 0) {
+            return makeCheckResult(check, true, `${files.length} markdown file(s) have valid frontmatter.`);
+        }
+        return makeCheckResult(check, false, `${validation.invalid_frontmatter} of ${files.length} markdown file(s) have invalid frontmatter.`, { invalid: validation.invalid_frontmatter, total: files.length });
+    },
+    frontmatter_required_keys(check, context) {
+        const target = resolveTargetPath(check, context);
+        if (!target) {
+            return makeCheckResult(check, false, "No target path provided for frontmatter_required_keys check.");
+        }
+        const keys = frontmatterKeys(check);
+        if (keys.length === 0) {
+            return makeCheckResult(check, false, "Build Plan check is missing required frontmatter keys. Use `params.keys: string[]`.");
+        }
+        const files = listMarkdownFiles(target);
+        if (files.length === 0) {
+            return makeCheckResult(check, true, "No markdown files to validate.");
+        }
+        const validation = validateSynthFiles(files, { requiredFrontmatterKeys: keys });
+        if (validation.invalid_frontmatter === 0) {
+            return makeCheckResult(check, true, `All ${files.length} markdown file(s) have required keys: ${keys.join(", ")}.`);
+        }
+        return makeCheckResult(check, false, `${validation.invalid_frontmatter} of ${files.length} file(s) missing required keys (${keys.join(", ")}).`, { invalid: validation.invalid_frontmatter, total: files.length, requiredKeys: keys });
+    },
+    frontmatter_nonempty_keys(check, context) {
+        const target = resolveTargetPath(check, context);
+        if (!target) {
+            return makeCheckResult(check, false, "No target path provided for frontmatter_nonempty_keys check.");
+        }
+        const keys = frontmatterKeys(check);
+        if (keys.length === 0) {
+            return makeCheckResult(check, false, "Build Plan check is missing non-empty frontmatter keys. Use `params.keys: string[]`.");
+        }
+        const files = listMarkdownFiles(target);
+        if (files.length === 0) {
+            return makeCheckResult(check, false, "No markdown files to validate.");
+        }
+        const { invalid, missing } = collectFrontmatterFailures(files, (frontmatter) => keys.every((key) => hasNonEmptyFrontmatterValue(frontmatter[key])));
+        if (invalid.length === 0 && missing.length === 0) {
+            return makeCheckResult(check, true, `All ${files.length} markdown file(s) have non-empty keys: ${keys.join(", ")}.`);
+        }
+        return makeCheckResult(check, false, `${invalid.length + missing.length} of ${files.length} markdown file(s) are missing non-empty keys (${keys.join(", ")}).`, { invalid, missing, requiredKeys: keys });
+    },
+    source_refs_required(check, context) {
+        const target = resolveTargetPath(check, context);
+        if (!target) {
+            return makeCheckResult(check, false, "No target path provided for source_refs_required check.");
+        }
+        const keys = frontmatterKeys(check);
+        const sourceRefKeys = keys.length > 0 ? keys : ["source_refs", "source_ref", "source_path"];
+        const exemptWhen = exemptWhenClause(check);
+        const files = listMarkdownFiles(target);
+        if (files.length === 0) {
+            return makeCheckResult(check, false, "No markdown files to validate.");
+        }
+        const { invalid, missing } = collectFrontmatterFailures(files, (frontmatter) => isExemptFromSourceRefs(frontmatter, exemptWhen)
+            || sourceRefKeys.some((key) => hasNonEmptyFrontmatterValue(frontmatter[key])));
+        if (invalid.length === 0 && missing.length === 0) {
+            return makeCheckResult(check, true, `All ${files.length} markdown file(s) have source refs.`);
+        }
+        return makeCheckResult(check, false, `${invalid.length + missing.length} of ${files.length} markdown file(s) are missing source refs.`, { invalid, missing, sourceRefKeys });
+    },
+    summary_backlinks_present(check, context) {
+        const target = resolveTargetPath(check, context);
+        if (!target) {
+            return makeCheckResult(check, false, "No target path provided for summary_backlinks_present check.");
+        }
+        const summariesDir = typeof check.params?.summaries_dir === "string" ? check.params.summaries_dir : "summaries";
+        const summaryFile = typeof check.params?.summary_file === "string" ? check.params.summary_file : "summary.md";
+        const manifestFile = typeof check.params?.manifest_file === "string" ? check.params.manifest_file : "manifest.md";
+        const analysis = analyzeSummaryBacklinks(target, context, { summariesDir, summaryFile, manifestFile });
+        // An ambiguous basename-only citation cannot be proven backlinked: it names a
+        // basename two or more summary folders share, so we refuse to credit one
+        // arbitrarily. Surface it as a gap rather than silently passing — that is the
+        // exact orphan the old first-basename-wins alias hid. Fails even when nothing
+        // resolved cleanly, because the citation itself is unverifiable.
+        if (analysis.ambiguousCitations.length > 0) {
+            return makeCheckResult(check, false, `${analysis.ambiguousCitations.length} note(s) cite a summary by an ambiguous basename that two or more summary folders share; cite the full summary-folder path so the backlink can be verified.`, {
+                cited_summaries: analysis.citedSummaries.length,
+                linked_summaries: analysis.linkedSummaries.size,
+                ambiguous_citations: analysis.ambiguousCitations.length,
+                notes_with_ambiguous_citations: analysis.ambiguousCitations,
+                orphaned_summaries: analysis.orphanedSummaries.length,
+                orphaned_summary_folders: analysis.orphanedSummaries,
+            });
+        }
+        if (analysis.citedSummaries.length === 0) {
+            return makeCheckResult(check, true, "No notes cite a summary source ref yet; nothing to backlink.", { notesScanned: analysis.notesScanned });
+        }
+        if (analysis.orphanedSummaries.length === 0) {
+            return makeCheckResult(check, true, `All ${analysis.citedSummaries.length} cited summary folder(s) are wikilinked from this layer.`, {
+                cited_summaries: analysis.citedSummaries.length,
+                linked_summaries: analysis.linkedSummaries.size,
+                orphaned_summaries: 0,
+            });
+        }
+        return makeCheckResult(check, false, `${analysis.orphanedSummaries.length} of ${analysis.citedSummaries.length} cited summary folder(s) are orphaned (cited via source_refs but never wikilinked).`, {
+            cited_summaries: analysis.citedSummaries.length,
+            linked_summaries: analysis.linkedSummaries.size,
+            orphaned_summaries: analysis.orphanedSummaries.length,
+            orphaned_summary_folders: analysis.orphanedSummaries,
+            notes_with_unlinked_citations: analysis.notesWithUnlinkedCitations,
+        });
+    },
+    knowledge_web_connectivity(check, context) {
+        const target = resolveTargetPath(check, context);
+        if (!target) {
+            return makeCheckResult(check, false, "No target path provided for knowledge_web_connectivity check.");
+        }
+        // The artifact's target path IS the knowledge layer to scan — derived from the
+        // artifact this check is attached to, never hardcoded to `knowledge/` from the
+        // root. `params.knowledge_dir` is a graph-root-relative override that may only
+        // NARROW the scan to a sub-directory inside the target; an override that escapes
+        // the target layer (e.g. a sibling layer) is rejected so the check cannot be
+        // pointed at a different, possibly-passing subtree.
+        let scanRoot = target;
+        if (typeof check.params?.knowledge_dir === "string" && check.params.knowledge_dir.trim().length > 0) {
+            const narrowed = resolve(context.rootPath, check.params.knowledge_dir);
+            if (narrowed !== target && !narrowed.startsWith(`${target}/`)) {
+                return makeCheckResult(check, false, "params.knowledge_dir resolves outside this check's target layer; it may only narrow the scan inside the target.", { knowledge_dir: check.params.knowledge_dir, target_dir: context.targetPath });
+            }
+            scanRoot = narrowed;
+        }
+        const web = analyzeNoteWeb(listMarkdownFiles(scanRoot), context);
+        // A bare basename two or more notes share cannot be proven to connect either
+        // namesake, so it credits no edge — surface it as a "cite the full path" gap
+        // rather than silently connecting the linker and hiding an island. Fails even
+        // when no island remains, because the link itself is unverifiable.
+        if (web.ambiguousLinkNotes.length > 0) {
+            return makeCheckResult(check, false, `${web.ambiguousLinkNotes.length} knowledge note(s) link another knowledge note by an ambiguous basename two or more notes share; link the full graph path so the web edge can be verified.`, {
+                knowledge_notes: web.notes,
+                connected: web.connected,
+                islands: web.islands.length,
+                island_notes: web.islands,
+                ambiguous_links: web.ambiguousLinkNotes.length,
+                notes_with_ambiguous_links: web.ambiguousLinkNotes,
+            });
+        }
+        if (web.islands.length === 0) {
+            return makeCheckResult(check, true, web.notes <= 1
+                ? `${web.notes} knowledge note(s); too few to form a web.`
+                : `${web.connected} / ${web.notes} knowledge notes link another knowledge note.`, { knowledge_notes: web.notes, connected: web.connected, islands: 0 });
+        }
+        return makeCheckResult(check, false, `${web.islands.length} of ${web.notes} knowledge note(s) link no other knowledge note (disconnected island${web.islands.length === 1 ? "" : "s"}).`, {
+            knowledge_notes: web.notes,
+            connected: web.connected,
+            islands: web.islands.length,
+            island_notes: web.islands,
+        });
+    },
+    /**
+     * Whole-graph connectivity floor. The `knowledge_web_connectivity` check only
+     * scans the `knowledge/` layer, and `summary_backlinks_present` only flags a
+     * summary that a knowledge note CITES via source_refs but does not wikilink.
+     * Neither sees a summary that no note cites at all — so a Context Graph can
+     * pass readiness while the bulk of its `summaries/` notes are free-floating
+     * islands no entrypoint or note reaches. This is the "no disconnected island
+     * passing silently" rule applied to the WHOLE graph, not just the 7 knowledge
+     * notes: every markdown note across `summaries/`, `knowledge/`, `artifacts/`,
+     * and `home.md` must have undirected degree ≥ 1 in the note-link web. A note no
+     * other note links AND that links no other note is a disconnected island and
+     * fails readiness. Connectedness, not a count — one genuine inbound or outbound
+     * edge is enough. By default the scan root is the Context Graph root; a Build
+     * Plan may pass `params.graph_root` to narrow the floor to one layer (it may
+     * only narrow inside the graph root, never escape it).
+     */
+    graph_notes_connected(check, context) {
+        // Default scope: the canonical CONTENT layers of the whole Context Graph
+        // (summaries/, knowledge/, artifacts/, home.md) as one web — NOT the raw graph
+        // root, which also holds runtime scaffolding (.interf/, .claude/, SKILL.md
+        // docs, CLAUDE.md) that is not graph content and would inject false islands.
+        // Intentionally spans all CONTENT layers, not `targetPath`: a knowledge note
+        // or an entrypoint route may be the only thing connecting a summary, so scoping
+        // to one layer in isolation would re-introduce the uncited-summary-island bug.
+        const graphRoot = resolve(context.rootPath);
+        let noteFiles;
+        if (typeof check.params?.graph_root === "string" && check.params.graph_root.trim().length > 0) {
+            const narrowed = resolve(graphRoot, check.params.graph_root);
+            // May only NARROW inside the graph root; an override that escapes the root
+            // is rejected so the floor cannot be pointed at a different, passing tree.
+            if (narrowed !== graphRoot && !narrowed.startsWith(`${graphRoot}/`)) {
+                return makeCheckResult(check, false, "params.graph_root resolves outside the Context Graph root; it may only narrow the connectivity floor to a path inside the graph.", { graph_root: check.params.graph_root });
+            }
+            // A narrowed scope scans that subtree's markdown notes directly (the caller
+            // is naming a content path, so no scaffolding filter is applied beyond the
+            // shared output-markdown filter).
+            noteFiles = listMarkdownFiles(narrowed);
+        }
+        else {
+            noteFiles = collectGraphContentNotes(graphRoot);
+        }
+        const web = analyzeNoteWeb(noteFiles, context);
+        if (web.ambiguousLinkNotes.length > 0) {
+            return makeCheckResult(check, false, `${web.ambiguousLinkNotes.length} note(s) link another note by an ambiguous basename two or more notes share; link the full graph path so the web edge can be verified.`, {
+                graph_notes: web.notes,
+                connected: web.connected,
+                islands: web.islands.length,
+                island_notes: web.islands,
+                ambiguous_links: web.ambiguousLinkNotes.length,
+                notes_with_ambiguous_links: web.ambiguousLinkNotes,
+            });
+        }
+        if (web.islands.length === 0) {
+            return makeCheckResult(check, true, web.notes <= 1
+                ? `${web.notes} note(s); too few to form a web.`
+                : `${web.connected} / ${web.notes} notes are link-connected to another note (no islands).`, { graph_notes: web.notes, connected: web.connected, islands: 0 });
+        }
+        return makeCheckResult(check, false, `${web.islands.length} of ${web.notes} note(s) link no other note and are linked by none (disconnected island${web.islands.length === 1 ? "" : "s"}). Every Context Graph note — including every summary — must be reachable through the link web.`, {
+            graph_notes: web.notes,
+            connected: web.connected,
+            islands: web.islands.length,
+            island_notes: web.islands,
+        });
+    },
+    wikilinks_valid(check, context) {
+        const target = resolveTargetPath(check, context);
+        if (!target) {
+            return makeCheckResult(check, false, "No target path provided for wikilinks_valid check.");
+        }
+        const broken = countBrokenWikilinks(context.rootPath, [context.rootPath], [target]);
+        if (broken === 0) {
+            return makeCheckResult(check, true, "All wikilinks resolve.");
+        }
+        return makeCheckResult(check, false, `${broken} broken wikilink(s).`, { broken });
+    },
+    must_not_contain(check, context) {
+        const target = resolveTargetPath(check, context);
+        if (!target || !existsSync(target)) {
+            return makeCheckResult(check, false, "Target path does not exist.", { path: context.targetPath });
+        }
+        const phrases = checkPhrases(check);
+        if (phrases.length === 0) {
+            return makeCheckResult(check, false, "Requested output diagnostic is missing forbidden text. Use `params.phrases: string[]` or `params.text: string`.");
+        }
+        try {
+            const stats = statSync(target);
+            const files = stats.isFile() ? [target] : listFilesRecursive(target, () => true);
+            const offenders = [];
+            for (const file of files) {
+                const content = readFileSync(file, "utf8");
+                for (const phrase of phrases) {
+                    if (content.includes(phrase)) {
+                        offenders.push(`${file}: contains "${phrase}"`);
+                        break;
+                    }
+                }
+            }
+            if (offenders.length === 0) {
+                return makeCheckResult(check, true, `No forbidden phrases found across ${files.length} file(s).`);
+            }
+            return makeCheckResult(check, false, `${offenders.length} file(s) contain forbidden phrases.`, { offenders, phrases });
+        }
+        catch (error) {
+            return makeCheckResult(check, false, `Error reading target: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    },
+    must_contain(check, context) {
+        const target = resolveTargetPath(check, context);
+        if (!target || !existsSync(target)) {
+            return makeCheckResult(check, false, "Target path does not exist.", { path: context.targetPath });
+        }
+        const phrases = checkPhrases(check);
+        if (phrases.length === 0) {
+            return makeCheckResult(check, false, "Requested output diagnostic is missing required text. Use `params.phrases: string[]` or `params.text: string`.");
+        }
+        try {
+            const stats = statSync(target);
+            // For directories, must_contain checks across ALL files (every phrase
+            // must appear in at least one file). For files, all phrases must
+            // appear in that single file.
+            if (stats.isFile()) {
+                const content = readFileSync(target, "utf8");
+                const missing = phrases.filter((phrase) => !content.includes(phrase));
+                if (missing.length === 0) {
+                    return makeCheckResult(check, true, `All ${phrases.length} required phrase(s) present.`);
+                }
+                return makeCheckResult(check, false, `${missing.length} required phrase(s) missing.`, { missing });
+            }
+            const files = listFilesRecursive(target, () => true);
+            const remaining = new Set(phrases);
+            for (const file of files) {
+                const content = readFileSync(file, "utf8");
+                for (const phrase of [...remaining]) {
+                    if (content.includes(phrase))
+                        remaining.delete(phrase);
+                }
+                if (remaining.size === 0)
+                    break;
+            }
+            if (remaining.size === 0) {
+                return makeCheckResult(check, true, `All ${phrases.length} required phrase(s) found across files.`);
+            }
+            return makeCheckResult(check, false, `${remaining.size} required phrase(s) missing across all files.`, { missing: [...remaining] });
+        }
+        catch (error) {
+            return makeCheckResult(check, false, `Error reading target: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    },
+    qa_match(check, context) {
+        const expected = typeof check.params?.expected === "string" ? check.params.expected : "";
+        const strictness = typeof check.params?.strictness === "string" ? check.params.strictness : "loose";
+        const answer = context.agentAnswer ?? "";
+        if (!expected) {
+            return makeCheckResult(check, false, "qa_match check requires `params.expected: string`.");
+        }
+        if (!answer) {
+            return makeCheckResult(check, false, "No agent answer available for qa_match evaluation.");
+        }
+        if (strictness === "strict") {
+            const passed = answer.trim() === expected.trim();
+            return makeCheckResult(check, passed, passed ? "Answer matches expected exactly." : "Answer does not match expected.");
+        }
+        // Loose: case-insensitive substring match either direction.
+        const a = answer.trim().toLowerCase();
+        const e = expected.trim().toLowerCase();
+        const passed = a.includes(e) || e.includes(a);
+        return makeCheckResult(check, passed, passed ? "Answer matches expected (loose)." : "Answer does not match expected.");
+    },
+};
+/**
+ * Evaluate a single Check against a context, returning a CheckResult.
+ */
+export function evaluateCheck(check, context) {
+    const evaluator = EVALUATORS[check.kind];
+    if (!evaluator) {
+        return {
+            check_id: check.id,
+            kind: check.kind,
+            passed: false,
+            required: check.required,
+            summary: `Unknown check kind: ${check.kind}`,
+            evaluated_at: new Date().toISOString(),
+        };
+    }
+    return evaluator(check, context);
+}
+/**
+ * Evaluate a list of checks. Aggregate ready/not_ready verdict over
+ * the check_results: `ready` if every required check passed, otherwise
+ * `not_ready`. Soft checks (required: false) that fail produce a
+ * check result but don't change the verdict.
+ */
+export function evaluateChecks(checks, context) {
+    const check_results = checks.map((check) => evaluateCheck(check, context));
+    const failures = check_results.filter((result) => !result.passed && result.required);
+    return {
+        check_results,
+        ready: failures.length === 0,
+        failures,
+    };
+}
+/**
+ * Type guard for the canonical CheckKinds. Useful at parse boundaries
+ * where a string came from on-disk JSON.
+ */
+export function isCheckKind(value) {
+    return CheckKindSchema.safeParse(value).success;
+}