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

package/dist/commands/finish.command.js

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

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

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

package/dist/commands/help.command.js

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

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

@@ -12,9 +12,14 @@
  *   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.
+ * Layers 3 and 4 CHAIN: the singular/plural variants and the suffix transform
+ * compose, so a doubly-off noun still lands (`buttons` →(plural)→ `button`
+ * →(suffix)→ `button-command`) where a single layer would no-op. When both
+ * transforms fire, the resolution reports `SingularPluralSuffix`.
+ *
+ * The first candidate that lands on a DECLARED id wins; when nothing resolves,
+ * the noun is returned unchanged and unmatched (the honest "genuinely not
+ * declared" answer). No layer invents an id that isn't in the registry.
  */
 /** How a noun resolved to its canonical registered id (for a truthful report). */
 export declare enum ERegistryResolveVia {
@@ -22,7 +27,9 @@ export declare enum ERegistryResolveVia {
     Alias = "alias",
     Case = "case-fold",
     SingularPlural = "singular/plural",
-    Suffix = "suffix"
+    Suffix = "suffix",
+    /** Both a singular/plural AND a suffix transform were applied (chained). */
+    SingularPluralSuffix = "singular/plural+suffix"
 }
 export interface IRegistryResolution {
     /** The canonical id to test for existence (may equal the input noun). */

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

@@ -1 +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"}
+{"version":3,"file":"registry-resolve.d.ts","sourceRoot":"","sources":["../../src/commands/registry-resolve.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,kFAAkF;AAClF,oBAAY,mBAAmB;IAC7B,QAAQ,aAAa;IACrB,KAAK,UAAU;IACf,IAAI,cAAc;IAClB,cAAc,oBAAoB;IAClC,MAAM,WAAW;IACjB,4EAA4E;IAC5E,oBAAoB,2BAA2B;CAChD;AAED,MAAM,WAAW,mBAAmB;IAClC,yEAAyE;IACzE,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,uEAAuE;IACvE,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,sDAAsD;IACtD,QAAQ,CAAC,GAAG,EAAE,mBAAmB,CAAC;CACnC;AAYD;;;;GAIG;AACH,wBAAgB,mBAAmB,CACjC,WAAW,EAAE,SAAS,MAAM,EAAE,EAC9B,OAAO,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,GAAG,SAAS,EACrD,IAAI,EAAE,MAAM,GACX,mBAAmB,CAwErB"}

package/dist/commands/registry-resolve.js

@@ -12,9 +12,14 @@
  *   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.
+ * Layers 3 and 4 CHAIN: the singular/plural variants and the suffix transform
+ * compose, so a doubly-off noun still lands (`buttons` →(plural)→ `button`
+ * →(suffix)→ `button-command`) where a single layer would no-op. When both
+ * transforms fire, the resolution reports `SingularPluralSuffix`.
+ *
+ * The first candidate that lands on a DECLARED id wins; when nothing resolves,
+ * the noun is returned unchanged and unmatched (the honest "genuinely not
+ * declared" answer). No layer invents an id that isn't in the registry.
  */
 /** How a noun resolved to its canonical registered id (for a truthful report). */
 export var ERegistryResolveVia;
@@ -24,6 +29,8 @@ export var ERegistryResolveVia;
     ERegistryResolveVia["Case"] = "case-fold";
     ERegistryResolveVia["SingularPlural"] = "singular/plural";
     ERegistryResolveVia["Suffix"] = "suffix";
+    /** Both a singular/plural AND a suffix transform were applied (chained). */
+    ERegistryResolveVia["SingularPluralSuffix"] = "singular/plural+suffix";
 })(ERegistryResolveVia || (ERegistryResolveVia = {}));
 function singularPluralVariants(noun) {
     const out = [];
@@ -60,28 +67,47 @@ export function resolveRegistryNoun(declaredIds, aliases, noun) {
     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 };
+    // 3 + 4. Chained singular/plural × suffix strip/append.
+    //
+    // Build an ordered candidate list — the noun itself first, then its
+    // singular/plural variants (plural variants BEFORE the suffix test) — and for
+    // EACH candidate test an exact (case-insensitive) match against the declared
+    // ids, then a suffix strip, then a suffix append. The first candidate that
+    // lands on a DECLARED id wins. Because the transforms compose, a doubly-off
+    // noun (`buttons` →(plural)→ `button` →(suffix)→ `button-command`) resolves
+    // where either layer alone would no-op. `via` records which transforms fired:
+    // a variant matching exactly is `SingularPlural`, the original noun matching
+    // by suffix is `Suffix`, and a variant matching by suffix is the chained
+    // `SingularPluralSuffix`. The original noun can never match here EXACTLY (the
+    // identity / case-fold short-circuits above already handled that).
+    const candidates = [noun, ...singularPluralVariants(noun)];
+    for (const candidate of candidates) {
+        const isVariant = candidate !== noun;
+        const cLower = candidate.toLowerCase();
+        const exact = declaredIds.find((d) => d.toLowerCase() === cLower);
+        if (exact !== undefined && isVariant) {
+            return { canonical: exact, matched: true, via: ERegistryResolveVia.SingularPlural };
         }
-    }
-    // 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 };
+        const suffixStripped = declaredIds.find((d) => {
+            const stripped = d.replace(/[-_.][a-z0-9]+$/i, '');
+            return stripped.toLowerCase() === cLower && stripped.toLowerCase() !== d.toLowerCase();
+        });
+        if (suffixStripped !== undefined) {
+            return {
+                canonical: suffixStripped,
+                matched: true,
+                via: isVariant ? ERegistryResolveVia.SingularPluralSuffix : ERegistryResolveVia.Suffix,
+            };
+        }
+        for (const d of declaredIds) {
+            const m = d.match(/([-_.][a-z0-9]+)$/i);
+            if (m && `${cLower}${m[1].toLowerCase()}` === d.toLowerCase()) {
+                return {
+                    canonical: d,
+                    matched: true,
+                    via: isVariant ? ERegistryResolveVia.SingularPluralSuffix : ERegistryResolveVia.Suffix,
+                };
+            }
         }
     }
     // Nothing resolved — the honest unmatched identity.

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

@@ -46,4 +46,45 @@ export declare function promoteForStrict(code: number, strict: boolean): number;
  * 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

@@ -1 +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"}
+{"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

@@ -59,3 +59,88 @@ export function argvHasStrict(argv) {
     }
     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`. */