@shrkcrft/cli 0.1.0-alpha.29 → 0.1.0-alpha.30

package/dist/commands/baseline.command.d.ts

@@ -1,4 +1,29 @@
+import type { IBaselineRule } from '@shrkcrft/core';
+import { type IBaselineDiff } from '@shrkcrft/boundaries';
 import { type ICommandHandler } from '../command-registry.js';
+/**
+ * One rule's outcome, shared by check / diff / update — and by `shrk gates
+ * check`, which aggregates every plane. Exported so the aggregate runs the
+ * IDENTICAL evaluation as the per-plane verb: two implementations of "did this
+ * baseline drift?" would eventually disagree, and the one nobody runs would be
+ * the one that is wrong.
+ */
+export interface IBaselineOutcome {
+    readonly rule: IBaselineRule;
+    readonly status: 'passed' | 'failed' | 'skipped' | 'error';
+    readonly diff?: IBaselineDiff;
+    readonly committed?: string;
+    readonly current?: string;
+    readonly committedCount: number;
+    readonly currentCount: number;
+    readonly error?: string;
+    readonly skipReason?: string;
+    /** The recompute produced 0 entries while the baseline has some — likely a broken compute. */
+    readonly emptyCompute?: boolean;
+    /** No committed artifact exists yet — `committed` is absent, not zero. */
+    readonly missingBaseline?: boolean;
+}
+export declare function evaluateBaselineRule(cwd: string, rule: IBaselineRule, excludeDirs: readonly string[], changedFiles: readonly string[] | undefined): IBaselineOutcome;
 export declare const baselineListCommand: ICommandHandler;
 export declare const baselineCheckCommand: ICommandHandler;
 export declare const baselineDiffCommand: ICommandHandler;

package/dist/commands/baseline.command.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"baseline.command.d.ts","sourceRoot":"","sources":["../../src/commands/baseline.command.ts"],"names":[],"mappings":"AA8BA,OAAO,EAIL,KAAK,eAAe,EAErB,MAAM,wBAAwB,CAAC;AA6ShC,eAAO,MAAM,mBAAmB,EAAE,eAyCjC,CAAC;AAEF,eAAO,MAAM,oBAAoB,EAAE,eAyGlC,CAAC;AAEF,eAAO,MAAM,mBAAmB,EAAE,eA8BjC,CAAC;AAEF,eAAO,MAAM,qBAAqB,EAAE,eAwDnC,CAAC;AAEF,eAAO,MAAM,sBAAsB,EAAE,eA2DpC,CAAC;AAEF,eAAO,MAAM,eAAe,EAAE,eAc7B,CAAC"}
+{"version":3,"file":"baseline.command.d.ts","sourceRoot":"","sources":["../../src/commands/baseline.command.ts"],"names":[],"mappings":"AAmBA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAGpD,OAAO,EAML,KAAK,aAAa,EACnB,MAAM,sBAAsB,CAAC;AAE9B,OAAO,EAIL,KAAK,eAAe,EAErB,MAAM,wBAAwB,CAAC;AAuFhC;;;;;;GAMG;AACH,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,IAAI,EAAE,aAAa,CAAC;IAC7B,QAAQ,CAAC,MAAM,EAAE,QAAQ,GAAG,QAAQ,GAAG,SAAS,GAAG,OAAO,CAAC;IAC3D,QAAQ,CAAC,IAAI,CAAC,EAAE,aAAa,CAAC;IAC9B,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,8FAA8F;IAC9F,QAAQ,CAAC,YAAY,CAAC,EAAE,OAAO,CAAC;IAChC,0EAA0E;IAC1E,QAAQ,CAAC,eAAe,CAAC,EAAE,OAAO,CAAC;CACpC;AAED,wBAAgB,oBAAoB,CAClC,GAAG,EAAE,MAAM,EACX,IAAI,EAAE,aAAa,EACnB,WAAW,EAAE,SAAS,MAAM,EAAE,EAC9B,YAAY,EAAE,SAAS,MAAM,EAAE,GAAG,SAAS,GAC1C,gBAAgB,CAiHlB;AA4FD,eAAO,MAAM,mBAAmB,EAAE,eAyCjC,CAAC;AAEF,eAAO,MAAM,oBAAoB,EAAE,eAyGlC,CAAC;AAEF,eAAO,MAAM,mBAAmB,EAAE,eA8BjC,CAAC;AAEF,eAAO,MAAM,qBAAqB,EAAE,eAwDnC,CAAC;AAEF,eAAO,MAAM,sBAAsB,EAAE,eAiEpC,CAAC;AAEF,eAAO,MAAM,eAAe,EAAE,eAc7B,CAAC"}

package/dist/commands/baseline.command.js

@@ -17,7 +17,7 @@
 import { spawnSync } from 'node:child_process';
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
 import * as nodePath from 'node:path';
-import { failsWhenEmpty } from '@shrkcrft/core';
+import { resolveSourceGlobs, failsWhenEmpty } from '@shrkcrft/core';
 import { baselineCount, baselineFails, computeBaselineFromExtractor, diffBaseline, matchesAny, } from '@shrkcrft/boundaries';
 import { resolveChangedFiles, resolveProjectConfig } from '@shrkcrft/inspector';
 import { flagBool, flagString, resolveCwd, } from "../command-registry.js";
@@ -87,7 +87,7 @@ function computeCurrent(cwd, rule, excludeDirs) {
     }
     return { text: String(child.stdout ?? '') };
 }
-function evaluateRule(cwd, rule, excludeDirs, changedFiles) {
+export function evaluateBaselineRule(cwd, rule, excludeDirs, changedFiles) {
     // --changed-only is honest about what it CANNOT scope: a command compute with
     // no `watchFiles` has no file footprint, so it is reported as skipped rather
     // than quietly passing.
@@ -95,7 +95,7 @@ function evaluateRule(cwd, rule, excludeDirs, changedFiles) {
         const globs = rule.watchFiles && rule.watchFiles.length > 0
             ? rule.watchFiles
             : rule.compute.kind === 'extractor'
-                ? (rule.compute.source?.files ?? [])
+                ? (resolveSourceGlobs(rule.compute.source ?? { files: [] }))
                 : undefined;
         if (globs === undefined) {
             return {
@@ -158,6 +158,19 @@ function evaluateRule(cwd, rule, excludeDirs, changedFiles) {
     // the baseline has entries and the recompute has none, that is real drift
     // (everything vanished) and must be reported as such, not swallowed as a skip.
     if (currentCount === 0 && committedCount === 0) {
+        // A fence ASSERTS emptiness, so for it the empty case is the verified pass
+        // rather than "nothing was checked" — otherwise the rule could never be
+        // green and could not gate anything.
+        if (rule.expectEmpty === true) {
+            return {
+                rule,
+                status: 'passed',
+                committed,
+                current: computed.text,
+                committedCount,
+                currentCount,
+            };
+        }
         return {
             rule,
             status: failsWhenEmpty(rule) ? 'failed' : 'skipped',
@@ -320,7 +333,7 @@ export const baselineCheckCommand = {
         const json = flagBool(args, 'json');
         if (prep.rules.length === 0)
             return writeNoRules(json);
-        const outcomes = prep.rules.map((r) => evaluateRule(prep.cwd, r, prep.excludeDirs, prep.changedFiles));
+        const outcomes = prep.rules.map((r) => evaluateBaselineRule(prep.cwd, r, prep.excludeDirs, prep.changedFiles));
         const failed = outcomes.filter((o) => o.status === 'failed' || (o.status === 'error' && (o.rule.severity ?? 'error') === 'error'));
         const evaluated = outcomes.filter((o) => o.status !== 'skipped').length;
         // 0 only when a NON-EMPTY scope was actually compared; 2 when nothing was.
@@ -407,7 +420,7 @@ export const baselineDiffCommand = {
         const json = flagBool(args, 'json');
         if (prep.rules.length === 0)
             return writeNoRules(json);
-        const outcomes = prep.rules.map((r) => evaluateRule(prep.cwd, r, prep.excludeDirs, undefined));
+        const outcomes = prep.rules.map((r) => evaluateBaselineRule(prep.cwd, r, prep.excludeDirs, undefined));
         if (json) {
             process.stdout.write(asJson({ schema: SCHEMA, results: outcomes.map(outcomeJson), inspection: true }) + '\n');
             return ExitCode.VerifiedPass;
@@ -494,7 +507,7 @@ export const baselineExplainCommand = {
             process.stderr.write(`No baseline "${id}". Declared: ${prep.all.map((r) => r.id).join(', ') || '(none)'}\n`);
             return ExitCode.UsageError;
         }
-        const outcome = evaluateRule(prep.cwd, rule, prep.excludeDirs, undefined);
+        const outcome = evaluateBaselineRule(prep.cwd, rule, prep.excludeDirs, undefined);
         if (flagBool(args, 'json')) {
             process.stdout.write(asJson({
                 schema: 'sharkcraft.baseline-explain/v1',
@@ -508,7 +521,10 @@ export const baselineExplainCommand = {
         if (rule.description)
             process.stdout.write(`  ${rule.description}\n`);
         process.stdout.write(kv('committed', rule.baseline) + '\n');
-        process.stdout.write(kv('compute', rule.compute.kind === 'command' ? `command · ${rule.compute.run}` : `extractor · ${rule.compute.source?.extract ?? 'sugar'}`) + '\n');
+        process.stdout.write(kv('compute', rule.compute.kind === 'command'
+            ? `command · ${rule.compute.run}`
+            : `extractor · ${rule.compute.source?.extract ?? 'sugar'}` +
+                (rule.compute.source?.$use ? `  (via $use:${rule.compute.source.$use})` : '')) + '\n');
         process.stdout.write(kv('direction', rule.direction ?? 'two-way') + '\n');
         process.stdout.write(kv('canonical', outcome.diff?.canonical ?? rule.compute.canonical ?? 'auto') + '\n');
         if (rule.keyBy)

package/dist/commands/changelog-data.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"changelog-data.d.ts","sourceRoot":"","sources":["../../src/commands/changelog-data.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,2CAA2C;AAC3C,MAAM,WAAW,oBAAoB;IACnC,oDAAoD;IACpD,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,yCAAyC;IACzC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,iDAAiD;IACjD,QAAQ,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,CAAC;IAClC,wDAAwD;IACxD,QAAQ,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,CAAC;IACpC,6CAA6C;IAC7C,QAAQ,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,CAAC;CACrC;AAED,eAAO,MAAM,sBAAsB,EAAE,SAAS,oBAAoB,EAkJjE,CAAC"}
+{"version":3,"file":"changelog-data.d.ts","sourceRoot":"","sources":["../../src/commands/changelog-data.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,2CAA2C;AAC3C,MAAM,WAAW,oBAAoB;IACnC,oDAAoD;IACpD,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,yCAAyC;IACzC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,iDAAiD;IACjD,QAAQ,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,CAAC;IAClC,wDAAwD;IACxD,QAAQ,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,CAAC;IACpC,6CAA6C;IAC7C,QAAQ,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,CAAC;CACrC;AAED,eAAO,MAAM,sBAAsB,EAAE,SAAS,oBAAoB,EA4KjE,CAAC"}

package/dist/commands/changelog-data.js

@@ -134,6 +134,32 @@ export const RELEASE_SURFACE_DELTAS = [
         ],
         removed: [],
     },
+    {
+        version: '0.1.0-alpha.30',
+        title: 'The engine taps the import graph, and reads its own prose',
+        added: [
+            '`shrk docs references check|explain|list` — the seventh rule plane (`docReferences[]`): ids cited in free-text PROSE (READMEs, docs, agent skill files) that no longer resolve. Markdown has no build, so these drift with zero signal. `requireContext` (default `backtick`), `exempt[]`, a per-line `<!-- ref-allow: why -->` marker, and a length-scaled `did you mean` keep it low-noise. Reads dot-directories a glob explicitly names, so `.claude/skills/**` works.',
+            '`shrk gates check` — every rule plane in ONE pass with one exit code (the CI / pre-commit primitive); `--changed-only` scopes by rule footprint, `--strict` promotes warning-severity findings to failures.',
+            '`shrk gates try --rule-file <f> [--full]` — dry-run a candidate rule against the tree without adding it to config. Dumps every captured token, so an over-matching `tokenPattern` is visible in one run instead of arriving as noise in CI.',
+            '`import-edges` extractor — the resolved dependency graph as a rule input (`emit: edge|symbol|from`, targetable by `to.module` / `to.modulePattern` / `to.files` / `to.match`). Existing planes now express adoption ledgers, orphan detection, deprecation ratchets and targeted fences. Alias-aware; no persisted index, so no staleness.',
+            '`filenames` extractor + `mode: parity` — companion-file invariants (every `X.ts` has an `X.test.ts`).',
+            'Shared extractors: a top-level `extractors` map plus `{ $use: "<id>" }` on any plane (local fields override). The planes describing one id set can no longer drift apart, and a typo\'d id fails the config load rather than silently matching nothing.',
+            '`generatedArtifacts[]` for MIXED trees: `sources[]` (N writers, each verifying its own sub-glob), `handMaintained[]` (literal filenames only, so the exemption cannot silently widen) and `handMaintainedMarker` for an in-file bless. A file under the tree owned by neither is an `unclassified` finding.',
+            '`expectEmpty: true` on `baselines[]` — a fence that fails the moment the edge set becomes non-empty.',
+            '`shrk check wiring --fix` now adds the missing IMPORT alongside the array member when the specifier is a pure function of the member name AND resolves to the declaring file; otherwise it refuses with `needs-import`.',
+        ],
+        changed: [
+            'FIXED (P1): `--fix --write` could green the wiring gate over a file that no longer compiles. The common registry shape IMPORTS its array members, and appending the token alone left `TS2304: Cannot find name`. It now writes both edits or refuses.',
+            'FIXED (P1): reference resolution ran in THREE modules — the prose linter and both self-config doctors — each from its own sources, agreeing only by coincidence. The self-config doctor reported 17 of shrk\'s own correctly-registered ids as unknown (its hand-written "known ids" union omitted policies, decisions, scaffold patterns and paths). One resolver now answers for every kind, and each kind reads the source its `list` verb reads.',
+            'FIXED (P2): `shrk graph status` judged index freshness by working-tree DIVERGENCE while `shrk code-intel` judged it by wall-clock age — contradictory verdicts on the same index in the same second, with every arch/cycle count derived from it inheriting the staleness unmarked. Divergence is now the single verdict; age is a display detail (`current (indexed 5d ago)` / `STALE — N file(s) changed since index`).',
+            'A finding DERIVED from a stale graph index is reported `NOT VERIFIED` rather than as a count — the loud-skip contract the rule planes already honour, extended to the graph-derived surfaces. An unmeasured verdict is never a pass.',
+            'An ERRORED rule is no longer counted as `evaluated` by `gates check` / `docs references check`, so a warning-severity rule that could not run exits `2` instead of printing "not blocking" above exit `0`.',
+            'A doc-reference rule whose registries are ALL empty refuses loudly instead of reporting every id as unresolved — a gate that confidently flags correct usage is worse than no gate.',
+            '`detectGraphFreshness` no longer throws on a store whose `meta.json` exists but whose remaining parts do not (an interrupted index); it reports "could not measure", which reads as not-verified.',
+            '`shrk graph status` labels its snapshot size `files indexed` — it deliberately does not move when a new file appears on disk; that shows up on the `drift` line.',
+        ],
+        removed: [],
+    },
     {
         version: '0.1.0-alpha.29',
         title: 'The exit code has to agree with the sentence',

package/dist/commands/check.command.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"check.command.d.ts","sourceRoot":"","sources":["../../src/commands/check.command.ts"],"names":[],"mappings":"AAoBA,OAAO,EAML,KAAK,eAAe,EAErB,MAAM,wBAAwB,CAAC;AA2iChC,eAAO,MAAM,YAAY,EAAE,eA+G1B,CAAC"}
+{"version":3,"file":"check.command.d.ts","sourceRoot":"","sources":["../../src/commands/check.command.ts"],"names":[],"mappings":"AAoBA,OAAO,EAML,KAAK,eAAe,EAErB,MAAM,wBAAwB,CAAC;AA2jChC,eAAO,MAAM,YAAY,EAAE,eA+G1B,CAAC"}

package/dist/commands/check.command.js

@@ -524,7 +524,8 @@ async function checkBoundariesOnce(args) {
 // ────────────────────────────────────────────────────────────────────────
 // Subcommand: wiring — "declared but not wired" completeness checks
 // ────────────────────────────────────────────────────────────────────────
-const WIRING_CHECK_USAGE = 'shrk check wiring [--changed-only] [--since <ref>] [--base <ref>] [--only <ids>] [--explain <ruleId>] [--json] [--strict]\n' +
+const WIRING_CHECK_USAGE = 'shrk check wiring [--changed-only] [--since <ref>] [--base <ref>] [--only <ids>] [--explain <ruleId>]\n' +
+    '                  [--fix [--write]] [--json] [--strict]\n' +
     '  Cross-file "declared but not wired" completeness gate. Scope flags select rules by\n' +
     '  FOOTPRINT — a rule fires when the diff touches EITHER its declared or its registered\n' +
     '  side (so a registration edited in file B fires a rule declared in file A).\n' +
@@ -532,6 +533,10 @@ const WIRING_CHECK_USAGE = 'shrk check wiring [--changed-only] [--since <ref>] [
     '    --since <ref>    scope the diff to changes since <ref> (--base is a synonym)\n' +
     '    --only <ids>     run only these rule ids (comma-separated)\n' +
     '    --explain <id>   dry-run ONE rule and print the declared/registered sets it extracts\n' +
+    '    --fix            plan the deterministic repair (append the token to its sink array);\n' +
+    '                     dry-run by default, prints every edit AND any import it must add.\n' +
+    '                     Refuses anything ambiguous — see `needs-import` in docs/wiring.md.\n' +
+    '    --write          apply the planned edits (only meaningful with --fix)\n' +
     '  Exit: 0 verified pass · 1 violations · 2 not-verified (0 rules evaluated in scope).';
 /**
  * The honest exit code for a wiring run.
@@ -606,7 +611,14 @@ function runWiringFix(cwd, rules, report, write, wantJson) {
     }
     for (const e of allEdits) {
         process.stdout.write(`  ${write ? 'wrote  ' : 'would add'} ${e.token} → ${e.file}:${e.line}\n`);
-        process.stdout.write(`      + ${e.insert}\n`);
+        // Show BOTH halves of the edit. An array append whose import is invisible
+        // in the preview is exactly how the reviewer approves a change they have
+        // not actually seen — and the import is the half that decides whether the
+        // result compiles.
+        if (e.importInsert !== undefined) {
+            process.stdout.write(`      + ${e.importInsert}${e.importLine !== undefined ? `   (line ${e.importLine})` : ''}\n`);
+        }
+        process.stdout.write(`      + ${e.insert}${e.importInsert !== undefined ? `   (line ${e.line})` : ''}\n`);
     }
     if (allSkips.length > 0) {
         process.stdout.write(`\n  Left untouched (${allSkips.length}) — not mechanically unambiguous:\n`);
@@ -815,6 +827,11 @@ async function checkWiring(args) {
             continue;
         process.stdout.write(`\n  ! ${r.ruleId}: the registered side extracted 0 ids while ${r.declaredCount} were declared —\n` +
             `    every declared token "fails". Check the registered glob before chasing the tokens.\n`);
+        // When the engine knows WHY the sink came back empty, say it here — the
+        // generic advice above would otherwise send the reader to inspect a glob
+        // that is perfectly fine.
+        if (r.sinkHint)
+            process.stdout.write(`    → ${r.sinkHint}\n`);
     }
     if (report.violations.length === 0 && report.diagnostics.length === 0) {
         // A failOnEmpty skip produces no violation object but IS a failure.

package/dist/commands/code-intel.command.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"code-intel.command.d.ts","sourceRoot":"","sources":["../../src/commands/code-intel.command.ts"],"names":[],"mappings":"AAKA,OAAO,EAIL,KAAK,eAAe,EAErB,MAAM,wBAAwB,CAAC;AAGhC;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,gBAAgB,EAAE,eAuE9B,CAAC"}
+{"version":3,"file":"code-intel.command.d.ts","sourceRoot":"","sources":["../../src/commands/code-intel.command.ts"],"names":[],"mappings":"AAKA,OAAO,EAIL,KAAK,eAAe,EAErB,MAAM,wBAAwB,CAAC;AAIhC;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,gBAAgB,EAAE,eA6E9B,CAAC"}

package/dist/commands/code-intel.command.js

@@ -1,5 +1,6 @@
 import { buildCodeIntelligenceChecks, DoctorSeverity, } from '@shrkcrft/inspector';
 import { flagBool, flagString, resolveCwd, } from "../command-registry.js";
+import { detectGraphFreshness } from '@shrkcrft/graph';
 import { asJson, header, kv } from "../output/format-output.js";
 /**
  * `shrk code-intel` — one-shot view of the 14 code-intelligence
@@ -28,7 +29,10 @@ export const codeIntelCommand = {
         const checkId = flagString(args, 'check');
         const staleDaysRaw = flagString(args, 'stale-days');
         const staleDays = staleDaysRaw ? Number.parseInt(staleDaysRaw, 10) : undefined;
-        const options = {};
+        // Divergence against the working tree — the SAME check `shrk graph status`
+        // reports, so the two surfaces cannot contradict each other. Injected
+        // because `@shrkcrft/graph` sits above inspector in the layer order.
+        const options = { graphDivergence: detectGraphFreshness(cwd) };
         if (typeof staleDays === 'number' && Number.isFinite(staleDays) && staleDays > 0) {
             options.staleThresholdDays = staleDays;
         }

package/dist/commands/docs-references.command.d.ts

@@ -0,0 +1,7 @@
+import { type ICommandHandler } from '../command-registry.js';
+export declare const docsReferencesCheckCommand: ICommandHandler;
+export declare const docsReferencesExplainCommand: ICommandHandler;
+export declare const docsReferencesListCommand: ICommandHandler;
+/** `shrk docs references <verb>` — dispatches to check / explain / list. */
+export declare const docsReferencesCommand: ICommandHandler;
+//# sourceMappingURL=docs-references.command.d.ts.map

package/dist/commands/docs-references.command.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"docs-references.command.d.ts","sourceRoot":"","sources":["../../src/commands/docs-references.command.ts"],"names":[],"mappings":"AAyBA,OAAO,EAIL,KAAK,eAAe,EAErB,MAAM,wBAAwB,CAAC;AAsGhC,eAAO,MAAM,0BAA0B,EAAE,eAuIxC,CAAC;AAEF,eAAO,MAAM,4BAA4B,EAAE,eA4D1C,CAAC;AAEF,eAAO,MAAM,yBAAyB,EAAE,eAyBvC,CAAC;AAEF,4EAA4E;AAC5E,eAAO,MAAM,qBAAqB,EAAE,eAkBnC,CAAC"}

package/dist/commands/docs-references.command.js

@@ -0,0 +1,323 @@
+/**
+ * `shrk docs references {check,explain,list}` — the prose-reference linter.
+ *
+ *   shrk docs references check [--id X] [--json]     # unresolved id → finding
+ *   shrk docs references explain --id X              # every token + where it resolved
+ *   shrk docs references list                        # the declared rules
+ *
+ * shrk validates the STRUCTURED `references[]` on knowledge entries. The same
+ * ids written as prose — a README, an architecture doc, an agent skill file
+ * saying `shrk gen nge.foo` — had no gate at all, and markdown has no build
+ * behind it. This points the existing reference resolver at that surface.
+ *
+ * Read-only: it scans documents and consults registries. Nothing is written and
+ * nothing is spawned.
+ */
+import * as nodePath from 'node:path';
+import { checkDocReferences, inspectSharkcraft, warmReferenceRegistries, resolveProjectConfig, } from '@shrkcrft/inspector';
+import { flagBool, flagString, resolveCwd, } from "../command-registry.js";
+import { ExitCode } from "../exit-codes.js";
+import { asJson, header, kv } from "../output/format-output.js";
+import { buildGateEnvelope } from "../gates/gate-envelope.js";
+const SCHEMA = 'sharkcraft.doc-references/v1';
+async function prepare(args) {
+    const cwd = resolveCwd(args);
+    const json = flagBool(args, 'json');
+    const loaded = await resolveProjectConfig(cwd);
+    if (!loaded.ok) {
+        const msg = loaded.error.message;
+        if (json)
+            process.stdout.write(asJson({ schema: SCHEMA, error: msg }) + '\n');
+        else
+            process.stderr.write(`Could not load config: ${msg}\n  Run \`shrk doctor\` for details.\n`);
+        return { ok: false, code: ExitCode.UsageError };
+    }
+    const all = loaded.value.config.docReferences ?? [];
+    const rel = nodePath.relative(cwd, loaded.value.sharkcraftDir).split(nodePath.sep).join('/');
+    let rules = all;
+    const id = flagString(args, 'id');
+    if (id) {
+        const wanted = id.split(',').map((s) => s.trim()).filter(Boolean);
+        const known = new Set(all.map((r) => r.id));
+        const unknown = wanted.filter((w) => !known.has(w));
+        if (unknown.length > 0) {
+            process.stderr.write(`Unknown doc-reference rule id(s): ${unknown.join(', ')}. Declared: ${[...known].join(', ') || '(none)'}\n`);
+            return { ok: false, code: ExitCode.UsageError };
+        }
+        rules = all.filter((r) => wanted.includes(r.id));
+    }
+    return {
+        ok: true,
+        value: {
+            cwd,
+            rules,
+            all,
+            excludeDirs: rel && !rel.startsWith('..') ? [rel] : [],
+            planeDiagnostics: loaded.value.planeDiagnostics,
+        },
+    };
+}
+/**
+ * Build the inspection the resolver needs.
+ *
+ * Deliberately lazy — it is only paid for when a `docReferences` rule exists,
+ * so a repo without the plane never loads the registries just to be told it has
+ * no rules.
+ */
+async function inspectionFor(cwd) {
+    // Playbook / construct ids come from a cache an ASYNC load populates; the
+    // resolver is sync. Warming here is what makes a correct pack playbook cited
+    // in prose actually resolve.
+    const inspection = await inspectSharkcraft({ cwd });
+    await warmReferenceRegistries(inspection);
+    return inspection;
+}
+function writeNoRules(json) {
+    if (json) {
+        process.stdout.write(asJson({ schema: SCHEMA, results: [], evaluated: 0, verdict: 'not-verified' }) + '\n');
+        return ExitCode.NotVerified;
+    }
+    process.stdout.write(header('Doc references'));
+    process.stdout.write('  No doc-reference rules declared. Add `docReferences[]` to sharkcraft.config.ts to\n' +
+        '  catch ids cited in prose (READMEs, docs, agent skill files) that no longer resolve\n' +
+        '  (see docs/doc-references.md).\n');
+    return ExitCode.NotVerified;
+}
+function resultJson(r) {
+    return {
+        id: r.ruleId,
+        ...(r.description ? { description: r.description } : {}),
+        status: r.status,
+        severity: r.severity,
+        filesScanned: r.filesScanned,
+        tokensChecked: r.tokensChecked,
+        tokensSkipped: r.tokensSkipped,
+        findings: r.findings,
+        ...(r.skipReason ? { skipReason: r.skipReason } : {}),
+        ...(r.error ? { error: r.error } : {}),
+    };
+}
+export const docsReferencesCheckCommand = {
+    name: 'check',
+    description: 'Scan configured docs for id-shaped tokens and assert each resolves to a registered id. Catches a README or skill file citing a template that no longer exists.',
+    usage: 'shrk docs references check [--id <ids>] [--json]',
+    booleanFlags: new Set(['json']),
+    async run(args) {
+        const prep = await prepare(args);
+        if (!prep.ok)
+            return prep.code;
+        const json = flagBool(args, 'json');
+        if (prep.value.rules.length === 0)
+            return writeNoRules(json);
+        const inspection = await inspectionFor(prep.value.cwd);
+        const results = prep.value.rules.map((r) => checkDocReferences(prep.value.cwd, r, inspection, prep.value.excludeDirs));
+        // A rule that ERRORED proved nothing — it never got as far as checking an
+        // id. So it is not `evaluated`, whatever its severity: a warning-severity
+        // rule that could not run must not leave the banner saying "not blocking"
+        // over an exit code of 0, which is the same half-truth as a green banner
+        // above a list of findings.
+        const errored = results.filter((r) => r.status === 'error');
+        const failed = results.filter((r) => r.status === 'failed');
+        const blocking = [...failed, ...errored].filter((r) => r.severity === 'error');
+        const evaluated = results.filter((r) => r.status !== 'skipped' && r.status !== 'error').length;
+        const skipped = results.length - evaluated;
+        const exit = blocking.length > 0
+            ? ExitCode.Failure
+            : evaluated === 0 || skipped > 0
+                ? ExitCode.NotVerified
+                : ExitCode.VerifiedPass;
+        if (json) {
+            process.stdout.write(asJson({
+                schema: SCHEMA,
+                results: results.map(resultJson),
+                evaluated,
+                skipped,
+                verdict: blocking.length > 0 ? 'errors' : evaluated === 0 ? 'not-verified' : 'pass',
+                diagnostics: prep.value.planeDiagnostics,
+                exitCode: exit,
+                gate: buildGateEnvelope('docs references check', exit, results.map((r) => ({
+                    id: r.ruleId,
+                    type: 'doc-reference',
+                    status: r.status,
+                    severity: r.severity,
+                    counts: { files: r.filesScanned, tokens: r.tokensChecked, skipped: r.tokensSkipped },
+                    violations: r.findings.map((f) => ({
+                        id: f.token,
+                        file: f.file,
+                        line: f.line,
+                        message: f.message,
+                        ...(f.didYouMean.length > 0 ? { hint: `did you mean: ${f.didYouMean.join(', ')}` } : {}),
+                    })),
+                    ...(r.skipReason ? { skipReason: r.skipReason } : {}),
+                    ...(r.error ? { error: r.error } : {}),
+                }))),
+            }) + '\n');
+            return exit;
+        }
+        process.stdout.write(header('Doc references'));
+        process.stdout.write(kv('evaluated', `${evaluated} of ${prep.value.rules.length}`) + '\n');
+        for (const r of results) {
+            if (r.status === 'skipped') {
+                process.stdout.write(`  – ${r.ruleId}  SKIPPED — ${r.skipReason}\n`);
+                continue;
+            }
+            if (r.status === 'error') {
+                process.stdout.write(`  ! ${r.ruleId}  ${r.error}\n`);
+                continue;
+            }
+            if (r.status === 'passed') {
+                process.stdout.write(`  ✓ ${r.ruleId}  (${r.tokensChecked} reference(s) across ${r.filesScanned} doc(s) all resolve)\n`);
+                continue;
+            }
+            // A rule that CHECKED nothing failed for a different reason than one with
+            // findings, and the loud-skip contract is worthless if it does not say
+            // which. `0 unresolved of 0 checked` would send the reader hunting for a
+            // bad id when the real problem is a moved directory.
+            if (r.skipReason) {
+                process.stdout.write(`  ✗ ${r.ruleId}  FAILED — ${r.skipReason}\n`);
+                process.stdout.write('      Nothing was checked, so nothing was enforced. Fix the glob, or set\n' +
+                    '      `failOnEmpty: false` if this rule may legitimately cover no docs.\n');
+                continue;
+            }
+            process.stdout.write(`  ✗ ${r.ruleId}  ${r.findings.length} unresolved reference(s) of ${r.tokensChecked} checked\n`);
+            for (const f of r.findings.slice(0, 25)) {
+                process.stdout.write(`      • ${f.token}  (${f.file}:${f.line})\n`);
+                if (f.didYouMean.length > 0) {
+                    process.stdout.write(`          did you mean: ${f.didYouMean.join(', ')}\n`);
+                }
+            }
+            if (r.findings.length > 25) {
+                process.stdout.write(`      … (${r.findings.length - 25} more)\n`);
+            }
+            const hint = r.findings.find((f) => f.hint)?.hint;
+            if (hint)
+                process.stdout.write(`      → ${hint}\n`);
+        }
+        for (const d of prep.value.planeDiagnostics)
+            process.stdout.write(`  ! ${d}\n`);
+        // A warning-severity rule reports without blocking, but the banner must
+        // still say it FIRED. "Every id resolves ✓" printed under a list of
+        // unresolved ids is the kind of half-truth that trains people to stop
+        // reading the output.
+        const warned = failed.filter((r) => r.severity !== 'error');
+        if (exit === ExitCode.VerifiedPass && warned.length > 0) {
+            const count = warned.reduce((n, r) => n + r.findings.length, 0);
+            process.stdout.write(`\n${count} unresolved reference(s) reported by ${warned.length} warning rule(s) — not blocking.\n`);
+        }
+        else if (exit === ExitCode.VerifiedPass) {
+            process.stdout.write('\nEvery id cited in prose resolves. ✓\n');
+        }
+        else if (exit === ExitCode.NotVerified) {
+            process.stdout.write(errored.length > 0
+                ? `\n${errored.length} rule(s) could not run — nothing was proved. This is NOT a pass.\n`
+                : '\nNothing was checked — this is NOT a pass.\n');
+        }
+        return exit;
+    },
+};
+export const docsReferencesExplainCommand = {
+    name: 'explain',
+    description: 'Show every id-shaped token ONE rule considered: where it was found, whether it resolved, and why a token was skipped.',
+    usage: 'shrk docs references explain --id <id> [--json]',
+    booleanFlags: new Set(['json']),
+    async run(args) {
+        const id = flagString(args, 'id') ?? args.positional[0];
+        if (!id) {
+            process.stderr.write('Usage: shrk docs references explain --id <id>\n');
+            return ExitCode.UsageError;
+        }
+        const forwarded = { ...args, flags: new Map(args.flags) };
+        forwarded.flags.set('id', id);
+        const prep = await prepare(forwarded);
+        if (!prep.ok)
+            return prep.code;
+        const rule = prep.value.rules[0];
+        if (!rule)
+            return writeNoRules(flagBool(args, 'json'));
+        const inspection = await inspectionFor(prep.value.cwd);
+        const result = checkDocReferences(prep.value.cwd, rule, inspection, prep.value.excludeDirs);
+        if (flagBool(args, 'json')) {
+            process.stdout.write(asJson({
+                schema: 'sharkcraft.doc-references-explain/v1',
+                ...resultJson(result),
+                tokens: result.tokens,
+                resolvesAs: rule.resolvesAs,
+                requireContext: rule.requireContext ?? 'backtick',
+            }) + '\n');
+            return ExitCode.VerifiedPass;
+        }
+        process.stdout.write(header(`Doc references: ${rule.id}`));
+        if (rule.description)
+            process.stdout.write(`  ${rule.description}\n`);
+        process.stdout.write(kv('files', rule.files.join(', ')) + '\n');
+        process.stdout.write(kv('token pattern', `/${rule.tokenPattern}/`) + '\n');
+        process.stdout.write(kv('resolves as', rule.resolvesAs.join(', ')) + '\n');
+        process.stdout.write(kv('context gate', rule.requireContext ?? 'backtick') + '\n');
+        process.stdout.write(kv('docs scanned', String(result.filesScanned)) + '\n');
+        process.stdout.write(kv('tokens', `${result.tokensChecked} checked, ${result.tokensSkipped} skipped`) + '\n');
+        if (result.error)
+            process.stdout.write(`  ! ${result.error}\n`);
+        process.stdout.write('\n');
+        for (const t of result.tokens.slice(0, 100)) {
+            const verdict = t.skipped
+                ? `skipped (${t.skipped})`
+                : t.resolvedAs
+                    ? `✓ ${t.resolvedAs}`
+                    : '✗ UNRESOLVED';
+            process.stdout.write(`  ${t.token}  (${t.file}:${t.line})  — ${verdict}\n`);
+        }
+        if (result.tokens.length > 100) {
+            process.stdout.write(`  … (${result.tokens.length - 100} more)\n`);
+        }
+        return ExitCode.VerifiedPass;
+    },
+};
+export const docsReferencesListCommand = {
+    name: 'list',
+    description: 'List every declared doc-reference rule: its globs, token shape, and target registries.',
+    usage: 'shrk docs references list [--json]',
+    booleanFlags: new Set(['json']),
+    async run(args) {
+        const prep = await prepare(args);
+        if (!prep.ok)
+            return prep.code;
+        const json = flagBool(args, 'json');
+        if (prep.value.all.length === 0)
+            return writeNoRules(json);
+        if (json) {
+            process.stdout.write(asJson({ schema: SCHEMA, rules: prep.value.all }) + '\n');
+            return ExitCode.VerifiedPass;
+        }
+        process.stdout.write(header(`Doc-reference rules (${prep.value.all.length})`));
+        for (const r of prep.value.all) {
+            process.stdout.write(`  • ${r.id}\n`);
+            process.stdout.write(`      files    ${r.files.join(', ')}\n`);
+            process.stdout.write(`      token    /${r.tokenPattern}/\n`);
+            process.stdout.write(`      resolves ${r.resolvesAs.join(', ')}\n`);
+            process.stdout.write(`      context  ${r.requireContext ?? 'backtick'}\n`);
+            if (r.description)
+                process.stdout.write(`      ${r.description}\n`);
+        }
+        return ExitCode.VerifiedPass;
+    },
+};
+/** `shrk docs references <verb>` — dispatches to check / explain / list. */
+export const docsReferencesCommand = {
+    name: 'references',
+    description: 'Prose-reference linter: assert every id cited in free text (READMEs, docs, agent skill files) still resolves to a registered id.',
+    usage: 'shrk docs references check | explain --id <id> | list',
+    booleanFlags: new Set(['json']),
+    async run(args) {
+        const sub = args.positional[0];
+        const rest = { ...args, positional: args.positional.slice(1) };
+        if (sub === 'check')
+            return docsReferencesCheckCommand.run(rest);
+        if (sub === 'explain')
+            return docsReferencesExplainCommand.run(rest);
+        if (sub === 'list')
+            return docsReferencesListCommand.run(rest);
+        process.stderr.write((sub ? `Unknown subcommand "${sub}". ` : '') +
+            'Usage: shrk docs references check | explain --id <id> | list\n');
+        return ExitCode.UsageError;
+    },
+};

package/dist/commands/doctor.command.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"doctor.command.d.ts","sourceRoot":"","sources":["../../src/commands/doctor.command.ts"],"names":[],"mappings":"AAqBA,OAAO,EAML,KAAK,eAAe,EAErB,MAAM,wBAAwB,CAAC;AA6PhC,eAAO,MAAM,aAAa,EAAE,eAW3B,CAAC;AAwfF,eAAO,MAAM,qBAAqB,EAAE,eAmCnC,CAAC;AAuDF,eAAO,MAAM,yBAAyB,EAAE,eAavC,CAAC;AAIF,eAAO,MAAM,wBAAwB,EAAE,eA2CtC,CAAC;AAgCF,eAAO,MAAM,6BAA6B,EAAE,eAa3C,CAAC"}
+{"version":3,"file":"doctor.command.d.ts","sourceRoot":"","sources":["../../src/commands/doctor.command.ts"],"names":[],"mappings":"AAsBA,OAAO,EAML,KAAK,eAAe,EAErB,MAAM,wBAAwB,CAAC;AA6PhC,eAAO,MAAM,aAAa,EAAE,eAW3B,CAAC;AA2fF,eAAO,MAAM,qBAAqB,EAAE,eAmCnC,CAAC;AAuDF,eAAO,MAAM,yBAAyB,EAAE,eAavC,CAAC;AAIF,eAAO,MAAM,wBAAwB,EAAE,eA2CtC,CAAC;AAgCF,eAAO,MAAM,6BAA6B,EAAE,eAa3C,CAAC"}

package/dist/commands/doctor.command.js

@@ -1,3 +1,4 @@
+import { detectGraphFreshness } from '@shrkcrft/graph';
 import { buildAcknowledgement, buildAiReadinessReport, buildSuppressionEntry, doctorSuppressionsFile, DoctorSeverity, filterDoctorResult, inspectSharkcraft, loadDoctorSuppressions, renderAcknowledgementsText, runDoctor, saveDoctorSuppressions, summarizeAcknowledgements, } from '@shrkcrft/inspector';
 import { detectProjectShape } from '@shrkcrft/workspace';
 import { loadSurfaceContext } from "../surface/load-surface-context.js";
@@ -236,7 +237,7 @@ async function doctorCommandImpl(args) {
         inspectOpts.loaderTimeoutMs = loaderTimeout;
     }
     const inspection = await inspectSharkcraft(inspectOpts);
-    const result = augmentWithSemanticIndexCheck(runDoctor(inspection), cwd);
+    const result = augmentWithSemanticIndexCheck(runDoctor(inspection, { graphDivergence: detectGraphFreshness(cwd) }), cwd);
     const report = buildAiReadinessReport(inspection);
     if (debug) {
         process.stderr.write(`[debug] inspection elapsed ${inspection.inspectionElapsedMs}ms cache=${inspection.cacheEnabled ? 'on' : 'off'} loaders=${inspection.loaderDiagnostics.length}\n`);
@@ -707,7 +708,7 @@ async function suppressionsListRun(args) {
 async function suppressionsCheckRun(args) {
     const cwd = resolveCwd(args);
     const inspection = await inspectSharkcraft({ cwd });
-    const result = runDoctor(inspection);
+    const result = runDoctor(inspection, { graphDivergence: detectGraphFreshness(cwd) });
     const cfg = loadDoctorSuppressions(cwd);
     const filtered = filterDoctorResult(result, { suppressions: cfg.doctorSuppressions });
     const unused = filtered.appliedSuppressions.filter((a) => a.matched === 0);

package/dist/commands/gates.command.d.ts

@@ -1,6 +1,8 @@
 import { type ICommandHandler, type ParsedArgs } from '../command-registry.js';
 export declare const gatesListCommand: ICommandHandler;
 export declare const gatesCoverageCommand: ICommandHandler;
+export declare const gatesCheckCommand: ICommandHandler;
+export declare const gatesTryCommand: ICommandHandler;
 export declare const gatesExplainCommand: ICommandHandler;
 /**
  * Try to explain `id` as a data-defined rule on ANY plane.

package/dist/commands/gates.command.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"gates.command.d.ts","sourceRoot":"","sources":["../../src/commands/gates.command.ts"],"names":[],"mappings":"AAyBA,OAAO,EAIL,KAAK,eAAe,EACpB,KAAK,UAAU,EAChB,MAAM,wBAAwB,CAAC;AAgFhC,eAAO,MAAM,gBAAgB,EAAE,eAsD9B,CAAC;AAEF,eAAO,MAAM,oBAAoB,EAAE,eAuGlC,CAAC;AAuCF,eAAO,MAAM,mBAAmB,EAAE,eA4FjC,CAAC;AAEF;;;;;;;;GAQG;AACH,wBAAsB,kBAAkB,CACtC,IAAI,EAAE,UAAU,EAChB,EAAE,EAAE,MAAM,GACT,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAQ7B;AAED,eAAO,MAAM,YAAY,EAAE,eAe1B,CAAC"}
+{"version":3,"file":"gates.command.d.ts","sourceRoot":"","sources":["../../src/commands/gates.command.ts"],"names":[],"mappings":"AA6CA,OAAO,EAKL,KAAK,eAAe,EACpB,KAAK,UAAU,EAChB,MAAM,wBAAwB,CAAC;AAgOhC,eAAO,MAAM,gBAAgB,EAAE,eAsD9B,CAAC;AAEF,eAAO,MAAM,oBAAoB,EAAE,eA+KlC,CAAC;AAGF,eAAO,MAAM,iBAAiB,EAAE,eAwK/B,CAAC;AAkCF,eAAO,MAAM,eAAe,EAAE,eAgN7B,CAAC;AA+FF,eAAO,MAAM,mBAAmB,EAAE,eAmGjC,CAAC;AAEF;;;;;;;;GAQG;AACH,wBAAsB,kBAAkB,CACtC,IAAI,EAAE,UAAU,EAChB,EAAE,EAAE,MAAM,GACT,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAQ7B;AAED,eAAO,MAAM,YAAY,EAAE,eAuB1B,CAAC"}