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

package/dist/pack-signature-status.js

@@ -2,58 +2,36 @@
  * Pack signature freshness inspector.
  *
  * Reports each discovered pack's signature state without ever computing or
- * faking HMAC. Surfaces three statuses:
+ * faking HMAC. Freshness is read from THE pack-asset freshness authority
+ * (`detectPackAssetFreshness`): content digests recorded at sign time, never an
+ * mtime. Statuses:
  *
- *   present       — manifest has a signature and the timestamp is >= any
- *                   contribution file mtime we can see (heuristic — real
- *                   HMAC validation happens in pack-doctor).
- *   stale         — manifest has a signature but at least one contribution
- *                   file has a newer mtime than the signature timestamp.
- *   missing       — manifest has no signature block.
+ *   present     — signed, and every recorded contribution file still has the
+ *                 content that was signed (real HMAC validation happens in
+ *                 pack-doctor / packs verify).
+ *   stale       — signed, but a recorded contribution file changed since.
+ *   unverified  — signed, but the signature records no content digest for some
+ *                 file (signed before digests existed) — freshness NOT verified.
+ *   missing     — manifest has no signature block.
  *
  * The check is deterministic, read-only, and never requires the pack secret.
  */
-import { existsSync, statSync } from 'node:fs';
 import * as nodePath from 'node:path';
+import { describePackAssetFreshness, detectPackAssetFreshness } from "./pack-asset-freshness.js";
 export const PACK_SIGNATURE_STATUS_SCHEMA = 'sharkcraft.pack-signature-status/v1';
 export var PackSignatureStatusKind;
 (function (PackSignatureStatusKind) {
     PackSignatureStatusKind["Present"] = "present";
     PackSignatureStatusKind["Stale"] = "stale";
+    PackSignatureStatusKind["Unverified"] = "unverified";
     PackSignatureStatusKind["Missing"] = "missing";
 })(PackSignatureStatusKind || (PackSignatureStatusKind = {}));
-const CONTRIB_SLOTS = [
-    'knowledgeFiles',
-    'ruleFiles',
-    'pathFiles',
-    'pathConventionFiles',
-    'templateFiles',
-    'pipelineFiles',
-    'presetFiles',
-    'boundaryFiles',
-    'contextTestFiles',
-    'agentTestFiles',
-    'scaffoldPatternFiles',
-    'policyCheckFiles',
-    'constructFiles',
-    'constructFacetFiles',
-    'playbookFiles',
-    'searchTuningFiles',
-    'feedbackRuleFiles',
-    'decisionFiles',
-    'mcpToolFiles',
-    'aiProviderFiles',
-    'docsFiles',
-    'contractTemplateFiles',
-    'migrationProfileFiles',
-    'conventionFiles',
-    'helperFiles',
-    'taskRoutingHintFiles',
-];
 export function buildPackSignatureStatusReport(inspection) {
     const secret = Boolean(process.env['SHARKCRAFT_PACK_SECRET']);
     const out = [];
     for (const pack of inspection.packs.validPacks ?? []) {
+        const rel = nodePath.relative(inspection.projectRoot, pack.packageRoot);
+        const signCmd = secret ? `shrk packs sign ${rel}` : `SHARKCRAFT_PACK_SECRET=<secret> shrk packs sign ${rel}`;
         const sig = pack.manifest?.signature;
         if (!sig) {
             out.push({
@@ -63,87 +41,57 @@ export function buildPackSignatureStatusReport(inspection) {
                 status: PackSignatureStatusKind.Missing,
                 reason: 'no signature block on manifest',
                 secretAvailable: secret,
-                nextCommand: secret
-                    ? `shrk packs sign ${nodePath.relative(inspection.projectRoot, pack.packageRoot)}`
-                    : `SHARKCRAFT_PACK_SECRET=<secret> shrk packs sign ${nodePath.relative(inspection.projectRoot, pack.packageRoot)}`,
+                nextCommand: signCmd,
             });
             continue;
         }
-        const sigMs = (() => {
-            try {
-                return new Date(sig.signedAt).getTime();
-            }
-            catch {
-                return 0;
-            }
-        })();
-        let newerFile;
-        let newerMtime;
-        const contributions = (pack.manifest?.contributions ?? {});
-        for (const slot of CONTRIB_SLOTS) {
-            const rels = contributions[slot];
-            if (!rels)
-                continue;
-            for (const rel of rels) {
-                const abs = nodePath.resolve(pack.packageRoot, rel);
-                if (!existsSync(abs))
-                    continue;
-                try {
-                    const st = statSync(abs);
-                    if (st.mtimeMs > sigMs + 1000) {
-                        newerFile = rel;
-                        newerMtime = new Date(st.mtimeMs).toISOString();
-                        break;
-                    }
-                }
-                catch {
-                    continue;
-                }
-            }
-            if (newerFile)
-                break;
-        }
-        if (newerFile && sig.dev === true) {
+        const freshness = detectPackAssetFreshness(pack);
+        const said = describePackAssetFreshness(freshness).signature;
+        const base = {
+            packageName: pack.packageName,
+            packageVersion: pack.packageVersion,
+            packageRoot: pack.packageRoot,
+            signatureSignedAt: sig.signedAt,
+            secretAvailable: secret,
+            ...(freshness.signature.diverged.length > 0
+                ? { divergedFiles: freshness.signature.diverged, newerContributionFile: freshness.signature.diverged[0] }
+                : {}),
+            ...(freshness.signature.unrecorded.length > 0 ? { unrecordedFiles: freshness.signature.unrecorded } : {}),
+        };
+        if (freshness.signature.state === 'diverged' && sig.dev === true) {
             // Dev packs are signed with the well-known PACK_DEV_SECRET and load fine
-            // locally unsigned/dev — every local `npm run build` re-stales them, so a
-            // standing "stale" warning is pure noise during pack development. Keep
-            // them out of the stale bucket (still counted under summary.dev) and
-            // soften the reason. Production (non-dev) signed packs are untouched.
+            // locally — every local build re-stales them, so a standing "stale" is
+            // pure noise during pack development. Keep them out of the stale bucket
+            // (still counted under summary.dev) and soften the reason. Production
+            // (non-dev) signed packs are untouched.
             out.push({
-                packageName: pack.packageName,
-                packageVersion: pack.packageVersion,
-                packageRoot: pack.packageRoot,
+                ...base,
                 status: PackSignatureStatusKind.Present,
-                signatureSignedAt: sig.signedAt,
-                secretAvailable: secret,
                 dev: true,
-                reason: `dev signature re-staled by a local build ("${newerFile}" newer) — dev packs load fine locally; re-sign before release`,
+                reason: `dev signature re-staled by a local build ("${freshness.signature.diverged[0]}" changed since signing) — dev packs load fine locally; re-sign before release`,
             });
         }
-        else if (newerFile) {
+        else if (freshness.signature.state === 'diverged') {
             out.push({
-                packageName: pack.packageName,
-                packageVersion: pack.packageVersion,
-                packageRoot: pack.packageRoot,
+                ...base,
                 status: PackSignatureStatusKind.Stale,
-                signatureSignedAt: sig.signedAt,
-                reason: `contribution file "${newerFile}" mtime (${newerMtime}) is newer than signature (${sig.signedAt})`,
-                newerContributionFile: newerFile,
-                newerContributionMtime: newerMtime,
-                secretAvailable: secret,
-                nextCommand: secret
-                    ? `shrk packs sign ${nodePath.relative(inspection.projectRoot, pack.packageRoot)}`
-                    : `SHARKCRAFT_PACK_SECRET=<secret> shrk packs sign ${nodePath.relative(inspection.projectRoot, pack.packageRoot)}`,
+                ...(said ? { reason: said } : {}),
+                nextCommand: signCmd,
+            });
+        }
+        else if (freshness.signature.state === 'unrecorded') {
+            out.push({
+                ...base,
+                status: PackSignatureStatusKind.Unverified,
+                ...(said ? { reason: said } : {}),
+                ...(sig.dev === true ? { dev: true } : {}),
+                nextCommand: signCmd,
             });
         }
         else {
             out.push({
-                packageName: pack.packageName,
-                packageVersion: pack.packageVersion,
-                packageRoot: pack.packageRoot,
+                ...base,
                 status: PackSignatureStatusKind.Present,
-                signatureSignedAt: sig.signedAt,
-                secretAvailable: secret,
                 ...(sig.dev === true ? { dev: true } : {}),
             });
         }
@@ -156,6 +104,7 @@ export function buildPackSignatureStatusReport(inspection) {
             total: out.length,
             present: out.filter((p) => p.status === PackSignatureStatusKind.Present).length,
             stale: out.filter((p) => p.status === PackSignatureStatusKind.Stale).length,
+            unverified: out.filter((p) => p.status === PackSignatureStatusKind.Unverified).length,
             missing: out.filter((p) => p.status === PackSignatureStatusKind.Missing).length,
             dev: out.filter((p) => p.dev === true).length,
         },
@@ -209,16 +158,21 @@ export function explainPackSignatureStatus(inspection, options = {}) {
         }
         else if (fresh?.status === 'stale') {
             state = 'stale';
-            explanation = `${fresh.reason ?? 'Signature is older than at least one contribution file.'}`;
+            explanation = `${fresh.reason ?? 'A contribution file changed since the signature was made.'}`;
+            nextCommand = signCmd;
+        }
+        else if (fresh?.status === 'unverified') {
+            state = 'freshness-unverified';
+            explanation = `${fresh.reason ?? 'The signature records no content digests, so freshness is NOT verified.'}`;
             nextCommand = signCmd;
         }
         else if (fresh?.status === 'present') {
             // Freshness only — the HMAC was NOT checked this run. Reserve `valid`
-            // strictly for a real verifier pass so a bogus-HMAC-but-fresh-timestamp
-            // pack is never mislabelled as verified.
+            // strictly for a real verifier pass so a bogus-HMAC-but-fresh pack is
+            // never mislabelled as verified.
             state = 'present-unverified';
             explanation =
-                'Signature present and newer than every contribution file, but the HMAC was NOT checked this run.';
+                'Signature present and every contribution file still matches its signed content digest, but the HMAC was NOT checked this run.';
             nextCommand = 'shrk packs verify --required';
         }
         else {

package/dist/pack-test-runner.d.ts

@@ -8,10 +8,19 @@
  *
  * The runner:
  *   1. Loads the pack tests via dynamic import (Bun handles TS natively).
- *   2. For each test case, builds a task packet against an isolated inspection.
- *   3. Validates the packet contains every `expect*Ids` and none of the
- *      `mustNotIncludeIds`, optionally capping the token budget.
- *   4. Emits a structured diagnostic report.
+ *   2. Inspects the pack once and warms the shared reference registry.
+ *   3. For each test case, builds a task packet and checks the expectations —
+ *      two classes of assertion, reported separately:
+ *        - ranker-SURFACED (`expectKnowledgeIds` / `expectRuleIds` /
+ *          `expectTemplateIds` / `expectPipelineIds`): the id is in the packet.
+ *          Order-sensitive; an unrelated content edit can flip it.
+ *        - registry-EXISTENCE (`expectPlaybookIds` / `expectConstructIds`): the
+ *          id is registered. Stable. These were declared but never evaluated
+ *          (the packet summary hard-coded both lists to []), so a typo'd id
+ *          passed silently.
+ *   4. Emits a structured diagnostic report. A surfaced-class miss says whether
+ *      the id exists at all (`unknown-id` — can never pass) or merely did not
+ *      rank (`not-surfaced`), and names the registry it consulted.
  */
 export interface IPackTestCase {
     id: string;
@@ -32,8 +41,21 @@ export interface IPackTestResult {
     task: string;
     passed: boolean;
     diagnostics: ReadonlyArray<{
-        code: 'missing-id' | 'unexpected-id' | 'token-budget' | 'load-error';
+        /**
+         * `unknown-id` — not registered at all (can never pass); `not-surfaced` —
+         * registered but not in the packet; `unexpected-id` — a mustNotInclude id
+         * was surfaced.
+         */
+        code: 'unknown-id' | 'not-surfaced' | 'unexpected-id' | 'token-budget' | 'load-error';
         field?: string;
+        /** `surfaced` (in the task packet) or `exists` (registered). */
+        assertion?: 'surfaced' | 'exists';
+        /** The registry the existence answer came from. */
+        consulted?: {
+            kind: string;
+            listVerb: string;
+            size: number;
+        };
         expected?: string;
         actual?: string;
         suggestion?: string;

package/dist/pack-test-runner.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"pack-test-runner.d.ts","sourceRoot":"","sources":["../src/pack-test-runner.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAQH,MAAM,WAAW,aAAa;IAC5B,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,kBAAkB,CAAC,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC;IAC3C,aAAa,CAAC,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC;IACtC,iBAAiB,CAAC,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC;IAC1C,iBAAiB,CAAC,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC;IAC1C,iBAAiB,CAAC,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC;IAC1C,kBAAkB,CAAC,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC;IAC3C,iBAAiB,CAAC,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC;IAC1C,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,wBAAgB,cAAc,CAAC,CAAC,SAAS,aAAa,EAAE,CAAC,EAAE,CAAC,GAAG,CAAC,CAE/D;AAED,MAAM,WAAW,eAAe;IAC9B,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,OAAO,CAAC;IAChB,WAAW,EAAE,aAAa,CAAC;QACzB,IAAI,EAAE,YAAY,GAAG,eAAe,GAAG,cAAc,GAAG,YAAY,CAAC;QACrE,KAAK,CAAC,EAAE,MAAM,CAAC;QACf,QAAQ,CAAC,EAAE,MAAM,CAAC;QAClB,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,UAAU,CAAC,EAAE,MAAM,CAAC;QACpB,OAAO,EAAE,MAAM,CAAC;KACjB,CAAC,CAAC;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,MAAM,WAAW,eAAe;IAC9B,MAAM,EAAE,gCAAgC,CAAC;IACzC,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,GAAG,EAAE,MAAM,CAAC;IACZ,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,aAAa,CAAC,eAAe,CAAC,CAAC;CACvC;AA4HD,wBAAsB,YAAY,CAAC,KAAK,EAAE;IACxC,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,eAAe,CAAC,EAAE,OAAO,CAAC;CAC3B,GAAG,OAAO,CAAC,eAAe,CAAC,CAgE3B;AAED,wBAAgB,wBAAwB,CAAC,MAAM,EAAE,eAAe,GAAG,MAAM,CAiBxE"}
+{"version":3,"file":"pack-test-runner.d.ts","sourceRoot":"","sources":["../src/pack-test-runner.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAcH,MAAM,WAAW,aAAa;IAC5B,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,CAAC,EAAE,MAAM,CAAC;IAErB,kBAAkB,CAAC,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC;IAC3C,aAAa,CAAC,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC;IACtC,iBAAiB,CAAC,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC;IAC1C,iBAAiB,CAAC,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC;IAE1C,iBAAiB,CAAC,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC;IAC1C,kBAAkB,CAAC,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC;IAC3C,iBAAiB,CAAC,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC;IAC1C,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,wBAAgB,cAAc,CAAC,CAAC,SAAS,aAAa,EAAE,CAAC,EAAE,CAAC,GAAG,CAAC,CAE/D;AAED,MAAM,WAAW,eAAe;IAC9B,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,OAAO,CAAC;IAChB,WAAW,EAAE,aAAa,CAAC;QACzB;;;;WAIG;QACH,IAAI,EAAE,YAAY,GAAG,cAAc,GAAG,eAAe,GAAG,cAAc,GAAG,YAAY,CAAC;QACtF,KAAK,CAAC,EAAE,MAAM,CAAC;QACf,gEAAgE;QAChE,SAAS,CAAC,EAAE,UAAU,GAAG,QAAQ,CAAC;QAClC,mDAAmD;QACnD,SAAS,CAAC,EAAE;YAAE,IAAI,EAAE,MAAM,CAAC;YAAC,QAAQ,EAAE,MAAM,CAAC;YAAC,IAAI,EAAE,MAAM,CAAA;SAAE,CAAC;QAC7D,QAAQ,CAAC,EAAE,MAAM,CAAC;QAClB,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,UAAU,CAAC,EAAE,MAAM,CAAC;QACpB,OAAO,EAAE,MAAM,CAAC;KACjB,CAAC,CAAC;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,MAAM,WAAW,eAAe;IAC9B,MAAM,EAAE,gCAAgC,CAAC;IACzC,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,GAAG,EAAE,MAAM,CAAC;IACZ,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,aAAa,CAAC,eAAe,CAAC,CAAC;CACvC;AAsKD,wBAAsB,YAAY,CAAC,KAAK,EAAE;IACxC,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,eAAe,CAAC,EAAE,OAAO,CAAC;CAC3B,GAAG,OAAO,CAAC,eAAe,CAAC,CAsE3B;AAED,wBAAgB,wBAAwB,CAAC,MAAM,EAAE,eAAe,GAAG,MAAM,CAoBxE"}

package/dist/pack-test-runner.js

@@ -8,16 +8,26 @@
  *
  * The runner:
  *   1. Loads the pack tests via dynamic import (Bun handles TS natively).
- *   2. For each test case, builds a task packet against an isolated inspection.
- *   3. Validates the packet contains every `expect*Ids` and none of the
- *      `mustNotIncludeIds`, optionally capping the token budget.
- *   4. Emits a structured diagnostic report.
+ *   2. Inspects the pack once and warms the shared reference registry.
+ *   3. For each test case, builds a task packet and checks the expectations —
+ *      two classes of assertion, reported separately:
+ *        - ranker-SURFACED (`expectKnowledgeIds` / `expectRuleIds` /
+ *          `expectTemplateIds` / `expectPipelineIds`): the id is in the packet.
+ *          Order-sensitive; an unrelated content edit can flip it.
+ *        - registry-EXISTENCE (`expectPlaybookIds` / `expectConstructIds`): the
+ *          id is registered. Stable. These were declared but never evaluated
+ *          (the packet summary hard-coded both lists to []), so a typo'd id
+ *          passed silently.
+ *   4. Emits a structured diagnostic report. A surfaced-class miss says whether
+ *      the id exists at all (`unknown-id` — can never pass) or merely did not
+ *      rank (`not-surfaced`), and names the registry it consulted.
  */
 import { existsSync, writeFileSync, mkdirSync } from 'node:fs';
 import { join } from 'node:path';
 import { inspectSharkcraft } from "./sharkcraft-inspector.js";
 import { buildTaskPacket } from "./task-packet.js";
 import { importModuleViaLoader } from '@shrkcrft/core';
+import { referenceIdExists, referenceIdsFor, warmReferenceRegistries, } from "./reference-registry.js";
 export function definePackTest(t) {
     return t;
 }
@@ -26,6 +36,14 @@ const TEST_FILE_CANDIDATES = [
     'src/assets/pack-tests.ts',
     'pack-tests.ts',
 ];
+const LIST_VERBS = Object.freeze({
+    knowledge: 'shrk knowledge list',
+    rule: 'shrk rules list',
+    template: 'shrk templates list',
+    pipeline: 'shrk pipelines list',
+    playbook: 'shrk playbooks list',
+    construct: 'shrk constructs list',
+});
 function findTestsFile(packPath) {
     for (const rel of TEST_FILE_CANDIDATES) {
         const abs = join(packPath, rel);
@@ -42,45 +60,73 @@ async function loadTestCases(file) {
 function unique(arr) {
     return [...new Set(arr)];
 }
-async function summariseTaskPacket(packPath, task) {
-    const inspection = await inspectSharkcraft({ cwd: packPath });
+function summariseTaskPacket(inspection, task) {
     const packet = buildTaskPacket(inspection, task);
-    const knowledgeIds = unique(packet.context.sections.flatMap((s) => [...s.entryIds]));
-    const ruleIds = unique(packet.relevantRules.map((r) => r.id));
-    const templateIds = unique(packet.relevantTemplates.map((t) => t.id));
-    const pipelineIds = unique(packet.recommendedPipelines.map((p) => p.pipelineId));
     return {
-        knowledgeIds,
-        ruleIds,
-        templateIds,
-        pipelineIds,
-        playbookIds: [],
-        constructIds: [],
+        knowledgeIds: unique(packet.context.sections.flatMap((s) => [...s.entryIds])),
+        ruleIds: unique(packet.relevantRules.map((r) => r.id)),
+        templateIds: unique(packet.relevantTemplates.map((t) => t.id)),
+        pipelineIds: unique(packet.recommendedPipelines.map((p) => p.pipelineId)),
         tokenEstimate: packet.tokenEstimate,
     };
 }
-function evaluateCase(testCase, packet) {
+function consultedRegistry(inspection, kind) {
+    return {
+        kind,
+        listVerb: LIST_VERBS[kind] ?? `shrk ${kind} list`,
+        size: referenceIdsFor(inspection, kind).length,
+    };
+}
+function evaluateCase(testCase, packet, inspection) {
     const diagnostics = [];
-    const checks = [
-        { field: 'knowledgeIds', expected: testCase.expectKnowledgeIds },
-        { field: 'ruleIds', expected: testCase.expectRuleIds },
-        { field: 'templateIds', expected: testCase.expectTemplateIds },
-        { field: 'pipelineIds', expected: testCase.expectPipelineIds },
+    const surfaced = [
+        { field: 'knowledgeIds', kind: 'knowledge', expected: testCase.expectKnowledgeIds },
+        { field: 'ruleIds', kind: 'rule', expected: testCase.expectRuleIds },
+        { field: 'templateIds', kind: 'template', expected: testCase.expectTemplateIds },
+        { field: 'pipelineIds', kind: 'pipeline', expected: testCase.expectPipelineIds },
     ];
-    for (const c of checks) {
+    for (const c of surfaced) {
         if (!c.expected)
             continue;
         const actualList = packet[c.field];
         for (const id of c.expected) {
-            if (!actualList.includes(id)) {
-                diagnostics.push({
-                    code: 'missing-id',
-                    field: c.field,
-                    expected: id,
-                    suggestion: `Add ${id} to the pack's ${c.field} or to the recommender for "${testCase.task}".`,
-                    message: `Expected ${c.field} to include "${id}" for task "${testCase.task}", but it did not.`,
-                });
-            }
+            if (actualList.includes(id))
+                continue;
+            const registry = consultedRegistry(inspection, c.kind);
+            const exists = referenceIdExists(inspection, c.kind, id);
+            diagnostics.push({
+                code: exists ? 'not-surfaced' : 'unknown-id',
+                field: c.field,
+                assertion: 'surfaced',
+                consulted: registry,
+                expected: id,
+                suggestion: exists
+                    ? `Tune ${id}'s tags / appliesWhen, or reference it from a preset, so the recommender surfaces it for "${testCase.task}".`
+                    : `Correct the id or ship the ${c.kind} — it is not among the ${registry.size} ids \`${registry.listVerb}\` prints.`,
+                message: exists
+                    ? `Expected ${c.field} to include "${id}" for task "${testCase.task}": it is registered but was not surfaced.`
+                    : `Expected ${c.field} to include "${id}", but no ${c.kind} "${id}" is registered — this expectation can never pass.`,
+            });
+        }
+    }
+    const existence = [
+        { field: 'playbookIds', kind: 'playbook', expected: testCase.expectPlaybookIds },
+        { field: 'constructIds', kind: 'construct', expected: testCase.expectConstructIds },
+    ];
+    for (const c of existence) {
+        for (const id of c.expected ?? []) {
+            if (referenceIdExists(inspection, c.kind, id))
+                continue;
+            const registry = consultedRegistry(inspection, c.kind);
+            diagnostics.push({
+                code: 'unknown-id',
+                field: c.field,
+                assertion: 'exists',
+                consulted: registry,
+                expected: id,
+                suggestion: `Correct the id or ship the ${c.kind} — it is not among the ${registry.size} ids \`${registry.listVerb}\` prints.`,
+                message: `Expected ${c.kind} "${id}" to be registered, but it is not.`,
+            });
         }
     }
     if (testCase.mustNotIncludeIds && testCase.mustNotIncludeIds.length > 0) {
@@ -94,6 +140,7 @@ function evaluateCase(testCase, packet) {
             if (allIds.includes(id)) {
                 diagnostics.push({
                     code: 'unexpected-id',
+                    assertion: 'surfaced',
                     expected: id,
                     actual: id,
                     message: `"${id}" should not have been included in the packet for task "${testCase.task}".`,
@@ -159,9 +206,15 @@ export async function runPackTests(input) {
     if (caseId)
         cases = cases.filter((c) => c.id === caseId);
     const results = [];
-    for (const tc of cases) {
-        const summary = await summariseTaskPacket(packPath, tc.task);
-        results.push(evaluateCase(tc, summary));
+    if (cases.length > 0) {
+        // One inspection, warmed once: every existence answer comes from the
+        // shared reference registry (the playbook / construct kinds are
+        // cache-backed and read empty until warmed).
+        const inspection = await inspectSharkcraft({ cwd: packPath });
+        await warmReferenceRegistries(inspection);
+        for (const tc of cases) {
+            results.push(evaluateCase(tc, summariseTaskPacket(inspection, tc.task), inspection));
+        }
     }
     if (input.updateSnapshots) {
         const snapsDir = join(packPath, 'sharkcraft', 'pack-test-snapshots');
@@ -195,6 +248,9 @@ export function renderPackTestReportText(report) {
         lines.push(`  ${c.passed ? '✓' : '✗'} ${c.id}  ${c.task}`);
         for (const d of c.diagnostics) {
             lines.push(`      - [${d.code}] ${d.message}`);
+            if (d.consulted) {
+                lines.push(`        consulted: ${d.consulted.kind} registry (${d.consulted.size} ids, \`${d.consulted.listVerb}\`)`);
+            }
             if (d.suggestion)
                 lines.push(`        ↳ ${d.suggestion}`);
         }

package/dist/pack-typecheck.d.ts

@@ -0,0 +1,8 @@
+import { type ISharkCraftPackManifest } from '@shrkcrft/plugin-api';
+import { type ITypecheckFilesResult } from './typecheck-files.js';
+export declare function typecheckPackAssets(pack: {
+    readonly packageRoot: string;
+    readonly manifestPath?: string | null;
+    readonly manifest?: ISharkCraftPackManifest | null;
+}): ITypecheckFilesResult;
+//# sourceMappingURL=pack-typecheck.d.ts.map

package/dist/pack-typecheck.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pack-typecheck.d.ts","sourceRoot":"","sources":["../src/pack-typecheck.ts"],"names":[],"mappings":"AAiBA,OAAO,EAGL,KAAK,uBAAuB,EAC7B,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EAAkB,KAAK,qBAAqB,EAAE,MAAM,sBAAsB,CAAC;AAIlF,wBAAgB,mBAAmB,CAAC,IAAI,EAAE;IACxC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACtC,QAAQ,CAAC,QAAQ,CAAC,EAAE,uBAAuB,GAAG,IAAI,CAAC;CACpD,GAAG,qBAAqB,CAoBxB"}

package/dist/pack-typecheck.js

@@ -0,0 +1,76 @@
+/**
+ * Type-check a pack's own TypeScript assets — the manifest file plus every
+ * `.ts`/`.tsx` contribution the manifest declares — with the ONE in-process
+ * check (`typecheckFiles`). Pack loading is transpile-only, so this is the
+ * only place an implicit-any parameter or a misspelled field in an asset is
+ * caught before it ships.
+ *
+ * Opt-in (`--typecheck` on `packs test | doctor | release-check`): it is
+ * costly, and default loading must not change behaviour. The pack's own
+ * `tsconfig.json` applies when present; otherwise strict defaults with `.ts`
+ * import specifiers allowed (Bun loads them). Every diagnostic in a file under
+ * the pack root is reported (so a group module an asset imports is checked
+ * too). `ran: false` — no TS files, or TypeScript could not run — is a
+ * not-verified outcome for callers, never a pass.
+ */
+import { existsSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { CONTRIBUTION_FILE_KEYS, FUTURE_CONTRIBUTION_FILE_KEYS, } from '@shrkcrft/plugin-api';
+import { typecheckFiles } from "./typecheck-files.js";
+const TS_SOURCE = /\.(?:[cm]?ts|tsx)$/;
+export function typecheckPackAssets(pack) {
+    const roots = new Set();
+    if (pack.manifestPath && TS_SOURCE.test(pack.manifestPath) && existsSync(pack.manifestPath)) {
+        roots.add(resolve(pack.manifestPath));
+    }
+    const contributions = (pack.manifest?.contributions ?? {});
+    for (const key of [...CONTRIBUTION_FILE_KEYS, ...FUTURE_CONTRIBUTION_FILE_KEYS]) {
+        for (const rel of contributions[key] ?? []) {
+            if (typeof rel !== 'string' || !TS_SOURCE.test(rel))
+                continue;
+            const abs = resolve(pack.packageRoot, rel);
+            if (existsSync(abs))
+                roots.add(abs);
+        }
+    }
+    const result = typecheckFiles(pack.packageRoot, {
+        rootNames: [...roots].sort(),
+        reportOnlyUnder: pack.packageRoot,
+        allowTsExtensionsByDefault: true,
+        includeGlobalDiagnostics: true,
+    });
+    return sdkUnresolved(result, pack.packageRoot) ?? result;
+}
+/** "Cannot find module" — 2307, and 2792 (its moduleResolution-hint variant). */
+const MODULE_NOT_FOUND = new Set([2307, 2792]);
+const SDK_SPECIFIER = /['"](@shrkcrft\/[^'"]+)['"]/;
+/**
+ * A pack that imports the SharkCraft SDK (`@shrkcrft/*`) from a tree where it
+ * is not installed (a fresh `packs new` scaffold before `npm install`) cannot
+ * be type-checked: every SDK type is unresolved, so the diagnostics are the
+ * missing devDependency — cascading into implicit-any errors — not defects in
+ * the pack. That run examined nothing trustworthy: report it as NOT run (a
+ * not-verified outcome for every caller), never as pack errors.
+ */
+function sdkUnresolved(result, packageRoot) {
+    if (!result.ran)
+        return undefined;
+    const missing = new Set();
+    for (const e of result.errors) {
+        if (!MODULE_NOT_FOUND.has(e.code))
+            continue;
+        const m = SDK_SPECIFIER.exec(e.message);
+        if (m)
+            missing.add(m[1]);
+    }
+    if (missing.size === 0)
+        return undefined;
+    return {
+        ran: false,
+        errors: [],
+        checkedFiles: result.checkedFiles,
+        tsconfigPath: result.tsconfigPath,
+        note: `SDK not installed — ${[...missing].sort().join(', ')} cannot be resolved from ${packageRoot}, so the ` +
+            `${result.errors.length} diagnostic(s) it produced are withheld; run \`npm install\` in the pack and re-run — typecheck NOT verified`,
+    };
+}

package/dist/plan-review.d.ts

@@ -56,6 +56,8 @@ export interface IPlanReviewReport {
      * scanning its imports against the boundary rules.
      */
     planIntroducedBoundaryConcerns: readonly IPlanIntroducedBoundaryConcern[];
+    /** Why `potentialBoundaryConcerns` is not the full answer for the targets (THE boundary verdict's shortfalls). */
+    boundaryShortfalls?: readonly string[];
     /** Verification commands recommended to run after apply. */
     verificationCommands: readonly string[];
     humanApprovalReminder: string;

package/dist/plan-review.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"plan-review.d.ts","sourceRoot":"","sources":["../src/plan-review.ts"],"names":[],"mappings":"AAeA,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,2BAA2B,CAAC;AAEvE,MAAM,WAAW,eAAe;IAC9B,8FAA8F;IAC9F,IAAI,EACA,QAAQ,GACR,QAAQ,GACR,QAAQ,GACR,cAAc,GACd,eAAe,GACf,SAAS,GACT,QAAQ,GACR,MAAM,GACN,UAAU,GACV,SAAS,CAAC;IACd,YAAY,EAAE,MAAM,CAAC;IACrB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,4FAA4F;IAC5F,gBAAgB,CAAC,EAAE,OAAO,CAAC;CAC5B;AAED,MAAM,WAAW,8BAA8B;IAC7C,oDAAoD;IACpD,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,MAAM,CAAC;IAClB,eAAe,EAAE,MAAM,CAAC;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;IAChB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,mBAAmB;IAClC,IAAI,EAAE,eAAe,GAAG,eAAe,CAAC;IACxC,UAAU,EAAE,MAAM,CAAC;IACnB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,GAAG,QAAQ,CAAC;IAC1B,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,mFAAmF;IACnF,iBAAiB,EAAE,kBAAkB,GAAG,sCAAsC,CAAC;CAChF;AAED,MAAM,WAAW,iBAAiB;IAChC,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,gCAAgC;IAChC,KAAK,EAAE,eAAe,EAAE,CAAC;IACzB,6CAA6C;IAC7C,SAAS,EAAE,SAAS,mBAAmB,EAAE,CAAC;IAC1C,oDAAoD;IACpD,SAAS,EAAE,QAAQ,GAAG,SAAS,GAAG,SAAS,CAAC;IAC5C,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,+DAA+D;IAC/D,aAAa,EAAE,SAAS,MAAM,EAAE,CAAC;IACjC,iEAAiE;IACjE,qBAAqB,EAAE,SAAS,MAAM,EAAE,CAAC;IACzC,8EAA8E;IAC9E,yBAAyB,EAAE,SAAS;QAClC,IAAI,EAAE,MAAM,CAAC;QACb,MAAM,EAAE,MAAM,CAAC;QACf,eAAe,EAAE,MAAM,CAAC;QACxB,IAAI,EAAE,MAAM,CAAC;QACb,QAAQ,EAAE,MAAM,CAAC;KAClB,EAAE,CAAC;IACJ;;;;OAIG;IACH,8BAA8B,EAAE,SAAS,8BAA8B,EAAE,CAAC;IAC1E,4DAA4D;IAC5D,oBAAoB,EAAE,SAAS,MAAM,EAAE,CAAC;IACxC,qBAAqB,EAAE,MAAM,CAAC;CAC/B;AAED,wBAAgB,eAAe,CAC7B,UAAU,EAAE,qBAAqB,EACjC,QAAQ,EAAE,MAAM,GACf,iBAAiB,CAkLnB"}
+{"version":3,"file":"plan-review.d.ts","sourceRoot":"","sources":["../src/plan-review.ts"],"names":[],"mappings":"AAgBA,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,2BAA2B,CAAC;AAEvE,MAAM,WAAW,eAAe;IAC9B,8FAA8F;IAC9F,IAAI,EACA,QAAQ,GACR,QAAQ,GACR,QAAQ,GACR,cAAc,GACd,eAAe,GACf,SAAS,GACT,QAAQ,GACR,MAAM,GACN,UAAU,GACV,SAAS,CAAC;IACd,YAAY,EAAE,MAAM,CAAC;IACrB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,4FAA4F;IAC5F,gBAAgB,CAAC,EAAE,OAAO,CAAC;CAC5B;AAED,MAAM,WAAW,8BAA8B;IAC7C,oDAAoD;IACpD,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,MAAM,CAAC;IAClB,eAAe,EAAE,MAAM,CAAC;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;IAChB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,mBAAmB;IAClC,IAAI,EAAE,eAAe,GAAG,eAAe,CAAC;IACxC,UAAU,EAAE,MAAM,CAAC;IACnB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,GAAG,QAAQ,CAAC;IAC1B,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,mFAAmF;IACnF,iBAAiB,EAAE,kBAAkB,GAAG,sCAAsC,CAAC;CAChF;AAED,MAAM,WAAW,iBAAiB;IAChC,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,gCAAgC;IAChC,KAAK,EAAE,eAAe,EAAE,CAAC;IACzB,6CAA6C;IAC7C,SAAS,EAAE,SAAS,mBAAmB,EAAE,CAAC;IAC1C,oDAAoD;IACpD,SAAS,EAAE,QAAQ,GAAG,SAAS,GAAG,SAAS,CAAC;IAC5C,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,+DAA+D;IAC/D,aAAa,EAAE,SAAS,MAAM,EAAE,CAAC;IACjC,iEAAiE;IACjE,qBAAqB,EAAE,SAAS,MAAM,EAAE,CAAC;IACzC,8EAA8E;IAC9E,yBAAyB,EAAE,SAAS;QAClC,IAAI,EAAE,MAAM,CAAC;QACb,MAAM,EAAE,MAAM,CAAC;QACf,eAAe,EAAE,MAAM,CAAC;QACxB,IAAI,EAAE,MAAM,CAAC;QACb,QAAQ,EAAE,MAAM,CAAC;KAClB,EAAE,CAAC;IACJ;;;;OAIG;IACH,8BAA8B,EAAE,SAAS,8BAA8B,EAAE,CAAC;IAC1E,kHAAkH;IAClH,kBAAkB,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACvC,4DAA4D;IAC5D,oBAAoB,EAAE,SAAS,MAAM,EAAE,CAAC;IACxC,qBAAqB,EAAE,MAAM,CAAC;CAC/B;AAED,wBAAgB,eAAe,CAC7B,UAAU,EAAE,qBAAqB,EACjC,QAAQ,EAAE,MAAM,GACf,iBAAiB,CAwLnB"}

package/dist/plan-review.js

@@ -1,5 +1,7 @@
 import { readFileSync } from 'node:fs';
-import { evaluateBoundaries, loadTsconfigPaths, scanImports, } from '@shrkcrft/boundaries';
+import { evaluateBoundaries, loadTsconfigPaths, } from '@shrkcrft/boundaries';
+import { ChangedScopeMode } from "./boundaries-changed-only.js";
+import { runBoundaryCheck } from "./run-boundary-check.js";
 import { checkFolderOpSafety, FolderOpSafety, planGeneration, verifyPlan, } from '@shrkcrft/generator';
 import { matchAffectedConventions } from '@shrkcrft/paths';
 export function reviewSavedPlan(inspection, planPath) {
@@ -88,14 +90,20 @@ export function reviewSavedPlan(inspection, planPath) {
             missingTestsHeuristic.push(`${f.relativePath} → expected ${candidate}`);
         }
     }
-    // Current-state boundary scan on the target paths (existing behavior).
+    // Current-state boundary scan on the target paths — through THE boundary
+    // orchestrator, scoped to the planned paths (round 11 review R11-GAP-3): a
+    // governed target it could not read is named in `boundaryShortfalls`.
     let potentialBoundaryConcerns = [];
+    let boundaryShortfalls = [];
     const tsconfigPaths = loadTsconfigPaths(inspection.projectRoot);
     const aliasOpts = tsconfigPaths.aliases.size > 0 ? { tsconfigPaths } : {};
     if (inspection.boundaryRegistry.size() > 0 && files.length > 0) {
-        const scan = scanImports({ projectRoot: inspection.projectRoot });
-        const evalResult = evaluateBoundaries(scan, inspection.boundaryRegistry.list(), aliasOpts);
-        const targetSet = new Set(files.map((f) => f.relativePath));
+        const targets = files.map((f) => f.relativePath);
+        const evalResult = runBoundaryCheck(inspection, { changed: { mode: ChangedScopeMode.Files, files: targets } });
+        if (evalResult.verdict === 'not-verified' && evalResult.selectedRuleIds.length > 0) {
+            boundaryShortfalls = evalResult.shortfalls;
+        }
+        const targetSet = new Set(targets);
         potentialBoundaryConcerns = evalResult.violations
             .filter((v) => targetSet.has(v.file))
             .map((v) => ({
@@ -111,6 +119,9 @@ export function reviewSavedPlan(inspection, planPath) {
     // planned paths.
     const planIntroducedBoundaryConcerns = [];
     if (inspection.boundaryRegistry.size() > 0 && liveChanges.length > 0) {
+        // PLANNED contents are not on disk, so the orchestrator cannot scan them:
+        // a sanctioned direct `evaluateBoundaries` over planned edges only (the
+        // r75 one-boundary-authority lock names this call site).
         const plannedEdges = collectPlannedEdges(liveChanges);
         const evalResult = evaluateBoundaries({ filesScanned: liveChanges.length, edges: plannedEdges, warnings: [] }, inspection.boundaryRegistry.list(), aliasOpts);
         for (const v of evalResult.violations) {
@@ -157,6 +168,7 @@ export function reviewSavedPlan(inspection, planPath) {
         missingTestsHeuristic,
         potentialBoundaryConcerns,
         planIntroducedBoundaryConcerns,
+        ...(boundaryShortfalls.length > 0 ? { boundaryShortfalls } : {}),
         verificationCommands: [
             'shrk doctor',
             'shrk check boundaries',