@shrkcrft/cli 0.1.0-alpha.24 → 0.1.0-alpha.26

package/dist/commands/graph.command.js

@@ -1,8 +1,63 @@
 import { mkdirSync, writeFileSync } from 'node:fs';
 import * as nodePath from 'node:path';
 import { analyzeImportGraph, buildKnowledgeGraph, findGraphPath, getGraphNode, inspectSharkcraft, } from '@shrkcrft/inspector';
-import { flagBool, flagString, resolveCwd, } from "../command-registry.js";
+import { firstUnknownFlag, flagBool, flagString, resolveCwd, } from "../command-registry.js";
+import { ExitCode } from "../exit-codes.js";
 import { asJson, header, kv } from "../output/format-output.js";
+/**
+ * The code-intelligence subverbs that share one arg parser. Each is guarded so
+ * an unrecognized/misspelled flag is rejected loudly instead of parsing as a
+ * silent `true` that reads as a confident opt-in (a25 §2.1). The allow-set is
+ * the UNION of every flag any code-graph subverb reads, plus the global flags,
+ * so a real flag is never false-rejected — only a genuinely unknown token is.
+ */
+const CODE_GRAPH_SUBVERBS = new Set([
+    'index',
+    'status',
+    'search',
+    'context',
+    'impact',
+    'path',
+    'hubs',
+    'callers',
+    'cycles',
+    'unresolved',
+    'deps',
+]);
+const CODE_GRAPH_ALLOWED_FLAGS = new Set([
+    // code-subverb flags (union across index/status/search/context/impact/path/
+    // hubs/callers/cycles/unresolved/deps)
+    'changed',
+    'compact',
+    'depth',
+    'full',
+    'has-unresolved-imports',
+    'include-type-edges',
+    'json',
+    'kind',
+    'limit',
+    'max-depth',
+    'min-size',
+    'mode',
+    'no-bridge',
+    'no-framework',
+    'no-refresh',
+    'path',
+    'since',
+    'table',
+    // --watch loop (graph index --watch)
+    'watch',
+    'paths',
+    'debounce',
+    'once',
+    // global / meta flags that reach any verb
+    'cwd',
+    'strict',
+    'help',
+    'h',
+    'no-color',
+    'color',
+]);
 import { runGraphCallers, runGraphContext, runGraphCycles, runGraphDeps, runGraphHubs, runGraphImpact, runGraphIndex, runGraphPath, runGraphSearch, runGraphStatus, runGraphUnresolved, } from "./graph-code-subverbs.js";
 const KNOWN_KINDS = [
     'knowledge',
@@ -26,6 +81,18 @@ export const graphCommand = {
         // Code-intelligence subverbs (R65) don't need the knowledge graph —
         // dispatch them before the expensive inspection so they stay fast.
         const earlySub = args.positional[0];
+        // Reject unknown/misspelled flags on the code-graph family BEFORE dispatch:
+        // an unrecognized flag must never parse as a silent success (a25 §2.1). Any
+        // real flag is in the union allow-set, so this only fires on a genuine typo.
+        if (typeof earlySub === 'string' && CODE_GRAPH_SUBVERBS.has(earlySub)) {
+            const unknown = firstUnknownFlag(args, CODE_GRAPH_ALLOWED_FLAGS);
+            if (unknown) {
+                const dash = unknown.length === 1 ? '-' : '--';
+                process.stderr.write(`unknown option '${dash}${unknown}' for 'shrk graph ${earlySub}'. ` +
+                    `Run 'shrk graph --help' for valid flags.\n`);
+                return ExitCode.NotVerified;
+            }
+        }
         if (earlySub === 'index')
             return runGraphIndex(args);
         if (earlySub === 'status')

package/dist/commands/policy-lint.command.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"policy-lint.command.d.ts","sourceRoot":"","sources":["../../src/commands/policy-lint.command.ts"],"names":[],"mappings":"AAIA,OAAO,EAIL,KAAK,eAAe,EAErB,MAAM,wBAAwB,CAAC;AAKhC,eAAO,MAAM,iBAAiB,EAAE,eAkJ/B,CAAC"}
+{"version":3,"file":"policy-lint.command.d.ts","sourceRoot":"","sources":["../../src/commands/policy-lint.command.ts"],"names":[],"mappings":"AAIA,OAAO,EAIL,KAAK,eAAe,EAErB,MAAM,wBAAwB,CAAC;AAKhC,eAAO,MAAM,iBAAiB,EAAE,eA6L/B,CAAC"}

package/dist/commands/policy-lint.command.js

@@ -1,17 +1,21 @@
 import * as nodePath from 'node:path';
 import { runPolicyLint } from '@shrkcrft/boundaries';
-import { resolveChangedFiles, resolveProjectConfig } from '@shrkcrft/inspector';
+import { classifyChangedScope, resolveChangedFiles, resolveProjectConfig } from '@shrkcrft/inspector';
 import { flagBool, flagString, resolveCwd, } from "../command-registry.js";
 import { asJson, header, kv } from "../output/format-output.js";
 const VALID_SURFACES = new Set(['template', 'style', 'ts']);
 export const policyLintCommand = {
     name: 'policy-lint',
     description: 'Lint template/markup, stylesheet, and AOT-invisible TS surfaces against data-defined policyRules[] (e.g. flag raw markup when a primitive exists). Sees `.html` files AND inline `template:` strings — surfaces tsc/AOT cannot. Deterministic; no AI.',
-    usage: 'shrk [--cwd <dir>] policy-lint [--surface template|style|ts] [--changed-only] [--since <ref>] [--only <ids>] [--json]',
+    usage: 'shrk [--cwd <dir>] policy-lint [--surface template|style|ts] [--changed-only] [--new-only] [--since <ref>] [--only <ids>] [--json]\n         (--changed-only SCANS just the changed files; --new-only scans the whole tree but shows only findings the change introduced, hiding pre-existing baseline debt)',
     async run(args) {
         const cwd = resolveCwd(args);
         const wantJson = flagBool(args, 'json');
         const changedOnly = flagBool(args, 'changed-only');
+        // --new-only: scan the WHOLE tree, then show only findings the current change
+        // introduced (baseline debt is bucketed as hidden, not printed) — the
+        // finding-level complement to --changed-only's file-level scoping.
+        const newOnly = flagBool(args, 'new-only');
         const since = flagString(args, 'since');
         const only = flagString(args, 'only');
         const surfaceRaw = flagString(args, 'surface');
@@ -60,11 +64,11 @@ export const policyLintCommand = {
             }
         }
         let changedFiles;
-        if (changedOnly || since) {
+        if (changedOnly || newOnly || since) {
             changedFiles = resolveChangedFiles({
                 projectRoot: cwd,
                 ...(since ? { since } : {}),
-                ...(changedOnly && !since ? { includeWorktree: true } : {}),
+                ...((changedOnly || newOnly) && !since ? { includeWorktree: true } : {}),
             }).files;
         }
         // Don't lint SharkCraft's own asset/config dir by default (its .ts files
@@ -73,17 +77,46 @@ export const policyLintCommand = {
         const excludeDirs = sharkcraftRel && !sharkcraftRel.startsWith('..') ? [sharkcraftRel] : [];
         const reportRaw = runPolicyLint(cwd, rules, {
             ...(surfaces ? { surfaces } : {}),
-            ...(changedOnly || since ? { changedOnly: true, changedFiles: changedFiles ?? [] } : {}),
+            // --changed-only narrows the SCAN; --new-only scans the full tree so it can
+            // still diff findings (it filters after, below).
+            ...((changedOnly || since) && !newOnly ? { changedOnly: true, changedFiles: changedFiles ?? [] } : {}),
             ...(only ? { only: only.split(',').map((s) => s.trim()).filter(Boolean) } : {}),
             ...(excludeDirs.length > 0 ? { excludeDirs } : {}),
         });
         // Surface pack-plane merge notes (missing/invalid pack policy files, dropped
         // collisions) in the same diagnostics array the engine already emits.
-        const report = planeDiagnostics.length > 0
+        let report = planeDiagnostics.length > 0
             ? { ...reportRaw, diagnostics: [...reportRaw.diagnostics, ...planeDiagnostics] }
             : reportRaw;
+        // --new-only: partition the full-tree findings against the changed set and
+        // keep only the ones the current change introduced; pre-existing baseline
+        // debt is bucketed as hidden (reported as a count, never printed as green).
+        let hiddenBaseline = 0;
+        if (newOnly) {
+            const keyOf = (f) => `${f.ruleId}|${f.file}:${f.line}|${f.match}`;
+            const classification = classifyChangedScope({
+                projectRoot: cwd,
+                current: report.findings.map((f) => ({
+                    key: keyOf(f),
+                    file: f.file,
+                    code: f.ruleId,
+                    severity: f.severity,
+                    message: f.message,
+                })),
+                changedFiles: changedFiles ?? [],
+            });
+            const newKeys = new Set(classification.newIssues.map((n) => n.key));
+            const newFindings = report.findings.filter((f) => newKeys.has(keyOf(f)));
+            hiddenBaseline = report.findings.length - newFindings.length;
+            const verdict = newFindings.some((f) => f.severity === 'error')
+                ? 'errors'
+                : newFindings.length > 0
+                    ? report.verdict
+                    : 'pass';
+            report = { ...report, findings: newFindings, verdict };
+        }
         if (wantJson) {
-            process.stdout.write(asJson(report) + '\n');
+            process.stdout.write(asJson({ ...report, ...(newOnly ? { newOnly: true, hiddenBaseline } : {}) }) + '\n');
             return report.verdict === 'errors' ? 1 : 0;
         }
         process.stdout.write(header('Policy lint'));
@@ -99,13 +132,18 @@ export const policyLintCommand = {
         const errors = report.findings.filter((f) => f.severity === 'error').length;
         const warnings = report.findings.filter((f) => f.severity === 'warning').length;
         process.stdout.write(kv('findings', `${errors} error(s), ${warnings} warning(s)`) + '\n');
+        if (newOnly) {
+            process.stdout.write(kv('scope', `new-only (${hiddenBaseline} pre-existing finding(s) hidden — run without --new-only to see all)`) + '\n');
+        }
         if (report.diagnostics.length > 0) {
             process.stdout.write('\nMisconfigured rules:\n');
             for (const d of report.diagnostics)
                 process.stdout.write(`  ! ${d}\n`);
         }
         if (report.findings.length === 0 && report.diagnostics.length === 0) {
-            process.stdout.write('\nNo policy violations on the scanned surfaces. ✓\n');
+            process.stdout.write(newOnly
+                ? `\nNo NEW policy violations from this change${hiddenBaseline > 0 ? ` (${hiddenBaseline} pre-existing hidden)` : ''}. ✓\n`
+                : '\nNo policy violations on the scanned surfaces. ✓\n');
             return 0;
         }
         // Group findings by rule.

package/dist/commands/registry-resolve.d.ts

@@ -0,0 +1,41 @@
+/**
+ * `--resolve` support for `shrk registry <name> exists <id>`.
+ *
+ * The noun an author types is not always the exact registered slug. `--resolve`
+ * bridges that vocabulary gap before the existence check so a duplicate guard
+ * can't return a false "not declared" for a construct that DOES exist under its
+ * canonical id (a25 §2.4). Resolution is deterministic and layered, most
+ * author-controlled first:
+ *
+ *   1. the registry's declared `aliases` map (explicit synonym → canonical),
+ *   2. a case-insensitive exact match against the declared ids,
+ *   3. singular/plural normalization (`commands` ↔ `command`),
+ *   4. suffix strip/append (`button` ↔ `button-command`, `foo` ↔ `foo.tool`).
+ *
+ * The first layer that lands on a DECLARED id wins; when nothing resolves, the
+ * noun is returned unchanged and unmatched (the honest "genuinely not declared"
+ * answer). No layer invents an id that isn't in the registry.
+ */
+/** How a noun resolved to its canonical registered id (for a truthful report). */
+export declare enum ERegistryResolveVia {
+    Identity = "identity",
+    Alias = "alias",
+    Case = "case-fold",
+    SingularPlural = "singular/plural",
+    Suffix = "suffix"
+}
+export interface IRegistryResolution {
+    /** The canonical id to test for existence (may equal the input noun). */
+    readonly canonical: string;
+    /** True when `canonical` is actually a declared id in the registry. */
+    readonly matched: boolean;
+    /** Which normalization layer produced `canonical`. */
+    readonly via: ERegistryResolveVia;
+}
+/**
+ * Resolve a human/synonym `noun` to a canonical registered id. `declaredIds` is
+ * the registry's actual declared id list (so no layer can resolve to something
+ * that isn't declared); `aliases` is the registry's optional declared map.
+ */
+export declare function resolveRegistryNoun(declaredIds: readonly string[], aliases: Readonly<Record<string, string>> | undefined, noun: string): IRegistryResolution;
+//# sourceMappingURL=registry-resolve.d.ts.map

package/dist/commands/registry-resolve.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry-resolve.d.ts","sourceRoot":"","sources":["../../src/commands/registry-resolve.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,kFAAkF;AAClF,oBAAY,mBAAmB;IAC7B,QAAQ,aAAa;IACrB,KAAK,UAAU;IACf,IAAI,cAAc;IAClB,cAAc,oBAAoB;IAClC,MAAM,WAAW;CAClB;AAED,MAAM,WAAW,mBAAmB;IAClC,yEAAyE;IACzE,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,uEAAuE;IACvE,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,sDAAsD;IACtD,QAAQ,CAAC,GAAG,EAAE,mBAAmB,CAAC;CACnC;AAYD;;;;GAIG;AACH,wBAAgB,mBAAmB,CACjC,WAAW,EAAE,SAAS,MAAM,EAAE,EAC9B,OAAO,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,GAAG,SAAS,EACrD,IAAI,EAAE,MAAM,GACX,mBAAmB,CAmDrB"}

package/dist/commands/registry-resolve.js

@@ -0,0 +1,89 @@
+/**
+ * `--resolve` support for `shrk registry <name> exists <id>`.
+ *
+ * The noun an author types is not always the exact registered slug. `--resolve`
+ * bridges that vocabulary gap before the existence check so a duplicate guard
+ * can't return a false "not declared" for a construct that DOES exist under its
+ * canonical id (a25 §2.4). Resolution is deterministic and layered, most
+ * author-controlled first:
+ *
+ *   1. the registry's declared `aliases` map (explicit synonym → canonical),
+ *   2. a case-insensitive exact match against the declared ids,
+ *   3. singular/plural normalization (`commands` ↔ `command`),
+ *   4. suffix strip/append (`button` ↔ `button-command`, `foo` ↔ `foo.tool`).
+ *
+ * The first layer that lands on a DECLARED id wins; when nothing resolves, the
+ * noun is returned unchanged and unmatched (the honest "genuinely not declared"
+ * answer). No layer invents an id that isn't in the registry.
+ */
+/** How a noun resolved to its canonical registered id (for a truthful report). */
+export var ERegistryResolveVia;
+(function (ERegistryResolveVia) {
+    ERegistryResolveVia["Identity"] = "identity";
+    ERegistryResolveVia["Alias"] = "alias";
+    ERegistryResolveVia["Case"] = "case-fold";
+    ERegistryResolveVia["SingularPlural"] = "singular/plural";
+    ERegistryResolveVia["Suffix"] = "suffix";
+})(ERegistryResolveVia || (ERegistryResolveVia = {}));
+function singularPluralVariants(noun) {
+    const out = [];
+    const lower = noun.toLowerCase();
+    if (lower.endsWith('ies'))
+        out.push(noun.slice(0, -3) + 'y');
+    if (lower.endsWith('s'))
+        out.push(noun.slice(0, -1));
+    if (lower.endsWith('y'))
+        out.push(noun.slice(0, -1) + 'ies');
+    out.push(noun + 's');
+    return out;
+}
+/**
+ * Resolve a human/synonym `noun` to a canonical registered id. `declaredIds` is
+ * the registry's actual declared id list (so no layer can resolve to something
+ * that isn't declared); `aliases` is the registry's optional declared map.
+ */
+export function resolveRegistryNoun(declaredIds, aliases, noun) {
+    const idSet = new Set(declaredIds);
+    // 1. Author-declared alias map — highest priority, honored even if it points
+    //    at an id the current scan didn't find (the author asserted the mapping).
+    const aliased = aliases?.[noun];
+    if (aliased !== undefined) {
+        return { canonical: aliased, matched: idSet.has(aliased), via: ERegistryResolveVia.Alias };
+    }
+    // Exact identity.
+    if (idSet.has(noun)) {
+        return { canonical: noun, matched: true, via: ERegistryResolveVia.Identity };
+    }
+    const lower = noun.toLowerCase();
+    // 2. Case-insensitive exact.
+    const ciHit = declaredIds.find((d) => d.toLowerCase() === lower);
+    if (ciHit !== undefined) {
+        return { canonical: ciHit, matched: true, via: ERegistryResolveVia.Case };
+    }
+    // 3. Singular/plural.
+    for (const variant of singularPluralVariants(noun)) {
+        const v = variant.toLowerCase();
+        const hit = declaredIds.find((d) => d.toLowerCase() === v);
+        if (hit !== undefined) {
+            return { canonical: hit, matched: true, via: ERegistryResolveVia.SingularPlural };
+        }
+    }
+    // 4. Suffix strip/append. A declared id whose trailing `-`/`.`/`_` segment,
+    //    once stripped, equals the noun (`button` ← `button-command`); or the noun
+    //    plus a suffix another declared id carries yields a declared id.
+    const suffixStripped = declaredIds.find((d) => {
+        const stripped = d.replace(/[-_.][a-z0-9]+$/i, '');
+        return stripped.toLowerCase() === lower && stripped.toLowerCase() !== d.toLowerCase();
+    });
+    if (suffixStripped !== undefined) {
+        return { canonical: suffixStripped, matched: true, via: ERegistryResolveVia.Suffix };
+    }
+    for (const d of declaredIds) {
+        const m = d.match(/([-_.][a-z0-9]+)$/i);
+        if (m && `${lower}${m[1].toLowerCase()}` === d.toLowerCase()) {
+            return { canonical: d, matched: true, via: ERegistryResolveVia.Suffix };
+        }
+    }
+    // Nothing resolved — the honest unmatched identity.
+    return { canonical: noun, matched: false, via: ERegistryResolveVia.Identity };
+}

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

@@ -1 +1 @@
-{"version":3,"file":"registry.command.d.ts","sourceRoot":"","sources":["../../src/commands/registry.command.ts"],"names":[],"mappings":"AAwBA,OAAO,EAIL,KAAK,eAAe,EAErB,MAAM,wBAAwB,CAAC;AAGhC,eAAO,MAAM,wBAAwB,EAAE,eAetC,CAAC;AAsGF,eAAO,MAAM,eAAe,EAAE,eAuB7B,CAAC"}
+{"version":3,"file":"registry.command.d.ts","sourceRoot":"","sources":["../../src/commands/registry.command.ts"],"names":[],"mappings":"AA4BA,OAAO,EAIL,KAAK,eAAe,EAErB,MAAM,wBAAwB,CAAC;AAKhC,eAAO,MAAM,wBAAwB,EAAE,eA8CtC,CAAC;AA6IF,eAAO,MAAM,eAAe,EAAE,eA4B7B,CAAC"}

package/dist/commands/registry.command.js

@@ -4,30 +4,66 @@
  *   shrk registry lifecycle [--json]            # register/remove symmetry
  *   shrk registry <name> list [--json]          # every declared id
  *   shrk registry <name> exists <id> [--json]   # is the id taken? (exit 1 if not)
+ *       [--resolve]                             #   map a synonym → canonical id first
+ *       [--fail-if-taken]                       #   guard: non-zero when taken (free → 0)
+ *       [--fail-if-missing]                     #   guard: non-zero when NOT registered
  *   shrk registry <name> where <id> [--json]    # declaration (+ consumer) sites
  *
  * `<name>` resolves a `registries[]` declaration in sharkcraft.config.ts — one
  * deterministic multi-root scan that answers "is this id taken / where is it"
  * without an agent re-running a fragile grep.
  */
-import { buildRegistryLifecycleReport, renderRegistryLifecycleReportText, resolveProjectConfig, } from '@shrkcrft/inspector';
+import { buildRegistryLifecycleReport, renderRegistryLifecycleReportText, resolveChangedFiles, resolveProjectConfig, } from '@shrkcrft/inspector';
 import { scanRegistry, registryExists, registryWhere, } from '@shrkcrft/boundaries';
 import { flagBool, flagString, resolveCwd, } from "../command-registry.js";
+import { ExitCode } from "../exit-codes.js";
 import { asJson } from "../output/format-output.js";
+import { resolveRegistryNoun } from "./registry-resolve.js";
 export const registryLifecycleCommand = {
     name: 'lifecycle',
     description: 'Scan the workspace for register/remove symmetry. Read-only.',
-    usage: 'shrk registry lifecycle [--scope <dir>] [--json]',
+    usage: 'shrk registry lifecycle [--scope <dir>] [--changed-only] [--since <ref>] [--json]',
     async run(args) {
         const cwd = resolveCwd(args);
         const scope = flagString(args, 'scope');
-        const report = buildRegistryLifecycleReport({ projectRoot: cwd, ...(scope ? { scope } : {}) });
+        const changedOnly = flagBool(args, 'changed-only');
+        const since = flagString(args, 'since');
+        let files;
+        if (changedOnly || since) {
+            const changed = resolveChangedFiles({
+                projectRoot: cwd,
+                ...(since ? { since } : {}),
+                ...(changedOnly && !since ? { includeWorktree: true } : {}),
+            });
+            files = changed.files;
+        }
+        // Full-tree walk honors the project's skipDirs override.
+        let skipDirs;
+        if (files === undefined) {
+            const loaded = await resolveProjectConfig(cwd);
+            if (loaded.ok)
+                skipDirs = loaded.value.config.registryLifecycle?.skipDirs;
+        }
+        const report = buildRegistryLifecycleReport({
+            projectRoot: cwd,
+            ...(files !== undefined ? { files } : {}),
+            ...(scope ? { scope } : {}),
+            ...(skipDirs ? { skipDirs } : {}),
+        });
+        // Honest exit-code contract (a25 §1 / §2.5): a wedged/timed-out scan OR a
+        // scope with zero registrations to check is NOT verified (`2`), never a
+        // green `0` an agent's `&& next` would march past.
+        const exit = report.timedOut || report.registersFound === 0
+            ? ExitCode.NotVerified
+            : report.missingRemovers.length === 0
+                ? ExitCode.VerifiedPass
+                : ExitCode.Failure;
         if (flagBool(args, 'json')) {
             process.stdout.write(asJson(report) + '\n');
-            return report.missingRemovers.length === 0 ? 0 : 1;
+            return exit;
         }
         process.stdout.write(renderRegistryLifecycleReportText(report));
-        return report.missingRemovers.length === 0 ? 0 : 1;
+        return exit;
     },
 };
 async function loadRegistries(cwd) {
@@ -87,15 +123,48 @@ async function runRegistryInventory(args, name) {
     }
     if (action === 'exists') {
         if (!id) {
-            process.stderr.write(`Usage: shrk registry ${name} exists <id>\n`);
+            process.stderr.write(`Usage: shrk registry ${name} exists <id> [--resolve] [--fail-if-taken|--fail-if-missing]\n`);
             return 2;
         }
-        const exists = registryExists(inventory, id);
-        if (json)
-            process.stdout.write(asJson({ name: inventory.name, id, exists }) + '\n');
-        else
-            process.stdout.write(`${exists ? 'yes' : 'no'} — "${id}" is ${exists ? 'declared' : 'NOT declared'} in registry "${inventory.name}".\n`);
-        return exists ? 0 : 1;
+        const failIfTaken = flagBool(args, 'fail-if-taken');
+        const failIfMissing = flagBool(args, 'fail-if-missing');
+        if (failIfTaken && failIfMissing) {
+            process.stderr.write('Pass at most one of --fail-if-taken / --fail-if-missing.\n');
+            return 2;
+        }
+        // `--resolve` maps a human noun to the canonical registered id before the
+        // existence test — via the registry's declared `aliases` map AND generic
+        // normalization (case-fold, singular/plural, suffix strip/append) — so a
+        // duplicate guard can't return a false "free" on a synonym of an
+        // already-taken slug (a25 §2.4).
+        const doResolve = flagBool(args, 'resolve');
+        const resolution = doResolve
+            ? resolveRegistryNoun(inventory.entries.map((e) => e.id), decl.aliases, id)
+            : undefined;
+        const canonical = resolution ? resolution.canonical : id;
+        const resolved = canonical !== id;
+        const exists = registryExists(inventory, canonical);
+        // Exit-code convention:
+        //   --fail-if-taken   → non-zero when the id is already registered (free → 0),
+        //                       so `exists <id> --fail-if-taken && <author>` is a natural guard.
+        //   --fail-if-missing → non-zero when the id is NOT registered (the consume-side check).
+        //   neither           → the historical query convention (taken → 0, free → 1).
+        const code = failIfTaken ? (exists ? 1 : 0) : exists ? 0 : 1;
+        if (json) {
+            process.stdout.write(asJson({
+                name: inventory.name,
+                id,
+                ...(resolved ? { resolvedId: canonical, resolvedVia: resolution?.via } : {}),
+                exists,
+                exitCode: code,
+            }) + '\n');
+            return code;
+        }
+        if (resolved) {
+            process.stdout.write(`resolved "${id}" → "${canonical}" (${resolution?.via})\n`);
+        }
+        process.stdout.write(`${exists ? 'yes' : 'no'} — "${canonical}" is ${exists ? 'declared' : 'NOT declared'} in registry "${inventory.name}".\n`);
+        return code;
     }
     if (action === 'where') {
         if (!id) {
@@ -124,7 +193,11 @@ async function runRegistryInventory(args, name) {
 export const registryCommand = {
     name: 'registry',
     description: 'Registry inspections: lifecycle symmetry + declared-registry inventory. Read-only.',
-    usage: 'shrk registry lifecycle | <name> list | <name> exists <id> | <name> where <id>',
+    usage: 'shrk registry lifecycle | <name> list | <name> exists <id> [--resolve] [--fail-if-taken|--fail-if-missing] | <name> where <id>',
+    // Guard-mode + query flags take no value — declare them so `exists <id>
+    // --fail-if-taken` (flag last) and `exists --resolve <id>` (flag first) both
+    // keep the id as a positional instead of swallowing it.
+    booleanFlags: new Set(['json', 'resolve', 'fail-if-taken', 'fail-if-missing']),
     async run(args) {
         const sub = args.positional[0];
         if (sub === 'lifecycle') {

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

@@ -1,3 +1,23 @@
+import type { IReusePrimitive } from '@shrkcrft/core';
 import { type ICommandHandler } from '../command-registry.js';
+/** A weak (below-confidence) candidate offered as a did-you-mean, never as an answer. */
+interface IReuseSuggestion {
+    symbol: string;
+    score: number;
+    confidence: number;
+    matched: readonly string[];
+    roles: readonly string[];
+}
+/**
+ * Rank ALL primitives by the matcher's own score (descending; ties broken by
+ * symbol name so the order is deterministic), then return the top-`k` as scored
+ * did-you-mean suggestions. Pure — no graph, no IO — so it is directly
+ * unit-testable. When every candidate scores 0 (a nonsense intent that shares no
+ * term) the result is the alphabetically-first `k` primitives, each with
+ * `score: 0`; the caller states "no candidate shares any term" in that case
+ * rather than dumping the whole catalog.
+ */
+export declare function rankReuseSuggestions(primitives: readonly IReusePrimitive[], tokens: readonly string[], k: number): IReuseSuggestion[];
 export declare const reuseCommand: ICommandHandler;
+export {};
 //# sourceMappingURL=reuse.command.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"reuse.command.d.ts","sourceRoot":"","sources":["../../src/commands/reuse.command.ts"],"names":[],"mappings":"AAGA,OAAO,EAIL,KAAK,eAAe,EAErB,MAAM,wBAAwB,CAAC;AA4DhC,eAAO,MAAM,YAAY,EAAE,eAqK1B,CAAC"}
+{"version":3,"file":"reuse.command.d.ts","sourceRoot":"","sources":["../../src/commands/reuse.command.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAC;AACtD,OAAO,EAIL,KAAK,eAAe,EAErB,MAAM,wBAAwB,CAAC;AAkGhC,yFAAyF;AACzF,UAAU,gBAAgB;IACxB,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;IACd,UAAU,EAAE,MAAM,CAAC;IACnB,OAAO,EAAE,SAAS,MAAM,EAAE,CAAC;IAC3B,KAAK,EAAE,SAAS,MAAM,EAAE,CAAC;CAC1B;AAED;;;;;;;;GAQG;AACH,wBAAgB,oBAAoB,CAClC,UAAU,EAAE,SAAS,eAAe,EAAE,EACtC,MAAM,EAAE,SAAS,MAAM,EAAE,EACzB,CAAC,EAAE,MAAM,GACR,gBAAgB,EAAE,CAapB;AAED,eAAO,MAAM,YAAY,EAAE,eA6Q1B,CAAC"}