@shrkcrft/cli 0.1.0-alpha.25 → 0.1.0-alpha.27

package/dist/commands/finish.command.js

@@ -35,7 +35,7 @@ function renderText(report) {
     else if (report.impact.note) {
         process.stdout.write(kv('impact', `(skipped — ${report.impact.note})`) + '\n');
     }
-    process.stdout.write(kv('verdict', report.verdict) + '\n\n');
+    process.stdout.write(kv('verdict', `${report.verdict} (exit ${report.exit})`) + '\n\n');
     process.stdout.write(report.summary + '\n');
     const failing = report.gates.filter((g) => g.status === 'fail');
     for (const g of failing) {
@@ -52,7 +52,7 @@ function renderText(report) {
 }
 export const finishCommand = {
     name: 'finish',
-    description: 'Composite "is this changeset safe to finish?" gate: EXECUTES every deterministic changed-only check inline — boundaries + import-hygiene + wiring + policy + deleted-orphans — plus an impact summary, and returns ONE pass/fail. The single trustworthy "done?" call after editing (superset of `diff-check`; honors 0-rules→skipped). Read-only.',
+    description: 'Composite "is this changeset safe to finish?" gate: EXECUTES every deterministic changed-only check inline — boundaries + import-hygiene + wiring + unprovided (DI graph) + policy + deleted-orphans + arch (advisory cycles) — over tracked AND untracked changes, and returns ONE honest 0/1/2 verdict (0 pass · 1 fail · 2 not-verified — "evaluated nothing" is 2, never a green 0). The single trustworthy "done?" call after editing (superset of `diff-check`). Read-only.',
     usage: 'shrk [--cwd <dir>] finish [files... | --files a.ts,b.ts | --staged | --since <ref>] [--json]',
     booleanFlags: new Set(['json', 'staged']),
     async run(args) {
@@ -62,9 +62,9 @@ export const finishCommand = {
         const report = await runFinishGates({ cwd, mode, scope: options });
         if (wantJson) {
             process.stdout.write(asJson(report) + '\n');
-            return report.verdict === 'fail' ? 1 : 0;
+            return report.exit;
         }
         renderText(report);
-        return report.verdict === 'fail' ? 1 : 0;
+        return report.exit;
     },
 };

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

@@ -1 +1 @@
-{"version":3,"file":"gate.command.d.ts","sourceRoot":"","sources":["../../src/commands/gate.command.ts"],"names":[],"mappings":"AAaA,OAAO,EAIL,KAAK,eAAe,EAErB,MAAM,wBAAwB,CAAC;AAGhC;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,WAAW,EAAE,eAsMzB,CAAC"}
+{"version":3,"file":"gate.command.d.ts","sourceRoot":"","sources":["../../src/commands/gate.command.ts"],"names":[],"mappings":"AAcA,OAAO,EAIL,KAAK,eAAe,EAErB,MAAM,wBAAwB,CAAC;AAGhC;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,WAAW,EAAE,eAwNzB,CAAC"}

package/dist/commands/gate.command.js

@@ -1,4 +1,5 @@
 import { QualityGateReportStore, renderGateReportMarkdown, runQualityGates, } from '@shrkcrft/quality-gates';
+import { ArchReportStore, runArchCheck } from '@shrkcrft/architecture-guard';
 import { inspectSharkcraft, resolveChangedFiles, resolveProjectConfig, } from '@shrkcrft/inspector';
 import { chmodSync, existsSync, mkdirSync, writeFileSync } from 'node:fs';
 import * as nodePath from 'node:path';
@@ -19,7 +20,7 @@ import { asJson, header, kv } from "../output/format-output.js";
 export const gateCommand = {
     name: 'gate',
     description: 'Aggregator: runs the code-intelligence quality gates (graph freshness, architecture, impact-since-ref) and reports a single pass/fail.',
-    usage: 'shrk gate [--since <gitref>] [--changed-only] [--staged] [--files a,b,c] [--fail-on critical,high] [--arch-all] [--disable arch,impact,policy,knowledge-symbol,api-diff] [--api-baseline <path>] [--no-fail-on-breaking] [--strict] [--no-persist] [--json] [--markdown] [--output <path>]\n         (the arch gate is baseline-relative once a baseline is frozen — fails only on NEW errors; with no baseline it warns on errors rather than going perpetually red — --arch-all fails on total, --strict escalates the warn)\n         (--changed-only / --staged / --files / --since scope the wiring + policy + knowledge-symbol gates to the changeset; they also drive the impact gate — --since diffs the gitref, the others analyze the changed-file set)\n         shrk gate scaffold-ci [--provider github|generic] [--force] [--json]\n         shrk gate scaffold-hook [--provider husky|raw] [--force] [--json]',
+    usage: 'shrk gate [--since <gitref>] [--changed-only] [--staged] [--files a,b,c] [--fail-on critical,high] [--arch-all] [--disable arch,impact,policy,knowledge-symbol,api-diff] [--api-baseline <path>] [--no-fail-on-breaking] [--strict] [--no-persist] [--json] [--markdown] [--output <path>]\n         (the arch gate is change-scoped once a baseline is frozen — a NEW error blocks only when the working diff vs HEAD touched its origin file; drift in untouched files is informational — --arch-all fails on total, --strict escalates the warn)\n         (--changed-only / --staged / --files / --since scope the wiring + policy + knowledge-symbol gates to the changeset; they also drive the impact gate — --since diffs the gitref, the others analyze the changed-file set)\n         shrk gate scaffold-ci [--provider github|generic] [--force] [--json]\n         shrk gate scaffold-hook [--provider husky|raw] [--force] [--json]\n         shrk gate baseline --refreeze [--json]  (operational reset: re-freeze the arch baseline to the current state — NOT the change-scoped gate)',
     async run(args) {
         if (args.positional[0] === 'scaffold-ci') {
             const sliced = { ...args, positional: args.positional.slice(1) };
@@ -29,6 +30,10 @@ export const gateCommand = {
             const sliced = { ...args, positional: args.positional.slice(1) };
             return runGateScaffoldHook(sliced);
         }
+        if (args.positional[0] === 'baseline') {
+            const sliced = { ...args, positional: args.positional.slice(1) };
+            return runGateBaseline(sliced);
+        }
         const cwd = resolveCwd(args);
         const wantJson = flagBool(args, 'json');
         const wantMarkdown = flagBool(args, 'markdown');
@@ -101,6 +106,17 @@ export const gateCommand = {
         const scopeOpts = wantChangedScope
             ? { changedOnly: true, changedFiles: changedFiles ?? [] }
             : {};
+        // §3.1 — the architecture gate's "NEW" is ALWAYS change-scoped: a NEW error
+        // means one introduced by the working change (diff vs HEAD), never drift
+        // against a frozen (possibly months-old) baseline in a file the change never
+        // touched. When an explicit scope flag is passed we reuse its resolution;
+        // otherwise we default to the worktree diff vs HEAD — empty in a clean tree,
+        // so pre-existing baseline drift stays informational and can't red the gate
+        // on its own. `--arch-all` (baselineRelative:false) ignores this and fails
+        // on total errors, keeping a clean-tree CI demand expressible.
+        const archChangedFiles = wantChangedScope
+            ? changedFiles ?? []
+            : resolveChangedFiles({ projectRoot: cwd, includeWorktree: true }).files;
         // Knowledge symbol-ref integrity needs the loaded knowledge entries. The
         // inspection is async, so we build it here and inject it; the gate stays
         // synchronous and resolves the code graph itself. Best-effort — a failed
@@ -116,7 +132,10 @@ export const gateCommand = {
         }
         const report = runQualityGates({
             projectRoot: cwd,
-            ...(archAll ? { arch: { baselineRelative: false } } : {}),
+            arch: {
+                ...(archAll ? { baselineRelative: false } : {}),
+                changedFiles: archChangedFiles,
+            },
             wiring: {
                 ...(configError
                     ? { configError }
@@ -400,3 +419,39 @@ async function runGateScaffoldCi(args) {
     process.stdout.write(`Scaffolded ${provider} CI runner → ${target}\n`);
     return 0;
 }
+/**
+ * `shrk gate baseline --refreeze` — deliberate operational reset that re-freezes
+ * the architecture baseline to the CURRENT state, absorbing accumulated drift so
+ * the informational "baseline drift" line resets to zero.
+ *
+ * This is an operational complement, NOT the gate itself: the gate's blocking
+ * verdict is change-scoped (a NEW error blocks only when the working diff touched
+ * its origin file), so a stale baseline never reds the gate on its own. Refreeze
+ * is only for tidying the informational drift line. It mirrors `shrk arch
+ * baseline write`.
+ */
+async function runGateBaseline(args) {
+    const cwd = resolveCwd(args);
+    const wantJson = flagBool(args, 'json');
+    const refreeze = flagBool(args, 'refreeze');
+    if (!refreeze) {
+        process.stderr.write('Usage: shrk gate baseline --refreeze [--json]\n' +
+            '  Re-freeze the architecture baseline to the current state (operational reset,\n' +
+            '  not the change-scoped gate). Equivalent to `shrk arch baseline write`.\n');
+        return 2;
+    }
+    const report = runArchCheck({ projectRoot: cwd });
+    if (report.diagnostics.some((d) => d.includes('code-graph store missing'))) {
+        process.stderr.write('Cannot refreeze — graph index missing. Run `shrk graph index` first.\n');
+        return 2;
+    }
+    const store = new ArchReportStore(cwd);
+    const snap = store.writeBaseline(report);
+    if (wantJson) {
+        process.stdout.write(asJson({ ok: true, wrote: store.baselinePath, baseline: snap }) + '\n');
+        return 0;
+    }
+    process.stdout.write(`Architecture baseline re-frozen → ${store.baselinePath}\n`);
+    process.stdout.write(kv('violations', `${snap.countsBySeverity.error} error, ${snap.countsBySeverity.warning} warning`) + '\n');
+    return 0;
+}

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

@@ -1 +1 @@
-{"version":3,"file":"graph.command.d.ts","sourceRoot":"","sources":["../../src/commands/graph.command.ts"],"names":[],"mappings":"AAUA,OAAO,EAIL,KAAK,eAAe,EAErB,MAAM,wBAAwB,CAAC;AA4BhC,eAAO,MAAM,YAAY,EAAE,eAuN1B,CAAC"}
+{"version":3,"file":"graph.command.d.ts","sourceRoot":"","sources":["../../src/commands/graph.command.ts"],"names":[],"mappings":"AAUA,OAAO,EAKL,KAAK,eAAe,EAErB,MAAM,wBAAwB,CAAC;AAqFhC,eAAO,MAAM,YAAY,EAAE,eAqO1B,CAAC"}

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/help.command.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"help.command.d.ts","sourceRoot":"","sources":["../../src/commands/help.command.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AA4B9D;;;;;;;;GAQG;AACH,wBAAgB,iBAAiB,IAAI,MAAM,CAwC1C;AAED,wBAAgB,eAAe,CAAC,QAAQ,EAAE,eAAe;;;;cAK3C;QAAE,UAAU,EAAE,MAAM,EAAE,CAAC;QAAC,KAAK,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,CAAA;KAAE,GAAG,MAAM;EAwIpF"}
+{"version":3,"file":"help.command.d.ts","sourceRoot":"","sources":["../../src/commands/help.command.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AAqF9D;;;;;;;;GAQG;AACH,wBAAgB,iBAAiB,IAAI,MAAM,CAwC1C;AAED,wBAAgB,eAAe,CAAC,QAAQ,EAAE,eAAe;;;;cAK3C;QAAE,UAAU,EAAE,MAAM,EAAE,CAAC;QAAC,KAAK,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,CAAA;KAAE,GAAG,MAAM;EAqJpF"}

package/dist/commands/help.command.js

@@ -6,6 +6,65 @@ function firstSentence(description) {
     const head = dot > 0 ? description.slice(0, dot + 1) : description;
     return head.length > 100 ? head.slice(0, 97).trimEnd() + '…' : head;
 }
+/** Levenshtein edit distance — small, local helper for the unknown-topic guard. */
+function editDistance(a, b) {
+    const m = a.length;
+    const n = b.length;
+    if (m === 0)
+        return n;
+    if (n === 0)
+        return m;
+    let prev = Array.from({ length: n + 1 }, (_, i) => i);
+    let curr = new Array(n + 1);
+    for (let i = 1; i <= m; i += 1) {
+        curr[0] = i;
+        for (let j = 1; j <= n; j += 1) {
+            const cost = a[i - 1] === b[j - 1] ? 0 : 1;
+            curr[j] = Math.min(prev[j] + 1, curr[j - 1] + 1, prev[j - 1] + cost);
+        }
+        [prev, curr] = [curr, prev];
+    }
+    return prev[n];
+}
+/**
+ * The set of real, callable help topics: every registered top-level command
+ * and group name, plus every top-level verb in the catalog. Used only to
+ * suggest a near-typo when an unknown topic is requested — never to fabricate
+ * one that isn't real.
+ */
+function realHelpTopics(registry) {
+    const topics = new Set();
+    for (const c of registry.list())
+        topics.add(c.name);
+    for (const g of registry.listGroups())
+        topics.add(g);
+    for (const entry of COMMAND_CATALOG) {
+        const verb = entry.command.split(/\s+/)[0];
+        if (verb)
+            topics.add(verb);
+    }
+    return topics;
+}
+/**
+ * Nearest real topic to `attempt` within a typo-tolerant edit-distance bound,
+ * or undefined when nothing is close enough. Mirrors main.ts's confidence
+ * tolerance (`max(1, len/4)` edits) so a fingers-on-keys typo suggests but a
+ * genuinely-unrelated token does not. Deterministic: ties break lexically.
+ */
+function nearestHelpTopic(attempt, topics) {
+    const lower = attempt.toLowerCase();
+    const tolerance = Math.max(1, Math.floor(lower.length / 4));
+    let best;
+    let bestDist = Number.POSITIVE_INFINITY;
+    for (const topic of topics) {
+        const dist = editDistance(lower, topic.toLowerCase());
+        if (dist < bestDist || (dist === bestDist && best !== undefined && topic < best)) {
+            bestDist = dist;
+            best = topic;
+        }
+    }
+    return best !== undefined && bestDist <= tolerance ? best : undefined;
+}
 const EXTRA_HELP_LINES = Object.freeze({
     graph: [
         '',
@@ -89,6 +148,20 @@ export function makeHelpCommand(registry) {
                     ? args.positional[0].split(/\s+/).filter(Boolean)
                     : args.positional.filter(Boolean);
                 const { handler, matchedPath, node } = registry.resolve(tokens);
+                if (matchedPath.length === 0 && tokens.length > 0) {
+                    // Unknown topic: the descent matched NOTHING and stopped at the root
+                    // (which carries every top-level verb as a child). Do NOT fall through
+                    // to the group-listing branch below — that reprints the entire real
+                    // catalog re-prefixed with the bogus token, a false self-discovery
+                    // that exits 0. Error out honestly instead, with a did-you-mean when
+                    // a real topic is a near-typo of the request.
+                    const attempt = tokens.join(' ');
+                    process.stderr.write(`no such help topic: '${attempt}'\n`);
+                    const suggestion = nearestHelpTopic(attempt, realHelpTopics(registry));
+                    if (suggestion)
+                        process.stderr.write(`Did you mean: ${suggestion}?\n`);
+                    return 1;
+                }
                 if (handler && matchedPath.join(' ') === tokens.join(' ') && node.children.size === 0) {
                     // Exact match on a callable command.
                     const canonical = registry.listCommandAliases().get(tokens[0]);

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

@@ -0,0 +1,48 @@
+/**
+ * `--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`).
+ *
+ * Layers 3 and 4 CHAIN: the singular/plural variants and the suffix transform
+ * compose, so a doubly-off noun still lands (`buttons` →(plural)→ `button`
+ * →(suffix)→ `button-command`) where a single layer would no-op. When both
+ * transforms fire, the resolution reports `SingularPluralSuffix`.
+ *
+ * The first candidate 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",
+    /** Both a singular/plural AND a suffix transform were applied (chained). */
+    SingularPluralSuffix = "singular/plural+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;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,kFAAkF;AAClF,oBAAY,mBAAmB;IAC7B,QAAQ,aAAa;IACrB,KAAK,UAAU;IACf,IAAI,cAAc;IAClB,cAAc,oBAAoB;IAClC,MAAM,WAAW;IACjB,4EAA4E;IAC5E,oBAAoB,2BAA2B;CAChD;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,CAwErB"}

package/dist/commands/registry-resolve.js

@@ -0,0 +1,115 @@
+/**
+ * `--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`).
+ *
+ * Layers 3 and 4 CHAIN: the singular/plural variants and the suffix transform
+ * compose, so a doubly-off noun still lands (`buttons` →(plural)→ `button`
+ * →(suffix)→ `button-command`) where a single layer would no-op. When both
+ * transforms fire, the resolution reports `SingularPluralSuffix`.
+ *
+ * The first candidate 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";
+    /** Both a singular/plural AND a suffix transform were applied (chained). */
+    ERegistryResolveVia["SingularPluralSuffix"] = "singular/plural+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 + 4. Chained singular/plural × suffix strip/append.
+    //
+    // Build an ordered candidate list — the noun itself first, then its
+    // singular/plural variants (plural variants BEFORE the suffix test) — and for
+    // EACH candidate test an exact (case-insensitive) match against the declared
+    // ids, then a suffix strip, then a suffix append. The first candidate that
+    // lands on a DECLARED id wins. Because the transforms compose, a doubly-off
+    // noun (`buttons` →(plural)→ `button` →(suffix)→ `button-command`) resolves
+    // where either layer alone would no-op. `via` records which transforms fired:
+    // a variant matching exactly is `SingularPlural`, the original noun matching
+    // by suffix is `Suffix`, and a variant matching by suffix is the chained
+    // `SingularPluralSuffix`. The original noun can never match here EXACTLY (the
+    // identity / case-fold short-circuits above already handled that).
+    const candidates = [noun, ...singularPluralVariants(noun)];
+    for (const candidate of candidates) {
+        const isVariant = candidate !== noun;
+        const cLower = candidate.toLowerCase();
+        const exact = declaredIds.find((d) => d.toLowerCase() === cLower);
+        if (exact !== undefined && isVariant) {
+            return { canonical: exact, matched: true, via: ERegistryResolveVia.SingularPlural };
+        }
+        const suffixStripped = declaredIds.find((d) => {
+            const stripped = d.replace(/[-_.][a-z0-9]+$/i, '');
+            return stripped.toLowerCase() === cLower && stripped.toLowerCase() !== d.toLowerCase();
+        });
+        if (suffixStripped !== undefined) {
+            return {
+                canonical: suffixStripped,
+                matched: true,
+                via: isVariant ? ERegistryResolveVia.SingularPluralSuffix : ERegistryResolveVia.Suffix,
+            };
+        }
+        for (const d of declaredIds) {
+            const m = d.match(/([-_.][a-z0-9]+)$/i);
+            if (m && `${cLower}${m[1].toLowerCase()}` === d.toLowerCase()) {
+                return {
+                    canonical: d,
+                    matched: true,
+                    via: isVariant ? ERegistryResolveVia.SingularPluralSuffix : 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":"AA4BA,OAAO,EAIL,KAAK,eAAe,EAErB,MAAM,wBAAwB,CAAC;AAGhC,eAAO,MAAM,wBAAwB,EAAE,eAsCtC,CAAC;AAsIF,eAAO,MAAM,eAAe,EAAE,eA4B7B,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

@@ -16,7 +16,9 @@
 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.',
@@ -48,7 +50,14 @@ export const registryLifecycleCommand = {
             ...(scope ? { scope } : {}),
             ...(skipDirs ? { skipDirs } : {}),
         });
-        const exit = report.timedOut ? 2 : report.missingRemovers.length === 0 ? 0 : 1;
+        // 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 exit;
@@ -123,11 +132,16 @@ async function runRegistryInventory(args, name) {
             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 via the
-        // registry's `aliases` map before the existence test — so a duplicate guard
-        // can't return a false "free" on a synonym of an already-taken slug.
+        // `--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 canonical = doResolve ? (decl.aliases?.[id] ?? id) : id;
+        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:
@@ -140,14 +154,15 @@ async function runRegistryInventory(args, name) {
             process.stdout.write(asJson({
                 name: inventory.name,
                 id,
-                ...(resolved ? { resolvedId: canonical } : {}),
+                ...(resolved ? { resolvedId: canonical, resolvedVia: resolution?.via } : {}),
                 exists,
                 exitCode: code,
             }) + '\n');
             return code;
         }
-        if (resolved)
-            process.stdout.write(`resolved "${id}" → "${canonical}" (alias)\n`);
+        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;
     }

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;AA2GhC,eAAO,MAAM,YAAY,EAAE,eA0N1B,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"}