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

package/dist/command-registry.d.ts

@@ -191,5 +191,15 @@ export interface IFlagListOptions {
 }
 export declare function flagList(args: ParsedArgs, name: string, options?: IFlagListOptions): string[];
 export declare function flagVars(args: ParsedArgs): Record<string, string>;
+/**
+ * Return the first parsed flag whose name is NOT in `allowed`, or `undefined`
+ * when every flag is recognized. The parser does not reject unknown flags on its
+ * own — without a per-command allow-list a typo'd flag (`--no-such-flag`) parses
+ * as `true`, reads as a confident opt-in, and the verb runs the bare command at
+ * exit `0`. A verb that opts into strict flag handling calls this with its known
+ * set and rejects the result loudly, so a mistyped/renamed flag can never read
+ * as success (see docs/exit-codes.md · a25 §2.1).
+ */
+export declare function firstUnknownFlag(args: ParsedArgs, allowed: ReadonlySet<string>): string | undefined;
 export {};
 //# sourceMappingURL=command-registry.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"command-registry.d.ts","sourceRoot":"","sources":["../src/command-registry.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"command-registry.d.ts","sourceRoot":"","sources":["../src/command-registry.ts"],"names":[],"mappings":"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"}

package/dist/command-registry.js

@@ -451,3 +451,19 @@ export function flagVars(args) {
     }
     return out;
 }
+/**
+ * Return the first parsed flag whose name is NOT in `allowed`, or `undefined`
+ * when every flag is recognized. The parser does not reject unknown flags on its
+ * own — without a per-command allow-list a typo'd flag (`--no-such-flag`) parses
+ * as `true`, reads as a confident opt-in, and the verb runs the bare command at
+ * exit `0`. A verb that opts into strict flag handling calls this with its known
+ * set and rejects the result loudly, so a mistyped/renamed flag can never read
+ * as success (see docs/exit-codes.md · a25 §2.1).
+ */
+export function firstUnknownFlag(args, allowed) {
+    for (const key of args.flags.keys()) {
+        if (!allowed.has(key))
+            return key;
+    }
+    return undefined;
+}

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,EA2DjE,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,EAmFjE,CAAC"}

package/dist/commands/changelog-data.js

@@ -67,4 +67,28 @@ export const RELEASE_SURFACE_DELTAS = [
         ],
         removed: [],
     },
+    {
+        version: '0.1.0-alpha.26',
+        title: 'Honest exit codes',
+        added: [
+            'A unified exit-code contract across every gate/verify/check verb: `0` verified pass, `1` failure, `2` NOT-verified (empty scope / degraded / timeout). See docs/exit-codes.md.',
+            'Global `--strict` — promote a NOT-verified (`2`) verdict to a failure-class nonzero (`1`) across every gate, for a hard CI gate in one switch.',
+            '`shrk gate baseline --refreeze` — re-freeze the architecture baseline to the current state (operational reset).',
+            '`shrk check wiring --base <ref>` (synonym of `--since`); `check wiring` now shows the rule ids selected by footprint under a scoped run.',
+            '`shrk reuse … --all` — the full candidate catalog (default is now a scored top-K did-you-mean).',
+        ],
+        changed: [
+            '`shrk check wiring` (0 rules evaluated) and `shrk registry lifecycle` / `check registry-lifecycle` (0 registrations, or wall-clock timeout) now exit `2` (NOT verified), not a green `0` a chained `&& next` would march past.',
+            'The graph/query family (`graph cycles|hubs|callers|impact|search|context|…`) rejects an unknown/misspelled flag (`unknown option --x`, exit `2`) instead of silently swallowing it as a confident success.',
+            'Piping any streaming list (`… | head`, `| grep`) no longer crashes with `write EPIPE` — a downstream early-close is swallowed and the real exit code is preserved.',
+            '`shrk check wiring --help` documents its own scoping flags instead of running the bare check.',
+            '`shrk reuse "<intent>"` returns a scored top-K did-you-mean (score per row) on a weak/no-match intent instead of dumping the whole catalog.',
+            '`shrk registry <name> exists <id> --resolve` also normalizes (case-fold, singular/plural, suffix strip/append), not just the declared `aliases` map.',
+            '`shrk compress` prints a `fidelity: lossy|lossless|passthrough` banner on the human text path (parity with `--json`).',
+            '`shrk changes summary` ships a built-in config/tooling area for non-lib paths — only genuinely unclassifiable files stay `unknown`.',
+            '`shrk gen` saved plans persist the rendered file `body` + a per-entry `sha256` digest (reviewable/diffable/re-appliable), not just `sizeBytes`.',
+            '`shrk gate` counts only change-attributable (diff-vs-HEAD) architecture errors as blocking; stale-baseline drift in untouched files is informational.',
+        ],
+        removed: [],
+    },
 ];

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;AAm1BhC,eAAO,MAAM,YAAY,EAAE,eAoG1B,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;AAu4BhC,eAAO,MAAM,YAAY,EAAE,eA+G1B,CAAC"}

package/dist/commands/check.command.js

@@ -3,6 +3,7 @@ import { mkdirSync, writeFileSync, readFileSync, existsSync } from 'node:fs';
 import * as nodePath from 'node:path';
 import { flagBool, flagNumber, flagString, flagVars, resolveCwd, } from "../command-registry.js";
 import { asJson, header, kv } from "../output/format-output.js";
+import { ExitCode } from "../exit-codes.js";
 import { maybeRunInWatchMode } from "../output/watch-loop.js";
 import { computeDeletedOrphans } from "../diff/deleted-orphans.js";
 import { renderWiringExplain } from "./wiring.command.js";
@@ -522,11 +523,29 @@ 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' +
+    '  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' +
+    '    --changed-only   run only rules whose footprint intersects the working diff\n' +
+    '    --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' +
+    '  Exit: 0 verified pass · 1 violations · 2 not-verified (0 rules evaluated in scope).';
 async function checkWiring(args) {
     const cwd = resolveCwd(args);
+    // `--help`/`-h` on the subverb documents its own scoping flags instead of
+    // silently running the bare check (a25 §3.2). The check dispatcher doesn't
+    // intercept a subverb-level `--help`, so handle it here.
+    if (flagBool(args, 'help') || flagBool(args, 'h')) {
+        process.stdout.write(WIRING_CHECK_USAGE + '\n');
+        return 0;
+    }
     const wantJson = flagBool(args, 'json');
     const changedOnly = flagBool(args, 'changed-only');
-    const since = flagString(args, 'since');
+    // `--base <ref>` is an accepted synonym for `--since <ref>` (a25 §3.2) —
+    // scope the footprint diff to changes since an arbitrary ref.
+    const since = flagString(args, 'since') ?? flagString(args, 'base');
     const only = flagString(args, 'only');
     // Distinguish "config is invalid" from "config valid with no wiring rules":
     // an invalid config (e.g. a malformed wiringRule) must NOT fail open with a
@@ -613,22 +632,50 @@ async function checkWiring(args) {
     if (matchedNothing > 0)
         parts.push(`${matchedNothing} matched no files`);
     const breakdown = parts.length > 0 ? ` (${parts.join(', ')})` : '';
+    // Rule ids selected by footprint (declared OR registered side intersecting the
+    // diff) — positive evidence the gate ran the RIGHT rules for the change's
+    // blast radius, not just the rules whose literal files were edited (a25 §3.2).
+    const selectedRuleIds = report.rules.map((r) => r.ruleId);
+    const scoped = changedOnly || since !== undefined;
     if (wantJson) {
         // Carry the honest counts so a machine consumer can tell "0 evaluated" from
-        // a real green, and see how many rules the scope skipped.
-        process.stdout.write(asJson({ ...report, configured, selected, evaluated, skippedByScope, matchedNothing, notVerified }) + '\n');
-        return report.verdict === 'errors' ? 1 : 0;
+        // a real green, and see how many rules the scope skipped + which fired.
+        process.stdout.write(asJson({
+            ...report,
+            configured,
+            selected,
+            evaluated,
+            skippedByScope,
+            matchedNothing,
+            notVerified,
+            selectedRuleIds,
+            // Distinguish verified-pass / failure / not-verified for a chained gate.
+            exitCode: evaluated === 0 ? ExitCode.NotVerified : report.verdict === 'errors' ? ExitCode.Failure : ExitCode.VerifiedPass,
+        }) + '\n');
+        // `evaluated === 0` = nothing checked in scope → NOT verified (`2`), never a
+        // silent `0` an agent's `&& next` would march past (a25 §1.1).
+        return evaluated === 0
+            ? ExitCode.NotVerified
+            : report.verdict === 'errors'
+                ? ExitCode.Failure
+                : ExitCode.VerifiedPass;
     }
     process.stdout.write(header('Wiring check'));
     // `evaluated` counts rules that actually ran a comparison (globs matched >0
     // files). When 0 rules evaluated but rules ARE configured, say so loudly —
-    // "checked nothing" must never read as the green "every token is wired" pass.
+    // "checked nothing" must never read as the green "every token is wired" pass,
+    // and the exit code must say NOT verified (`2`) too, not a lying `0`.
     if (evaluated === 0) {
         process.stdout.write(`  ! 0 rules evaluated — NOT verified. ${configured} rule(s) configured${breakdown}; ` +
             'none ran a comparison in scope. Wiring was not checked — this is not a pass.\n');
-        return 0;
+        return ExitCode.NotVerified;
     }
     process.stdout.write(kv('rules evaluated', `${evaluated} of ${configured}${breakdown}`) + '\n');
+    if (scoped && selectedRuleIds.length > 0) {
+        // Show WHICH rules the diff's footprint selected so the scoping is provable,
+        // not indistinguishable from plain changed-file scoping.
+        process.stdout.write(kv('selected by footprint', selectedRuleIds.join(', ')) + '\n');
+    }
     const errors = report.violations.filter((v) => v.severity === 'error').length;
     const warnings = report.violations.filter((v) => v.severity === 'warning').length;
     process.stdout.write(kv('violations', `${errors} error(s), ${warnings} warning(s)`) + '\n');
@@ -821,8 +868,18 @@ export const checkCommand = {
                 ...(scope ? { scope } : {}),
                 ...(skipDirs ? { skipDirs } : {}),
             });
-            // Deterministic non-zero on timeout so a wedged scan fails loud, not silent.
-            const exit = report.timedOut ? 2 : report.missingRemovers.length === 0 ? 0 : 1;
+            // Honest exit-code contract (a25 §1 / §2.5):
+            //   timedOut          → NOT verified (2): the budget flushed partial results.
+            //   registersFound=0  → NOT verified (2): nothing to check in scope — a
+            //                       "nothing to verify" run must never read as a green
+            //                       pass (an agent's `&& next` would march past it).
+            //   missingRemovers>0 → failure (1).
+            //   otherwise         → verified pass (0).
+            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;

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

@@ -1 +1 @@
-{"version":3,"file":"compress.command.d.ts","sourceRoot":"","sources":["../../src/commands/compress.command.ts"],"names":[],"mappings":"AAQA,OAAO,EAKL,KAAK,eAAe,EAErB,MAAM,wBAAwB,CAAC;AAqEhC,eAAO,MAAM,eAAe,EAAE,eAqH7B,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,aAAa,EAAE,eA4B3B,CAAC"}
+{"version":3,"file":"compress.command.d.ts","sourceRoot":"","sources":["../../src/commands/compress.command.ts"],"names":[],"mappings":"AASA,OAAO,EAKL,KAAK,eAAe,EAErB,MAAM,wBAAwB,CAAC;AA8FhC,eAAO,MAAM,eAAe,EAAE,eA0H7B,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,aAAa,EAAE,eA4B3B,CAAC"}

package/dist/commands/compress.command.js

@@ -38,6 +38,31 @@ function resolveContentType(raw) {
 // legitimately have nothing to compress). Above it, a silent `−0%` re-emit is
 // the opposite of the tool's purpose — nudge the user toward `--type`.
 const PASSTHROUGH_HINT_MIN_BYTES = 128;
+/**
+ * The no-win / passthrough test, shared by the `--json` envelope and the human
+ * text banner: a Passthrough strategy or a non-positive saving means the engine
+ * declined to compress and `compressed` is the verbatim original. Keeping it in
+ * one place is what makes the two output paths agree on fidelity.
+ */
+function isNoWin(result) {
+    return result.strategy === ECompressionStrategy.Passthrough || result.savings.saved <= 0;
+}
+/**
+ * The fidelity label for the human text path, mirroring the `fidelity` field
+ * the `--json` envelope surfaces: `passthrough` for a no-win re-emit, `lossy`
+ * for a reduction that drops detail (markdown line-omission or the code
+ * outline), and `lossless` otherwise. Same classification as `--json` — the
+ * text path just names the no-win case explicitly instead of via a separate
+ * `passthrough` boolean, so an agent reading stderr sees the fidelity at a
+ * glance.
+ */
+function textFidelity(result) {
+    if (isNoWin(result))
+        return 'passthrough';
+    if (result.strategy === ECompressionStrategy.Code || result.lossy)
+        return 'lossy';
+    return 'lossless';
+}
 function readInput(args) {
     const positional = args.positional[0];
     const useStdin = flagBool(args, 'stdin') || positional === undefined || positional === '-';
@@ -133,7 +158,7 @@ export const compressCommand = {
             // VERBATIM original as `compressed`. Echoing it back inside the JSON
             // envelope (plus scaffold) costs more tokens than the input. Signal
             // passthrough and omit the duplicated content — the caller still has it.
-            const noWin = result.strategy === ECompressionStrategy.Passthrough || result.savings.saved <= 0;
+            const noWin = isNoWin(result);
             const payload = noWin
                 ? { ...base, passthrough: true, inputBytes: Buffer.byteLength(content, 'utf8') }
                 : { ...base, compressed: result.compressed };
@@ -143,6 +168,11 @@ export const compressCommand = {
         process.stdout.write(result.compressed + '\n');
         const cached = result.ccrKey ? ` · original cached as ${result.ccrKey} (shrk expand ${result.ccrKey})` : '';
         process.stderr.write(`${result.strategy}: ~${result.savings.before} → ~${result.savings.after} tokens (−${pct}%, est.)${cached}\n`);
+        // Fidelity parity with `--json`: print the same classification the JSON
+        // envelope carries as a one-line banner so an agent reading only stderr can
+        // see the output was lossy — and see the no-win `passthrough` case named
+        // explicitly rather than inferred from a bare `−0%` ratio.
+        process.stderr.write(`fidelity: ${textFidelity(result)}\n`);
         // Fidelity banner: the code outline elides function bodies, so it is a
         // footgun as a cheaper Read. Say so loudly — same failure mode as a lossy
         // result that doesn't *look* lossy.

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/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":"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"}

package/dist/commands/reuse.command.js

@@ -60,17 +60,47 @@ function isConfidentMatch(detail, queryTokenCount) {
     return queryTokenCount <= 1;
 }
 const INDEX_RE = /(^|\/)index\.[cm]?[jt]sx?$/;
+/**
+ * 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 function rankReuseSuggestions(primitives, tokens, k) {
+    const cap = Math.max(1, Math.floor(k));
+    return primitives
+        .map((p) => ({ p, detail: scorePrimitive(p, tokens) }))
+        .sort((a, b) => b.detail.score - a.detail.score || a.p.symbol.localeCompare(b.p.symbol))
+        .slice(0, cap)
+        .map(({ p, detail }) => ({
+        symbol: p.symbol,
+        score: detail.score,
+        confidence: tokens.length === 0 ? 0 : detail.matched.length / tokens.length,
+        matched: detail.matched,
+        roles: p.roles,
+    }));
+}
 export const reuseCommand = {
     name: 'reuse',
     description: 'Intent → the canonical primitive to reuse. Matches your intent against configured reusePrimitives[], then resolves the symbol in the code graph to its declaration, public import path, sibling exports, and real consumer files to copy. Deterministic; no AI.',
-    usage: 'shrk reuse "<what I want to build>" [--limit N] [--json]',
+    usage: 'shrk reuse "<what I want to build>" [--limit N] [--all] [--json]',
+    booleanFlags: new Set(['json', 'all']),
     async run(args) {
         const cwd = resolveCwd(args);
         const wantJson = flagBool(args, 'json');
-        const limit = flagNumber(args, 'limit') ?? 3;
+        const wantAll = flagBool(args, 'all');
+        // `--limit N` caps both the confident results (historic default 3) and the
+        // did-you-mean suggestion list. When omitted, suggestions default to 5 (a
+        // couple more than results — the point of a did-you-mean is a short menu).
+        const limitFlag = flagNumber(args, 'limit');
+        const limit = limitFlag ?? 3;
+        const suggestK = limitFlag ?? 5;
         const intent = args.positional.join(' ').trim();
         if (!intent) {
-            process.stderr.write('Usage: shrk reuse "<what I want to build>" [--limit N] [--json]\n');
+            process.stderr.write('Usage: shrk reuse "<what I want to build>" [--limit N] [--all] [--json]\n');
             return 2;
         }
         const loaded = await resolveProjectConfig(cwd);
@@ -115,17 +145,39 @@ export const reuseCommand = {
         const ranked = confident.slice(0, Math.max(1, limit));
         const store = new GraphStore(cwd);
         const api = store.exists() ? GraphQueryApi.fromStore(cwd) : null;
-        // Zero keyword overlap: nothing matched at all → surface available roles.
+        // Zero keyword overlap: nothing matched at all. Rather than dump the entire
+        // declared catalog (dozens of lines an agent must re-read), rank ALL
+        // candidates and surface the nearest top-K by name — every score is 0 here,
+        // so this is an alphabetized short menu, stated as such. The full catalog is
+        // available only behind an explicit `--all`.
         if (scored.length === 0) {
+            const suggestions = rankReuseSuggestions(primitives, tokens, suggestK);
             const roles = [...new Set(primitives.flatMap((p) => p.roles))].sort();
             if (wantJson) {
-                process.stdout.write(asJson({ schema: 'sharkcraft.reuse/v1', intent, results: [], availableRoles: roles, ...planeJson }) + '\n');
+                process.stdout.write(asJson({
+                    schema: 'sharkcraft.reuse/v1',
+                    intent,
+                    confident: false,
+                    results: [],
+                    suggestions,
+                    ...(wantAll ? { availableRoles: roles } : {}),
+                    ...planeJson,
+                }) + '\n');
                 return 0;
             }
             process.stdout.write(header(`Reuse: "${intent}"`));
-            process.stdout.write('  No primitive matched. Available roles:\n');
-            for (const r of roles.slice(0, 40))
-                process.stdout.write(`    • ${r}\n`);
+            if (wantAll) {
+                process.stdout.write('  No primitive matched — no candidate shares any term — showing full catalog:\n');
+                for (const r of roles.slice(0, 40))
+                    process.stdout.write(`    • ${r}\n`);
+            }
+            else {
+                process.stdout.write('  No strong match — no candidate shares any term with the intent.\n' +
+                    '  Nearest primitives (pass --all for the full catalog):\n');
+                for (const s of suggestions) {
+                    process.stdout.write(`    • ${s.symbol}  (score ${s.score}; roles: ${s.roles.join(', ') || '—'})\n`);
+                }
+            }
             writePlaneNotes();
             return 0;
         }
@@ -133,23 +185,41 @@ export const reuseCommand = {
         // entry): below the confidence floor. A miss must look like a miss — never
         // return the nearest collision as a confident answer. Offer did-you-mean.
         if (ranked.length === 0) {
-            const didYouMean = scored.slice(0, 5).map((x) => ({
+            // Rank the weakly-overlapping candidates (score > 0) and cap at K — never
+            // the whole catalog. `suggestions` and the legacy `didYouMean` alias carry
+            // the same scored rows; `--all` additionally dumps every declared role.
+            const suggestions = scored.slice(0, Math.max(1, suggestK)).map((x) => ({
                 symbol: x.p.symbol,
                 score: x.detail.score,
                 confidence: confidenceOf(x.detail.matched.length),
                 matched: x.detail.matched,
                 roles: x.p.roles,
             }));
+            const roles = [...new Set(primitives.flatMap((p) => p.roles))].sort();
             if (wantJson) {
-                process.stdout.write(asJson({ schema: 'sharkcraft.reuse/v1', intent, confident: false, results: [], didYouMean, ...planeJson }) + '\n');
+                process.stdout.write(asJson({
+                    schema: 'sharkcraft.reuse/v1',
+                    intent,
+                    confident: false,
+                    results: [],
+                    suggestions,
+                    didYouMean: suggestions,
+                    ...(wantAll ? { availableRoles: roles } : {}),
+                    ...planeJson,
+                }) + '\n');
                 return 0;
             }
             process.stdout.write(header(`Reuse: "${intent}"`));
             process.stdout.write('  No confident match — the intent only weakly overlaps existing primitives.\n' +
                 '  Did you mean (weak, verify before reusing):\n');
-            for (const s of didYouMean) {
+            for (const s of suggestions) {
                 process.stdout.write(`    • ${s.symbol}  (score ${s.score}, ${Math.round(s.confidence * 100)}% of intent; matched: ${s.matched.join(', ') || '—'})\n`);
             }
+            if (wantAll) {
+                process.stdout.write('  Full catalog (all declared roles):\n');
+                for (const r of roles.slice(0, 40))
+                    process.stdout.write(`    • ${r}\n`);
+            }
             writePlaneNotes();
             return 0;
         }

package/dist/exit-codes.d.ts

@@ -0,0 +1,49 @@
+/**
+ * The canonical exit-code contract for every gate / verify / check verb.
+ *
+ * alpha.24 and alpha.25 made the STDOUT verdicts honest ("not verified",
+ * "degraded", "0 rules evaluated", "this is not a pass") but left the exit
+ * code returning `0` over those same unverified paths. An agent almost never
+ * parses the banner — it chains `shrk <cmd> && <next>` on the *exit code*, so a
+ * `0` over a "not verified" result marches straight past the gate. This module
+ * is the single source of truth so a chained gate can finally tell apart
+ * "passed", "failed", and "never ran".
+ *
+ *   0  VerifiedPass  — checks ran over a NON-EMPTY scope and passed. Never
+ *                      returned when zero units were evaluated.
+ *   1  Failure       — checks ran and found violations.
+ *   2  NotVerified   — indeterminate: empty evaluation scope, degraded
+ *                      fallback, short-circuit, timeout, or "refused to run".
+ *                      Distinct from both pass and fail so a chain can branch
+ *                      on it (`|| handle-indeterminate`). This is also the
+ *                      code the CLI already uses for usage errors — both mean
+ *                      "did not produce a verified result".
+ *
+ * The `gen --typecheck` pre-write gate already refuses-to-nonzero rather than
+ * emit an unverified artifact; this generalizes that instinct across the gate
+ * surface, adding the third code so "unverified" is distinguishable from
+ * "broken".
+ */
+export declare enum ExitCode {
+    VerifiedPass = 0,
+    Failure = 1,
+    NotVerified = 2
+}
+/**
+ * Promote a NotVerified (`2`) exit into a Failure-class nonzero (`1`) when the
+ * caller opted into `--strict`. This is the one switch an agent flips to make a
+ * hard CI gate treat "unverified" as a failure. Any other code passes through
+ * unchanged (a real pass stays `0`, a real failure stays `1`). Applied globally
+ * in {@link runCli} after the handler returns, so every gate/verify verb honors
+ * `--strict` uniformly without threading the flag through each call site.
+ */
+export declare function promoteForStrict(code: number, strict: boolean): number;
+/**
+ * True when the argv carries a global `--strict` (bare or `--strict=<level>`).
+ * `--strict` is also an established per-command flag (e.g. `check --strict`,
+ * `doctor --strict=warnings`) whose local meaning is preserved — this global
+ * layer only adds the NotVerified→Failure promotion on top, and only affects a
+ * command that actually returned `2`.
+ */
+export declare function argvHasStrict(argv: readonly string[]): boolean;
+//# sourceMappingURL=exit-codes.d.ts.map

package/dist/exit-codes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"exit-codes.d.ts","sourceRoot":"","sources":["../src/exit-codes.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,oBAAY,QAAQ;IAClB,YAAY,IAAI;IAChB,OAAO,IAAI;IACX,WAAW,IAAI;CAChB;AAED;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,GAAG,MAAM,CAGtE;AAED;;;;;;GAMG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,GAAG,OAAO,CAM9D"}

package/dist/exit-codes.js

@@ -0,0 +1,61 @@
+/**
+ * The canonical exit-code contract for every gate / verify / check verb.
+ *
+ * alpha.24 and alpha.25 made the STDOUT verdicts honest ("not verified",
+ * "degraded", "0 rules evaluated", "this is not a pass") but left the exit
+ * code returning `0` over those same unverified paths. An agent almost never
+ * parses the banner — it chains `shrk <cmd> && <next>` on the *exit code*, so a
+ * `0` over a "not verified" result marches straight past the gate. This module
+ * is the single source of truth so a chained gate can finally tell apart
+ * "passed", "failed", and "never ran".
+ *
+ *   0  VerifiedPass  — checks ran over a NON-EMPTY scope and passed. Never
+ *                      returned when zero units were evaluated.
+ *   1  Failure       — checks ran and found violations.
+ *   2  NotVerified   — indeterminate: empty evaluation scope, degraded
+ *                      fallback, short-circuit, timeout, or "refused to run".
+ *                      Distinct from both pass and fail so a chain can branch
+ *                      on it (`|| handle-indeterminate`). This is also the
+ *                      code the CLI already uses for usage errors — both mean
+ *                      "did not produce a verified result".
+ *
+ * The `gen --typecheck` pre-write gate already refuses-to-nonzero rather than
+ * emit an unverified artifact; this generalizes that instinct across the gate
+ * surface, adding the third code so "unverified" is distinguishable from
+ * "broken".
+ */
+export var ExitCode;
+(function (ExitCode) {
+    ExitCode[ExitCode["VerifiedPass"] = 0] = "VerifiedPass";
+    ExitCode[ExitCode["Failure"] = 1] = "Failure";
+    ExitCode[ExitCode["NotVerified"] = 2] = "NotVerified";
+})(ExitCode || (ExitCode = {}));
+/**
+ * Promote a NotVerified (`2`) exit into a Failure-class nonzero (`1`) when the
+ * caller opted into `--strict`. This is the one switch an agent flips to make a
+ * hard CI gate treat "unverified" as a failure. Any other code passes through
+ * unchanged (a real pass stays `0`, a real failure stays `1`). Applied globally
+ * in {@link runCli} after the handler returns, so every gate/verify verb honors
+ * `--strict` uniformly without threading the flag through each call site.
+ */
+export function promoteForStrict(code, strict) {
+    if (strict && code === ExitCode.NotVerified)
+        return ExitCode.Failure;
+    return code;
+}
+/**
+ * True when the argv carries a global `--strict` (bare or `--strict=<level>`).
+ * `--strict` is also an established per-command flag (e.g. `check --strict`,
+ * `doctor --strict=warnings`) whose local meaning is preserved — this global
+ * layer only adds the NotVerified→Failure promotion on top, and only affects a
+ * command that actually returned `2`.
+ */
+export function argvHasStrict(argv) {
+    for (const t of argv) {
+        if (t === '--')
+            break;
+        if (t === '--strict' || t.startsWith('--strict='))
+            return true;
+    }
+    return false;
+}

package/dist/main.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"main.d.ts","sourceRoot":"","sources":["../src/main.ts"],"names":[],"mappings":";AAEA,OAAO,EACL,eAAe,EAKhB,MAAM,uBAAuB,CAAC;AA6X/B,wBAAgB,aAAa,IAAI,eAAe,CAiY/C;AAED,wBAAsB,MAAM,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC,CA2BrE;AAqID;;;;;;;;;;;GAWG;AACH,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,GAAG,OAAO,CAoDxE"}
+{"version":3,"file":"main.d.ts","sourceRoot":"","sources":["../src/main.ts"],"names":[],"mappings":";AAEA,OAAO,EACL,eAAe,EAKhB,MAAM,uBAAuB,CAAC;AA8X/B,wBAAgB,aAAa,IAAI,eAAe,CAiY/C;AAED,wBAAsB,MAAM,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC,CAiCrE;AAqID;;;;;;;;;;;GAWG;AACH,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,GAAG,OAAO,CAoDxE"}

package/dist/main.js

@@ -1,6 +1,7 @@
 #!/usr/bin/env node
 import { loadDotenv } from "./env/load-dotenv.js";
 import { CommandRegistry, extractGlobalCompress, extractGlobalCwd, parseArgs, } from "./command-registry.js";
+import { argvHasStrict, promoteForStrict } from "./exit-codes.js";
 import { runCommandWithCompression } from "./output/output-compression.js";
 import { initCommand } from "./commands/init.command.js";
 import { inspectCommand } from "./commands/inspect.command.js";
@@ -509,9 +510,15 @@ export function buildRegistry() {
 export async function runCli(argv) {
     const usageStart = performance.now();
     const { cwd: probeCwd, rest: probeArgv } = extractGlobalCwd(argv);
+    // Global `--strict` promotes a NotVerified (`2`) verdict to a Failure-class
+    // nonzero across every gate/verify verb — one switch to make an "unverified"
+    // result fail a hard CI gate. A real pass (`0`) or failure (`1`) is untouched,
+    // and each command's own `--strict` semantics (e.g. `check --strict`) still
+    // apply beneath this (a25 §1.1).
+    const strict = argvHasStrict(argv);
     let exitCode = 0;
     try {
-        exitCode = await runCliInner(argv);
+        exitCode = promoteForStrict(await runCliInner(argv), strict);
         return exitCode;
     }
     finally {
@@ -923,6 +930,22 @@ if (isMain ||
     // test). Commands that re-exec themselves in an isolated child gate on this
     // so unit tests calling `run()` in-process never spawn a subprocess.
     process.env.SHRK_CLI = '1';
+    // Global broken-pipe containment. When a downstream reader closes early
+    // (`shrk registry <name> list | head`, `… | grep`), Node raises `write EPIPE`
+    // on stdout from the async write/flush path — with no `error` listener that
+    // becomes an uncaught exception and a nonzero exit, forging a false failure on
+    // a happy-path query whose data was fine (a25 §2.2). Swallowing EPIPE here (a
+    // no-op listener) turns it back into a benign early-close: the command keeps
+    // its REAL exit code, and nothing is written to the dead pipe. Registered once
+    // at startup so every verb that streams a list is covered.
+    const swallowPipeError = (err) => {
+        if (err && err.code === 'EPIPE')
+            return;
+        // Any other stdio error (ENOSPC, …) is unrecoverable mid-write; there is
+        // nothing safe to print, so contain it rather than crash the shutdown path.
+    };
+    process.stdout.on('error', swallowPipeError);
+    process.stderr.on('error', swallowPipeError);
     loadDotenv(process.cwd());
     const argv = process.argv.slice(2);
     const cleanShutdown = async (code) => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shrkcrft/cli",
-  "version": "0.1.0-alpha.25",
+  "version": "0.1.0-alpha.26",
   "description": "SharkCraft CLI (`shrk`): structured project intelligence for AI coding agents.",
   "license": "MIT",
   "author": "SharkCraft contributors",
@@ -47,38 +47,38 @@
     "typecheck": "tsc --noEmit -p tsconfig.json"
   },
   "dependencies": {
-    "@shrkcrft/core": "^0.1.0-alpha.25",
-    "@shrkcrft/compress": "^0.1.0-alpha.25",
-    "@shrkcrft/config": "^0.1.0-alpha.25",
-    "@shrkcrft/workspace": "^0.1.0-alpha.25",
-    "@shrkcrft/knowledge": "^0.1.0-alpha.25",
-    "@shrkcrft/context": "^0.1.0-alpha.25",
-    "@shrkcrft/rules": "^0.1.0-alpha.25",
-    "@shrkcrft/paths": "^0.1.0-alpha.25",
-    "@shrkcrft/templates": "^0.1.0-alpha.25",
-    "@shrkcrft/plugin-api": "^0.1.0-alpha.25",
-    "@shrkcrft/dashboard": "^0.1.0-alpha.25",
-    "@shrkcrft/dashboard-api": "^0.1.0-alpha.25",
-    "@shrkcrft/pipelines": "^0.1.0-alpha.25",
-    "@shrkcrft/presets": "^0.1.0-alpha.25",
-    "@shrkcrft/boundaries": "^0.1.0-alpha.25",
-    "@shrkcrft/graph": "^0.1.0-alpha.25",
-    "@shrkcrft/rule-graph": "^0.1.0-alpha.25",
-    "@shrkcrft/structural-search": "^0.1.0-alpha.25",
-    "@shrkcrft/impact-engine": "^0.1.0-alpha.25",
-    "@shrkcrft/context-planner": "^0.1.0-alpha.25",
-    "@shrkcrft/architecture-guard": "^0.1.0-alpha.25",
-    "@shrkcrft/framework-scanners": "^0.1.0-alpha.25",
-    "@shrkcrft/api-surface-diff": "^0.1.0-alpha.25",
-    "@shrkcrft/quality-gates": "^0.1.0-alpha.25",
-    "@shrkcrft/migrate": "^0.1.0-alpha.25",
-    "@shrkcrft/generator": "^0.1.0-alpha.25",
-    "@shrkcrft/importer": "^0.1.0-alpha.25",
-    "@shrkcrft/inspector": "^0.1.0-alpha.25",
-    "@shrkcrft/ai": "^0.1.0-alpha.25",
-    "@shrkcrft/embeddings": "^0.1.0-alpha.25",
-    "@shrkcrft/shared": "^0.1.0-alpha.25",
-    "@shrkcrft/mcp-server": "^0.1.0-alpha.25",
+    "@shrkcrft/core": "^0.1.0-alpha.26",
+    "@shrkcrft/compress": "^0.1.0-alpha.26",
+    "@shrkcrft/config": "^0.1.0-alpha.26",
+    "@shrkcrft/workspace": "^0.1.0-alpha.26",
+    "@shrkcrft/knowledge": "^0.1.0-alpha.26",
+    "@shrkcrft/context": "^0.1.0-alpha.26",
+    "@shrkcrft/rules": "^0.1.0-alpha.26",
+    "@shrkcrft/paths": "^0.1.0-alpha.26",
+    "@shrkcrft/templates": "^0.1.0-alpha.26",
+    "@shrkcrft/plugin-api": "^0.1.0-alpha.26",
+    "@shrkcrft/dashboard": "^0.1.0-alpha.26",
+    "@shrkcrft/dashboard-api": "^0.1.0-alpha.26",
+    "@shrkcrft/pipelines": "^0.1.0-alpha.26",
+    "@shrkcrft/presets": "^0.1.0-alpha.26",
+    "@shrkcrft/boundaries": "^0.1.0-alpha.26",
+    "@shrkcrft/graph": "^0.1.0-alpha.26",
+    "@shrkcrft/rule-graph": "^0.1.0-alpha.26",
+    "@shrkcrft/structural-search": "^0.1.0-alpha.26",
+    "@shrkcrft/impact-engine": "^0.1.0-alpha.26",
+    "@shrkcrft/context-planner": "^0.1.0-alpha.26",
+    "@shrkcrft/architecture-guard": "^0.1.0-alpha.26",
+    "@shrkcrft/framework-scanners": "^0.1.0-alpha.26",
+    "@shrkcrft/api-surface-diff": "^0.1.0-alpha.26",
+    "@shrkcrft/quality-gates": "^0.1.0-alpha.26",
+    "@shrkcrft/migrate": "^0.1.0-alpha.26",
+    "@shrkcrft/generator": "^0.1.0-alpha.26",
+    "@shrkcrft/importer": "^0.1.0-alpha.26",
+    "@shrkcrft/inspector": "^0.1.0-alpha.26",
+    "@shrkcrft/ai": "^0.1.0-alpha.26",
+    "@shrkcrft/embeddings": "^0.1.0-alpha.26",
+    "@shrkcrft/shared": "^0.1.0-alpha.26",
+    "@shrkcrft/mcp-server": "^0.1.0-alpha.26",
     "@huggingface/transformers": "^3.7.5"
   },
   "publishConfig": {