@interf/compiler 0.33.0 → 0.50.0

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

@@ -2,6 +2,7 @@ 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";
 /**
@@ -143,6 +144,464 @@ function sourceSummaryCoverage(absolutePath, manifest, options) {
         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");
@@ -183,6 +642,44 @@ function collectFrontmatterFailures(files, predicate) {
     }
     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))
@@ -379,7 +876,7 @@ const EVALUATORS = {
         if (!target) {
             return makeCheckResult(check, false, "No target path provided for frontmatter_required_keys check.");
         }
-        const keys = Array.isArray(check.params?.keys) ? check.params.keys.filter((k) => typeof k === "string") : [];
+        const keys = frontmatterKeys(check);
         if (keys.length === 0) {
             return makeCheckResult(check, false, "Build Plan check is missing required frontmatter keys. Use `params.keys: string[]`.");
         }
@@ -419,16 +916,170 @@ const EVALUATORS = {
         }
         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) => sourceRefKeys.some((key) => hasNonEmptyFrontmatterValue(frontmatter[key])));
+        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) {
@@ -447,7 +1098,7 @@ const EVALUATORS = {
         }
         const phrases = checkPhrases(check);
         if (phrases.length === 0) {
-            return makeCheckResult(check, false, "Artifact diagnostic is missing forbidden text. Use `params.phrases: string[]` or `params.text: string`.");
+            return makeCheckResult(check, false, "Requested output diagnostic is missing forbidden text. Use `params.phrases: string[]` or `params.text: string`.");
         }
         try {
             const stats = statSync(target);
@@ -478,7 +1129,7 @@ const EVALUATORS = {
         }
         const phrases = checkPhrases(check);
         if (phrases.length === 0) {
-            return makeCheckResult(check, false, "Artifact diagnostic is missing required text. Use `params.phrases: string[]` or `params.text: string`.");
+            return makeCheckResult(check, false, "Requested output diagnostic is missing required text. Use `params.phrases: string[]` or `params.text: string`.");
         }
         try {
             const stats = statSync(target);