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

package/dist/declared-gate-plane-rules.js

@@ -0,0 +1,39 @@
+import { GATE_PLANE_CONFIG_KEY, GATE_PLANE_ORDER } from '@shrkcrft/config';
+import { isProjectConfigAbsent, resolveProjectConfig } from "./resolve-project-config.js";
+/**
+ * How many data-defined gate-plane rules the project declares, per plane —
+ * read through `resolveProjectConfig` (THE config reader that sees
+ * pack-contributed planes) under THE plane → config-key list beside the config
+ * schema (`GATE_PLANE_CONFIG_KEY`), the one the CLI's `collectGateRules` reads.
+ *
+ * Two "no config was read" answers, kept apart (round 11 review R12-REG-2):
+ *   - NO config — the loader found no `sharkcraft/` folder
+ *     (`isProjectConfigAbsent`, the answer `finish` reads as "gate not
+ *     applicable"): zero rules and no `loadError`; there are no planes to run;
+ *   - a config that EXISTS but failed to load: `loadError` is set, since
+ *     nothing can be said about what it declares.
+ *
+ * `buildQualityReport` consumers other than `shrk quality` (MCP, the
+ * dashboard, the report site) do not run the planes — some spawn shells — so
+ * they report a not-run `gate-planes` row from this count; `shrk quality`
+ * runs them.
+ */
+export async function declaredGatePlaneRules(projectRoot) {
+    const resolved = await resolveProjectConfig(projectRoot);
+    if (!resolved.ok) {
+        return isProjectConfigAbsent(resolved.error)
+            ? { total: 0, byPlane: {} }
+            : { total: 0, byPlane: {}, loadError: resolved.error.message };
+    }
+    const config = resolved.value.config;
+    const byPlane = {};
+    let total = 0;
+    for (const plane of GATE_PLANE_ORDER) {
+        const list = config[GATE_PLANE_CONFIG_KEY[plane]];
+        const n = Array.isArray(list) ? list.length : 0;
+        if (n > 0)
+            byPlane[plane] = n;
+        total += n;
+    }
+    return { total, byPlane };
+}

package/dist/declared-reference-coverage.d.ts

@@ -0,0 +1,27 @@
+import type { IVerdictCoverage } from '@shrkcrft/core';
+import { type IKnowledgeAnchorCheck, type IKnowledgeReferenceCheck } from './knowledge-stale.js';
+/** Why a malformed reference is unexamined — the words every surface prints. */
+export declare const MALFORMED_REFERENCE_REASON = "malformed (a kind outside the vocabulary, or a required field missing), so never checked \u2014 `shrk doctor` names each";
+/**
+ * THE fold of declared references into one coverage record.
+ *
+ * A reference whose outcome was CHECKED (ok / stale / missing —
+ * `isCheckableOutcome`) was examined. A MALFORMED one (`invalid`) was declared
+ * to be checked and never was: it is expected, not examined, so a run holding
+ * one is never a clean pass. An `unknown` one (a url, an unpinned or ambiguous
+ * symbol, a file that failed to read) is neither: the stale-check accounts for
+ * it at the ENTRY level (an entry with nothing checkable is unverifiable), so
+ * it leaves both sides here — which is why a scope of ONLY unknown references
+ * is `expected: 0`, "nothing to examine", never a pass.
+ *
+ * `shrk knowledge stale-check` / `verify` (and so `shrk quality`, MCP
+ * `get_quality_report`, the dashboard) and the `shrk gate` knowledge-symbol
+ * gate all settle on this one record — the gate used to count every
+ * non-stale, non-missing reference as "resolving", so a malformed or unpinned
+ * reference read as a pass there while the stale-check said 2.
+ */
+export declare function declaredReferenceCoverage(input: {
+    readonly references: readonly IKnowledgeReferenceCheck[];
+    readonly anchors?: readonly IKnowledgeAnchorCheck[];
+}): IVerdictCoverage;
+//# sourceMappingURL=declared-reference-coverage.d.ts.map

package/dist/declared-reference-coverage.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"declared-reference-coverage.d.ts","sourceRoot":"","sources":["../src/declared-reference-coverage.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AAEvD,OAAO,EAGL,KAAK,qBAAqB,EAC1B,KAAK,wBAAwB,EAC9B,MAAM,sBAAsB,CAAC;AAK9B,gFAAgF;AAChF,eAAO,MAAM,0BAA0B,6HACgF,CAAC;AAExH;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,yBAAyB,CAAC,KAAK,EAAE;IAC/C,QAAQ,CAAC,UAAU,EAAE,SAAS,wBAAwB,EAAE,CAAC;IACzD,QAAQ,CAAC,OAAO,CAAC,EAAE,SAAS,qBAAqB,EAAE,CAAC;CACrD,GAAG,gBAAgB,CA0BnB"}

package/dist/declared-reference-coverage.js

@@ -0,0 +1,50 @@
+import { formatKnowledgeReference } from '@shrkcrft/knowledge';
+import { isCheckableOutcome, ReferenceCheckOutcome, } from "./knowledge-stale.js";
+/** Unexamined labels carried on the coverage record (the full list is in the JSON). */
+const LABEL_CAP = 20;
+/** Why a malformed reference is unexamined — the words every surface prints. */
+export const MALFORMED_REFERENCE_REASON = 'malformed (a kind outside the vocabulary, or a required field missing), so never checked — `shrk doctor` names each';
+/**
+ * THE fold of declared references into one coverage record.
+ *
+ * A reference whose outcome was CHECKED (ok / stale / missing —
+ * `isCheckableOutcome`) was examined. A MALFORMED one (`invalid`) was declared
+ * to be checked and never was: it is expected, not examined, so a run holding
+ * one is never a clean pass. An `unknown` one (a url, an unpinned or ambiguous
+ * symbol, a file that failed to read) is neither: the stale-check accounts for
+ * it at the ENTRY level (an entry with nothing checkable is unverifiable), so
+ * it leaves both sides here — which is why a scope of ONLY unknown references
+ * is `expected: 0`, "nothing to examine", never a pass.
+ *
+ * `shrk knowledge stale-check` / `verify` (and so `shrk quality`, MCP
+ * `get_quality_report`, the dashboard) and the `shrk gate` knowledge-symbol
+ * gate all settle on this one record — the gate used to count every
+ * non-stale, non-missing reference as "resolving", so a malformed or unpinned
+ * reference read as a pass there while the stale-check said 2.
+ */
+export function declaredReferenceCoverage(input) {
+    const anchors = input.anchors ?? [];
+    const invalidRefs = input.references.filter((c) => c.outcome === ReferenceCheckOutcome.Invalid);
+    const invalidAnchors = anchors.filter((a) => a.outcome === ReferenceCheckOutcome.Invalid);
+    const invalidCount = invalidRefs.length + invalidAnchors.length;
+    const invalidLabels = [
+        ...invalidRefs.map((c) => `${c.entryId} → ${formatKnowledgeReference(c.reference)}`),
+        ...invalidAnchors.map((a) => `${a.entryId} anchor[${a.anchor.id}]`),
+    ];
+    const checkable = input.references.filter((c) => isCheckableOutcome(c.outcome)).length +
+        anchors.filter((a) => isCheckableOutcome(a.outcome)).length;
+    return {
+        unit: 'declared references',
+        expected: checkable + invalidCount,
+        examined: checkable,
+        ...(invalidCount > 0
+            ? {
+                unexamined: invalidLabels.slice(0, LABEL_CAP),
+                unexaminedTotal: invalidCount,
+                reason: MALFORMED_REFERENCE_REASON,
+            }
+            : checkable === 0
+                ? { reason: 'no entry in scope declares a checkable reference' }
+                : {}),
+    };
+}

package/dist/declared-xref-status.d.ts

@@ -0,0 +1,19 @@
+/**
+ * How one declared cross-reference id resolved.
+ *
+ * `Unverified` is its own outcome, never folded into either of the others: an
+ * id checked against a registry that was never warmed (or is empty) could not
+ * be looked up, and reporting it `Dangling` is how a correct id gets flagged,
+ * while reporting it `Ok` is how a dead one ships.
+ */
+export declare enum DeclaredXrefStatus {
+    /** Resolves in a kind the field accepts. */
+    Ok = "ok",
+    /** Resolves in NO registry. */
+    Dangling = "dangling",
+    /** Resolves, but only in kinds the field does not accept (a template id in `relatedRules`). */
+    WrongKind = "wrong-kind",
+    /** Could not be decided — an accepted registry was not warmed, or is empty. NOT VERIFIED. */
+    Unverified = "unverified"
+}
+//# sourceMappingURL=declared-xref-status.d.ts.map

package/dist/declared-xref-status.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"declared-xref-status.d.ts","sourceRoot":"","sources":["../src/declared-xref-status.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,oBAAY,kBAAkB;IAC5B,4CAA4C;IAC5C,EAAE,OAAO;IACT,+BAA+B;IAC/B,QAAQ,aAAa;IACrB,+FAA+F;IAC/F,SAAS,eAAe;IACxB,6FAA6F;IAC7F,UAAU,eAAe;CAC1B"}

package/dist/declared-xref-status.js

@@ -0,0 +1,19 @@
+/**
+ * How one declared cross-reference id resolved.
+ *
+ * `Unverified` is its own outcome, never folded into either of the others: an
+ * id checked against a registry that was never warmed (or is empty) could not
+ * be looked up, and reporting it `Dangling` is how a correct id gets flagged,
+ * while reporting it `Ok` is how a dead one ships.
+ */
+export var DeclaredXrefStatus;
+(function (DeclaredXrefStatus) {
+    /** Resolves in a kind the field accepts. */
+    DeclaredXrefStatus["Ok"] = "ok";
+    /** Resolves in NO registry. */
+    DeclaredXrefStatus["Dangling"] = "dangling";
+    /** Resolves, but only in kinds the field does not accept (a template id in `relatedRules`). */
+    DeclaredXrefStatus["WrongKind"] = "wrong-kind";
+    /** Could not be decided — an accepted registry was not warmed, or is empty. NOT VERIFIED. */
+    DeclaredXrefStatus["Unverified"] = "unverified";
+})(DeclaredXrefStatus || (DeclaredXrefStatus = {}));

package/dist/delegate-pack-recipes.d.ts

@@ -1,5 +1,5 @@
-import { type IDelegateRecipe } from '@shrkcrft/core';
-import type { ISharkCraftConfig } from '@shrkcrft/config';
+import { type IDelegateRecipe, type IRejectedEntry } from '@shrkcrft/core';
+import { type ISharkCraftConfig } from '@shrkcrft/config';
 import { type IDiscoveredPack } from '@shrkcrft/packs';
 import { type IResolvedDelegateRecipe } from './delegate-catalog.js';
 export interface IPackDelegateRecipe {
@@ -12,11 +12,22 @@ export interface IPackRecipeIssue {
     severity: 'warning' | 'error';
     message: string;
     source?: string;
+    /** `load-failed` / `missing-file` — lifted into THE contribution load-failure map (round 12). */
+    code?: 'load-failed' | 'missing-file';
 }
 export interface ILoadPackRecipesResult {
     recipes: readonly IPackDelegateRecipe[];
     issues: readonly IPackRecipeIssue[];
+    /** Every declared recipe the loader refused — invalid or a duplicate id (round 12, 12.1). */
+    rejected: readonly IRejectedEntry[];
 }
+/**
+ * THE pack delegate-recipe acceptance predicate (round 12, 12.1): the SAME
+ * zod schema the config loader validates an inline recipe with
+ * (`DelegateRecipeSchema`), one `<path>: <message>` per issue — `[]` means
+ * accepted. A pack recipe used to be accepted with no validation at all.
+ */
+export declare function delegateRecipeRejectionReasons(raw: unknown): readonly string[];
 export declare function loadDelegateRecipesFromPacks(validPacks: readonly IDiscoveredPack[]): Promise<ILoadPackRecipesResult>;
 /**
  * One-shot: discover packs under `projectRoot`, load their delegate recipes, and

package/dist/delegate-pack-recipes.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"delegate-pack-recipes.d.ts","sourceRoot":"","sources":["../src/delegate-pack-recipes.ts"],"names":[],"mappings":"AAWA,OAAO,EAAyB,KAAK,eAAe,EAAE,MAAM,gBAAgB,CAAC;AAC7E,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AAC1D,OAAO,EAAiB,KAAK,eAAe,EAAE,MAAM,iBAAiB,CAAC;AACtE,OAAO,EAA0B,KAAK,uBAAuB,EAAE,MAAM,uBAAuB,CAAC;AAE7F,MAAM,WAAW,mBAAmB;IAClC,MAAM,EAAE,eAAe,CAAC;IACxB,WAAW,EAAE,MAAM,CAAC;IACpB,8DAA8D;IAC9D,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,EAAE,SAAS,GAAG,OAAO,CAAC;IAC9B,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,sBAAsB;IACrC,OAAO,EAAE,SAAS,mBAAmB,EAAE,CAAC;IACxC,MAAM,EAAE,SAAS,gBAAgB,EAAE,CAAC;CACrC;AAaD,wBAAsB,4BAA4B,CAChD,UAAU,EAAE,SAAS,eAAe,EAAE,GACrC,OAAO,CAAC,sBAAsB,CAAC,CA8BjC;AAED;;;;;;GAMG;AACH,wBAAsB,gCAAgC,CACpD,MAAM,EAAE,iBAAiB,EACzB,WAAW,EAAE,MAAM,GAClB,OAAO,CAAC,SAAS,uBAAuB,EAAE,CAAC,CAY7C"}
+{"version":3,"file":"delegate-pack-recipes.d.ts","sourceRoot":"","sources":["../src/delegate-pack-recipes.ts"],"names":[],"mappings":"AAWA,OAAO,EAIL,KAAK,eAAe,EACpB,KAAK,cAAc,EACpB,MAAM,gBAAgB,CAAC;AACxB,OAAO,EAAwB,KAAK,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AAChF,OAAO,EAAiB,KAAK,eAAe,EAAE,MAAM,iBAAiB,CAAC;AACtE,OAAO,EAA0B,KAAK,uBAAuB,EAAE,MAAM,uBAAuB,CAAC;AAE7F,MAAM,WAAW,mBAAmB;IAClC,MAAM,EAAE,eAAe,CAAC;IACxB,WAAW,EAAE,MAAM,CAAC;IACpB,8DAA8D;IAC9D,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,EAAE,SAAS,GAAG,OAAO,CAAC;IAC9B,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,iGAAiG;IACjG,IAAI,CAAC,EAAE,aAAa,GAAG,cAAc,CAAC;CACvC;AAED,MAAM,WAAW,sBAAsB;IACrC,OAAO,EAAE,SAAS,mBAAmB,EAAE,CAAC;IACxC,MAAM,EAAE,SAAS,gBAAgB,EAAE,CAAC;IACpC,6FAA6F;IAC7F,QAAQ,EAAE,SAAS,cAAc,EAAE,CAAC;CACrC;AAED;;;;;GAKG;AACH,wBAAgB,8BAA8B,CAAC,GAAG,EAAE,OAAO,GAAG,SAAS,MAAM,EAAE,CAI9E;AAED,wBAAsB,4BAA4B,CAChD,UAAU,EAAE,SAAS,eAAe,EAAE,GACrC,OAAO,CAAC,sBAAsB,CAAC,CA0DjC;AAED;;;;;;GAMG;AACH,wBAAsB,gCAAgC,CACpD,MAAM,EAAE,iBAAiB,EACzB,WAAW,EAAE,MAAM,GAClB,OAAO,CAAC,SAAS,uBAAuB,EAAE,CAAC,CAY7C"}

package/dist/delegate-pack-recipes.js

@@ -9,22 +9,27 @@
  */
 import { existsSync } from 'node:fs';
 import * as nodePath from 'node:path';
-import { importModuleViaLoader } from '@shrkcrft/core';
+import { importModuleViaLoader, readContributionExport, RejectionCause, } from '@shrkcrft/core';
+import { DelegateRecipeSchema } from '@shrkcrft/config';
 import { discoverPacks } from '@shrkcrft/packs';
 import { resolveDelegateCatalog } from "./delegate-catalog.js";
-async function importRecipes(file) {
-    const mod = (await importModuleViaLoader(file));
-    if (Array.isArray(mod.default))
-        return mod.default;
-    if (mod.default && typeof mod.default === 'object')
-        return [mod.default];
-    if (Array.isArray(mod.delegateRecipes))
-        return mod.delegateRecipes;
-    return [];
+/**
+ * THE pack delegate-recipe acceptance predicate (round 12, 12.1): the SAME
+ * zod schema the config loader validates an inline recipe with
+ * (`DelegateRecipeSchema`), one `<path>: <message>` per issue — `[]` means
+ * accepted. A pack recipe used to be accepted with no validation at all.
+ */
+export function delegateRecipeRejectionReasons(raw) {
+    const parsed = DelegateRecipeSchema.safeParse(raw);
+    if (parsed.success)
+        return [];
+    return parsed.error.issues.map((i) => `${i.path.join('.') || '(entry)'}: ${i.message}`);
 }
 export async function loadDelegateRecipesFromPacks(validPacks) {
     const recipes = [];
     const issues = [];
+    const rejected = [];
+    const seen = new Map();
     for (const pack of validPacks) {
         const files = pack.manifest?.contributions?.delegateRecipeFiles ?? [];
         for (const rel of files) {
@@ -32,27 +37,53 @@ export async function loadDelegateRecipesFromPacks(validPacks) {
             if (!existsSync(file)) {
                 issues.push({
                     severity: 'warning',
+                    code: 'missing-file',
                     message: `Pack ${pack.packageName} declares ${rel} but the file is missing.`,
                     source: file,
                 });
                 continue;
             }
             try {
-                const list = await importRecipes(file);
-                for (const recipe of list) {
+                const exp = readContributionExport(await importModuleViaLoader(file), { namedKeys: ['delegateRecipes'] });
+                exp.items.forEach((raw, i) => {
+                    const at = {
+                        file,
+                        index: exp.single ? -1 : i,
+                        ...(exp.exportName ? { exportName: exp.exportName } : {}),
+                    };
+                    const rawId = raw && typeof raw === 'object' ? raw.id : undefined;
+                    const id = typeof rawId === 'string' ? rawId : undefined;
+                    const reasons = delegateRecipeRejectionReasons(raw);
+                    if (reasons.length > 0) {
+                        rejected.push({ ...at, ...(id ? { entryId: id } : {}), reasons, cause: RejectionCause.Invalid });
+                        return;
+                    }
+                    const recipe = raw;
+                    const prev = seen.get(recipe.id);
+                    if (prev !== undefined) {
+                        rejected.push({
+                            ...at,
+                            entryId: recipe.id,
+                            reasons: [`id: "${recipe.id}" is already declared in ${prev}`],
+                            cause: RejectionCause.DuplicateId,
+                        });
+                        return;
+                    }
+                    seen.set(recipe.id, `${pack.packageName} (${rel})`);
                     recipes.push({ recipe, packageName: pack.packageName, sourceFile: rel });
-                }
+                });
             }
             catch (e) {
                 issues.push({
                     severity: 'warning',
+                    code: 'load-failed',
                     message: `Pack ${pack.packageName} (${rel}): ${e.message}`,
                     source: file,
                 });
             }
         }
     }
-    return { recipes, issues };
+    return { recipes, issues, rejected };
 }
 /**
  * One-shot: discover packs under `projectRoot`, load their delegate recipes, and

package/dist/demo-package.js

@@ -12,7 +12,7 @@ function readme(scenarios) {
     const lines = [];
     lines.push('# SharkCraft demo package');
     lines.push('');
-    lines.push('Generated by `shrk demo package`. Drop this folder onto another machine,');
+    lines.push('Generated by SharkCraft (demo package). Drop this folder onto another machine,');
     lines.push('read `expected-commands.md`, then run `demo.sh` after reviewing it.');
     lines.push('');
     lines.push('## Scenarios');
@@ -45,7 +45,7 @@ function readme(scenarios) {
 function combinedDemoScript(scenarios) {
     const lines = [];
     lines.push('#!/usr/bin/env bash');
-    lines.push('# SharkCraft demo bundle — generated by `shrk demo package`.');
+    lines.push('# SharkCraft demo bundle — generated by SharkCraft (demo package).');
     lines.push('# Each scenario is delegated to its scenario-<name>.sh file so you can');
     lines.push('# run them individually or as a group. Nothing destructive runs here.');
     lines.push('set -euo pipefail');

package/dist/demo-script.js

@@ -111,8 +111,8 @@ const SCRIPTS = {
             {
                 title: 'Compare quality baselines',
                 commands: [
-                    'shrk quality baseline history',
-                    'shrk quality baseline diff latest previous --json',
+                    'shrk quality --json',
+                    'shrk report quality --format json',
                 ],
             },
             {

package/dist/demo-workflow.js

@@ -9,7 +9,7 @@ export const DEMO_WORKFLOW_SCHEMA = 'sharkcraft.demo-workflow/v1';
 function ghaPrReview(bun) {
     const lines = [];
     lines.push('# SharkCraft demo PR review workflow.');
-    lines.push('# Generated by `shrk demo workflow pr-review --provider github-actions`.');
+    lines.push('# Generated by SharkCraft (demo PR-review workflow, github-actions).');
     lines.push('# - runs the read-only review surface on every PR.');
     lines.push('# - no publishing, no posting comments by default.');
     lines.push('# - uncomment the optional `gh pr comment` step to opt into PR comment posting.');
@@ -70,7 +70,7 @@ function ghaPrReview(bun) {
 function gitlabPrReview(bun) {
     const lines = [];
     lines.push('# SharkCraft demo PR review pipeline.');
-    lines.push('# Generated by `shrk demo workflow pr-review --provider gitlab`.');
+    lines.push('# Generated by SharkCraft (demo PR-review workflow, gitlab).');
     lines.push('# - runs the read-only review surface on every MR.');
     lines.push('# - no publishing, no posting comments by default.');
     lines.push('');
@@ -114,7 +114,7 @@ function gitlabPrReview(bun) {
 function bitbucketPrReview(bun) {
     const lines = [];
     lines.push('# SharkCraft demo PR review pipeline.');
-    lines.push('# Generated by `shrk demo workflow pr-review --provider bitbucket`.');
+    lines.push('# Generated by SharkCraft (demo PR-review workflow, bitbucket).');
     lines.push('# - runs the read-only review surface on every pull request.');
     lines.push('# - no publishing, no posting comments by default.');
     lines.push('');

package/dist/dev-cycle.js

@@ -63,7 +63,7 @@ const RELEASE = {
         { id: 'release-readiness', title: 'Release readiness (strict)', command: 'shrk release readiness --strict', canFail: false, category: 'gate' },
         { id: 'release-smoke', title: 'Release smoke (default scenarios)', command: 'shrk release smoke', canFail: true, category: 'gate' },
         { id: 'safety-audit', title: 'Safety audit', command: 'shrk safety audit', canFail: false, category: 'audit' },
-        { id: 'product-check', title: 'Product check', command: 'shrk product check', canFail: true, category: 'gate' },
+        { id: 'product-check', title: 'Product check', command: 'shrk quality', canFail: true, category: 'gate' },
         { id: 'commands-doctor', title: 'Commands doctor', command: 'shrk commands doctor', canFail: true, category: 'doctor' },
     ],
 };

package/dist/dev-session.js

@@ -243,7 +243,7 @@ export function computeDevNextAction(load) {
     if (state?.phase === DevSessionPhase.Completed) {
         return {
             action: 'Session complete',
-            command: `shrk session show ${id}`,
+            command: `shrk dev reports ${id}`,
             reason: 'Final report has been generated.',
             requiresHumanApproval: false,
         };

package/dist/doc-references.d.ts

@@ -1,4 +1,5 @@
-import type { IDocReferenceRule } from '@shrkcrft/core';
+import { type IDocReferenceRule, type IUnitLiveness, type IUnitStateLists, type IVerdictCoverage } from '@shrkcrft/core';
+import { type IReadScope } from '@shrkcrft/boundaries';
 import type { ISharkcraftInspection } from './sharkcraft-inspector.js';
 /**
  * The prose-reference linter.
@@ -53,7 +54,27 @@ export interface IDocReferenceResult {
     readonly tokens: readonly IDocReferenceToken[];
     readonly skipReason?: string;
     readonly error?: string;
+    /**
+     * Set only when a document the globs matched was NOT read (over the read
+     * cap, or unreadable): the documents read, and the unread ones. A reference
+     * in an unread document was never checked, so the rule's coverage names it
+     * (`readScopeCoverage`) and it is never a pass.
+     */
+    readonly readScope?: IReadScope;
+    /**
+     * Set only when the rule is INTENDED-empty (round 13): every inclusion glob
+     * of its `files` is marked `expectEmpty` and no document matched. It is the
+     * settle's acceptance and stands in for the rule's own coverage record
+     * (`docReferenceCoverage`), so the rule passes with the acceptance printed.
+     */
+    readonly emptyCoverage?: IVerdictCoverage;
+    /** Settle record B of the rule's `files` — the acceptance of its intended-empty units. */
+    readonly unitAcceptance?: IVerdictCoverage;
+    /** The rule's dead / intended-empty / went-live `files` units as printed lines (`unitStateLists`). */
+    readonly units?: IUnitStateLists;
+    /** The rule's non-live `files` units, for `--fail-on-dead-units` (`selectorUnitFails`). */
+    readonly unitLiveness?: readonly IUnitLiveness[];
 }
 /** Evaluate one doc-reference rule against the tree. */
-export declare function checkDocReferences(projectRoot: string, rule: IDocReferenceRule, inspection: ISharkcraftInspection, excludeDirs?: readonly string[]): IDocReferenceResult;
+export declare function checkDocReferences(projectRoot: string, authored: IDocReferenceRule, inspection: ISharkcraftInspection, excludeDirs?: readonly string[]): IDocReferenceResult;
 //# sourceMappingURL=doc-references.d.ts.map

package/dist/doc-references.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"doc-references.d.ts","sourceRoot":"","sources":["../src/doc-references.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,gBAAgB,CAAC;AAUxD,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,2BAA2B,CAAC;AAEvE;;;;;;;;;;;GAWG;AAEH,qCAAqC;AACrC,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,6CAA6C;IAC7C,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,oBAAoB;IACpB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,uDAAuD;IACvD,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,kEAAkE;IAClE,QAAQ,CAAC,OAAO,CAAC,EAAE,SAAS,GAAG,QAAQ,GAAG,eAAe,CAAC;CAC3D;AAED,mDAAmD;AACnD,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,QAAQ,EAAE,OAAO,GAAG,SAAS,CAAC;IACvC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,0EAA0E;IAC1E,QAAQ,CAAC,UAAU,EAAE,SAAS,MAAM,EAAE,CAAC;IACvC,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,0BAA0B;AAC1B,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,QAAQ,EAAE,OAAO,GAAG,SAAS,CAAC;IACvC,QAAQ,CAAC,MAAM,EAAE,QAAQ,GAAG,QAAQ,GAAG,SAAS,GAAG,OAAO,CAAC;IAC3D,mCAAmC;IACnC,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,qEAAqE;IACrE,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,iEAAiE;IACjE,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,QAAQ,EAAE,SAAS,oBAAoB,EAAE,CAAC;IACnD,mDAAmD;IACnD,QAAQ,CAAC,MAAM,EAAE,SAAS,kBAAkB,EAAE,CAAC;IAC/C,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;CACzB;AAmDD,wDAAwD;AACxD,wBAAgB,kBAAkB,CAChC,WAAW,EAAE,MAAM,EACnB,IAAI,EAAE,iBAAiB,EACvB,UAAU,EAAE,qBAAqB,EACjC,WAAW,GAAE,SAAS,MAAM,EAAO,GAClC,mBAAmB,CA6JrB"}
+{"version":3,"file":"doc-references.d.ts","sourceRoot":"","sources":["../src/doc-references.ts"],"names":[],"mappings":"AAAA,OAAO,EAOL,KAAK,iBAAiB,EACtB,KAAK,aAAa,EAClB,KAAK,eAAe,EACpB,KAAK,gBAAgB,EACtB,MAAM,gBAAgB,CAAC;AACxB,OAAO,EAKL,KAAK,UAAU,EAChB,MAAM,sBAAsB,CAAC;AAS9B,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,2BAA2B,CAAC;AAEvE;;;;;;;;;;;GAWG;AAEH,qCAAqC;AACrC,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,6CAA6C;IAC7C,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,oBAAoB;IACpB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,uDAAuD;IACvD,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,kEAAkE;IAClE,QAAQ,CAAC,OAAO,CAAC,EAAE,SAAS,GAAG,QAAQ,GAAG,eAAe,CAAC;CAC3D;AAED,mDAAmD;AACnD,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,QAAQ,EAAE,OAAO,GAAG,SAAS,CAAC;IACvC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,0EAA0E;IAC1E,QAAQ,CAAC,UAAU,EAAE,SAAS,MAAM,EAAE,CAAC;IACvC,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,0BAA0B;AAC1B,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,QAAQ,EAAE,OAAO,GAAG,SAAS,CAAC;IACvC,QAAQ,CAAC,MAAM,EAAE,QAAQ,GAAG,QAAQ,GAAG,SAAS,GAAG,OAAO,CAAC;IAC3D,mCAAmC;IACnC,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,qEAAqE;IACrE,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,iEAAiE;IACjE,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,QAAQ,EAAE,SAAS,oBAAoB,EAAE,CAAC;IACnD,mDAAmD;IACnD,QAAQ,CAAC,MAAM,EAAE,SAAS,kBAAkB,EAAE,CAAC;IAC/C,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB;;;;;OAKG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,UAAU,CAAC;IAChC;;;;;OAKG;IACH,QAAQ,CAAC,aAAa,CAAC,EAAE,gBAAgB,CAAC;IAC1C,0FAA0F;IAC1F,QAAQ,CAAC,cAAc,CAAC,EAAE,gBAAgB,CAAC;IAC3C,sGAAsG;IACtG,QAAQ,CAAC,KAAK,CAAC,EAAE,eAAe,CAAC;IACjC,2FAA2F;IAC3F,QAAQ,CAAC,YAAY,CAAC,EAAE,SAAS,aAAa,EAAE,CAAC;CAClD;AAmDD,wDAAwD;AACxD,wBAAgB,kBAAkB,CAChC,WAAW,EAAE,MAAM,EACnB,QAAQ,EAAE,iBAAiB,EAC3B,UAAU,EAAE,qBAAqB,EACjC,WAAW,GAAE,SAAS,MAAM,EAAO,GAClC,mBAAmB,CA4OrB"}

package/dist/doc-references.js

@@ -1,4 +1,5 @@
-import { dotDirsNamedBy, matchesAny, readMatchingFiles, safeCompile } from '@shrkcrft/boundaries';
+import { failsWhenEmpty, normalizeRuleList, RuleEmptiness, settleRuleEmptiness, unitStateLists, UnitLivenessState, } from '@shrkcrft/core';
+import { dotDirsNamedBy, readGlobListLiveness, readSelectedFiles, safeCompile, } from '@shrkcrft/boundaries';
 import { nearestIds } from "./nearest-id.js";
 import { emptyReferenceKinds, isCacheBackedKind, referenceIdExists, referenceIdPool, } from "./reference-registry.js";
 /** Matches `<!-- marker -->`, with or without a trailing `: reason`. */
@@ -46,13 +47,46 @@ function passesContext(rule, line, index, insideFence) {
     return backtickRanges(line).some((r) => index >= r.start && index < r.end);
 }
 /** Evaluate one doc-reference rule against the tree. */
-export function checkDocReferences(projectRoot, rule, inspection, excludeDirs = []) {
-    const severity = rule.severity ?? 'error';
+export function checkDocReferences(projectRoot, authored, inspection, excludeDirs = []) {
+    const severity = authored.severity ?? 'error';
     const base = {
-        ruleId: rule.id,
-        ...(rule.description ? { description: rule.description } : {}),
+        ruleId: authored.id,
+        ...(authored.description ? { description: authored.description } : {}),
         severity,
     };
+    // The engine entry normalises idempotently (round 13): a loaded rule comes
+    // back as the SAME object; a hand-built `{ pattern, expectEmpty }` entry is a
+    // glob plus a marker; a malformed entry is a misconfigured rule, never a crash.
+    const normalized = normalizeRuleList(authored, 'files');
+    if (!normalized.ok) {
+        return {
+            ...base,
+            status: 'error',
+            filesScanned: 0,
+            tokensChecked: 0,
+            tokensSkipped: 0,
+            findings: [],
+            tokens: [],
+            error: `files ${normalized.error.message}`,
+        };
+    }
+    const rule = normalized.value;
+    // The rule's `files` judged per unit off the walk the check reads (its
+    // dot-dirs included) and settled with its `expectEmpty` markers — what an
+    // empty rule is decided from, and what rides on the result.
+    const live = readGlobListLiveness(projectRoot, 'files', rule.files, rule.expectEmptyUnits ?? [], {
+        subject: rule.id,
+        excludeDirs: new Set(excludeDirs),
+        allowDotDirs: dotDirsNamedBy(rule.files),
+    });
+    const nonLive = live.liveness.units.filter((u) => u.state !== UnitLivenessState.Live);
+    const unitFields = {
+        ...(live.liveness.acceptance !== undefined ? { unitAcceptance: live.liveness.acceptance } : {}),
+        ...(live.liveness.dead.length + live.liveness.intendedEmpty.length + live.liveness.wentLive.length > 0
+            ? { units: unitStateLists(live.liveness) }
+            : {}),
+        ...(nonLive.length > 0 ? { unitLiveness: nonLive } : {}),
+    };
     const compiled = safeCompile(rule.tokenPattern, `${rule.tokenPatternFlags ?? ''}g`);
     if (compiled.error || !compiled.re) {
         return {
@@ -93,10 +127,11 @@ export function checkDocReferences(projectRoot, rule, inspection, excludeDirs =
     // Prose lives in places the code walkers deliberately avoid — an agent skill
     // file sits in `.claude/skills`. The rule's own globs say which dot-dirs it
     // means, and it gets exactly those.
-    const cache = readMatchingFiles(projectRoot, rule.files, new Set(excludeDirs), dotDirsNamedBy(rule.files));
-    const docs = [...cache.entries()]
-        .filter(([path]) => matchesAny(path, rule.files))
-        .sort(([a], [b]) => a.localeCompare(b));
+    // The files the rule's list SELECTS: a `!docs/drafts/**` entry excludes.
+    const matched = readSelectedFiles(projectRoot, rule.files, new Set(excludeDirs), dotDirsNamedBy(rule.files));
+    const docs = [...matched.files.entries()].sort(([a], [b]) => a.localeCompare(b));
+    const unread = matched.unread;
+    const readScope = unread.length > 0 ? { read: docs.length, unread } : undefined;
     const pool = referenceIdPool(inspection, kinds);
     const exempt = new Set(rule.exempt ?? []);
     const marker = rule.exemptMarker;
@@ -158,24 +193,66 @@ export function checkDocReferences(projectRoot, rule, inspection, excludeDirs =
     }
     const tokensChecked = tokens.filter((t) => t.skipped === undefined).length;
     const tokensSkipped = tokens.length - tokensChecked;
+    // Its globs matched a document the reader could not read: its zero is not
+    // "matched nothing". It ran over everything readable and is PARTIAL (its
+    // coverage names the unread document), never failOnEmpty's 1 and never a pass.
+    if (tokensChecked === 0 && readScope !== undefined) {
+        return {
+            ...base,
+            status: 'passed',
+            filesScanned: docs.length,
+            tokensChecked,
+            tokensSkipped,
+            findings: [],
+            tokens,
+            readScope,
+            ...unitFields,
+        };
+    }
     // A rule that CHECKED nothing enforced nothing. Which of "0 docs" or "0
     // tokens" happened matters to whoever has to fix it, so the reason says.
     if (tokensChecked === 0) {
-        const failed = rule.failOnEmpty ?? severity === 'error';
+        // THE rule-emptiness settle (round 13, `settleRuleEmptiness`), with THE
+        // failOnEmpty authority (`failsWhenEmpty`) — never re-derived inline. Every
+        // inclusion glob of `files` marked `expectEmpty` and no document matched →
+        // the intended empty, accepted and printed. Documents that cite no token
+        // are the stale-extractor loud skip — never assertable.
+        const emptiness = settleRuleEmptiness({
+            subject: rule.id,
+            unitLabel: 'references',
+            filesMatched: docs.length,
+            unitsMatched: 0,
+            unread: false,
+            liveness: live.liveness,
+            primaryLists: ['files'],
+            failOnEmpty: failsWhenEmpty(rule),
+            noFilesReason: `0 documents matched (${rule.files.join(', ')})`,
+            noUnitsReason: `${docs.length} document(s) scanned but no token counted as a reference` +
+                (tokensSkipped > 0 ? ` (${tokensSkipped} matched and were skipped — check \`requireContext\`)` : ''),
+        });
+        if (emptiness.state === RuleEmptiness.IntendedEmpty && emptiness.coverage !== undefined) {
+            return {
+                ...base,
+                status: 'passed',
+                filesScanned: docs.length,
+                tokensChecked,
+                tokensSkipped,
+                findings: [],
+                tokens,
+                ...unitFields,
+                emptyCoverage: emptiness.coverage,
+            };
+        }
         return {
             ...base,
-            status: failed ? 'failed' : 'skipped',
+            status: emptiness.fails ? 'failed' : 'skipped',
             filesScanned: docs.length,
             tokensChecked,
             tokensSkipped,
             findings: [],
             tokens,
-            skipReason: docs.length === 0
-                ? `0 documents matched (${rule.files.join(', ')})`
-                : `${docs.length} document(s) scanned but no token counted as a reference` +
-                    (tokensSkipped > 0
-                        ? ` (${tokensSkipped} matched and were skipped — check \`requireContext\`)`
-                        : ''),
+            ...unitFields,
+            ...(emptiness.skipReason !== undefined ? { skipReason: emptiness.skipReason } : {}),
         };
     }
     return {
@@ -186,5 +263,7 @@ export function checkDocReferences(projectRoot, rule, inspection, excludeDirs =
         tokensSkipped,
         findings,
         tokens,
+        ...(readScope !== undefined ? { readScope } : {}),
+        ...unitFields,
     };
 }

package/dist/doctor-result.d.ts

@@ -1,3 +1,4 @@
+import type { IVerdictCoverage } from '@shrkcrft/core';
 export declare enum DoctorSeverity {
     Ok = "ok",
     Info = "info",
@@ -47,5 +48,12 @@ export interface IDoctorResult {
          */
         advisoryCount?: number;
     };
+    /**
+     * Scope the doctor could not verify: today, compiled pack builds with no
+     * build record (never compared with their source). `shrk doctor` settles
+     * its exit through it (NOT VERIFIED, 2, as `packs doctor` does) and never
+     * prints "Ready ✓" over it. Set only when non-empty.
+     */
+    coverage?: readonly IVerdictCoverage[];
 }
 //# sourceMappingURL=doctor-result.d.ts.map

package/dist/doctor-result.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"doctor-result.d.ts","sourceRoot":"","sources":["../src/doctor-result.ts"],"names":[],"mappings":"AAAA,oBAAY,cAAc;IACxB,EAAE,OAAO;IACT,IAAI,SAAS;IACb,OAAO,YAAY;IACnB,KAAK,UAAU;CAChB;AAED,MAAM,WAAW,YAAY;IAC3B,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,cAAc,CAAC;IACzB,OAAO,EAAE,MAAM,CAAC;IAChB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb;;;;;;;;;;;;;;OAcG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AAED,MAAM,WAAW,aAAa;IAC5B,MAAM,EAAE,OAAO,CAAC;IAChB,MAAM,EAAE,SAAS,YAAY,EAAE,CAAC;IAChC,OAAO,EAAE;QACP,EAAE,EAAE,MAAM,CAAC;QACX,IAAI,EAAE,MAAM,CAAC;QACb,QAAQ,EAAE,MAAM,CAAC;QACjB,MAAM,EAAE,MAAM,CAAC;QACf;;;;;WAKG;QACH,aAAa,CAAC,EAAE,MAAM,CAAC;KACxB,CAAC;CACH"}
+{"version":3,"file":"doctor-result.d.ts","sourceRoot":"","sources":["../src/doctor-result.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AAEvD,oBAAY,cAAc;IACxB,EAAE,OAAO;IACT,IAAI,SAAS;IACb,OAAO,YAAY;IACnB,KAAK,UAAU;CAChB;AAED,MAAM,WAAW,YAAY;IAC3B,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,cAAc,CAAC;IACzB,OAAO,EAAE,MAAM,CAAC;IAChB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb;;;;;;;;;;;;;;OAcG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AAED,MAAM,WAAW,aAAa;IAC5B,MAAM,EAAE,OAAO,CAAC;IAChB,MAAM,EAAE,SAAS,YAAY,EAAE,CAAC;IAChC,OAAO,EAAE;QACP,EAAE,EAAE,MAAM,CAAC;QACX,IAAI,EAAE,MAAM,CAAC;QACb,QAAQ,EAAE,MAAM,CAAC;QACjB,MAAM,EAAE,MAAM,CAAC;QACf;;;;;WAKG;QACH,aAAa,CAAC,EAAE,MAAM,CAAC;KACxB,CAAC;IACF;;;;;OAKG;IACH,QAAQ,CAAC,EAAE,SAAS,gBAAgB,EAAE,CAAC;CACxC"}

package/dist/doctor-verdict-kind.d.ts

@@ -0,0 +1,19 @@
+/**
+ * How one doctor run settles — THE reading of an `IDoctorResult` that every
+ * surface shares (`shrk doctor`, `shrk check`, the dashboard, MCP
+ * `inspect_sharkcraft_setup`), so none of them can call a setup ready that
+ * another calls not verified.
+ */
+export declare enum DoctorVerdictKind {
+    /** No error check, and every scope the doctor was asked to verify was verified. */
+    Ready = "ready",
+    /**
+     * No error check, but part of the setup could not be verified (today: a
+     * compiled pack build with no build record, never compared with its
+     * source). Never "ready".
+     */
+    NotVerified = "not-verified",
+    /** At least one error-severity check. */
+    Errors = "errors"
+}
+//# sourceMappingURL=doctor-verdict-kind.d.ts.map

package/dist/doctor-verdict-kind.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"doctor-verdict-kind.d.ts","sourceRoot":"","sources":["../src/doctor-verdict-kind.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,oBAAY,iBAAiB;IAC3B,mFAAmF;IACnF,KAAK,UAAU;IACf;;;;OAIG;IACH,WAAW,iBAAiB;IAC5B,yCAAyC;IACzC,MAAM,WAAW;CAClB"}