@shrkcrft/inspector 0.1.0-alpha.29 → 0.1.0-alpha.31

package/dist/knowledge-stale.js

@@ -1,18 +1,42 @@
 /**
- * Knowledge stale-check.
+ * Knowledge stale-check — THE staleness engine (every consumer reads it).
  *
- * Walks every knowledge entry's `references[]` + `anchors[]` and checks
- * whether each target still resolves against the current workspace.
+ * Walks every knowledge entry's `references[]` + `anchors[]` — and the
+ * references boundary rules and policy checks declare — and checks whether each
+ * target still resolves against the current workspace, and (with `contains` /
+ * `matches` / `count`) still says what the asset claims.
  *
- * Pure file-system + registry lookups — no network, no AST compilation.
- * Symbol checks are deterministic best-effort text scans so the doctor
- * stays cheap.
+ * It classifies every entry in scope into ONE of three buckets: `verified`,
+ * `stale`, `unverifiable`. An entry with nothing checkable used to contribute
+ * nothing and read as healthy — the less verifiable a corpus, the healthier it
+ * looked. The buckets make that shortfall a number the verdict can refuse on.
  *
- * Schema: sharkcraft.knowledge-stale/v1
+ * Callers MUST `await warmReferenceRegistries(inspection)` first: the
+ * playbook / policy / construct / helper registries are async-filled, and an
+ * unwarmed registry is reported `unknown` (NOT VERIFIED) here — never `stale`
+ * against a correct id.
+ *
+ * Pure file-system + registry lookups — no network, no whole-program
+ * compilation. Symbol checks use the single-file AST index.
+ *
+ * Schema: sharkcraft.knowledge-stale/v1 (additive fields since round 11)
  */
 import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs';
 import * as nodePath from 'node:path';
-import { HELPERS } from "./helper-registry.js";
+import { globListSelects, globToRegex } from '@shrkcrft/boundaries';
+import { KNOWLEDGE_REFERENCE_KINDS, todayUtcIso, verifiedOnAgeDays, } from '@shrkcrft/knowledge';
+import { isCacheBackedKind, isReferenceCacheWarm, referenceIdExists, referenceIdsFor, } from "./reference-registry.js";
+import { listPolicyDeclarations } from "./policy-registry.js";
+import { checkReferenceContent, checkReferenceCount, hasContentAssertion, } from "./reference-content-check.js";
+import { ReferenceFailure } from "./reference-failure.js";
+import { KnowledgeEntryVerdict } from "./knowledge-entry-verdict.js";
+import { KnowledgeUnverifiableReason } from "./knowledge-unverifiable-reason.js";
+import { KnowledgeAdvisoryCode } from "./knowledge-advisory-code.js";
+import { ReferenceAssetKind } from "./reference-asset-kind.js";
+import { buildSymbolIndex } from "./symbol-index.js";
+// The `command` reference case (and its anchor twin) — one injected resolver.
+import { COMMAND_INDEX_NOT_INJECTED, resolveShrkCommandReference } from "./reference-registry.js";
+import { CommandResolutionStatus } from "./command-resolution-status.js";
 import { resolveSymbolInFile, SymbolResolution } from "./symbol-index.js";
 export const KNOWLEDGE_STALE_SCHEMA = 'sharkcraft.knowledge-stale/v1';
 export var ReferenceCheckOutcome;
@@ -20,7 +44,16 @@ export var ReferenceCheckOutcome;
     ReferenceCheckOutcome["Ok"] = "ok";
     ReferenceCheckOutcome["Stale"] = "stale";
     ReferenceCheckOutcome["Missing"] = "missing";
+    /** Well-formed, but the check cannot evaluate it (a `url`, an unwarmed registry). */
     ReferenceCheckOutcome["Unknown"] = "unknown";
+    /**
+     * MALFORMED — a kind outside the vocabulary, or the field its kind cannot be
+     * checked without is missing (a symbol reference with no `symbol`). It
+     * verifies nothing; it used to share `unknown` with an unfetched url and
+     * count toward a green run. Now it is a coverage shortfall on the verdict
+     * (not verified) and fails under `--fail-on invalid`.
+     */
+    ReferenceCheckOutcome["Invalid"] = "invalid";
 })(ReferenceCheckOutcome || (ReferenceCheckOutcome = {}));
 export var SymbolConfidence;
 (function (SymbolConfidence) {
@@ -64,222 +97,453 @@ function dirExists(projectRoot, rel) {
         return false;
     }
 }
-function commandExistsInInspection(inspection, id) {
-    // Both `shrk` commands and pack-contributed commands live on the
-    // inspection. We do a permissive lookup against the recommendation
-    // catalog if available.
-    const commands = inspection.commandCatalog;
-    if (Array.isArray(commands)) {
-        if (commands.some((c) => c.id === id))
-            return true;
+/*
+ * Existence checks delegate to the SHARED reference registry.
+ *
+ * They used to be private copies here, each reading a differently-shaped
+ * structural cast off the inspection (`playbookRegistry`, `constructRegistry`,
+ * `policyChecks`) — properties nothing ever attached, so those kinds answered
+ * "does not exist" for every id including correct ones. An unchecked cast to a
+ * hoped-for shape compiles perfectly and fails silently forever; the registry
+ * imports the real accessors so the compiler can see a rename.
+ */
+/**
+ * A `command` reference (or anchor) through THE injected command resolver.
+ *
+ * Without a resolver (outside the CLI) the command was NOT checked: that is
+ * `Unknown` with a loud NOT VERIFIED message — never `Ok`. It used to be `Ok`
+ * for every `shrk …` string, which certified three dead commands in shrk's own
+ * knowledge as "Command available".
+ *
+ * Read as a command REFERENCE (`resolveShrkCommandReference`): a bare
+ * `frobnicate` is `shrk frobnicate` — stale — exactly as the self-config
+ * doctor and the agent-test runner read it, never `not-shrk` → `ok`.
+ */
+function checkCommandString(inspection, id, label) {
+    const resolution = resolveShrkCommandReference(inspection, id);
+    switch (resolution.status) {
+        case CommandResolutionStatus.Unverified:
+            return {
+                outcome: ReferenceCheckOutcome.Unknown,
+                message: `${label} ${id}: ${COMMAND_INDEX_NOT_INJECTED}`,
+                suggestion: 'Run the check through the CLI (`shrk knowledge stale-check`), which injects the live command index.',
+            };
+        case CommandResolutionStatus.Ok:
+        case CommandResolutionStatus.PrefixOnly:
+        case CommandResolutionStatus.NotShrk:
+            return {
+                outcome: ReferenceCheckOutcome.Ok,
+                message: resolution.status === CommandResolutionStatus.Ok
+                    ? `Command available: ${id}`
+                    : `Command ${id}: ${resolution.status}${resolution.reason ? ` (${resolution.reason})` : ''}`,
+            };
+        default: {
+            const closest = resolution.closest ?? [];
+            return {
+                outcome: ReferenceCheckOutcome.Stale,
+                message: `Command not registered: ${id} (${resolution.status}${resolution.reason ? ` — ${resolution.reason}` : ''})`,
+                suggestion: closest.length > 0
+                    ? `Did you mean \`${closest[0]}\`? Update the reference (or run \`shrk surface list\` for every real command).`
+                    : 'Update the reference — run `shrk surface list` for every real command.',
+            };
+        }
     }
-    // Fallback — accept anything that looks like a valid `shrk` command.
-    return id.startsWith('shrk ') || id.startsWith('bun ');
-}
-function templateExists(inspection, id) {
-    return inspection.templates.some((t) => t.id === id);
 }
-function playbookExists(inspection, id) {
-    const inspectionAny = inspection;
-    const reg = inspectionAny.playbookRegistry;
-    if (reg && typeof reg.list === 'function') {
-        return (reg.list() ?? []).some((p) => p.id === id);
+/**
+ * Why an id could not be CHECKED against a cache-backed registry, or undefined
+ * when the registry is loaded and non-empty.
+ *
+ * A negative answer from an unloaded (or empty) registry proves nothing: every
+ * id checked against it would be reported stale, including correct ones — the
+ * fastest way to get a check switched off. So it reads as NOT VERIFIED
+ * (`unknown`), the same safety net the doc-reference linter uses. A POSITIVE
+ * answer is always trusted.
+ */
+function unloadedRegistryReason(inspection, kind) {
+    if (!isCacheBackedKind(kind))
+        return undefined;
+    if (!isReferenceCacheWarm(inspection)) {
+        return `the ${kind} registry was not loaded — call warmReferenceRegistries() before building the report (NOT VERIFIED)`;
     }
-    return false;
-}
-function constructExists(inspection, id) {
-    const inspectionAny = inspection;
-    const reg = inspectionAny.constructRegistry;
-    if (reg && typeof reg.list === 'function') {
-        return (reg.list() ?? []).some((c) => c.id === id);
+    if (referenceIdsFor(inspection, kind).length === 0) {
+        return `the ${kind} registry is empty — it failed to load, or this repo declares no ${kind}s (NOT VERIFIED)`;
     }
-    return false;
+    return undefined;
 }
-function helperExists(id) {
-    return HELPERS.some((h) => h.id === id);
+/**
+ * An id-keyed reference, through THE shared resolver. The helper kind reads
+ * built-ins AND pack helpers there; a private built-in-only list used to answer
+ * here, calling every pack helper stale.
+ */
+function checkRegisteredId(inspection, kind, id, label) {
+    if (referenceIdExists(inspection, kind, id)) {
+        return { outcome: ReferenceCheckOutcome.Ok, message: `${label} exists: ${id}` };
+    }
+    const unloaded = unloadedRegistryReason(inspection, kind);
+    if (unloaded) {
+        return {
+            outcome: ReferenceCheckOutcome.Unknown,
+            failure: ReferenceFailure.Unverifiable,
+            message: `${label} ${id}: ${unloaded}`,
+            suggestion: 'Run through the CLI (`shrk knowledge stale-check`), which loads every registry first.',
+        };
+    }
+    return staleId(kind, id);
 }
-function policyExists(inspection, id) {
-    const inspectionAny = inspection;
-    const checks = inspectionAny.policyChecks;
-    if (Array.isArray(checks))
-        return checks.some((c) => c.id === id);
-    return false;
+/** Workspace package name → its directory (relative), per inspection. */
+const WORKSPACE_PACKAGES = new WeakMap();
+function readPackageJson(abs) {
+    try {
+        return JSON.parse(readFileSync(abs, 'utf8'));
+    }
+    catch {
+        return null;
+    }
 }
-function boundaryRuleExists(inspection, id) {
-    const reg = inspection.boundaryRegistry;
-    if (reg && typeof reg.list === 'function')
-        return reg.list().some((b) => b.id === id);
-    return false;
+/** Directories (relative) matching one `workspaces` glob. */
+function expandWorkspaceGlob(projectRoot, pattern) {
+    const norm = pattern.replace(/^\.\//, '').replace(/\/+$/, '');
+    const segs = norm.split('/');
+    const firstGlob = segs.findIndex((s) => /[*?[{]/.test(s));
+    if (firstGlob === -1)
+        return [norm];
+    const maxDepth = segs.includes('**') ? 4 : segs.length - firstGlob;
+    const out = [];
+    const walk = (rel, depth) => {
+        if (depth > maxDepth)
+            return;
+        let names;
+        try {
+            names = readdirSync(nodePath.join(projectRoot, rel));
+        }
+        catch {
+            return;
+        }
+        for (const n of names) {
+            if (n === 'node_modules' || n.startsWith('.'))
+                continue;
+            const child = rel ? `${rel}/${n}` : n;
+            if (!dirExists(projectRoot, child))
+                continue;
+            // One `workspaces` pattern against one directory — not a gate-plane list.
+            if (globToRegex(norm).test(child))
+                out.push(child);
+            walk(child, depth + 1);
+        }
+    };
+    walk(segs.slice(0, firstGlob).join('/'), 1);
+    return out;
 }
-function pathConventionExists(inspection, id) {
-    const svc = inspection.pathService;
-    if (svc && typeof svc.list === 'function') {
-        return svc.list().some((p) => p.id === id);
+/**
+ * Every workspace package the root `package.json` declares — the packages its
+ * `workspaces` globs reach, by their `name`. This replaces a read of
+ * `inspection.packages`, a property the inspection never has (the phantom-cast
+ * bug class): it answered "not a package" for every id and fell through to a
+ * hard-coded `packages/<name>` layout.
+ */
+function workspacePackages(inspection) {
+    const cached = WORKSPACE_PACKAGES.get(inspection);
+    if (cached)
+        return cached;
+    const out = new Map();
+    const root = readPackageJson(nodePath.join(inspection.projectRoot, 'package.json'));
+    if (root) {
+        if (typeof root.name === 'string')
+            out.set(root.name, '.');
+        const ws = root.workspaces;
+        const patterns = Array.isArray(ws)
+            ? ws
+            : Array.isArray(ws?.packages)
+                ? (ws.packages)
+                : [];
+        for (const pattern of patterns) {
+            if (typeof pattern !== 'string' || pattern.startsWith('!'))
+                continue;
+            for (const dir of expandWorkspaceGlob(inspection.projectRoot, pattern)) {
+                const pkg = readPackageJson(nodePath.join(inspection.projectRoot, dir, 'package.json'));
+                if (pkg && typeof pkg.name === 'string' && !out.has(pkg.name))
+                    out.set(pkg.name, dir);
+            }
+        }
     }
-    return false;
+    WORKSPACE_PACKAGES.set(inspection, out);
+    return out;
 }
-function packageExists(inspection, id) {
-    // Project packages live under `packages/<name>` for SharkCraft + many
-    // monorepos. Trust the inspection's package map if available, else
-    // fall back to a filesystem check.
-    const pkgs = inspection.packages;
-    if (Array.isArray(pkgs)) {
-        if (pkgs.some((p) => p.name === id))
-            return true;
+function checkPackageReference(inspection, id) {
+    const dir = workspacePackages(inspection).get(id);
+    if (dir) {
+        return { outcome: ReferenceCheckOutcome.Ok, message: `Package exists: ${id} (${dir})` };
+    }
+    // Last-resort backstop for repos without a `workspaces` field — reported as
+    // probable, because a directory name is not a package name.
+    const rel = id.startsWith('@') ? (id.split('/')[1] ?? '') : id;
+    if (rel && dirExists(inspection.projectRoot, `packages/${rel}`)) {
+        return {
+            outcome: ReferenceCheckOutcome.Ok,
+            message: `Package exists (probable): packages/${rel}/ is present, but no workspace package.json declares the name ${id}.`,
+        };
     }
-    // file lookup as a backstop
-    const rel = id.startsWith('@') ? id.split('/')[1] ?? '' : id;
-    return dirExists(inspection.projectRoot, `packages/${rel}`);
+    return staleId('package', id);
 }
 function normalizeRel(p) {
     return p.split(/[\\/]/).join('/').replace(/^\.\//, '');
 }
+/** `Foo` for `Foo.bar` / `Foo.prototype.bar`; null for a bare name. */
+function qualifiedOwner(sym) {
+    const cleaned = sym.replace(/\.prototype\./g, '.');
+    const dot = cleaned.indexOf('.');
+    return dot > 0 && dot < cleaned.length - 1 ? cleaned.slice(0, dot) : null;
+}
 function checkSymbolReference(projectRoot, ref, graph) {
     const sym = ref.symbol ?? '';
     if (!sym) {
         return {
-            outcome: ReferenceCheckOutcome.Unknown,
+            outcome: ReferenceCheckOutcome.Invalid,
             confidence: SymbolConfidence.Unknown,
-            message: 'Symbol reference has no `symbol` field.',
+            failure: ReferenceFailure.Malformed,
+            message: 'malformed reference: symbol reference missing required field `symbol`.',
         };
     }
+    // `Owner.member`: the graph indexes top-level symbols only, so it answers for
+    // the OWNER (moved-detection); the member itself is verified by the AST on
+    // the owner's declaring file.
+    const owner = qualifiedOwner(sym);
+    const lookup = owner ?? sym;
     // Graph-resolved, cross-file path (preferred when a graph is supplied).
     // A single-file AST scan cannot tell a *moved* symbol from a deleted one;
     // the graph's global symbol index can, so consult it first.
     if (graph) {
         const decl = graph
-            .findSymbol(sym)
+            .findSymbol(lookup)
             .map((n) => n.path)
             .filter((p) => typeof p === 'string' && p.length > 0)
             .map(normalizeRel);
         if (decl.length > 0) {
             if (ref.path) {
                 const target = normalizeRel(ref.path);
-                if (decl.includes(target)) {
+                if (!decl.includes(target)) {
+                    // Symbol exists but no longer at the pinned file — it moved.
+                    return {
+                        outcome: ReferenceCheckOutcome.Stale,
+                        confidence: SymbolConfidence.Missing,
+                        failure: ReferenceFailure.AnchorMissing,
+                        message: `Symbol \`${lookup}\` is no longer in ${ref.path}; the graph resolves it to ${decl
+                            .slice(0, 3)
+                            .join(', ')}.`,
+                    };
+                }
+                if (!owner && !hasContentAssertion(ref)) {
                     return {
                         outcome: ReferenceCheckOutcome.Ok,
                         confidence: SymbolConfidence.Exact,
                         message: `\`${sym}\` resolves to ${ref.path} (graph).`,
                     };
                 }
-                // Symbol exists but no longer at the pinned file — it moved.
+                // The owner is at the pinned file; the member (and any content span)
+                // is verified by the AST below.
+            }
+            else if (!owner) {
+                // No file pin, but the graph resolved it cross-file.
                 return {
-                    outcome: ReferenceCheckOutcome.Stale,
-                    confidence: SymbolConfidence.Missing,
-                    message: `Symbol \`${sym}\` is no longer in ${ref.path}; the graph resolves it to ${decl
-                        .slice(0, 3)
-                        .join(', ')}.`,
+                    outcome: ReferenceCheckOutcome.Ok,
+                    confidence: SymbolConfidence.Probable,
+                    message: `\`${sym}\` resolves via the code graph to ${decl.slice(0, 3).join(', ')}.`,
+                };
+            }
+            else if (decl.length === 1) {
+                return resolveSymbolAtPath(projectRoot, decl[0], sym, false);
+            }
+            else {
+                return {
+                    outcome: ReferenceCheckOutcome.Unknown,
+                    confidence: SymbolConfidence.Unknown,
+                    failure: ReferenceFailure.Unverifiable,
+                    message: `\`${owner}\` is declared in ${decl.length} files (${decl.slice(0, 3).join(', ')}) — pin the path to check \`${sym}\`.`,
                 };
             }
-            // No file pin, but the graph resolved it cross-file.
-            return {
-                outcome: ReferenceCheckOutcome.Ok,
-                confidence: SymbolConfidence.Probable,
-                message: `\`${sym}\` resolves via the code graph to ${decl.slice(0, 3).join(', ')}.`,
-            };
         }
-        // Absent from the graph. The graph may be partial (locals, unindexed
-        // languages), so fall through to the AST/text backstop when a file is
-        // pinned; otherwise we cannot verify.
-        if (!ref.path) {
+        else if (!ref.path) {
+            // Absent from the graph. The graph may be partial (locals, unindexed
+            // languages), so fall through to the AST/text backstop when a file is
+            // pinned; otherwise we cannot verify.
             return {
                 outcome: ReferenceCheckOutcome.Unknown,
                 confidence: SymbolConfidence.Unknown,
+                failure: ReferenceFailure.Unverifiable,
                 message: `Symbol reference \`${sym}\` has no file pin and is absent from the code graph; stale-check cannot verify.`,
             };
         }
     }
-    const file = ref.path ? nodePath.join(projectRoot, ref.path) : null;
-    if (file) {
-        if (!existsSync(file)) {
-            return {
-                outcome: ReferenceCheckOutcome.Missing,
-                confidence: SymbolConfidence.Missing,
-                message: `Referenced file does not exist: ${ref.path}`,
-            };
-        }
-        // AST-backed resolution (falls back to text-scan if parse fails).
-        try {
-            const res = resolveSymbolInFile(file, sym);
-            switch (res.resolution) {
-                case SymbolResolution.ExactExport:
-                    return {
-                        outcome: ReferenceCheckOutcome.Ok,
-                        confidence: SymbolConfidence.Exact,
-                        message: res.message,
-                    };
-                case SymbolResolution.ExactLocal:
-                case SymbolResolution.ExactReExport:
-                    return {
-                        outcome: ReferenceCheckOutcome.Ok,
-                        confidence: SymbolConfidence.Exact,
-                        message: res.message,
-                    };
-                case SymbolResolution.ProbableText:
-                    return {
-                        outcome: ReferenceCheckOutcome.Ok,
-                        confidence: SymbolConfidence.Probable,
-                        message: res.message,
-                    };
-                case SymbolResolution.Missing:
-                    return {
-                        outcome: ReferenceCheckOutcome.Stale,
-                        confidence: SymbolConfidence.Missing,
-                        message: res.message,
-                    };
-                default:
-                    return {
-                        outcome: ReferenceCheckOutcome.Unknown,
-                        confidence: SymbolConfidence.Unknown,
-                        message: res.message,
-                    };
-            }
-        }
-        catch {
-            // Fallback to text scan.
-            try {
-                const text = readFileSync(file, 'utf8');
-                const declRe = new RegExp(`(export\\s+(?:async\\s+)?(?:function|class|interface|enum|type|const|let|var)\\s+|class\\s+|function\\s+)${escapeRe(sym)}\\b`);
-                if (declRe.test(text)) {
-                    return {
-                        outcome: ReferenceCheckOutcome.Ok,
-                        confidence: SymbolConfidence.Exact,
-                        message: `Found declaration of \`${sym}\` in ${ref.path}.`,
-                    };
-                }
-                if (text.includes(sym)) {
-                    return {
-                        outcome: ReferenceCheckOutcome.Ok,
-                        confidence: SymbolConfidence.Probable,
-                        message: `\`${sym}\` appears in ${ref.path}, but not as an exported declaration.`,
-                    };
-                }
+    if (ref.path)
+        return resolveSymbolAtPath(projectRoot, ref.path, sym, true);
+    // No file pinned — best-effort confidence is `unknown`.
+    return {
+        outcome: ReferenceCheckOutcome.Unknown,
+        confidence: SymbolConfidence.Unknown,
+        failure: ReferenceFailure.Unverifiable,
+        message: `Symbol reference \`${sym}\` has no file pin; stale-check cannot verify (pin it as \`symbol:${sym}@<path>\`).`,
+    };
+}
+/** Resolve `sym` in one file through the AST index (text-scan backstop). */
+function resolveSymbolAtPath(projectRoot, relPath, sym, pinned) {
+    const file = nodePath.join(projectRoot, relPath);
+    if (!existsSync(file)) {
+        return {
+            outcome: ReferenceCheckOutcome.Missing,
+            confidence: SymbolConfidence.Missing,
+            failure: ReferenceFailure.PathMissing,
+            message: `Referenced file does not exist: ${relPath}`,
+        };
+    }
+    const via = pinned ? '' : ` (declaring file ${relPath}, from the code graph)`;
+    // AST-backed resolution (falls back to text-scan if parse fails).
+    try {
+        const res = resolveSymbolInFile(file, sym);
+        switch (res.resolution) {
+            case SymbolResolution.ExactExport:
+            case SymbolResolution.ExactLocal:
+            case SymbolResolution.ExactReExport:
+            case SymbolResolution.ExactMember:
+            case SymbolResolution.ExactLocalMember:
+                return {
+                    outcome: ReferenceCheckOutcome.Ok,
+                    confidence: pinned ? SymbolConfidence.Exact : SymbolConfidence.Probable,
+                    message: res.message + via,
+                    ...(res.span ? { span: res.span } : {}),
+                };
+            case SymbolResolution.ProbableText:
+                return {
+                    outcome: ReferenceCheckOutcome.Ok,
+                    confidence: SymbolConfidence.Probable,
+                    message: res.message + via,
+                };
+            case SymbolResolution.Missing:
                 return {
                     outcome: ReferenceCheckOutcome.Stale,
                     confidence: SymbolConfidence.Missing,
-                    message: `Symbol \`${sym}\` not found in ${ref.path}.`,
+                    failure: ReferenceFailure.AnchorMissing,
+                    message: res.message + via,
+                    ...(res.suggestedSymbol ? { suggestedSymbol: res.suggestedSymbol } : {}),
                 };
-            }
-            catch {
+            default:
                 return {
                     outcome: ReferenceCheckOutcome.Unknown,
                     confidence: SymbolConfidence.Unknown,
-                    message: `Failed to read ${ref.path}.`,
+                    failure: ReferenceFailure.Unverifiable,
+                    message: res.message + via,
+                };
+        }
+    }
+    catch {
+        // Fallback to text scan.
+        const token = qualifiedOwner(sym) ? sym.slice(sym.lastIndexOf('.') + 1) : sym;
+        try {
+            const text = readFileSync(file, 'utf8');
+            const declRe = new RegExp(`(export\\s+(?:async\\s+)?(?:function|class|interface|enum|type|const|let|var)\\s+|class\\s+|function\\s+)${escapeRe(token)}\\b`);
+            if (declRe.test(text)) {
+                return {
+                    outcome: ReferenceCheckOutcome.Ok,
+                    confidence: SymbolConfidence.Exact,
+                    message: `Found declaration of \`${sym}\` in ${relPath}.`,
                 };
             }
+            if (text.includes(token)) {
+                return {
+                    outcome: ReferenceCheckOutcome.Ok,
+                    confidence: SymbolConfidence.Probable,
+                    message: `\`${sym}\` appears in ${relPath}, but not as an exported declaration.`,
+                };
+            }
+            return {
+                outcome: ReferenceCheckOutcome.Stale,
+                confidence: SymbolConfidence.Missing,
+                failure: ReferenceFailure.AnchorMissing,
+                message: `Symbol \`${sym}\` not found in ${relPath}.`,
+            };
+        }
+        catch {
+            return {
+                outcome: ReferenceCheckOutcome.Unknown,
+                confidence: SymbolConfidence.Unknown,
+                failure: ReferenceFailure.Unverifiable,
+                message: `Failed to read ${relPath}.`,
+            };
         }
     }
-    // No file pinned — best-effort confidence is `unknown`.
-    return {
-        outcome: ReferenceCheckOutcome.Unknown,
-        confidence: SymbolConfidence.Unknown,
-        message: `Symbol reference \`${sym}\` has no file pin; stale-check cannot verify.`,
-    };
 }
 function escapeRe(s) {
     return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
 }
-function checkReference(inspection, ref, graph) {
+/**
+ * Check one reference: does its target exist — and, when it declares
+ * `contains` / `matches` / `count`, does the target still say what the asset
+ * claims. Every non-ok result carries a {@link ReferenceFailure}.
+ */
+function checkReference(inspection, ref, graph, excludeDirs = []) {
+    const base = checkReferenceTarget(inspection, ref, graph);
+    const result = base.outcome === ReferenceCheckOutcome.Ok
+        ? applyAssertions(inspection.projectRoot, ref, base, excludeDirs)
+        : base;
+    if (result.outcome === ReferenceCheckOutcome.Ok || result.failure !== undefined)
+        return result;
+    return { ...result, failure: defaultFailure(ref.kind, result.outcome) };
+}
+/** The failure mode of a non-ok check that did not name one. */
+function defaultFailure(kind, outcome) {
+    if (outcome === ReferenceCheckOutcome.Unknown)
+        return ReferenceFailure.Unverifiable;
+    if (outcome === ReferenceCheckOutcome.Invalid)
+        return ReferenceFailure.Malformed;
+    if (kind === 'file' || kind === 'directory')
+        return ReferenceFailure.PathMissing;
+    if (kind === 'symbol')
+        return ReferenceFailure.AnchorMissing;
+    return ReferenceFailure.IdUnregistered;
+}
+/**
+ * Content and count assertions, over a target that EXISTS — a mismatch on a
+ * missing file would report one break twice.
+ */
+function applyAssertions(projectRoot, ref, base, excludeDirs) {
+    const content = checkReferenceContent(projectRoot, ref, ref.kind === 'symbol' ? base.span : undefined);
+    if (content && !content.ok)
+        return assertionFailure(base, content, 'content');
+    const count = checkReferenceCount(projectRoot, ref, countExcludeDirsFor(ref, excludeDirs));
+    if (count && !count.ok)
+        return assertionFailure(base, count, 'count');
+    const held = [content?.message, count?.message].filter((m) => m !== undefined);
+    if (held.length === 0)
+        return base;
+    return {
+        ...base,
+        message: `${base.message} ${held.join(' ')}`,
+        ...(count ? { expected: count.expected, actual: count.actual } : {}),
+    };
+}
+function assertionFailure(base, a, what) {
+    const confidence = base.confidence ? { confidence: base.confidence } : {};
+    if (a.unverifiable) {
+        return {
+            outcome: ReferenceCheckOutcome.Unknown,
+            ...confidence,
+            failure: ReferenceFailure.Unverifiable,
+            message: `${base.message} Its ${what} assertion could not be evaluated: ${a.message}`,
+        };
+    }
+    return {
+        outcome: ReferenceCheckOutcome.Stale,
+        ...confidence,
+        failure: a.failure ?? (what === 'count' ? ReferenceFailure.CountMismatch : ReferenceFailure.ContentMismatch),
+        ...(a.expected !== undefined ? { expected: a.expected } : {}),
+        ...(a.actual !== undefined ? { actual: a.actual } : {}),
+        message: a.message,
+        suggestion: what === 'count'
+            ? `Update the claim in the entry, then set count.expected: ${String(a.actual)}.`
+            : 'Update the entry (and the assertion) to what the code says now.',
+    };
+}
+/** Does the reference's TARGET exist? (Assertions are layered on by {@link checkReference}.) */
+function checkReferenceTarget(inspection, ref, graph) {
     const projectRoot = inspection.projectRoot;
     switch (ref.kind) {
         case 'file': {
@@ -298,6 +562,7 @@ function checkReference(inspection, ref, graph) {
             }
             return {
                 outcome: ReferenceCheckOutcome.Stale,
+                failure: ReferenceFailure.PathMissing,
                 message: `Directory missing: ${ref.path}`,
                 suggestion: 'Move the directory or update the knowledge reference.',
             };
@@ -310,98 +575,78 @@ function checkReference(inspection, ref, graph) {
             const id = ref.id ?? ref.command ?? '';
             if (!id)
                 return missingField('command', 'id or command');
-            if (commandExistsInInspection(inspection, id)) {
-                return { outcome: ReferenceCheckOutcome.Ok, message: `Command available: ${id}` };
-            }
-            return {
-                outcome: ReferenceCheckOutcome.Stale,
-                message: `Command not registered: ${id}`,
-                suggestion: 'Register the command in the command catalog or update the reference.',
-            };
+            return checkCommandString(inspection, id, 'Command');
         }
         case 'template': {
             if (!ref.id)
                 return missingField('template', 'id');
-            if (templateExists(inspection, ref.id)) {
-                return { outcome: ReferenceCheckOutcome.Ok, message: `Template exists: ${ref.id}` };
-            }
-            return staleId('template', ref.id);
+            return checkRegisteredId(inspection, 'template', ref.id, 'Template');
         }
         case 'playbook': {
             if (!ref.id)
                 return missingField('playbook', 'id');
-            if (playbookExists(inspection, ref.id)) {
-                return { outcome: ReferenceCheckOutcome.Ok, message: `Playbook exists: ${ref.id}` };
-            }
-            return staleId('playbook', ref.id);
+            return checkRegisteredId(inspection, 'playbook', ref.id, 'Playbook');
         }
         case 'construct': {
             if (!ref.id)
                 return missingField('construct', 'id');
-            if (constructExists(inspection, ref.id)) {
-                return { outcome: ReferenceCheckOutcome.Ok, message: `Construct exists: ${ref.id}` };
-            }
-            return staleId('construct', ref.id);
+            return checkRegisteredId(inspection, 'construct', ref.id, 'Construct');
         }
         case 'helper': {
             if (!ref.id)
                 return missingField('helper', 'id');
-            if (helperExists(ref.id)) {
-                return { outcome: ReferenceCheckOutcome.Ok, message: `Helper exists: ${ref.id}` };
-            }
-            return staleId('helper', ref.id);
+            return checkRegisteredId(inspection, 'helper', ref.id, 'Helper');
         }
         case 'policy': {
             if (!ref.id)
                 return missingField('policy', 'id');
-            if (policyExists(inspection, ref.id)) {
-                return { outcome: ReferenceCheckOutcome.Ok, message: `Policy exists: ${ref.id}` };
-            }
-            return staleId('policy', ref.id);
+            return checkRegisteredId(inspection, 'policy', ref.id, 'Policy');
         }
         case 'boundary-rule': {
             if (!ref.id)
                 return missingField('boundary-rule', 'id');
-            if (boundaryRuleExists(inspection, ref.id)) {
-                return { outcome: ReferenceCheckOutcome.Ok, message: `Boundary rule exists: ${ref.id}` };
-            }
-            return staleId('boundary-rule', ref.id);
+            return checkRegisteredId(inspection, 'boundary-rule', ref.id, 'Boundary rule');
         }
         case 'path-convention': {
             if (!ref.id)
                 return missingField('path-convention', 'id');
-            if (pathConventionExists(inspection, ref.id)) {
-                return { outcome: ReferenceCheckOutcome.Ok, message: `Path convention exists: ${ref.id}` };
-            }
-            return staleId('path-convention', ref.id);
+            return checkRegisteredId(inspection, 'path-convention', ref.id, 'Path convention');
         }
         case 'package': {
             if (!ref.id)
                 return missingField('package', 'id');
-            if (packageExists(inspection, ref.id)) {
-                return { outcome: ReferenceCheckOutcome.Ok, message: `Package exists: ${ref.id}` };
-            }
-            return staleId('package', ref.id);
+            return checkPackageReference(inspection, ref.id);
         }
         case 'url': {
             // We never fetch URLs. Mark them unknown unless we can resolve to a
             // local docs file.
             return {
                 outcome: ReferenceCheckOutcome.Unknown,
+                failure: ReferenceFailure.Unverifiable,
                 message: 'URL references are not verified (no network).',
             };
         }
+        default:
+            // A kind outside the vocabulary still loads (the validator reports it as
+            // an error); here it is MALFORMED — never a crash, never a silent row.
+            return {
+                outcome: ReferenceCheckOutcome.Invalid,
+                failure: ReferenceFailure.Malformed,
+                message: `malformed reference: unsupported kind "${String(ref.kind)}" — expected one of: ${KNOWLEDGE_REFERENCE_KINDS.join(', ')}.`,
+            };
     }
 }
 function missingField(kind, field) {
     return {
-        outcome: ReferenceCheckOutcome.Unknown,
-        message: `${kind} reference missing required field: ${field}`,
+        outcome: ReferenceCheckOutcome.Invalid,
+        failure: ReferenceFailure.Malformed,
+        message: `malformed reference: ${kind} reference missing required field \`${field}\`.`,
     };
 }
 function staleFile(rel) {
     return {
         outcome: ReferenceCheckOutcome.Stale,
+        failure: ReferenceFailure.PathMissing,
         message: `File missing: ${rel}`,
         suggestion: 'Restore the file or run `shrk knowledge rename-file <old> <new> --dry-run`.',
     };
@@ -409,29 +654,237 @@ function staleFile(rel) {
 function staleId(kind, id) {
     return {
         outcome: ReferenceCheckOutcome.Stale,
+        failure: ReferenceFailure.IdUnregistered,
         message: `${kind} not found: ${id}`,
         suggestion: 'Register the target or remove the reference.',
     };
 }
-function entryTouchesChangedFiles(entry, changed) {
+function normalizeSlashes(p) {
+    return p.split(/[\\/]/).join('/');
+}
+/** `./src/a.ts` / `src\a.ts` / `src/svc/` → `src/a.ts` / `src/svc`. */
+function normalizeScopePath(p) {
+    return normalizeSlashes(p).replace(/^(?:\.\/)+/, '').replace(/\/+$/, '');
+}
+/**
+ * A changed path IS the target, or lies UNDER it — a `directory` reference
+ * whose files changed, or a directory deleted wholesale (git lists its files,
+ * never the directory itself).
+ */
+function pathTouched(target, changed) {
+    if (!target)
+        return false;
+    const p = normalizeScopePath(target);
+    if (p === '' || p === '.')
+        return false;
+    const under = `${p}/`;
+    return changed.some((c) => c === p || c.startsWith(under));
+}
+/**
+ * Is a subject — a knowledge entry, a boundary rule, a policy check — in a
+ * changeset's scope? THE one scoping rule for `--changed-only` / `--files`:
+ *
+ *   - the file that DECLARES it changed (its references were added or edited —
+ *     a typo in a new reference must be checked by the run that introduced it);
+ *   - a changed path equals a reference / anchor path, or lies under one;
+ *   - a changed path matches a `count` source glob (the number re-derives from
+ *     those globs, so a change there can move it with no pinned path changing).
+ *
+ * `source` is project-relative (`relativeSource`); `(unknown source)` matches
+ * nothing.
+ */
+function subjectTouchesChangedFiles(subject, changed) {
     if (changed.length === 0)
         return true;
-    const changedSet = new Set(changed.map((c) => c.split(/[\\/]/).join('/')));
-    for (const ref of entry.references ?? []) {
-        if (ref.path && changedSet.has(ref.path.split(/[\\/]/).join('/')))
+    const changedList = changed.map(normalizeScopePath);
+    if (changedList.includes(normalizeScopePath(subject.source)))
+        return true;
+    for (const ref of subject.references ?? []) {
+        if (pathTouched(ref.path, changedList))
+            return true;
+        // The scope the count is MEASURED over (`inspectSource` selects through
+        // `globListSelects`), so a change to a file its `!` excludes is no touch.
+        const globs = ref.count?.source?.files;
+        if (globs && globs.length > 0 && changedList.some((c) => globListSelects(c, globs)))
             return true;
     }
-    for (const anchor of entry.anchors ?? []) {
-        if (anchor.path && changedSet.has(anchor.path.split(/[\\/]/).join('/')))
+    for (const anchor of subject.anchors ?? []) {
+        if (pathTouched(anchor.path, changedList))
             return true;
     }
     return false;
 }
+/**
+ * The directories a `count` source never walks by default: the sharkcraft dir.
+ * Its `.ts` files hold the claims themselves — prose saying `registerService("<name>")`
+ * inside a count glob would count itself, and the mismatch hint would tell the
+ * author to bake that self-match into `expected` (policy-lint and finish prune
+ * the same dir for the same reason).
+ */
+function defaultCountExcludeDirs(inspection) {
+    const dir = inspection.sharkcraftDir;
+    if (!dir)
+        return [];
+    const rel = normalizeScopePath(nodePath.relative(inspection.projectRoot, dir));
+    return rel && rel !== '.' && !rel.startsWith('..') && !nodePath.isAbsolute(rel) ? [rel] : [];
+}
+/**
+ * The exclusions ONE count source walks under: an exclusion is dropped when the
+ * source's own globs target inside it (`sharkcraft/**` counts there on purpose).
+ */
+function countExcludeDirsFor(ref, excludeDirs) {
+    const globs = ref.count?.source?.files ?? [];
+    if (excludeDirs.length === 0 || globs.length === 0)
+        return excludeDirs;
+    const prefixes = globs.filter((g) => !g.startsWith('!')).map((g) => staticGlobPrefix(g));
+    return excludeDirs.filter((d) => !prefixes.some((p) => p === d || p.startsWith(`${d}/`)));
+}
+/** Every {@link ReferenceFailure} at 0 — the report always carries the full map. */
+function emptyFailureCounts() {
+    const out = {};
+    for (const f of Object.values(ReferenceFailure))
+        out[f] = 0;
+    return out;
+}
+function emptyKindBucket() {
+    return { scanned: 0, zeroReferences: 0, referencesChecked: 0, verified: 0, stale: 0, unverifiable: 0 };
+}
+/**
+ * ok / stale / missing are real checks; unknown and invalid (malformed) proved
+ * nothing either way. THE predicate — the stale-check's entry buckets, its
+ * verdict fold (`declaredReferenceCoverage`) and the `shrk gate`
+ * knowledge-symbol gate all read it.
+ */
+export function isCheckableOutcome(o) {
+    return o !== ReferenceCheckOutcome.Unknown && o !== ReferenceCheckOutcome.Invalid;
+}
+function isFailingOutcome(o) {
+    return o === ReferenceCheckOutcome.Stale || o === ReferenceCheckOutcome.Missing;
+}
+/**
+ * One subject's bucket from its checks: any failing check makes it stale; any
+ * passing one (and no failing) makes it verified; NOTHING checkable makes it
+ * unverifiable — never healthy.
+ */
+function classifyChecks(checkable, failing) {
+    if (failing > 0)
+        return KnowledgeEntryVerdict.Stale;
+    if (checkable > 0)
+        return KnowledgeEntryVerdict.Verified;
+    return KnowledgeEntryVerdict.Unverifiable;
+}
+function bumpBucket(b, declared, verdict) {
+    b.scanned += 1;
+    if (declared === 0)
+        b.zeroReferences += 1;
+    b.referencesChecked += declared;
+    if (verdict === KnowledgeEntryVerdict.Verified)
+        b.verified += 1;
+    else if (verdict === KnowledgeEntryVerdict.Stale)
+        b.stale += 1;
+    else
+        b.unverifiable += 1;
+}
+function tallyOutcome(b, outcome) {
+    b.checked += 1;
+    if (outcome === ReferenceCheckOutcome.Ok)
+        b.ok += 1;
+    else if (outcome === ReferenceCheckOutcome.Stale)
+        b.stale += 1;
+    else if (outcome === ReferenceCheckOutcome.Missing)
+        b.missing += 1;
+    else if (outcome === ReferenceCheckOutcome.Invalid)
+        b.invalid += 1;
+    else
+        b.unknown += 1;
+}
+function relativeSource(projectRoot, origin) {
+    if (!origin)
+        return '(unknown source)';
+    return normalizeSlashes(nodePath.isAbsolute(origin) ? nodePath.relative(projectRoot, origin) : origin);
+}
+function pct1(part, whole) {
+    return whole > 0 ? Math.round((part / whole) * 1000) / 10 : 0;
+}
+/** The static directory part of a glob (`apps/legacy/**` → `apps/legacy`); `''` when it starts with a wildcard. */
+function staticGlobPrefix(glob) {
+    const segs = normalizeSlashes(glob).replace(/^\.\//, '').split('/');
+    const firstGlob = segs.findIndex((s) => /[*?[{]/.test(s));
+    return (firstGlob === -1 ? segs : segs.slice(0, firstGlob)).join('/');
+}
+const BACKTICKED_IDENTIFIER = /`([A-Za-z_$][\w$]*(?:\.[A-Za-z_$][\w$]*)?)(?:\(\))?`/g;
+const TS_SOURCE = /\.(ts|tsx|js|jsx|mjs|cjs)$/;
+const PATH_ONLY_ADVISORY_CAP = 5;
+/**
+ * The path-only advisory: an entry whose references are all paths, whose prose
+ * names (in backticks) a symbol one of its referenced files DECLARES. Renaming
+ * that symbol would leave the entry wrong while every reference still resolves
+ * — the strong form (`symbol` pinned to the path) catches it. Never gating.
+ */
+function pathOnlyAdvisories(projectRoot, entry, refs, cache) {
+    if (refs.length === 0 || !refs.every((r) => r.kind === 'file' || r.kind === 'directory'))
+        return [];
+    const files = refs
+        .filter((r) => r.kind === 'file' && r.path !== undefined && TS_SOURCE.test(r.path))
+        .map((r) => r.path);
+    if (files.length === 0)
+        return [];
+    const names = new Set();
+    for (const text of [entry.summary ?? '', typeof entry.content === 'string' ? entry.content : '']) {
+        for (const m of text.matchAll(BACKTICKED_IDENTIFIER))
+            names.add(m[1]);
+    }
+    const out = [];
+    for (const name of names) {
+        if (out.length >= PATH_ONLY_ADVISORY_CAP)
+            break;
+        for (const rel of files) {
+            let idx = cache.get(rel);
+            if (idx === undefined) {
+                const abs = nodePath.join(projectRoot, rel);
+                idx = existsSync(abs) ? buildSymbolIndex(abs) : null;
+                cache.set(rel, idx);
+            }
+            if (!idx?.parsed)
+                continue;
+            const declared = name.includes('.')
+                ? (idx.members ?? []).some((m) => `${m.owner}.${m.name}` === name)
+                : idx.exports.some((e) => e.name === name);
+            if (!declared)
+                continue;
+            out.push({
+                code: KnowledgeAdvisoryCode.PathOnlyReference,
+                subjectId: entry.id,
+                assetKind: ReferenceAssetKind.Knowledge,
+                message: `entry names \`${name}\`, which ${rel} declares, but pins only the path — a rename inside the file would pass unnoticed. Add { kind: 'symbol', symbol: '${name}', path: '${rel}' }.`,
+                suggestion: { kind: 'symbol', symbol: name, path: rel },
+            });
+            break;
+        }
+    }
+    return out;
+}
 export function buildKnowledgeStaleReport(inspection, options = {}) {
     const strategy = options.renameStrategy ?? RenameStrategy.Strict;
+    const projectRoot = inspection.projectRoot;
+    // Default: never walk the sharkcraft dir — the claims live there and would
+    // count themselves (every caller gets this; none has to remember to pass it).
+    const excludeDirs = options.excludeDirs ?? defaultCountExcludeDirs(inspection);
     const referenceChecks = [];
     const anchorChecks = [];
-    const counts = { ok: 0, stale: 0, missing: 0, unknown: 0 };
+    const assetReferenceChecks = [];
+    const counts = { ok: 0, stale: 0, missing: 0, unknown: 0, invalid: 0 };
+    const failureCounts = emptyFailureCounts();
+    const byAssetKind = {
+        [ReferenceAssetKind.Knowledge]: emptyKindBucket(),
+        [ReferenceAssetKind.BoundaryRule]: emptyKindBucket(),
+        [ReferenceAssetKind.Policy]: emptyKindBucket(),
+    };
+    const byEntryType = {};
+    const byReferenceKind = {};
+    const entryVerdicts = [];
+    const advisories = [];
+    const symbolIndexCache = new Map();
     let totalReferences = 0;
     let totalAnchors = 0;
     // Lazy symbol → file index, built on first stale-symbol need.
@@ -458,108 +911,180 @@ export function buildKnowledgeStaleReport(inspection, options = {}) {
         dirBasenameIndex = buildBasenameDirIndex(inspection.projectRoot);
         return dirBasenameIndex;
     };
+    /**
+     * Check ONE declared reference and attach its rename signal — the same path
+     * for a knowledge entry, a boundary rule and a policy check, so every asset
+     * kind is verified by one checker.
+     */
+    const checkOne = (subjectId, ref, assetKind) => {
+        const result = checkReference(inspection, ref, options.graph, excludeDirs);
+        const outcome = result.outcome;
+        const check = {
+            entryId: subjectId,
+            reference: ref,
+            outcome,
+            message: result.message,
+            ...(result.confidence ? { symbolConfidence: result.confidence } : {}),
+            ...(result.suggestion ? { suggestion: result.suggestion } : {}),
+            ...(result.failure ? { failure: result.failure } : {}),
+            ...(result.expected !== undefined ? { expected: result.expected } : {}),
+            ...(result.actual !== undefined ? { actual: result.actual } : {}),
+            ...(assetKind ? { assetKind } : {}),
+        };
+        tallyOutcome((byReferenceKind[ref.kind] ??= { checked: 0, ok: 0, stale: 0, missing: 0, unknown: 0, invalid: 0 }), outcome);
+        if (result.failure)
+            failureCounts[result.failure] += 1;
+        const isStaleOrMissing = outcome === ReferenceCheckOutcome.Stale || outcome === ReferenceCheckOutcome.Missing;
+        // A bare MEMBER name: the qualified spelling resolves in the same file, so
+        // it is the replacement (`shrk fix --knowledge-stale` applies it).
+        if (isStaleOrMissing && result.suggestedSymbol) {
+            check.replaceWith = {
+                symbol: result.suggestedSymbol,
+                rationale: `\`${ref.symbol}\` is a member, not a top-level declaration — \`${result.suggestedSymbol}\` resolves in ${ref.path ?? 'the pinned file'}.`,
+                strategy: RenameStrategy.Strict,
+            };
+        }
+        // Symbol rename detection. Strict mode: emit `replaceWith.path`
+        // only for the single unambiguous candidate. Wide mode also
+        // emits scored candidate lists for the multi-candidate cases that
+        // strict silently drops.
+        if (isStaleOrMissing && ref.kind === 'symbol' && ref.symbol && !check.replaceWith) {
+            const all = (getSymbolIndex().get(ref.symbol) ?? []).filter((p) => p !== ref.path);
+            if (all.length === 1) {
+                check.replaceWith = {
+                    path: all[0],
+                    rationale: `\`${ref.symbol}\` is exported from \`${all[0]}\` — sole candidate.`,
+                    strategy: RenameStrategy.Strict,
+                };
+            }
+            else if (strategy === RenameStrategy.Wide && all.length > 1) {
+                check.replaceWith = buildWideReplacement({
+                    stalePath: ref.path ?? '',
+                    paths: all,
+                    kindLabel: `symbol \`${ref.symbol}\``,
+                });
+            }
+        }
+        // File rename detection (directory move, basename match).
+        if (isStaleOrMissing && ref.kind === 'file' && ref.path && !check.replaceWith) {
+            const indexed = getFileBasenameIndex();
+            const uniq = pickUniqueRenameCandidate(ref.path, indexed);
+            if (uniq) {
+                check.replaceWith = {
+                    path: uniq,
+                    rationale: `File basename \`${nodePath.basename(ref.path)}\` resolves uniquely to \`${uniq}\` (likely directory rename).`,
+                    strategy: RenameStrategy.Strict,
+                };
+            }
+            else if (strategy === RenameStrategy.Wide) {
+                const all = (indexed.get(nodePath.basename(ref.path)) ?? []).filter((p) => p !== ref.path);
+                if (all.length > 0) {
+                    check.replaceWith = buildWideReplacement({
+                        stalePath: ref.path,
+                        paths: all,
+                        kindLabel: `file \`${nodePath.basename(ref.path)}\``,
+                    });
+                }
+            }
+        }
+        // Directory rename detection.
+        if (isStaleOrMissing && ref.kind === 'directory' && ref.path && !check.replaceWith) {
+            const indexed = getDirBasenameIndex();
+            const uniq = pickUniqueRenameCandidate(ref.path, indexed);
+            if (uniq) {
+                check.replaceWith = {
+                    path: uniq,
+                    rationale: `Directory basename \`${nodePath.basename(ref.path)}\` resolves uniquely to \`${uniq}\`.`,
+                    strategy: RenameStrategy.Strict,
+                };
+            }
+            else if (strategy === RenameStrategy.Wide) {
+                const all = (indexed.get(nodePath.basename(ref.path)) ?? []).filter((p) => p !== ref.path);
+                if (all.length > 0) {
+                    check.replaceWith = buildWideReplacement({
+                        stalePath: ref.path,
+                        paths: all,
+                        kindLabel: `directory \`${nodePath.basename(ref.path)}\``,
+                    });
+                }
+            }
+        }
+        return check;
+    };
     for (const entry of inspection.knowledgeEntries) {
-        if (options.changedFiles && !entryTouchesChangedFiles(entry, options.changedFiles)) {
+        if (options.changedFiles &&
+            !subjectTouchesChangedFiles({
+                source: relativeSource(projectRoot, entry.source?.origin),
+                references: entry.references ?? [],
+                anchors: entry.anchors ?? [],
+            }, options.changedFiles)) {
             continue;
         }
-        for (const ref of entry.references ?? []) {
+        const refs = entry.references ?? [];
+        const anchors = entry.anchors ?? [];
+        let checkable = 0;
+        let failing = 0;
+        for (const ref of refs) {
             totalReferences += 1;
-            const result = checkReference(inspection, ref, options.graph);
-            const outcome = result.outcome;
-            if (outcome === ReferenceCheckOutcome.Ok)
+            const check = checkOne(entry.id, ref);
+            if (check.outcome === ReferenceCheckOutcome.Ok)
                 counts.ok += 1;
-            else if (outcome === ReferenceCheckOutcome.Stale)
+            else if (check.outcome === ReferenceCheckOutcome.Stale)
                 counts.stale += 1;
-            else if (outcome === ReferenceCheckOutcome.Missing)
+            else if (check.outcome === ReferenceCheckOutcome.Missing)
                 counts.missing += 1;
+            else if (check.outcome === ReferenceCheckOutcome.Invalid)
+                counts.invalid += 1;
             else
                 counts.unknown += 1;
-            const check = {
-                entryId: entry.id,
-                reference: ref,
-                outcome,
-                message: result.message,
-                ...(result.confidence ? { symbolConfidence: result.confidence } : {}),
-                ...(result.suggestion ? { suggestion: result.suggestion } : {}),
-            };
-            const isStaleOrMissing = outcome === ReferenceCheckOutcome.Stale || outcome === ReferenceCheckOutcome.Missing;
-            // Symbol rename detection. Strict mode: emit `replaceWith.path`
-            // only for the single unambiguous candidate. Wide mode also
-            // emits scored candidate lists for the multi-candidate cases that
-            // strict silently drops.
-            if (isStaleOrMissing && ref.kind === 'symbol' && ref.symbol) {
-                const all = (getSymbolIndex().get(ref.symbol) ?? []).filter((p) => p !== ref.path);
-                if (all.length === 1) {
-                    check.replaceWith = {
-                        path: all[0],
-                        rationale: `\`${ref.symbol}\` is exported from \`${all[0]}\` — sole candidate.`,
-                        strategy: RenameStrategy.Strict,
-                    };
-                }
-                else if (strategy === RenameStrategy.Wide && all.length > 1) {
-                    check.replaceWith = buildWideReplacement({
-                        stalePath: ref.path ?? '',
-                        paths: all,
-                        kindLabel: `symbol \`${ref.symbol}\``,
-                    });
-                }
-            }
-            // File rename detection (directory move, basename match).
-            if (isStaleOrMissing && ref.kind === 'file' && ref.path && !check.replaceWith) {
-                const indexed = getFileBasenameIndex();
-                const uniq = pickUniqueRenameCandidate(ref.path, indexed);
-                if (uniq) {
-                    check.replaceWith = {
-                        path: uniq,
-                        rationale: `File basename \`${nodePath.basename(ref.path)}\` resolves uniquely to \`${uniq}\` (likely directory rename).`,
-                        strategy: RenameStrategy.Strict,
-                    };
-                }
-                else if (strategy === RenameStrategy.Wide) {
-                    const all = (indexed.get(nodePath.basename(ref.path)) ?? []).filter((p) => p !== ref.path);
-                    if (all.length > 0) {
-                        check.replaceWith = buildWideReplacement({
-                            stalePath: ref.path,
-                            paths: all,
-                            kindLabel: `file \`${nodePath.basename(ref.path)}\``,
-                        });
-                    }
-                }
-            }
-            // Directory rename detection.
-            if (isStaleOrMissing && ref.kind === 'directory' && ref.path && !check.replaceWith) {
-                const indexed = getDirBasenameIndex();
-                const uniq = pickUniqueRenameCandidate(ref.path, indexed);
-                if (uniq) {
-                    check.replaceWith = {
-                        path: uniq,
-                        rationale: `Directory basename \`${nodePath.basename(ref.path)}\` resolves uniquely to \`${uniq}\`.`,
-                        strategy: RenameStrategy.Strict,
-                    };
-                }
-                else if (strategy === RenameStrategy.Wide) {
-                    const all = (indexed.get(nodePath.basename(ref.path)) ?? []).filter((p) => p !== ref.path);
-                    if (all.length > 0) {
-                        check.replaceWith = buildWideReplacement({
-                            stalePath: ref.path,
-                            paths: all,
-                            kindLabel: `directory \`${nodePath.basename(ref.path)}\``,
-                        });
-                    }
-                }
+            if (isCheckableOutcome(check.outcome)) {
+                checkable += 1;
+                if (isFailingOutcome(check.outcome))
+                    failing += 1;
             }
             referenceChecks.push(check);
         }
-        for (const anchor of entry.anchors ?? []) {
+        for (const anchor of anchors) {
             totalAnchors += 1;
             const inspected = checkAnchor(inspection, anchor, options.graph);
+            const failure = inspected.outcome === ReferenceCheckOutcome.Ok
+                ? undefined
+                : (inspected.failure ?? defaultFailure(anchor.kind, inspected.outcome));
+            if (failure)
+                failureCounts[failure] += 1;
+            if (isCheckableOutcome(inspected.outcome)) {
+                checkable += 1;
+                if (isFailingOutcome(inspected.outcome))
+                    failing += 1;
+            }
             anchorChecks.push({
                 entryId: entry.id,
                 anchor,
                 outcome: inspected.outcome,
                 message: inspected.message,
+                ...(failure ? { failure } : {}),
             });
         }
+        const verdict = classifyChecks(checkable, failing);
+        const declared = refs.length + anchors.length;
+        const reason = verdict !== KnowledgeEntryVerdict.Unverifiable
+            ? undefined
+            : declared === 0
+                ? KnowledgeUnverifiableReason.NoReferences
+                : KnowledgeUnverifiableReason.OnlyUnverifiableReferences;
+        const type = String(entry.type);
+        entryVerdicts.push({
+            entryId: entry.id,
+            verdict,
+            ...(reason ? { reason } : {}),
+            source: relativeSource(projectRoot, entry.source?.origin),
+            type,
+            checkable,
+            failing,
+        });
+        bumpBucket(byAssetKind[ReferenceAssetKind.Knowledge], declared, verdict);
+        bumpBucket((byEntryType[type] ??= emptyKindBucket()), declared, verdict);
+        advisories.push(...pathOnlyAdvisories(projectRoot, entry, refs, symbolIndexCache));
     }
     // Content-similarity boost: when multiple wide replacements in the
     // SAME entry name the same candidate path, raise that candidate's score
@@ -567,6 +1092,129 @@ export function buildKnowledgeStaleReport(inspection, options = {}) {
     // followed" case where a single per-reference signal is weak but the
     // aggregate is strong.
     applyEntryCorroborationBoost(referenceChecks);
+    // Boundary rules and policy checks declare references too — swept by the
+    // same checker, counted per kind, and NOT folded into the knowledge buckets
+    // (their coverage is reported, not gated by default).
+    const includeAssets = options.includeAssets !== false;
+    const boundaryRules = includeAssets ? (inspection.boundaryRegistry?.list() ?? []) : [];
+    const policyDecls = includeAssets ? listPolicyDeclarations(inspection) : [];
+    const subjects = [
+        ...boundaryRules.map((rule) => ({
+            assetKind: ReferenceAssetKind.BoundaryRule,
+            id: rule.id,
+            source: relativeSource(projectRoot, inspection.boundarySources?.get(rule.id)?.file),
+            references: rule.references ?? [],
+        })),
+        ...policyDecls.map((p) => ({
+            assetKind: ReferenceAssetKind.Policy,
+            id: p.qualifiedId,
+            source: relativeSource(projectRoot, p.sourceFile),
+            references: p.references ?? [],
+        })),
+    ];
+    for (const subject of subjects) {
+        if (options.changedFiles &&
+            !subjectTouchesChangedFiles({ source: subject.source ?? '(unknown source)', references: subject.references }, options.changedFiles)) {
+            continue;
+        }
+        let checkable = 0;
+        let failing = 0;
+        for (const ref of subject.references) {
+            const check = checkOne(subject.id, ref, subject.assetKind);
+            if (isCheckableOutcome(check.outcome)) {
+                checkable += 1;
+                if (isFailingOutcome(check.outcome))
+                    failing += 1;
+            }
+            assetReferenceChecks.push(check);
+        }
+        bumpBucket(byAssetKind[subject.assetKind], subject.references.length, classifyChecks(checkable, failing));
+    }
+    // IMPLICIT references (boundary rules only — their scope is data): a `from`
+    // glob whose static prefix does not exist governs nothing there. Advisory
+    // unless `--fail-on implicit`; never counted in `failureCounts`. Policy
+    // checks keep their scope inside `evaluate()`, which cannot be read without
+    // running it — that gap is reported, not guessed at.
+    if (!options.changedFiles) {
+        for (const rule of boundaryRules) {
+            for (const glob of rule.from ?? []) {
+                if (glob.startsWith('!'))
+                    continue;
+                const prefix = staticGlobPrefix(glob);
+                if (!prefix || fileExists(projectRoot, prefix))
+                    continue;
+                const message = `boundary rule ${rule.id} scopes '${glob}' but ${prefix} does not exist — the rule governs nothing there.`;
+                assetReferenceChecks.push({
+                    entryId: rule.id,
+                    reference: { kind: 'directory', path: prefix, note: `implicit: from '${glob}'` },
+                    outcome: ReferenceCheckOutcome.Stale,
+                    failure: ReferenceFailure.PathMissing,
+                    implicit: true,
+                    assetKind: ReferenceAssetKind.BoundaryRule,
+                    message,
+                    suggestion: 'Fix or remove the glob (gate it with --fail-on implicit).',
+                });
+                advisories.push({
+                    code: KnowledgeAdvisoryCode.ImplicitPathMissing,
+                    subjectId: rule.id,
+                    assetKind: ReferenceAssetKind.BoundaryRule,
+                    message,
+                });
+            }
+        }
+    }
+    const policySweep = {
+        loaded: isReferenceCacheWarm(inspection),
+        declared: policyDecls.length,
+        withReferences: policyDecls.filter((p) => (p.references?.length ?? 0) > 0).length,
+    };
+    if (policySweep.declared > policySweep.withReferences) {
+        advisories.push({
+            code: KnowledgeAdvisoryCode.PolicyScopeUnverifiable,
+            subjectId: 'policy',
+            assetKind: ReferenceAssetKind.Policy,
+            message: `policy: ${policySweep.declared} declared check(s), ${policySweep.withReferences} with references — the scope of the rest is unverifiable (it lives inside evaluate()).`,
+        });
+    }
+    const verified = entryVerdicts.filter((v) => v.verdict === KnowledgeEntryVerdict.Verified).length;
+    const stale = entryVerdicts.filter((v) => v.verdict === KnowledgeEntryVerdict.Stale).length;
+    const unverifiableIds = entryVerdicts
+        .filter((v) => v.verdict === KnowledgeEntryVerdict.Unverifiable)
+        .map((v) => v.entryId);
+    const entriesInScope = entryVerdicts.length;
+    const coverage = {
+        entriesInScope,
+        verified,
+        stale,
+        unverifiable: unverifiableIds.length,
+        unverifiablePct: pct1(unverifiableIds.length, entriesInScope),
+        referencedRatio: entriesInScope > 0 ? (verified + stale) / entriesInScope : 0,
+    };
+    let age;
+    if (options.staleAfterDays !== undefined) {
+        const asOf = options.asOf ?? todayUtcIso();
+        const inScope = new Set(entryVerdicts.map((v) => v.entryId));
+        const aged = [];
+        const neverVerified = [];
+        for (const entry of inspection.knowledgeEntries) {
+            if (!inScope.has(entry.id))
+                continue;
+            const days = entry.verifiedOn ? verifiedOnAgeDays(entry.verifiedOn, asOf) : undefined;
+            if (days === undefined) {
+                neverVerified.push(entry.id);
+            }
+            else if (days > options.staleAfterDays) {
+                aged.push({
+                    entryId: entry.id,
+                    verifiedOn: entry.verifiedOn,
+                    ageDays: days,
+                    source: relativeSource(projectRoot, entry.source?.origin),
+                });
+            }
+        }
+        aged.sort((a, b) => b.ageDays - a.ageDays || a.entryId.localeCompare(b.entryId));
+        age = { asOf, staleAfterDays: options.staleAfterDays, aged, neverVerified };
+    }
     return {
         schema: KNOWLEDGE_STALE_SCHEMA,
         entries: inspection.knowledgeEntries.length,
@@ -575,6 +1223,18 @@ export function buildKnowledgeStaleReport(inspection, options = {}) {
         counts,
         referenceChecks,
         anchorChecks,
+        entriesInScope,
+        coverage,
+        entryVerdicts,
+        unverifiableIds,
+        failureCounts,
+        byAssetKind,
+        byEntryType,
+        byReferenceKind,
+        assetReferenceChecks,
+        advisories,
+        policySweep,
+        ...(age ? { age } : {}),
     };
 }
 /**
@@ -891,51 +1551,77 @@ function checkAnchor(inspection, anchor, graph) {
     switch (anchor.kind) {
         case 'file':
             if (!anchor.path) {
-                return { outcome: ReferenceCheckOutcome.Unknown, message: 'anchor has no path' };
+                return {
+                    outcome: ReferenceCheckOutcome.Invalid,
+                    failure: ReferenceFailure.Malformed,
+                    message: 'malformed anchor: file anchor missing required field `path`.',
+                };
             }
             if (fileExists(inspection.projectRoot, anchor.path)) {
                 return { outcome: ReferenceCheckOutcome.Ok, message: `anchor file exists: ${anchor.path}` };
             }
-            return { outcome: ReferenceCheckOutcome.Stale, message: `anchor file missing: ${anchor.path}` };
+            return {
+                outcome: ReferenceCheckOutcome.Stale,
+                failure: ReferenceFailure.PathMissing,
+                message: `anchor file missing: ${anchor.path}`,
+            };
         case 'symbol':
             return checkSymbolAnchor(inspection, anchor, graph);
-        case 'command':
-            if (anchor.targetId && commandExistsInInspection(inspection, anchor.targetId)) {
-                return { outcome: ReferenceCheckOutcome.Ok, message: `command exists: ${anchor.targetId}` };
+        case 'command': {
+            if (!anchor.targetId) {
+                return { outcome: ReferenceCheckOutcome.Stale, message: 'command anchor unresolved: ?' };
             }
-            return { outcome: ReferenceCheckOutcome.Stale, message: `command anchor unresolved: ${anchor.targetId ?? '?'}` };
+            const r = checkCommandString(inspection, anchor.targetId, 'command anchor');
+            return { outcome: r.outcome, message: r.message };
+        }
         case 'construct':
-            if (anchor.targetId && constructExists(inspection, anchor.targetId)) {
-                return { outcome: ReferenceCheckOutcome.Ok, message: `construct exists: ${anchor.targetId}` };
-            }
-            return { outcome: ReferenceCheckOutcome.Stale, message: `construct anchor unresolved: ${anchor.targetId ?? '?'}` };
+            return checkAnchorId(inspection, 'construct', anchor.targetId);
         case 'template':
-            if (anchor.targetId && templateExists(inspection, anchor.targetId)) {
-                return { outcome: ReferenceCheckOutcome.Ok, message: `template exists: ${anchor.targetId}` };
-            }
-            return { outcome: ReferenceCheckOutcome.Stale, message: `template anchor unresolved: ${anchor.targetId ?? '?'}` };
+            return checkAnchorId(inspection, 'template', anchor.targetId);
         case 'helper':
-            if (anchor.targetId && helperExists(anchor.targetId)) {
-                return { outcome: ReferenceCheckOutcome.Ok, message: `helper exists: ${anchor.targetId}` };
-            }
-            return { outcome: ReferenceCheckOutcome.Stale, message: `helper anchor unresolved: ${anchor.targetId ?? '?'}` };
+            return checkAnchorId(inspection, 'helper', anchor.targetId);
         case 'playbook':
-            if (anchor.targetId && playbookExists(inspection, anchor.targetId)) {
-                return { outcome: ReferenceCheckOutcome.Ok, message: `playbook exists: ${anchor.targetId}` };
-            }
-            return { outcome: ReferenceCheckOutcome.Stale, message: `playbook anchor unresolved: ${anchor.targetId ?? '?'}` };
+            return checkAnchorId(inspection, 'playbook', anchor.targetId);
         case 'policy':
-            if (anchor.targetId && policyExists(inspection, anchor.targetId)) {
-                return { outcome: ReferenceCheckOutcome.Ok, message: `policy exists: ${anchor.targetId}` };
-            }
-            return { outcome: ReferenceCheckOutcome.Stale, message: `policy anchor unresolved: ${anchor.targetId ?? '?'}` };
+            return checkAnchorId(inspection, 'policy', anchor.targetId);
+        default:
+            return {
+                outcome: ReferenceCheckOutcome.Invalid,
+                failure: ReferenceFailure.Malformed,
+                message: `malformed anchor: unsupported anchor kind "${String(anchor.kind)}".`,
+            };
     }
 }
+/**
+ * An id-keyed anchor, through the same guarded resolver as a reference — an
+ * unloaded registry is NOT VERIFIED, never "unresolved".
+ */
+function checkAnchorId(inspection, kind, targetId) {
+    if (!targetId) {
+        return {
+            outcome: ReferenceCheckOutcome.Stale,
+            failure: ReferenceFailure.IdUnregistered,
+            message: `${kind} anchor unresolved: ?`,
+        };
+    }
+    const r = checkRegisteredId(inspection, kind, targetId, kind);
+    if (r.outcome === ReferenceCheckOutcome.Ok) {
+        return { outcome: ReferenceCheckOutcome.Ok, message: `${kind} exists: ${targetId}` };
+    }
+    if (r.outcome === ReferenceCheckOutcome.Unknown) {
+        return { outcome: r.outcome, message: r.message, failure: ReferenceFailure.Unverifiable };
+    }
+    return {
+        outcome: ReferenceCheckOutcome.Stale,
+        failure: ReferenceFailure.IdUnregistered,
+        message: `${kind} anchor unresolved: ${targetId}`,
+    };
+}
 function checkSymbolAnchor(inspection, anchor, graph) {
     const r = checkSymbolReference(inspection.projectRoot, {
         kind: 'symbol',
         symbol: anchor.symbol,
         ...(anchor.path ? { path: anchor.path } : {}),
     }, graph);
-    return { outcome: r.outcome, message: r.message };
+    return { outcome: r.outcome, message: r.message, ...(r.failure ? { failure: r.failure } : {}) };
 }