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

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

@@ -1 +1 @@
-{"version":3,"file":"trace.command.d.ts","sourceRoot":"","sources":["../../src/commands/trace.command.ts"],"names":[],"mappings":"AAmBA,OAAO,EAML,KAAK,eAAe,EAErB,MAAM,wBAAwB,CAAC;AA6EhC,eAAO,MAAM,YAAY,EAAE,eAwH1B,CAAC"}
+{"version":3,"file":"trace.command.d.ts","sourceRoot":"","sources":["../../src/commands/trace.command.ts"],"names":[],"mappings":"AAmBA,OAAO,EAML,KAAK,eAAe,EAErB,MAAM,wBAAwB,CAAC;AA8EhC,eAAO,MAAM,YAAY,EAAE,eA+H1B,CAAC"}

package/dist/commands/trace.command.js

@@ -17,6 +17,7 @@ const TRACE_ROLE_ORDER = [
     TraceRole.Declare,
     TraceRole.Register,
     TraceRole.Consume,
+    TraceRole.Render,
     TraceRole.Reference,
 ];
 function renderTraceLiteral(report, limit) {
@@ -31,7 +32,7 @@ function renderTraceLiteral(report, limit) {
     }
     // Mirror `shrk registry <name> where`'s `<role>  file:line` line idiom so the
     // two surfaces read the same — `trace literal` is the same scanner + classifier
-    // without a pre-declared registry, just with two extra roles (`registered`,
+    // without a pre-declared registry, just with extra roles (`register`, `render`,
     // `reference`). The raw source line stays in `--json` (`text`); the human view
     // is classification-first (direction), not a grep-style text dump.
     process.stdout.write('\n');
@@ -154,6 +155,11 @@ export const traceCommand = {
         process.stdout.write(header(`Trace: ${query}`));
         if (!resolution.bestMatch) {
             process.stdout.write('  no matches found.\n');
+            // The bare-`trace` path resolves a FUZZY registry query, not an exact
+            // string literal — quotes are stripped by the shell, so we can't tell a
+            // literal from a query and must not auto-route. Point the agent at the
+            // exact-literal tracer (`trace literal`) so a no-match here isn't a dead end.
+            process.stderr.write(`hint: to trace an exact string literal across files, use: shrk trace literal "${query}"\n`);
             return 1;
         }
         process.stdout.write(`Confidence: ${resolution.confidence}\n`);

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

@@ -1 +1 @@
-{"version":3,"file":"wiring.command.d.ts","sourceRoot":"","sources":["../../src/commands/wiring.command.ts"],"names":[],"mappings":"AAAA,OAAO,EASL,KAAK,cAAc,EACpB,MAAM,sBAAsB,CAAC;AAM9B,OAAO,EAAwB,KAAK,eAAe,EAAmB,MAAM,wBAAwB,CAAC;AAKrG;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,cAAc,EAAE,QAAQ,EAAE,OAAO,GAAG,MAAM,CAsDrF;AA+TD,eAAO,MAAM,aAAa,EAAE,eAgB3B,CAAC"}
+{"version":3,"file":"wiring.command.d.ts","sourceRoot":"","sources":["../../src/commands/wiring.command.ts"],"names":[],"mappings":"AAAA,OAAO,EASL,KAAK,cAAc,EACpB,MAAM,sBAAsB,CAAC;AAM9B,OAAO,EAIL,KAAK,eAAe,EAErB,MAAM,wBAAwB,CAAC;AAMhC;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,cAAc,EAAE,QAAQ,EAAE,OAAO,GAAG,MAAM,CAsDrF;AAyZD,eAAO,MAAM,aAAa,EAAE,eAgB3B,CAAC"}

package/dist/commands/wiring.command.js

@@ -1,9 +1,10 @@
 import { buildRegistrationGraph, explainWiring, registrationChain, registrationGraphSignature, registrationOrphans, registrationUnprovided, } from '@shrkcrft/boundaries';
-import { resolveProjectConfig } from '@shrkcrft/inspector';
+import { refExists, resolveChangedFiles, resolveProjectConfig } from '@shrkcrft/inspector';
 import { createHash } from 'node:crypto';
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
 import * as nodePath from 'node:path';
-import { flagBool, resolveCwd } from "../command-registry.js";
+import { flagBool, flagString, resolveCwd, } from "../command-registry.js";
+import { ExitCode } from "../exit-codes.js";
 import { asJson, header, kv } from "../output/format-output.js";
 const SITE_DISPLAY_CAP = 50;
 /**
@@ -245,6 +246,33 @@ function noIdiomsHint(wantJson) {
 function siteLine(s) {
     return `${s.file}:${s.line} [${s.idiom}]`;
 }
+/**
+ * The changed-file scope for a `--changed-only` / `--base <ref>` query, or an
+ * empty result when neither flag is set (whole-graph query). `--base <ref>` diffs
+ * against that ref; bare `--changed-only` uses the working tree. Reuses the same
+ * {@link resolveChangedFiles} the `finish` composite and boundary gates use, so
+ * the scope semantics match across every changed-only surface.
+ *
+ * Two honesty guards: an unresolvable `--base` ref returns a distinct `error`
+ * (never a silent empty scope that reads as "nothing changed" over a typo'd ref);
+ * and SHRK's own engine-written state under `.sharkcraft/` (this command writes a
+ * cache + usage log) is excluded so it can't pollute an otherwise-clean tree into
+ * a false non-empty scope.
+ */
+function changedScopeFor(args, cwd) {
+    const base = flagString(args, 'base');
+    const changedOnly = flagBool(args, 'changed-only');
+    if (!base && !changedOnly)
+        return {};
+    if (base && !refExists(cwd, base)) {
+        return { error: `cannot resolve --base ref '${base}' — not a valid commit/branch` };
+    }
+    const opts = base
+        ? { projectRoot: cwd, since: base }
+        : { projectRoot: cwd, includeWorktree: true };
+    const files = resolveChangedFiles(opts).files.filter((f) => f !== '.sharkcraft' && !f.startsWith('.sharkcraft/'));
+    return { files };
+}
 async function wiringChain(args) {
     const cwd = resolveCwd(args);
     const wantJson = flagBool(args, 'json');
@@ -312,15 +340,39 @@ async function wiringUnprovided(args) {
     }
     if (!loaded.graph)
         return noIdiomsHint(wantJson);
-    const unprovided = registrationUnprovided(loaded.graph);
+    const scoped = changedScopeFor(args, cwd);
+    if (scoped.error) {
+        if (wantJson) {
+            process.stdout.write(asJson({ schema: loaded.graph.schema, scoped: true, error: scoped.error, verified: false }) + '\n');
+        }
+        else {
+            process.stderr.write(`error: ${scoped.error}\n`);
+        }
+        return ExitCode.NotVerified;
+    }
+    const scope = scoped.files;
+    // An empty changed scope evaluated NOTHING — honest `2` (not-verified), never
+    // a green `0` that reads as "no unprovided tokens" (a25 §1.1 exit contract).
+    if (scope && scope.length === 0) {
+        if (wantJson) {
+            process.stdout.write(asJson({ schema: loaded.graph.schema, scoped: true, total: 0, unprovided: [], verified: false }) + '\n');
+            return ExitCode.NotVerified;
+        }
+        process.stdout.write(header('Unprovided tokens (declared/injected but never provided)'));
+        process.stdout.write('  – No files in the changed scope — nothing to verify (not verified).\n');
+        return ExitCode.NotVerified;
+    }
+    const unprovided = registrationUnprovided(loaded.graph, scope);
     if (wantJson) {
-        process.stdout.write(asJson({ schema: loaded.graph.schema, total: unprovided.length, unprovided }) + '\n');
-        return unprovided.length > 0 ? 1 : 0;
+        process.stdout.write(asJson({ schema: loaded.graph.schema, scoped: scope !== undefined, total: unprovided.length, unprovided }) + '\n');
+        return unprovided.length > 0 ? ExitCode.Failure : ExitCode.VerifiedPass;
     }
     process.stdout.write(header('Unprovided tokens (declared/injected but never provided)'));
+    if (scope)
+        process.stdout.write(kv('scope', `changed-only (${scope.length} file(s))`) + '\n');
     if (unprovided.length === 0) {
-        process.stdout.write('  ✓ Every declared/injected token has a provider. ✓\n');
-        return 0;
+        process.stdout.write(`  ✓ Every declared/injected token${scope ? ' in the changed scope' : ''} has a provider. ✓\n`);
+        return ExitCode.VerifiedPass;
     }
     process.stdout.write(`  ${unprovided.length} token(s) resolve to nothing at runtime:\n`);
     for (const u of unprovided) {
@@ -328,7 +380,7 @@ async function wiringUnprovided(args) {
         const where = site ? `  (${siteLine(site)})` : '';
         process.stdout.write(`  ✗ ${u.token}${where}\n`);
     }
-    return 1;
+    return ExitCode.Failure;
 }
 async function wiringOrphans(args) {
     const cwd = resolveCwd(args);
@@ -343,14 +395,36 @@ async function wiringOrphans(args) {
     }
     if (!loaded.graph)
         return noIdiomsHint(wantJson);
-    const orphans = registrationOrphans(loaded.graph);
+    const scoped = changedScopeFor(args, cwd);
+    if (scoped.error) {
+        if (wantJson) {
+            process.stdout.write(asJson({ schema: loaded.graph.schema, scoped: true, error: scoped.error, verified: false }) + '\n');
+        }
+        else {
+            process.stderr.write(`error: ${scoped.error}\n`);
+        }
+        return ExitCode.NotVerified;
+    }
+    const scope = scoped.files;
+    if (scope && scope.length === 0) {
+        if (wantJson) {
+            process.stdout.write(asJson({ schema: loaded.graph.schema, scoped: true, total: 0, orphans: [], verified: false }) + '\n');
+            return ExitCode.NotVerified;
+        }
+        process.stdout.write(header('Orphan registrations (provided but nothing consumes)'));
+        process.stdout.write('  – No files in the changed scope — nothing to verify (not verified).\n');
+        return ExitCode.NotVerified;
+    }
+    const orphans = registrationOrphans(loaded.graph, scope);
     if (wantJson) {
-        process.stdout.write(asJson({ schema: loaded.graph.schema, total: orphans.length, orphans }) + '\n');
+        process.stdout.write(asJson({ schema: loaded.graph.schema, scoped: scope !== undefined, total: orphans.length, orphans }) + '\n');
         return 0;
     }
     process.stdout.write(header('Orphan registrations (provided but nothing consumes)'));
+    if (scope)
+        process.stdout.write(kv('scope', `changed-only (${scope.length} file(s))`) + '\n');
     if (orphans.length === 0) {
-        process.stdout.write('  ✓ Every provided token is consumed somewhere. ✓\n');
+        process.stdout.write(`  ✓ Every provided token${scope ? ' in the changed scope' : ''} is consumed somewhere. ✓\n`);
         return 0;
     }
     process.stdout.write(`  ${orphans.length} provided token(s) nothing injects:\n`);
@@ -360,12 +434,12 @@ async function wiringOrphans(args) {
     }
     return 0;
 }
-const WIRING_USAGE = 'shrk wiring explain <ruleId> | test <candidate.json|inline> | chain <token> | unprovided | orphans [--json]';
+const WIRING_USAGE = 'shrk wiring explain <ruleId> | test <candidate.json|inline> | chain <token> | unprovided | orphans [--changed-only | --base <ref>] [--json]';
 export const wiringCommand = {
     name: 'wiring',
-    description: 'Author-loop + runtime-wiring queries (no config write): `explain <ruleId>` / `test <candidate>` show what a wiring rule extracts; `chain <token>` / `unprovided` / `orphans` query the DI/registration graph (declared→provided→consumed) for the silent-at-runtime bugs imports can\'t see.',
+    description: 'Author-loop + runtime-wiring queries (no config write): `explain <ruleId>` / `test <candidate>` show what a wiring rule extracts; `chain <token>` / `unprovided` / `orphans` query the DI/registration graph (declared→provided→consumed) for the silent-at-runtime bugs imports can\'t see. `unprovided` / `orphans` accept `--changed-only` (working tree) or `--base <ref>` to scope the verdict to the changeset.',
     usage: WIRING_USAGE,
-    booleanFlags: new Set(['json']),
+    booleanFlags: new Set(['json', 'changed-only']),
     async run(args) {
         const sub = args.positional[0];
         if (sub === 'explain')

package/dist/exit-codes.d.ts

@@ -0,0 +1,90 @@
+/**
+ * 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;
+/**
+ * True when the argv carries the global `--exit-trailer` (before the `--`
+ * sentinel). This is the machine channel that survives a pipe: when set, the
+ * final verdict is written as the LAST stderr line (`shrk-exit: <code>`), so an
+ * agent that pipes a gate to `head`/`grep` can still read shrk's real exit off a
+ * channel the pipe can't swallow. See {@link emitPipeExitSignal}.
+ */
+export declare function argvHasExitTrailer(argv: readonly string[]): boolean;
+/**
+ * Is `commandPath` (space-joined, e.g. `check boundaries` / `wiring unprovided`
+ * / `finish`) a gate/verify verb whose exit code carries a chained verdict?
+ * Matches the exact path, its first-two-token subverb, or its top-level verb —
+ * so `check boundaries --json` (2 tokens) and a bare `finish` (1) both resolve.
+ */
+export declare function isGateVerb(commandPath: string): boolean;
+/** Injectable surface for {@link emitPipeExitSignal} (isTTY + writer + trailer). */
+export interface IPipeExitOptions {
+    /** True when shrk's stdout is NOT a terminal (i.e. piped/redirected). */
+    readonly piped: boolean;
+    /** True when `--exit-trailer` was requested. */
+    readonly trailer: boolean;
+    /** stderr writer; defaults to `process.stderr.write`. Overridable for tests. */
+    readonly write?: (s: string) => void;
+}
+/**
+ * Keep the honest `0`/`1`/`2` exit code READABLE through the shape agents reach
+ * for first — the trailing pipe. `<gate> | head` reports `head`'s `$?`, so a true
+ * `2` (not-verified) or `1` (failure) evaporates into a `0`. Two channels survive
+ * the pipe because both go to stderr:
+ *
+ *   (a) a one-line WARNING when stdout is piped AND the code is non-zero — a
+ *       masked `0`→`0` is harmless, so the note is reserved for the case that
+ *       actually loses information (a masked `1`/`2`);
+ *   (b) the `shrk-exit: <code>` TRAILER whenever `--exit-trailer` is set (any
+ *       code), so a caller that opts in gets the verdict machine-readably.
+ *
+ * A no-op for non-gate verbs. Called once in {@link runCli} after the final
+ * (strict-promoted) code is known, so every gate/verify verb is covered without
+ * threading anything through each command.
+ */
+export declare function emitPipeExitSignal(commandPath: string, code: number, opts: IPipeExitOptions): void;
+//# 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;AAED;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,GAAG,OAAO,CAMnE;AA4BD;;;;;GAKG;AACH,wBAAgB,UAAU,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAMvD;AAED,oFAAoF;AACpF,MAAM,WAAW,gBAAgB;IAC/B,yEAAyE;IACzE,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;IACxB,gDAAgD;IAChD,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,gFAAgF;IAChF,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC,EAAE,MAAM,KAAK,IAAI,CAAC;CACtC;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,kBAAkB,CAChC,WAAW,EAAE,MAAM,EACnB,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,gBAAgB,GACrB,IAAI,CAWN"}

package/dist/exit-codes.js

@@ -0,0 +1,146 @@
+/**
+ * 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;
+}
+/**
+ * True when the argv carries the global `--exit-trailer` (before the `--`
+ * sentinel). This is the machine channel that survives a pipe: when set, the
+ * final verdict is written as the LAST stderr line (`shrk-exit: <code>`), so an
+ * agent that pipes a gate to `head`/`grep` can still read shrk's real exit off a
+ * channel the pipe can't swallow. See {@link emitPipeExitSignal}.
+ */
+export function argvHasExitTrailer(argv) {
+    for (const t of argv) {
+        if (t === '--')
+            break;
+        if (t === '--exit-trailer')
+            return true;
+    }
+    return false;
+}
+/**
+ * Command paths (space-joined top-level + subverb, as {@link extractCommandPath}
+ * emits) whose exit code is a HONEST verdict an agent chains on — the set for
+ * which a masked exit is a real hazard. Kept deliberately broad over the gate /
+ * verify surface; membership only ever gates whether {@link emitPipeExitSignal}
+ * may write a one-line stderr note, never behavior.
+ */
+const GATE_VERB_PATHS = new Set([
+    'finish',
+    'gate',
+    'arch',
+    'doctor',
+    'diff-check',
+    'check boundaries',
+    'check wiring',
+    'check orphans',
+    'check policy',
+    'check imports',
+    'wiring unprovided',
+    'wiring orphans',
+    'wiring chain',
+    'registry',
+    'graph why',
+    'graph cycles',
+]);
+/**
+ * Is `commandPath` (space-joined, e.g. `check boundaries` / `wiring unprovided`
+ * / `finish`) a gate/verify verb whose exit code carries a chained verdict?
+ * Matches the exact path, its first-two-token subverb, or its top-level verb —
+ * so `check boundaries --json` (2 tokens) and a bare `finish` (1) both resolve.
+ */
+export function isGateVerb(commandPath) {
+    if (GATE_VERB_PATHS.has(commandPath))
+        return true;
+    const parts = commandPath.split(' ').filter((p) => p.length > 0);
+    if (parts.length >= 2 && GATE_VERB_PATHS.has(`${parts[0]} ${parts[1]}`))
+        return true;
+    if (parts.length >= 1 && GATE_VERB_PATHS.has(parts[0]))
+        return true;
+    return false;
+}
+/**
+ * Keep the honest `0`/`1`/`2` exit code READABLE through the shape agents reach
+ * for first — the trailing pipe. `<gate> | head` reports `head`'s `$?`, so a true
+ * `2` (not-verified) or `1` (failure) evaporates into a `0`. Two channels survive
+ * the pipe because both go to stderr:
+ *
+ *   (a) a one-line WARNING when stdout is piped AND the code is non-zero — a
+ *       masked `0`→`0` is harmless, so the note is reserved for the case that
+ *       actually loses information (a masked `1`/`2`);
+ *   (b) the `shrk-exit: <code>` TRAILER whenever `--exit-trailer` is set (any
+ *       code), so a caller that opts in gets the verdict machine-readably.
+ *
+ * A no-op for non-gate verbs. Called once in {@link runCli} after the final
+ * (strict-promoted) code is known, so every gate/verify verb is covered without
+ * threading anything through each command.
+ */
+export function emitPipeExitSignal(commandPath, code, opts) {
+    if (!isGateVerb(commandPath))
+        return;
+    const write = opts.write ?? ((s) => void process.stderr.write(s));
+    if (opts.piped && code !== 0) {
+        write(`note: stdout is piped — $? reflects the downstream command, not shrk (exit ${code}); ` +
+            `use PIPESTATUS[0] or --exit-trailer to read shrk's verdict.\n`);
+    }
+    // The trailer is written LAST so it is the final stderr line a caller reads.
+    if (opts.trailer)
+        write(`shrk-exit: ${code}\n`);
+}

package/dist/finish/run-finish.d.ts

@@ -1,4 +1,5 @@
 import { type IChangedScopeOptions } from '@shrkcrft/inspector';
+import { ExitCode } from '../exit-codes.js';
 export declare const FINISH_SCHEMA: "sharkcraft.finish/v1";
 /** Outcome of one sub-gate. `skipped` = nothing to evaluate (loud, never silent green). */
 export type FinishGateStatus = 'pass' | 'fail' | 'skipped';
@@ -9,7 +10,7 @@ export interface IFinishItem {
     readonly message: string;
 }
 export interface IFinishGate {
-    readonly name: 'boundaries' | 'imports' | 'wiring' | 'policy' | 'orphans';
+    readonly name: 'boundaries' | 'imports' | 'wiring' | 'unprovided' | 'policy' | 'orphans' | 'arch';
     readonly status: FinishGateStatus;
     /** One-line reason (e.g. why skipped, or the error/warning counts). */
     readonly detail: string;
@@ -17,6 +18,14 @@ export interface IFinishGate {
     readonly warnings: number;
     /** Failing/notable items (capped by the renderer, full in JSON). */
     readonly items: readonly IFinishItem[];
+    /**
+     * Advisory gates report signal but NEVER decide the verdict: they cannot fail
+     * the composite and do not count as "something was evaluated" (so an advisory
+     * pass can't turn an all-skipped run green). Used by `arch`, whose cycle
+     * findings are change-informative but must not attribute a pre-existing cycle
+     * to this changeset.
+     */
+    readonly advisory?: boolean;
 }
 export interface IFinishImpact {
     readonly ran: boolean;
@@ -35,8 +44,18 @@ export interface IFinishReport {
     };
     readonly gates: readonly IFinishGate[];
     readonly impact: IFinishImpact;
-    /** `fail` iff any gate failed OR the config could not load; else `pass`. */
-    readonly verdict: 'pass' | 'fail';
+    /**
+     * The honest tri-state verdict:
+     *   `fail`         — a deciding gate failed (or the config could not load).
+     *   `not-verified` — NOTHING was actually evaluated (every deciding gate
+     *                    skipped / the changed scope had nothing to gate). Never a
+     *                    green `pass` — "evaluated nothing" is `2`, not `0`.
+     *   `pass`         — at least one deciding gate ran over a real scope and every
+     *                    deciding gate passed.
+     */
+    readonly verdict: 'pass' | 'fail' | 'not-verified';
+    /** The exit code this verdict maps to (0 pass / 1 fail / 2 not-verified). */
+    readonly exit: ExitCode;
     /** Total warning-severity findings across gates (non-blocking). */
     readonly warnings: number;
     /** Set when sharkcraft.config.ts could not be loaded — forces a `fail`. */

package/dist/finish/run-finish.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"run-finish.d.ts","sourceRoot":"","sources":["../../src/finish/run-finish.ts"],"names":[],"mappings":"AAAA,OAAO,EAML,KAAK,oBAAoB,EAC1B,MAAM,qBAAqB,CAAC;AAa7B,eAAO,MAAM,aAAa,EAAG,sBAA+B,CAAC;AAE7D,2FAA2F;AAC3F,MAAM,MAAM,gBAAgB,GAAG,MAAM,GAAG,MAAM,GAAG,SAAS,CAAC;AAE3D,8EAA8E;AAC9E,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AAED,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,IAAI,EAAE,YAAY,GAAG,SAAS,GAAG,QAAQ,GAAG,QAAQ,GAAG,SAAS,CAAC;IAC1E,QAAQ,CAAC,MAAM,EAAE,gBAAgB,CAAC;IAClC,uEAAuE;IACvE,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,oEAAoE;IACpE,QAAQ,CAAC,KAAK,EAAE,SAAS,WAAW,EAAE,CAAC;CACxC;AAED,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,GAAG,EAAE,OAAO,CAAC;IACtB,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,gBAAgB,CAAC,EAAE,MAAM,CAAC;IACnC,QAAQ,CAAC,oBAAoB,CAAC,EAAE,MAAM,CAAC;IACvC,yEAAyE;IACzE,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,MAAM,EAAE,OAAO,aAAa,CAAC;IACtC,QAAQ,CAAC,KAAK,EAAE;QACd,QAAQ,CAAC,IAAI,EAAE,UAAU,GAAG,QAAQ,GAAG,OAAO,GAAG,OAAO,CAAC;QACzD,QAAQ,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,CAAC;QAClC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;KAC5B,CAAC;IACF,QAAQ,CAAC,KAAK,EAAE,SAAS,WAAW,EAAE,CAAC;IACvC,QAAQ,CAAC,MAAM,EAAE,aAAa,CAAC;IAC/B,4EAA4E;IAC5E,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAAC;IAClC,mEAAmE;IACnE,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,2EAA2E;IAC3E,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;CAC7B;AAED,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,IAAI,EAAE,UAAU,GAAG,QAAQ,GAAG,OAAO,GAAG,OAAO,CAAC;IACzD,QAAQ,CAAC,KAAK,EAAE,oBAAoB,CAAC;CACtC;AAYD;;;;;;;;GAQG;AACH,wBAAsB,cAAc,CAAC,KAAK,EAAE,eAAe,GAAG,OAAO,CAAC,aAAa,CAAC,CAkHnF"}
+{"version":3,"file":"run-finish.d.ts","sourceRoot":"","sources":["../../src/finish/run-finish.ts"],"names":[],"mappings":"AAAA,OAAO,EAOL,KAAK,oBAAoB,EAC1B,MAAM,qBAAqB,CAAC;AAiB7B,OAAO,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAE5C,eAAO,MAAM,aAAa,EAAG,sBAA+B,CAAC;AAQ7D,2FAA2F;AAC3F,MAAM,MAAM,gBAAgB,GAAG,MAAM,GAAG,MAAM,GAAG,SAAS,CAAC;AAE3D,8EAA8E;AAC9E,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AAED,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,IAAI,EAAE,YAAY,GAAG,SAAS,GAAG,QAAQ,GAAG,YAAY,GAAG,QAAQ,GAAG,SAAS,GAAG,MAAM,CAAC;IAClG,QAAQ,CAAC,MAAM,EAAE,gBAAgB,CAAC;IAClC,uEAAuE;IACvE,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,oEAAoE;IACpE,QAAQ,CAAC,KAAK,EAAE,SAAS,WAAW,EAAE,CAAC;IACvC;;;;;;OAMG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,OAAO,CAAC;CAC7B;AAED,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,GAAG,EAAE,OAAO,CAAC;IACtB,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,gBAAgB,CAAC,EAAE,MAAM,CAAC;IACnC,QAAQ,CAAC,oBAAoB,CAAC,EAAE,MAAM,CAAC;IACvC,yEAAyE;IACzE,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,MAAM,EAAE,OAAO,aAAa,CAAC;IACtC,QAAQ,CAAC,KAAK,EAAE;QACd,QAAQ,CAAC,IAAI,EAAE,UAAU,GAAG,QAAQ,GAAG,OAAO,GAAG,OAAO,CAAC;QACzD,QAAQ,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,CAAC;QAClC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;KAC5B,CAAC;IACF,QAAQ,CAAC,KAAK,EAAE,SAAS,WAAW,EAAE,CAAC;IACvC,QAAQ,CAAC,MAAM,EAAE,aAAa,CAAC;IAC/B;;;;;;;;OAQG;IACH,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,GAAG,cAAc,CAAC;IACnD,6EAA6E;IAC7E,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC;IACxB,mEAAmE;IACnE,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,2EAA2E;IAC3E,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;CAC7B;AAED,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,IAAI,EAAE,UAAU,GAAG,QAAQ,GAAG,OAAO,GAAG,OAAO,CAAC;IACzD,QAAQ,CAAC,KAAK,EAAE,oBAAoB,CAAC;CACtC;AAmBD;;;;;;;;GAQG;AACH,wBAAsB,cAAc,CAAC,KAAK,EAAE,eAAe,GAAG,OAAO,CAAC,aAAa,CAAC,CAmJnF"}