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

package/dist/inspection-discovery.d.ts

@@ -0,0 +1,45 @@
+import type { ISharkcraftInspection } from './sharkcraft-inspector.js';
+import type { IKnowledgeLoadFailure } from './knowledge-load-failure.js';
+/**
+ * Where discovery landed, and why — read by any verdict that must refuse to
+ * pass over a corpus it never loaded.
+ *
+ * A corpus check run from a nested package (its own package.json, no
+ * `sharkcraft/` folder) resolves that package as the root, loads 0 entries, and
+ * used to print `ok=0 stale=0` with exit 0. The disconfirming facts were all on
+ * the inspection; nothing put them in front of the reader.
+ */
+export interface IInspectionDiscovery {
+    /** The directory discovery started from (the caller's cwd). */
+    readonly startDir: string;
+    /** The project root the inspection resolved — the nearest ancestor carrying a root marker. */
+    readonly resolvedRoot: string;
+    /** Which markers made {@link resolvedRoot} a root (`package.json`, `.git`, …). */
+    readonly rootMarkers: readonly string[];
+    readonly sharkcraftDir: string | null;
+    readonly configFile: string | null;
+    /** The loader's message when a config file EXISTS but failed to load. */
+    readonly configError?: string;
+    /** Knowledge entries loaded. */
+    readonly entriesLoaded: number;
+    /** Knowledge-bearing files the loaders were told about (local + pack; missing ones included). */
+    readonly knowledgeFilesAttempted: number;
+    /**
+     * Knowledge-bearing files whose entries never reached the corpus (failed,
+     * timed out, a cached failure, or declared and missing). Non-empty = the
+     * corpus is PARTIAL: a stale-check over it is never a pass, and
+     * `--allow-empty` never clears it.
+     */
+    readonly knowledgeLoadFailures: readonly IKnowledgeLoadFailure[];
+    /**
+     * When {@link resolvedRoot} has no `sharkcraft/` folder: the nearest ancestor
+     * (up to the repository top) that has one — the `--cwd` to rerun with.
+     */
+    readonly configuredAncestor?: string;
+}
+/**
+ * Describe the inspection's discovery. The ONE reader of "where did discovery
+ * land": the stale-check refusal, its JSON, and the MCP stale tool all call it.
+ */
+export declare function describeInspectionDiscovery(inspection: ISharkcraftInspection, startDir?: string): IInspectionDiscovery;
+//# sourceMappingURL=inspection-discovery.d.ts.map

package/dist/inspection-discovery.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"inspection-discovery.d.ts","sourceRoot":"","sources":["../src/inspection-discovery.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,2BAA2B,CAAC;AACvE,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,6BAA6B,CAAC;AAqDzE;;;;;;;;GAQG;AACH,MAAM,WAAW,oBAAoB;IACnC,+DAA+D;IAC/D,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,8FAA8F;IAC9F,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,kFAAkF;IAClF,QAAQ,CAAC,WAAW,EAAE,SAAS,MAAM,EAAE,CAAC;IACxC,QAAQ,CAAC,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;IACtC,QAAQ,CAAC,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IACnC,yEAAyE;IACzE,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,gCAAgC;IAChC,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,iGAAiG;IACjG,QAAQ,CAAC,uBAAuB,EAAE,MAAM,CAAC;IACzC;;;;;OAKG;IACH,QAAQ,CAAC,qBAAqB,EAAE,SAAS,qBAAqB,EAAE,CAAC;IACjE;;;OAGG;IACH,QAAQ,CAAC,kBAAkB,CAAC,EAAE,MAAM,CAAC;CACtC;AAED;;;GAGG;AACH,wBAAgB,2BAA2B,CACzC,UAAU,EAAE,qBAAqB,EACjC,QAAQ,GAAE,MAA+B,GACxC,oBAAoB,CAiBtB"}

package/dist/inspection-discovery.js

@@ -0,0 +1,70 @@
+import * as nodePath from 'node:path';
+import { detectProjectRoot, findConfiguredAncestor } from '@shrkcrft/config';
+/** The loader slots whose entries feed `inspection.knowledgeEntries`. */
+const KNOWLEDGE_LOADER_KINDS = new Set(['knowledge', 'rules', 'paths', 'docs']);
+/** `failed` / `timeout` / `cached-failed` / `missing`, or `ok` for a file whose entries loaded. */
+function loadOutcome(d) {
+    if (d.status === 'cached-skip') {
+        return d.cachedStatus !== undefined && d.cachedStatus !== 'ok' ? 'cached-failed' : 'ok';
+    }
+    return d.status;
+}
+/**
+ * Every knowledge-bearing file the loaders were told about, and the ones whose
+ * entries never reached the corpus — read off `inspection.loaderDiagnostics`,
+ * the one record of what each loader did.
+ */
+function knowledgeLoadOutcomes(inspection) {
+    const byFile = new Map();
+    for (const d of inspection.loaderDiagnostics ?? []) {
+        if (!KNOWLEDGE_LOADER_KINDS.has(d.kind))
+            continue;
+        const key = nodePath.resolve(d.filePath);
+        const prior = byFile.get(key);
+        // A failure recorded for a file wins over an ok one (never folded into it).
+        if (!prior || (loadOutcome(prior) === 'ok' && loadOutcome(d) !== 'ok'))
+            byFile.set(key, d);
+    }
+    const rel = (abs) => {
+        const r = nodePath.relative(inspection.projectRoot, abs);
+        return r && !r.startsWith('..') && !nodePath.isAbsolute(r) ? r.split(nodePath.sep).join('/') : abs;
+    };
+    const failures = [];
+    for (const d of byFile.values()) {
+        const status = loadOutcome(d);
+        if (status === 'ok')
+            continue;
+        failures.push({
+            file: rel(d.filePath),
+            kind: d.kind,
+            status,
+            message: d.errorMessage ??
+                (status === 'missing' ? 'declared by the config, but the file does not exist' : `the ${d.kind} loader reported ${status}`),
+            ...(d.packName ? { packName: d.packName } : {}),
+        });
+    }
+    failures.sort((a, b) => a.file.localeCompare(b.file));
+    return { attempted: byFile.size, failures };
+}
+/**
+ * Describe the inspection's discovery. The ONE reader of "where did discovery
+ * land": the stale-check refusal, its JSON, and the MCP stale tool all call it.
+ */
+export function describeInspectionDiscovery(inspection, startDir = inspection.projectRoot) {
+    const ancestor = inspection.hasSharkcraftFolder
+        ? null
+        : findConfiguredAncestor(inspection.projectRoot);
+    const loads = knowledgeLoadOutcomes(inspection);
+    return {
+        startDir,
+        resolvedRoot: inspection.projectRoot,
+        rootMarkers: detectProjectRoot(inspection.projectRoot).markers,
+        sharkcraftDir: inspection.sharkcraftDir,
+        configFile: inspection.configFile,
+        ...(inspection.configLoadError ? { configError: inspection.configLoadError.message } : {}),
+        entriesLoaded: inspection.knowledgeEntries.length,
+        knowledgeFilesAttempted: loads.attempted,
+        knowledgeLoadFailures: loads.failures,
+        ...(ancestor ? { configuredAncestor: ancestor } : {}),
+    };
+}

package/dist/knowledge-advisory-code.d.ts

@@ -0,0 +1,17 @@
+/** Advisory findings of a staleness sweep. None of them changes the exit code on its own. */
+export declare enum KnowledgeAdvisoryCode {
+    /**
+     * An entry whose references are all file / directory paths names, in its
+     * prose, a symbol one of those files declares — a rename inside the file
+     * would leave the entry wrong while every reference still resolves.
+     */
+    PathOnlyReference = "path-only-reference",
+    /**
+     * A boundary rule's `from` glob has a static prefix that does not exist —
+     * the rule governs nothing there (implicit reference, `--fail-on implicit`).
+     */
+    ImplicitPathMissing = "implicit-path-missing",
+    /** Policy checks keep their scope inside `evaluate()`, which cannot be read without running it. */
+    PolicyScopeUnverifiable = "policy-scope-unverifiable"
+}
+//# sourceMappingURL=knowledge-advisory-code.d.ts.map

package/dist/knowledge-advisory-code.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"knowledge-advisory-code.d.ts","sourceRoot":"","sources":["../src/knowledge-advisory-code.ts"],"names":[],"mappings":"AAAA,6FAA6F;AAC7F,oBAAY,qBAAqB;IAC/B;;;;OAIG;IACH,iBAAiB,wBAAwB;IACzC;;;OAGG;IACH,mBAAmB,0BAA0B;IAC7C,mGAAmG;IACnG,uBAAuB,8BAA8B;CACtD"}

package/dist/knowledge-advisory-code.js

@@ -0,0 +1,17 @@
+/** Advisory findings of a staleness sweep. None of them changes the exit code on its own. */
+export var KnowledgeAdvisoryCode;
+(function (KnowledgeAdvisoryCode) {
+    /**
+     * An entry whose references are all file / directory paths names, in its
+     * prose, a symbol one of those files declares — a rename inside the file
+     * would leave the entry wrong while every reference still resolves.
+     */
+    KnowledgeAdvisoryCode["PathOnlyReference"] = "path-only-reference";
+    /**
+     * A boundary rule's `from` glob has a static prefix that does not exist —
+     * the rule governs nothing there (implicit reference, `--fail-on implicit`).
+     */
+    KnowledgeAdvisoryCode["ImplicitPathMissing"] = "implicit-path-missing";
+    /** Policy checks keep their scope inside `evaluate()`, which cannot be read without running it. */
+    KnowledgeAdvisoryCode["PolicyScopeUnverifiable"] = "policy-scope-unverifiable";
+})(KnowledgeAdvisoryCode || (KnowledgeAdvisoryCode = {}));

package/dist/knowledge-aged-entry.d.ts

@@ -0,0 +1,10 @@
+/** An entry whose `verifiedOn` is older than `--stale-after`. */
+export interface IKnowledgeAgedEntry {
+    readonly entryId: string;
+    readonly verifiedOn: string;
+    /** Whole days from `verifiedOn` to the sweep's `asOf`. */
+    readonly ageDays: number;
+    /** Where the entry is declared, relative to the project root. */
+    readonly source: string;
+}
+//# sourceMappingURL=knowledge-aged-entry.d.ts.map

package/dist/knowledge-aged-entry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"knowledge-aged-entry.d.ts","sourceRoot":"","sources":["../src/knowledge-aged-entry.ts"],"names":[],"mappings":"AAAA,iEAAiE;AACjE,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,0DAA0D;IAC1D,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,iEAAiE;IACjE,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB"}

package/dist/knowledge-aged-entry.js

@@ -0,0 +1 @@
+export {};

package/dist/knowledge-authoring.d.ts

@@ -15,6 +15,7 @@
  *     remain.
  */
 import type { IKnowledgeAnchor, IKnowledgeEntry, IKnowledgeReference } from '@shrkcrft/knowledge';
+import type { IDeclaredXrefReport } from './i-declared-xref-report.js';
 export declare const KNOWLEDGE_AUTHORING_SCHEMA = "sharkcraft.knowledge-authoring/v1";
 export declare enum KnowledgeAuthoringOperation {
     Add = "add",
@@ -127,8 +128,20 @@ export interface IKnowledgeAuthoringResult {
     suggestedDeprecationInstead?: boolean;
 }
 export interface IReverseReference {
+    /** The referencing asset's id — a knowledge entry unless {@link sourceKind} says otherwise. */
     fromEntryId: string;
-    field: 'related' | 'reference.id' | 'reference.symbol' | 'reference.path' | 'anchor.targetId';
+    /**
+     * The referencing asset's kind (`construct`, `boundary-rule`, `template`).
+     * Absent for a knowledge entry, so knowledge-only results keep their shape.
+     */
+    sourceKind?: string;
+    /**
+     * The field holding the reference: `related`, `reference.id`,
+     * `anchor.targetId`, or any declared cross-reference field
+     * (`seeAlso`, `actionHints.relatedKnowledge`, `relatedKnowledge`,
+     * `facets.<name>`, …).
+     */
+    field: string;
     note?: string;
 }
 export interface IKnowledgeAuthoringPatch {
@@ -146,6 +159,16 @@ export interface IKnowledgeAuthoringPatchChange {
 export interface IKnowledgeAuthoringContext {
     /** Currently loaded entries — used for reverse-ref + duplicate detection. */
     entries: readonly IKnowledgeEntry[];
+    /**
+     * Every declared cross-reference in the workspace (`buildDeclaredXrefReport`).
+     * A removal is refused when ANY asset points at the entry — a construct's
+     * `relatedKnowledge`, a boundary rule's `relatedRules`, a template's
+     * `related` — not only another knowledge entry. Without it the check covers
+     * knowledge only, and the preview says so.
+     */
+    declaredXrefs?: IDeclaredXrefReport;
 }
+/** `construct:fx-construct` — or the bare id for a knowledge entry (the shape it always had). */
+export declare function reverseReferenceLabel(rr: IReverseReference): string;
 export declare function buildKnowledgeAuthoringPreview(input: IKnowledgeAuthoringInput, context: IKnowledgeAuthoringContext): IKnowledgeAuthoringResult;
 //# sourceMappingURL=knowledge-authoring.d.ts.map

package/dist/knowledge-authoring.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"knowledge-authoring.d.ts","sourceRoot":"","sources":["../src/knowledge-authoring.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"knowledge-authoring.d.ts","sourceRoot":"","sources":["../src/knowledge-authoring.ts"],"names":[],"mappings":"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"}

package/dist/knowledge-authoring.js

@@ -14,6 +14,7 @@
  *   - Remove always reports reverse references and refuses by default if any
  *     remain.
  */
+import { KNOWLEDGE_BACKED_KINDS, reverseXrefs } from "./declared-cross-references.js";
 export const KNOWLEDGE_AUTHORING_SCHEMA = 'sharkcraft.knowledge-authoring/v1';
 export var KnowledgeAuthoringOperation;
 (function (KnowledgeAuthoringOperation) {
@@ -55,14 +56,25 @@ function tsObject(value, indent) {
         .map((line, idx) => (idx === 0 ? line : indent + line))
         .join('\n'));
 }
-function findReverseReferences(entries, targetId) {
+/**
+ * Everything that points at `targetId`. The structured `references[].id` and
+ * `anchors[].targetId` are scanned here; every DECLARED cross-reference field
+ * (knowledge `related` / `seeAlso` / `supersededBy` / action hints, construct
+ * `related*` + declared facets, boundary `related*`, template `related`) comes
+ * from THE collector when the caller supplied it — this used to be a private
+ * knowledge-only `related` loop, so an entry a construct relied on could be
+ * removed without a word.
+ */
+function findReverseReferences(entries, targetId, declaredXrefs) {
     const out = [];
     for (const e of entries) {
         if (e.id === targetId)
             continue;
-        for (const r of e.related ?? []) {
-            if (r === targetId) {
-                out.push({ fromEntryId: e.id, field: 'related' });
+        if (!declaredXrefs) {
+            for (const r of e.related ?? []) {
+                if (r === targetId) {
+                    out.push({ fromEntryId: e.id, field: 'related' });
+                }
             }
         }
         for (const ref of e.references ?? []) {
@@ -76,8 +88,26 @@ function findReverseReferences(entries, targetId) {
             }
         }
     }
+    if (declaredXrefs) {
+        // Only fields that could mean THIS entry: a construct's
+        // `relatedTemplates: ['x']` is not a reference to a knowledge entry `x`.
+        for (const row of reverseXrefs(declaredXrefs, targetId, KNOWLEDGE_BACKED_KINDS)) {
+            if (row.sourceKind === 'knowledge' && row.sourceId === targetId)
+                continue;
+            out.push({
+                fromEntryId: row.sourceId,
+                ...(row.sourceKind !== 'knowledge' ? { sourceKind: row.sourceKind } : {}),
+                field: row.field,
+                ...(row.facetId ? { note: `facet value ${row.facetId}` } : {}),
+            });
+        }
+    }
     return out;
 }
+/** `construct:fx-construct` — or the bare id for a knowledge entry (the shape it always had). */
+export function reverseReferenceLabel(rr) {
+    return rr.sourceKind && rr.sourceKind !== 'knowledge' ? `${rr.sourceKind}:${rr.fromEntryId}` : rr.fromEntryId;
+}
 function buildEntryFromAdd(input) {
     return {
         id: input.id,
@@ -266,7 +296,7 @@ function buildExplainer(input, result) {
         lines.push(`## Reverse references`);
         lines.push('');
         for (const rr of result.reverseReferences) {
-            lines.push(`- \`${rr.fromEntryId}\` → \`${rr.field}\`${rr.note ? ` — ${rr.note}` : ''}`);
+            lines.push(`- \`${reverseReferenceLabel(rr)}\` → \`${rr.field}\`${rr.note ? ` — ${rr.note}` : ''}`);
         }
         lines.push('');
     }
@@ -453,15 +483,24 @@ export function buildKnowledgeAuthoringPreview(input, context) {
                 refused.explainer = files.explainer;
                 return refused;
             }
-            const reverseReferences = findReverseReferences(context.entries, input.id);
+            const reverseReferences = findReverseReferences(context.entries, input.id, context.declaredXrefs);
+            if (!context.declaredXrefs) {
+                // An unmeasured "no references" must not read as a clean one.
+                warnings.push('reverse references checked in knowledge only — constructs / boundaries / templates were not consulted (pass declaredXrefs from buildDeclaredXrefReport).');
+            }
+            const fromOtherKinds = reverseReferences.filter((r) => r.sourceKind !== undefined && r.sourceKind !== 'knowledge').length;
             if (reverseReferences.length > 0 && !input.forcePreview) {
+                const n = reverseReferences.length;
+                const refusal = fromOtherKinds === 0
+                    ? `Refused: ${n} other entr${n === 1 ? 'y references' : 'ies reference'} "${input.id}".`
+                    : `Refused: ${n} declared reference${n === 1 ? '' : 's'} point${n === 1 ? 's' : ''} at "${input.id}" — ${n - fromOtherKinds} from knowledge, ${fromOtherKinds} from constructs / boundary rules / templates.`;
                 const refused = {
                     schema: KNOWLEDGE_AUTHORING_SCHEMA,
                     generatedAt: nowIso(),
                     operation: input.operation,
                     entryId: input.id,
                     ok: false,
-                    refusal: `Refused: ${reverseReferences.length} other entr${reverseReferences.length === 1 ? 'y references' : 'ies reference'} "${input.id}". Pass --force-preview to preview removal anyway, or prefer deprecation via \`shrk knowledge update ${input.id} --mark-deprecated\`.`,
+                    refusal: `${refusal} Pass --force-preview to preview removal anyway, or prefer deprecation via \`shrk knowledge update ${input.id} --mark-deprecated\`.`,
                     tsDraft: emptyDraftFile(input.id, input.operation, 'typescript'),
                     jsonManifest: emptyDraftFile(input.id, input.operation, 'json'),
                     explainer: emptyDraftFile(input.id, input.operation, 'markdown'),

package/dist/knowledge-entry-verdict-record.d.ts

@@ -0,0 +1,22 @@
+import type { KnowledgeEntryVerdict } from './knowledge-entry-verdict.js';
+import type { KnowledgeUnverifiableReason } from './knowledge-unverifiable-reason.js';
+/** One entry in scope, classified — the unit the stale-check's coverage counts. */
+export interface IKnowledgeEntryVerdictRecord {
+    readonly entryId: string;
+    readonly verdict: KnowledgeEntryVerdict;
+    /** Set when {@link verdict} is `unverifiable`. */
+    readonly reason?: KnowledgeUnverifiableReason;
+    /**
+     * Where the entry is declared, relative to the project root
+     * (`sharkcraft/rules.ts`) — so the fix for an unverifiable entry names the
+     * file to edit. `(unknown source)` when the loader recorded none.
+     */
+    readonly source: string;
+    /** The entry's knowledge `type` (`rule`, `path`, `technical`, …). */
+    readonly type: string;
+    /** References + anchors whose outcome was a real check (ok / stale / missing). */
+    readonly checkable: number;
+    /** Of {@link checkable}, how many did not resolve (stale / missing). */
+    readonly failing: number;
+}
+//# sourceMappingURL=knowledge-entry-verdict-record.d.ts.map

package/dist/knowledge-entry-verdict-record.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"knowledge-entry-verdict-record.d.ts","sourceRoot":"","sources":["../src/knowledge-entry-verdict-record.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,8BAA8B,CAAC;AAC1E,OAAO,KAAK,EAAE,2BAA2B,EAAE,MAAM,oCAAoC,CAAC;AAEtF,mFAAmF;AACnF,MAAM,WAAW,4BAA4B;IAC3C,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,OAAO,EAAE,qBAAqB,CAAC;IACxC,kDAAkD;IAClD,QAAQ,CAAC,MAAM,CAAC,EAAE,2BAA2B,CAAC;IAC9C;;;;OAIG;IACH,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,qEAAqE;IACrE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,kFAAkF;IAClF,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,wEAAwE;IACxE,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B"}

package/dist/knowledge-entry-verdict-record.js

@@ -0,0 +1 @@
+export {};

package/dist/knowledge-entry-verdict.d.ts

@@ -0,0 +1,17 @@
+/**
+ * One entry's verdict in the staleness sweep — three buckets, never one.
+ *
+ * The sweep used to report only reference-level counts, so an entry that
+ * declared NO references contributed nothing and was folded into the healthy
+ * total: the less verifiable a corpus was, the healthier it looked. An entry
+ * the check could not examine is its own bucket, reported with its id.
+ */
+export declare enum KnowledgeEntryVerdict {
+    /** At least one reference / anchor was checked, and every checked one resolved. */
+    Verified = "verified",
+    /** At least one checked reference / anchor did not resolve. */
+    Stale = "stale",
+    /** Nothing about this entry could be checked — see its reason. */
+    Unverifiable = "unverifiable"
+}
+//# sourceMappingURL=knowledge-entry-verdict.d.ts.map

package/dist/knowledge-entry-verdict.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"knowledge-entry-verdict.d.ts","sourceRoot":"","sources":["../src/knowledge-entry-verdict.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,oBAAY,qBAAqB;IAC/B,mFAAmF;IACnF,QAAQ,aAAa;IACrB,+DAA+D;IAC/D,KAAK,UAAU;IACf,kEAAkE;IAClE,YAAY,iBAAiB;CAC9B"}

package/dist/knowledge-entry-verdict.js

@@ -0,0 +1,17 @@
+/**
+ * One entry's verdict in the staleness sweep — three buckets, never one.
+ *
+ * The sweep used to report only reference-level counts, so an entry that
+ * declared NO references contributed nothing and was folded into the healthy
+ * total: the less verifiable a corpus was, the healthier it looked. An entry
+ * the check could not examine is its own bucket, reported with its id.
+ */
+export var KnowledgeEntryVerdict;
+(function (KnowledgeEntryVerdict) {
+    /** At least one reference / anchor was checked, and every checked one resolved. */
+    KnowledgeEntryVerdict["Verified"] = "verified";
+    /** At least one checked reference / anchor did not resolve. */
+    KnowledgeEntryVerdict["Stale"] = "stale";
+    /** Nothing about this entry could be checked — see its reason. */
+    KnowledgeEntryVerdict["Unverifiable"] = "unverifiable";
+})(KnowledgeEntryVerdict || (KnowledgeEntryVerdict = {}));

package/dist/knowledge-graph.d.ts

@@ -22,6 +22,12 @@ export interface IKnowledgeGraph {
     edges: IGraphEdge[];
     /** Convenience: lookup by composite id (kind:id). */
     byId: ReadonlyMap<string, IGraphNode>;
+    /**
+     * Declared edges NOT drawn because an endpoint is not a node of this graph
+     * (a dangling id, or a kind the graph does not model). A shrunken graph says
+     * it shrank — `shrk self-config xrefs --dangling-only` lists the ids.
+     */
+    droppedEdges?: number;
 }
 /**
  * Build the full SharkCraft knowledge graph for the current inspection.

package/dist/knowledge-graph.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"knowledge-graph.d.ts","sourceRoot":"","sources":["../src/knowledge-graph.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,2BAA2B,CAAC;AAEvE,MAAM,MAAM,aAAa,GACrB,WAAW,GACX,MAAM,GACN,MAAM,GACN,UAAU,GACV,UAAU,GACV,QAAQ,GACR,MAAM,GACN,UAAU,GACV,KAAK,CAAC;AAEV,MAAM,WAAW,UAAU;IACzB,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,aAAa,CAAC;IACpB,KAAK,EAAE,MAAM,CAAC;IACd,iCAAiC;IACjC,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,4CAA4C;IAC5C,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,MAAM,iBAAiB,GACzB,kBAAkB,GAClB,cAAc,GACd,cAAc,GACd,iBAAiB,GACjB,mBAAmB,GACnB,0BAA0B,GAC1B,kBAAkB,GAClB,uBAAuB,GACvB,uBAAuB,GACvB,UAAU,CAAC;AAEf,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,EAAE,EAAE,MAAM,CAAC;IACX,QAAQ,EAAE,iBAAiB,CAAC;IAC5B,qDAAqD;IACrD,GAAG,EAAE,MAAM,CAAC;CACb;AAED,MAAM,WAAW,eAAe;IAC9B,KAAK,EAAE,UAAU,EAAE,CAAC;IACpB,KAAK,EAAE,UAAU,EAAE,CAAC;IACpB,qDAAqD;IACrD,IAAI,EAAE,WAAW,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC;CACvC;AAMD;;;GAGG;AACH,wBAAgB,mBAAmB,CAAC,UAAU,EAAE,qBAAqB,GAAG,eAAe,CAyQtF;AAED,MAAM,WAAW,cAAc;IAC7B,oCAAoC;IACpC,IAAI,EAAE,MAAM,CAAC;IACb,8DAA8D;IAC9D,GAAG,CAAC,EAAE;QAAE,QAAQ,EAAE,iBAAiB,CAAC;QAAC,GAAG,EAAE,MAAM,CAAA;KAAE,CAAC;CACpD;AAED,MAAM,WAAW,UAAU;IACzB,KAAK,EAAE,OAAO,CAAC;IACf,KAAK,EAAE,cAAc,EAAE,CAAC;IACxB,gFAAgF;IAChF,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;;;OAKG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED;;;;GAIG;AACH,wBAAgB,aAAa,CAC3B,KAAK,EAAE,eAAe,EACtB,OAAO,EAAE;IAAE,IAAI,CAAC,EAAE,aAAa,CAAC;IAAC,EAAE,EAAE,MAAM,CAAA;CAAE,EAC7C,KAAK,EAAE;IAAE,IAAI,CAAC,EAAE,aAAa,CAAC;IAAC,EAAE,EAAE,MAAM,CAAA;CAAE,GAC1C,UAAU,CA+DZ;AAgDD;;GAEG;AACH,wBAAgB,YAAY,CAC1B,KAAK,EAAE,eAAe,EACtB,GAAG,EAAE;IAAE,IAAI,CAAC,EAAE,aAAa,CAAC;IAAC,EAAE,EAAE,MAAM,CAAA;CAAE,GACxC;IACD,IAAI,EAAE,UAAU,GAAG,IAAI,CAAC;IACxB,QAAQ,EAAE,UAAU,EAAE,CAAC;IACvB,QAAQ,EAAE,UAAU,EAAE,CAAC;CACxB,GAAG,IAAI,CA+BP"}
+{"version":3,"file":"knowledge-graph.d.ts","sourceRoot":"","sources":["../src/knowledge-graph.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,2BAA2B,CAAC;AAEvE,MAAM,MAAM,aAAa,GACrB,WAAW,GACX,MAAM,GACN,MAAM,GACN,UAAU,GACV,UAAU,GACV,QAAQ,GACR,MAAM,GACN,UAAU,GACV,KAAK,CAAC;AAEV,MAAM,WAAW,UAAU;IACzB,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,aAAa,CAAC;IACpB,KAAK,EAAE,MAAM,CAAC;IACd,iCAAiC;IACjC,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,4CAA4C;IAC5C,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,MAAM,iBAAiB,GACzB,kBAAkB,GAClB,cAAc,GACd,cAAc,GACd,iBAAiB,GACjB,mBAAmB,GACnB,0BAA0B,GAC1B,kBAAkB,GAClB,uBAAuB,GACvB,uBAAuB,GACvB,UAAU,CAAC;AAEf,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,EAAE,EAAE,MAAM,CAAC;IACX,QAAQ,EAAE,iBAAiB,CAAC;IAC5B,qDAAqD;IACrD,GAAG,EAAE,MAAM,CAAC;CACb;AAED,MAAM,WAAW,eAAe;IAC9B,KAAK,EAAE,UAAU,EAAE,CAAC;IACpB,KAAK,EAAE,UAAU,EAAE,CAAC;IACpB,qDAAqD;IACrD,IAAI,EAAE,WAAW,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC;IACtC;;;;OAIG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAMD;;;GAGG;AACH,wBAAgB,mBAAmB,CAAC,UAAU,EAAE,qBAAqB,GAAG,eAAe,CA0RtF;AAED,MAAM,WAAW,cAAc;IAC7B,oCAAoC;IACpC,IAAI,EAAE,MAAM,CAAC;IACb,8DAA8D;IAC9D,GAAG,CAAC,EAAE;QAAE,QAAQ,EAAE,iBAAiB,CAAC;QAAC,GAAG,EAAE,MAAM,CAAA;KAAE,CAAC;CACpD;AAED,MAAM,WAAW,UAAU;IACzB,KAAK,EAAE,OAAO,CAAC;IACf,KAAK,EAAE,cAAc,EAAE,CAAC;IACxB,gFAAgF;IAChF,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;;;OAKG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED;;;;GAIG;AACH,wBAAgB,aAAa,CAC3B,KAAK,EAAE,eAAe,EACtB,OAAO,EAAE;IAAE,IAAI,CAAC,EAAE,aAAa,CAAC;IAAC,EAAE,EAAE,MAAM,CAAA;CAAE,EAC7C,KAAK,EAAE;IAAE,IAAI,CAAC,EAAE,aAAa,CAAC;IAAC,EAAE,EAAE,MAAM,CAAA;CAAE,GAC1C,UAAU,CA+DZ;AAgDD;;GAEG;AACH,wBAAgB,YAAY,CAC1B,KAAK,EAAE,eAAe,EACtB,GAAG,EAAE;IAAE,IAAI,CAAC,EAAE,aAAa,CAAC;IAAC,EAAE,EAAE,MAAM,CAAA;CAAE,GACxC;IACD,IAAI,EAAE,UAAU,GAAG,IAAI,CAAC;IACxB,QAAQ,EAAE,UAAU,EAAE,CAAC;IACvB,QAAQ,EAAE,UAAU,EAAE,CAAC;CACxB,GAAG,IAAI,CA+BP"}

package/dist/knowledge-graph.js

@@ -9,6 +9,7 @@ export function buildKnowledgeGraph(inspection) {
     const nodes = [];
     const edges = [];
     const byId = new Map();
+    let droppedEdges = 0;
     function addNode(n) {
         const key = nodeKey(n.kind, n.id);
         if (byId.has(key))
@@ -19,10 +20,12 @@ export function buildKnowledgeGraph(inspection) {
     function addEdge(from, to, relation, why) {
         const fromKey = nodeKey(from.kind, from.id);
         const toKey = nodeKey(to.kind, to.id);
-        if (!byId.has(toKey))
-            return; // don't add edges to nodes we didn't see
-        if (!byId.has(fromKey))
+        // An edge to a node we didn't see is not drawn — but it is COUNTED, so the
+        // graph never reads as complete while it silently lost edges.
+        if (!byId.has(toKey) || !byId.has(fromKey)) {
+            droppedEdges += 1;
             return;
+        }
         edges.push({ from: fromKey, to: toKey, relation, why });
     }
     function sourceOf(map, id) {
@@ -142,8 +145,10 @@ export function buildKnowledgeGraph(inspection) {
                             : byId.has(kKey)
                                 ? 'knowledge'
                                 : null;
-                if (!targetKind)
+                if (!targetKind) {
+                    droppedEdges += 1;
                     continue;
+                }
                 addEdge({ kind: 'pipeline', id: pipeline.id }, { kind: targetKind, id: ref }, 'pipeline-step-references', `step ${step.id} references`);
             }
         }
@@ -157,11 +162,17 @@ export function buildKnowledgeGraph(inspection) {
             addEdge({ kind: 'boundary', id: r.id }, { kind: 'path', id }, 'boundary-related-path', 'relatedPathConventions');
         }
     }
-    // Pack contributions: pack → its contributed items.
+    // Pack contributions: pack → its contributed items. A contributed rule or
+    // path convention is a `rule:` / `path:` node, not a `knowledge:` one — the
+    // edge used to target `knowledge:<id>` and was silently dropped for both.
+    const entryKinds = new Map();
+    for (const e of inspection.knowledgeEntries) {
+        entryKinds.set(e.id, String(e.type) === 'rule' ? 'rule' : String(e.type) === 'path' ? 'path' : 'knowledge');
+    }
     for (const [id, src] of inspection.entrySources) {
         if (src.type !== 'pack' || !src.packageName)
             continue;
-        addEdge({ kind: 'pack', id: src.packageName }, { kind: 'knowledge', id }, 'pack-contributes', 'knowledge entry');
+        addEdge({ kind: 'pack', id: src.packageName }, { kind: entryKinds.get(id) ?? 'knowledge', id }, 'pack-contributes', 'knowledge entry');
     }
     for (const [id, src] of inspection.templateSources) {
         if (src.type !== 'pack' || !src.packageName)
@@ -183,7 +194,7 @@ export function buildKnowledgeGraph(inspection) {
             continue;
         addEdge({ kind: 'pack', id: src.packageName }, { kind: 'boundary', id }, 'pack-contributes', 'boundary rule');
     }
-    return { nodes, edges, byId };
+    return { nodes, edges, byId, droppedEdges };
 }
 /**
  * Find the shortest directed path (BFS) between two graph nodes. Edges are

package/dist/knowledge-kind-bucket.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Per-kind counts of a staleness sweep — by asset kind (knowledge / boundary
+ * rule / policy) and by knowledge entry `type`.
+ *
+ * `scanned: 0` means the kind was NOT IN THE SWEEP, which a renderer must say
+ * in words — a row of zeros cannot tell "clean" from "never looked".
+ */
+export interface IKnowledgeKindBucket {
+    /** Subjects of this kind the sweep visited. */
+    scanned: number;
+    /** Of those, how many declare no references / anchors at all. */
+    zeroReferences: number;
+    /** References + anchors checked for this kind. */
+    referencesChecked: number;
+    verified: number;
+    stale: number;
+    unverifiable: number;
+}
+//# sourceMappingURL=knowledge-kind-bucket.d.ts.map

package/dist/knowledge-kind-bucket.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"knowledge-kind-bucket.d.ts","sourceRoot":"","sources":["../src/knowledge-kind-bucket.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,MAAM,WAAW,oBAAoB;IACnC,+CAA+C;IAC/C,OAAO,EAAE,MAAM,CAAC;IAChB,iEAAiE;IACjE,cAAc,EAAE,MAAM,CAAC;IACvB,kDAAkD;IAClD,iBAAiB,EAAE,MAAM,CAAC;IAC1B,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,MAAM,CAAC;IACd,YAAY,EAAE,MAAM,CAAC;CACtB"}

package/dist/knowledge-kind-bucket.js

@@ -0,0 +1 @@
+export {};

package/dist/knowledge-load-failure.d.ts

@@ -0,0 +1,23 @@
+/**
+ * One knowledge-bearing file (`knowledgeFiles` / `ruleFiles` / `pathFiles` /
+ * `docsFiles`, local or pack-contributed) whose entries never reached the
+ * corpus — it failed to import, timed out, was skipped as a cached failure, or
+ * is declared by the config and does not exist.
+ *
+ * Read off `inspection.loaderDiagnostics` (the ONE record of what each loader
+ * did) by `describeInspectionDiscovery`. A corpus verdict over a load failure
+ * examined part of what it was told to, so it is never a pass.
+ */
+export interface IKnowledgeLoadFailure {
+    /** Project-relative when inside the project, else absolute. */
+    readonly file: string;
+    /** The loader slot (`knowledge` / `rules` / `paths` / `docs`). */
+    readonly kind: string;
+    /** `failed` / `timeout` / `cached-failed` / `missing`. */
+    readonly status: string;
+    /** The loader's message (the import error), or why nothing was read. */
+    readonly message: string;
+    /** Set for a pack-contributed file. */
+    readonly packName?: string;
+}
+//# sourceMappingURL=knowledge-load-failure.d.ts.map

package/dist/knowledge-load-failure.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"knowledge-load-failure.d.ts","sourceRoot":"","sources":["../src/knowledge-load-failure.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,MAAM,WAAW,qBAAqB;IACpC,+DAA+D;IAC/D,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,kEAAkE;IAClE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,0DAA0D;IAC1D,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,wEAAwE;IACxE,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,uCAAuC;IACvC,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;CAC5B"}

package/dist/knowledge-load-failure.js

@@ -0,0 +1 @@
+export {};

package/dist/knowledge-reference-kind-bucket.d.ts

@@ -0,0 +1,11 @@
+/** Per-reference-kind outcome counts of a staleness sweep (`file`, `symbol`, `template`, …). */
+export interface IKnowledgeReferenceKindBucket {
+    checked: number;
+    ok: number;
+    stale: number;
+    missing: number;
+    unknown: number;
+    /** Malformed references of this kind (a missing required field) — never checked. */
+    invalid: number;
+}
+//# sourceMappingURL=knowledge-reference-kind-bucket.d.ts.map

package/dist/knowledge-reference-kind-bucket.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"knowledge-reference-kind-bucket.d.ts","sourceRoot":"","sources":["../src/knowledge-reference-kind-bucket.ts"],"names":[],"mappings":"AAAA,gGAAgG;AAChG,MAAM,WAAW,6BAA6B;IAC5C,OAAO,EAAE,MAAM,CAAC;IAChB,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,oFAAoF;IACpF,OAAO,EAAE,MAAM,CAAC;CACjB"}

package/dist/knowledge-reference-kind-bucket.js

@@ -0,0 +1 @@
+export {};

package/dist/knowledge-stale-advisory.d.ts

@@ -0,0 +1,14 @@
+import type { IAssetReference } from '@shrkcrft/core';
+import type { KnowledgeAdvisoryCode } from './knowledge-advisory-code.js';
+import type { ReferenceAssetKind } from './reference-asset-kind.js';
+/** One advisory from a staleness sweep — reported, never gating by itself. */
+export interface IKnowledgeStaleAdvisory {
+    readonly code: KnowledgeAdvisoryCode;
+    /** The entry / boundary rule / policy the advisory is about. */
+    readonly subjectId: string;
+    readonly assetKind: ReferenceAssetKind;
+    readonly message: string;
+    /** A reference that would verify the claim, ready to paste into `references[]`. */
+    readonly suggestion?: IAssetReference;
+}
+//# sourceMappingURL=knowledge-stale-advisory.d.ts.map

package/dist/knowledge-stale-advisory.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"knowledge-stale-advisory.d.ts","sourceRoot":"","sources":["../src/knowledge-stale-advisory.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAC;AACtD,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,8BAA8B,CAAC;AAC1E,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,2BAA2B,CAAC;AAEpE,8EAA8E;AAC9E,MAAM,WAAW,uBAAuB;IACtC,QAAQ,CAAC,IAAI,EAAE,qBAAqB,CAAC;IACrC,gEAAgE;IAChE,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,SAAS,EAAE,kBAAkB,CAAC;IACvC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,mFAAmF;IACnF,QAAQ,CAAC,UAAU,CAAC,EAAE,eAAe,CAAC;CACvC"}

package/dist/knowledge-stale-advisory.js

@@ -0,0 +1 @@
+export {};

package/dist/knowledge-stale-coverage.d.ts

@@ -0,0 +1,19 @@
+/**
+ * The three entry buckets of a staleness sweep, over the entries in scope.
+ *
+ * `verified + stale + unverifiable === entriesInScope`, always. The CLI renders
+ * the unverifiable count AND its percentage on the summary line where a bare
+ * `0 stale` used to sit, and turns {@link referencedRatio} into the verdict's
+ * coverage (`examined` = verified + stale).
+ */
+export interface IKnowledgeStaleCoverage {
+    readonly entriesInScope: number;
+    readonly verified: number;
+    readonly stale: number;
+    readonly unverifiable: number;
+    /** `unverifiable / entriesInScope × 100`, one decimal place; 0 for an empty scope. */
+    readonly unverifiablePct: number;
+    /** `(verified + stale) / entriesInScope` — the share the check could examine; 0 for an empty scope. */
+    readonly referencedRatio: number;
+}
+//# sourceMappingURL=knowledge-stale-coverage.d.ts.map