@shrkcrft/cli 0.1.0-alpha.30 → 0.1.0-alpha.31

package/dist/dispatch/unread-flags.d.ts

@@ -0,0 +1,152 @@
+import type { ICommandHandler, ParsedArgs } from '../command-registry.js';
+import type { ICommandIndex } from '../surface/i-command-index.js';
+import type { IDeclaredInvocation } from './i-declared-invocation.js';
+import type { IInvocationRejection } from './invocation-rejection.js';
+/**
+ * THE post-run unknown-flag detector (round 11 §5.2) — universal, zero
+ * annotation. `shrk check --tag auth` printed a green sweep at exit 0: `check`
+ * has no `--tag`, the parser accepted it as a flag, nothing read it. Now:
+ *
+ *   - a supplied flag the handler never READ and its usage never DOCUMENTS was
+ *     dropped → stderr names it (with the closest documented flag), and a `0`
+ *     becomes `usageExitFor(path)`: a clean verdict over a dropped input is the
+ *     lie. A non-zero exit is kept.
+ *   - a documented-but-unread flag (`doctor --provider` without
+ *     `--llm-recommendations`) NEVER changes the exit — reading a flag only in
+ *     some modes is legitimate.
+ *   - presentation flags (`SOFT_FLAGS`) are warned about, never escalated.
+ *
+ * Skipped when the handler declares `flags` (the pre-run guard is then
+ * authoritative) or `forwardsArgv` (a child process re-parses the argv, so
+ * this process's reads prove nothing).
+ */
+export declare function tracksFlagReads(handler: ICommandHandler, walk: IDeclaredInvocation): boolean;
+/**
+ * Swap `parsed.flags` / `parsed.multiFlags` for read-tracking copies (in place)
+ * and return a probe: the supplied flags nothing read, global flags and the
+ * bare `-` (stdin) sentinel excluded. Call the probe after the handler returns.
+ */
+export declare function beginFlagReadTracking(parsed: ParsedArgs): () => string[];
+/**
+ * Every text that documents the flags of the handler at `matchedPath` AS ITS
+ * USAGE records them: its usage, every declared subverb's usage (nested), and
+ * — from the command index — the usage, catalog row and folded flag variants of
+ * every entry at or below the path. Wider documentation only ever makes the
+ * detector quieter.
+ *
+ * This is the HANDLER-WIDE union — what `r75-flag-read-ledger` holds the
+ * ledger against ("is this flag named anywhere for this handler?"). It is
+ * NOT what an invocation is judged by: since round 13 a flag is a flag of the
+ * subverb that documents it, never of its siblings
+ * ({@link invocationFlagDocumentation}).
+ */
+export declare function usageFlagDocumentation(handler: ICommandHandler, matchedPath: readonly string[], index: ICommandIndex): string[];
+/**
+ * THE documentation an INVOCATION's flags are judged by (round 13): the usages
+ * along its declared-subverb walk ({@link walkedUsages}); from the command
+ * index, the usage, catalog row and folded variants of every entry at or below
+ * the handler whose path is a token prefix of the invocation (`check`, `check
+ * templates` for `shrk check templates …` — never `check boundaries`); and the
+ * handler's row of flags its code reads ({@link UNDOCUMENTED_FLAG_READS}).
+ *
+ * Before round 13 the post-run judgement read {@link flagDocumentation} — the
+ * whole group's — so `check --fail-on-dead-units` ran the full sweep at exit 0
+ * (only `check boundaries` documents the flag), and `self-config doctor
+ * --allow-empty` was accepted and ignored because `self-config broken-links`
+ * documents it. Documentation is per subverb, not per group
+ * ({@link settleUnreadFlags}).
+ */
+export declare function invocationFlagDocumentation(input: {
+    readonly handler: ICommandHandler;
+    readonly matchedPath: readonly string[];
+    /** The positionals as the dispatcher parsed them — BEFORE the run (a handler may consume them). */
+    readonly positional: readonly string[];
+    readonly index: ICommandIndex;
+}): string[];
+/**
+ * What the post-run detector treats as the flags of the handler at
+ * `matchedPath`: its {@link usageFlagDocumentation}, plus the flags its code
+ * READS that the usage does not show yet ({@link UNDOCUMENTED_FLAG_READS}, a
+ * ledger locked two-way against the code by `r75-flag-read-ledger`). With
+ * both, a flag the detector calls "not a flag of this command" is one no code
+ * path of the handler reads (a flag name computed at runtime excepted), so a
+ * `0` over it is a dropped input — never a real flag read behind a branch
+ * (`export claude-md --write --force` on a fresh file wrote it, then exited 2).
+ */
+export declare function flagDocumentation(handler: ICommandHandler, matchedPath: readonly string[], index: ICommandIndex): string[];
+/** True when `--key` (or `-k` for a one-letter key) appears as a flag in any of `docs`. */
+export declare function isFlagDocumented(key: string, docs: readonly string[]): boolean;
+/** Every `--flag` named in `docs` — the candidates a refusal's did-you-mean picks from. */
+export declare function documentedFlagNames(docs: readonly string[]): string[];
+/**
+ * THE pre-run half of the undocumented-flag rule (round 11 review): a supplied
+ * flag that is not a flag of the command GROUP — named by none of its
+ * {@link flagDocumentation} (its usage and every declared subverb's, the
+ * command index at or below the path, and the two-way-locked ledger of flags
+ * its code reads) — is refused BEFORE the body runs. Whether a flag is
+ * undocumented is static, so nothing justifies running first: `baseline
+ * update --dry-rn` performed the bless write, then exited 3; `check --tag
+ * auth` printed a whole sweep first.
+ *
+ * A flag the group documents only on a SIBLING subverb is judged after the run
+ * instead ({@link settleUnreadFlags} with the invocation's own
+ * {@link invocationFlagDocumentation}, round 13): whether THIS subverb's code
+ * reads it is not static knowledge — a group's shared option is often
+ * documented on one subverb and read by all of them — so refusing it here
+ * would refuse real inputs. The message is THE one refusal format
+ * ({@link unknownFlagRefusal}).
+ *
+ * Presentation flags (`SOFT_FLAGS`) are left to the post-run warning — losing
+ * `--verbose` loses formatting, not an input. The index is built only when the
+ * handler's own usages leave a flag unexplained, so the common run pays
+ * nothing.
+ */
+export declare function refuseUndocumentedFlags(input: {
+    readonly handler: ICommandHandler;
+    readonly matchedPath: readonly string[];
+    /** The declared walk's path — what the message and `usageExitFor` name. */
+    readonly label: string;
+    readonly parsed: ParsedArgs;
+    readonly index: () => ICommandIndex;
+}): IInvocationRejection | undefined;
+/**
+ * The command paths at or below `matchedPath` (other than the invocation's
+ * own chain) whose documentation names `key` — the sibling subverbs the
+ * refusal points at (`— only \`shrk check boundaries\` documents it`).
+ */
+export declare function siblingsDocumenting(key: string, matchedPath: readonly string[], invocationPath: readonly string[], index: ICommandIndex): string[];
+/**
+ * Judge the unread flags of a finished run against the INVOCATION's
+ * documentation (`documentation`: {@link invocationFlagDocumentation} — the
+ * subverb's own, never a sibling's):
+ *
+ *   - a flag named by no documentation of the group: warned, and a `0`
+ *     becomes `usageExitFor(path)` (the backstop for a name computed at
+ *     runtime — the pre-run judgement refuses the rest);
+ *   - round 13 — a flag only a SIBLING subverb documents (`groupDocumentation`
+ *     names it, the invocation's does not) that this run never read is REFUSED
+ *     like any dropped flag: a `0` becomes `usageExitFor(path)` on every verb,
+ *     and on a verdict verb a `2` does too (a found failure `1` is kept).
+ *     `check --fail-on-dead-units` ran the sweep at exit 0 (only `check
+ *     boundaries` documents the flag); `self-config doctor --allow-empty`
+ *     ignored it; `registrations list --fail-on-dead-units` kept its 0 with a
+ *     warning (round 13 review — documentation is per subverb on every verb). A
+ *     sibling-documented flag the run READ is a real input and never judged.
+ *
+ * Presentation flags (`SOFT_FLAGS`) are only ever warned about. Returns `exit`
+ * unchanged when nothing is judged.
+ */
+export declare function settleUnreadFlags(input: {
+    readonly unread: readonly string[];
+    readonly path: string;
+    readonly documentation: readonly string[];
+    /** The whole group's documentation ({@link flagDocumentation}) — what tells a sibling-only flag apart. */
+    readonly groupDocumentation?: readonly string[];
+    /** Per flag key, the sibling command paths that document it — named in the message. */
+    readonly documentedOn?: (key: string) => readonly string[];
+    readonly exit: number;
+    readonly write?: (text: string) => void;
+    /** The argv the handler's args were parsed from — to name each flag as TYPED. */
+    readonly argv?: readonly string[];
+}): number;
+//# sourceMappingURL=unread-flags.d.ts.map

package/dist/dispatch/unread-flags.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"unread-flags.d.ts","sourceRoot":"","sources":["../../src/dispatch/unread-flags.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,UAAU,EAAE,MAAM,wBAAwB,CAAC;AAE1E,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,+BAA+B,CAAC;AAEnE,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,4BAA4B,CAAC;AACtE,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,2BAA2B,CAAC;AAQtE;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,eAAe,EAAE,IAAI,EAAE,mBAAmB,GAAG,OAAO,CAE5F;AAED;;;;GAIG;AACH,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,UAAU,GAAG,MAAM,MAAM,EAAE,CAUxE;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,sBAAsB,CACpC,OAAO,EAAE,eAAe,EACxB,WAAW,EAAE,SAAS,MAAM,EAAE,EAC9B,KAAK,EAAE,aAAa,GACnB,MAAM,EAAE,CAUV;AAsCD;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,2BAA2B,CAAC,KAAK,EAAE;IACjD,QAAQ,CAAC,OAAO,EAAE,eAAe,CAAC;IAClC,QAAQ,CAAC,WAAW,EAAE,SAAS,MAAM,EAAE,CAAC;IACxC,mGAAmG;IACnG,QAAQ,CAAC,UAAU,EAAE,SAAS,MAAM,EAAE,CAAC;IACvC,QAAQ,CAAC,KAAK,EAAE,aAAa,CAAC;CAC/B,GAAG,MAAM,EAAE,CAcX;AAED;;;;;;;;;GASG;AACH,wBAAgB,iBAAiB,CAC/B,OAAO,EAAE,eAAe,EACxB,WAAW,EAAE,SAAS,MAAM,EAAE,EAC9B,KAAK,EAAE,aAAa,GACnB,MAAM,EAAE,CAKV;AAMD,2FAA2F;AAC3F,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,SAAS,MAAM,EAAE,GAAG,OAAO,CAI9E;AAED,2FAA2F;AAC3F,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,GAAG,MAAM,EAAE,CAQrE;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,uBAAuB,CAAC,KAAK,EAAE;IAC7C,QAAQ,CAAC,OAAO,EAAE,eAAe,CAAC;IAClC,QAAQ,CAAC,WAAW,EAAE,SAAS,MAAM,EAAE,CAAC;IACxC,2EAA2E;IAC3E,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,MAAM,EAAE,UAAU,CAAC;IAC5B,QAAQ,CAAC,KAAK,EAAE,MAAM,aAAa,CAAC;CACrC,GAAG,oBAAoB,GAAG,SAAS,CAkBnC;AAED;;;;GAIG;AACH,wBAAgB,mBAAmB,CACjC,GAAG,EAAE,MAAM,EACX,WAAW,EAAE,SAAS,MAAM,EAAE,EAC9B,cAAc,EAAE,SAAS,MAAM,EAAE,EACjC,KAAK,EAAE,aAAa,GACnB,MAAM,EAAE,CAWV;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE;IACvC,QAAQ,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC;IACnC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,aAAa,EAAE,SAAS,MAAM,EAAE,CAAC;IAC1C,0GAA0G;IAC1G,QAAQ,CAAC,kBAAkB,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAChD,uFAAuF;IACvF,QAAQ,CAAC,YAAY,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,SAAS,MAAM,EAAE,CAAC;IAC3D,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IACxC,iFAAiF;IACjF,QAAQ,CAAC,IAAI,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CACnC,GAAG,MAAM,CAqCT"}

package/dist/dispatch/unread-flags.js

@@ -0,0 +1,295 @@
+import { ExitCode, isGateVerb, usageExitFor } from "../exit-codes.js";
+import { GLOBAL_FLAGS, SOFT_FLAGS } from "./global-flags.js";
+import { ReadTrackingMap } from "./read-tracking-map.js";
+import { UNDOCUMENTED_FLAG_READS } from "./undocumented-flag-reads.js";
+import { unknownFlagRefusal } from "./unknown-flag-refusal.js";
+import { UnknownFlagRefusalMode } from "./unknown-flag-refusal-mode.js";
+import { walkDeclaredSubverbs } from "./walk-declared-subverbs.js";
+/**
+ * THE post-run unknown-flag detector (round 11 §5.2) — universal, zero
+ * annotation. `shrk check --tag auth` printed a green sweep at exit 0: `check`
+ * has no `--tag`, the parser accepted it as a flag, nothing read it. Now:
+ *
+ *   - a supplied flag the handler never READ and its usage never DOCUMENTS was
+ *     dropped → stderr names it (with the closest documented flag), and a `0`
+ *     becomes `usageExitFor(path)`: a clean verdict over a dropped input is the
+ *     lie. A non-zero exit is kept.
+ *   - a documented-but-unread flag (`doctor --provider` without
+ *     `--llm-recommendations`) NEVER changes the exit — reading a flag only in
+ *     some modes is legitimate.
+ *   - presentation flags (`SOFT_FLAGS`) are warned about, never escalated.
+ *
+ * Skipped when the handler declares `flags` (the pre-run guard is then
+ * authoritative) or `forwardsArgv` (a child process re-parses the argv, so
+ * this process's reads prove nothing).
+ */
+export function tracksFlagReads(handler, walk) {
+    return handler.forwardsArgv !== true && walk.flags === undefined;
+}
+/**
+ * Swap `parsed.flags` / `parsed.multiFlags` for read-tracking copies (in place)
+ * and return a probe: the supplied flags nothing read, global flags and the
+ * bare `-` (stdin) sentinel excluded. Call the probe after the handler returns.
+ */
+export function beginFlagReadTracking(parsed) {
+    const supplied = [...parsed.flags.keys()];
+    const flags = ReadTrackingMap.from(parsed.flags);
+    const multi = ReadTrackingMap.from(parsed.multiFlags);
+    parsed.flags = flags;
+    parsed.multiFlags = multi;
+    return () => supplied.filter((key) => key.length > 0 && !GLOBAL_FLAGS.has(key) && !flags.wasRead(key) && !multi.wasRead(key));
+}
+/**
+ * Every text that documents the flags of the handler at `matchedPath` AS ITS
+ * USAGE records them: its usage, every declared subverb's usage (nested), and
+ * — from the command index — the usage, catalog row and folded flag variants of
+ * every entry at or below the path. Wider documentation only ever makes the
+ * detector quieter.
+ *
+ * This is the HANDLER-WIDE union — what `r75-flag-read-ledger` holds the
+ * ledger against ("is this flag named anywhere for this handler?"). It is
+ * NOT what an invocation is judged by: since round 13 a flag is a flag of the
+ * subverb that documents it, never of its siblings
+ * ({@link invocationFlagDocumentation}).
+ */
+export function usageFlagDocumentation(handler, matchedPath, index) {
+    const docs = declaredUsages(handler);
+    const prefix = matchedPath.join(' ');
+    for (const e of index.entries) {
+        if (e.path !== prefix && !e.path.startsWith(`${prefix} `))
+            continue;
+        if (e.usage)
+            docs.push(e.usage);
+        if (e.catalogEntry)
+            docs.push(e.catalogEntry.command);
+        docs.push(...e.variants);
+    }
+    return docs;
+}
+/** The handler's own usage and every declared subverb's (nested) — no index needed. */
+function declaredUsages(handler) {
+    const docs = [handler.usage];
+    const addSpecs = (specs) => {
+        for (const spec of specs ?? []) {
+            docs.push(spec.usage);
+            addSpecs(spec.subverbs);
+        }
+    };
+    addSpecs(handler.subverbs);
+    return docs;
+}
+/** `--key`, or `-k` for a one-letter key — how a parsed flag is spelled on the command line. */
+function spellFlag(key) {
+    return `${key.length === 1 ? '-' : '--'}${key}`;
+}
+/**
+ * The usages along an invocation's declared-subverb walk: the handler's own,
+ * then each walked subverb's (`check` → `check templates`). A SIBLING's usage
+ * never appears — `check boundaries` documenting `--fail-on-dead-units` makes
+ * it a flag of `check boundaries`, not of `check` or `check templates`.
+ */
+function walkedUsages(handler, walk, matchedPath) {
+    const docs = [handler.usage];
+    let specs = handler.subverbs;
+    for (const name of walk.path.slice(matchedPath.length)) {
+        const spec = (specs ?? []).find((s) => s.name === name);
+        if (!spec)
+            break;
+        docs.push(spec.usage);
+        specs = spec.subverbs;
+    }
+    return docs;
+}
+/**
+ * THE documentation an INVOCATION's flags are judged by (round 13): the usages
+ * along its declared-subverb walk ({@link walkedUsages}); from the command
+ * index, the usage, catalog row and folded variants of every entry at or below
+ * the handler whose path is a token prefix of the invocation (`check`, `check
+ * templates` for `shrk check templates …` — never `check boundaries`); and the
+ * handler's row of flags its code reads ({@link UNDOCUMENTED_FLAG_READS}).
+ *
+ * Before round 13 the post-run judgement read {@link flagDocumentation} — the
+ * whole group's — so `check --fail-on-dead-units` ran the full sweep at exit 0
+ * (only `check boundaries` documents the flag), and `self-config doctor
+ * --allow-empty` was accepted and ignored because `self-config broken-links`
+ * documents it. Documentation is per subverb, not per group
+ * ({@link settleUnreadFlags}).
+ */
+export function invocationFlagDocumentation(input) {
+    const walk = walkDeclaredSubverbs(input.handler, input.matchedPath, input.positional);
+    const docs = walkedUsages(input.handler, walk, input.matchedPath);
+    const tokens = [...walk.path, ...input.positional.slice(walk.consumed)];
+    for (const e of input.index.entries) {
+        if (e.tokens.length < input.matchedPath.length || e.tokens.length > tokens.length)
+            continue;
+        if (e.tokens.some((t, i) => t !== tokens[i]))
+            continue;
+        if (e.usage)
+            docs.push(e.usage);
+        if (e.catalogEntry)
+            docs.push(e.catalogEntry.command);
+        docs.push(...e.variants);
+    }
+    const read = UNDOCUMENTED_FLAG_READS.get(input.matchedPath.join(' '));
+    if (read !== undefined && read.length > 0)
+        docs.push(read.map(spellFlag).join(' '));
+    return docs;
+}
+/**
+ * What the post-run detector treats as the flags of the handler at
+ * `matchedPath`: its {@link usageFlagDocumentation}, plus the flags its code
+ * READS that the usage does not show yet ({@link UNDOCUMENTED_FLAG_READS}, a
+ * ledger locked two-way against the code by `r75-flag-read-ledger`). With
+ * both, a flag the detector calls "not a flag of this command" is one no code
+ * path of the handler reads (a flag name computed at runtime excepted), so a
+ * `0` over it is a dropped input — never a real flag read behind a branch
+ * (`export claude-md --write --force` on a fresh file wrote it, then exited 2).
+ */
+export function flagDocumentation(handler, matchedPath, index) {
+    const docs = usageFlagDocumentation(handler, matchedPath, index);
+    const read = UNDOCUMENTED_FLAG_READS.get(matchedPath.join(' '));
+    if (read !== undefined && read.length > 0)
+        docs.push(read.map(spellFlag).join(' '));
+    return docs;
+}
+function escapeRegExp(text) {
+    return text.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+/** True when `--key` (or `-k` for a one-letter key) appears as a flag in any of `docs`. */
+export function isFlagDocumented(key, docs) {
+    const dashes = key.length === 1 ? '-' : '--';
+    const re = new RegExp(`(^|[^A-Za-z0-9-])${dashes}${escapeRegExp(key)}(?![A-Za-z0-9-])`);
+    return docs.some((d) => re.test(d));
+}
+/** Every `--flag` named in `docs` — the candidates a refusal's did-you-mean picks from. */
+export function documentedFlagNames(docs) {
+    const names = new Set();
+    for (const d of docs) {
+        for (const m of d.matchAll(/(?:^|[^A-Za-z0-9-])--([a-z0-9][a-z0-9-]*)/gi)) {
+            if (m[1])
+                names.add(m[1]);
+        }
+    }
+    return [...names];
+}
+/**
+ * THE pre-run half of the undocumented-flag rule (round 11 review): a supplied
+ * flag that is not a flag of the command GROUP — named by none of its
+ * {@link flagDocumentation} (its usage and every declared subverb's, the
+ * command index at or below the path, and the two-way-locked ledger of flags
+ * its code reads) — is refused BEFORE the body runs. Whether a flag is
+ * undocumented is static, so nothing justifies running first: `baseline
+ * update --dry-rn` performed the bless write, then exited 3; `check --tag
+ * auth` printed a whole sweep first.
+ *
+ * A flag the group documents only on a SIBLING subverb is judged after the run
+ * instead ({@link settleUnreadFlags} with the invocation's own
+ * {@link invocationFlagDocumentation}, round 13): whether THIS subverb's code
+ * reads it is not static knowledge — a group's shared option is often
+ * documented on one subverb and read by all of them — so refusing it here
+ * would refuse real inputs. The message is THE one refusal format
+ * ({@link unknownFlagRefusal}).
+ *
+ * Presentation flags (`SOFT_FLAGS`) are left to the post-run warning — losing
+ * `--verbose` loses formatting, not an input. The index is built only when the
+ * handler's own usages leave a flag unexplained, so the common run pays
+ * nothing.
+ */
+export function refuseUndocumentedFlags(input) {
+    const supplied = [...input.parsed.flags.keys()].filter((key) => key.length > 0 && !GLOBAL_FLAGS.has(key) && !SOFT_FLAGS.has(key));
+    if (supplied.length === 0)
+        return undefined;
+    const own = declaredUsages(input.handler);
+    const unsure = supplied.filter((key) => !isFlagDocumented(key, own));
+    if (unsure.length === 0)
+        return undefined;
+    const docs = flagDocumentation(input.handler, input.matchedPath, input.index());
+    const undocumented = unsure.filter((key) => !isFlagDocumented(key, docs));
+    if (undocumented.length === 0)
+        return undefined;
+    return unknownFlagRefusal({
+        label: input.label,
+        flags: undocumented,
+        known: documentedFlagNames(docs),
+        argv: input.parsed.argv,
+        exitCode: usageExitFor(input.label),
+    });
+}
+/**
+ * The command paths at or below `matchedPath` (other than the invocation's
+ * own chain) whose documentation names `key` — the sibling subverbs the
+ * refusal points at (`— only \`shrk check boundaries\` documents it`).
+ */
+export function siblingsDocumenting(key, matchedPath, invocationPath, index) {
+    const prefix = matchedPath.join(' ');
+    const own = new Set(invocationPath.map((_, i) => invocationPath.slice(0, i + 1).join(' ')));
+    const out = [];
+    for (const e of index.entries) {
+        if (e.path !== prefix && !e.path.startsWith(`${prefix} `))
+            continue;
+        if (own.has(e.path))
+            continue;
+        const docs = [e.usage ?? '', e.catalogEntry?.command ?? '', ...e.variants];
+        if (isFlagDocumented(key, docs))
+            out.push(e.path);
+    }
+    return out.slice(0, 3);
+}
+/**
+ * Judge the unread flags of a finished run against the INVOCATION's
+ * documentation (`documentation`: {@link invocationFlagDocumentation} — the
+ * subverb's own, never a sibling's):
+ *
+ *   - a flag named by no documentation of the group: warned, and a `0`
+ *     becomes `usageExitFor(path)` (the backstop for a name computed at
+ *     runtime — the pre-run judgement refuses the rest);
+ *   - round 13 — a flag only a SIBLING subverb documents (`groupDocumentation`
+ *     names it, the invocation's does not) that this run never read is REFUSED
+ *     like any dropped flag: a `0` becomes `usageExitFor(path)` on every verb,
+ *     and on a verdict verb a `2` does too (a found failure `1` is kept).
+ *     `check --fail-on-dead-units` ran the sweep at exit 0 (only `check
+ *     boundaries` documents the flag); `self-config doctor --allow-empty`
+ *     ignored it; `registrations list --fail-on-dead-units` kept its 0 with a
+ *     warning (round 13 review — documentation is per subverb on every verb). A
+ *     sibling-documented flag the run READ is a real input and never judged.
+ *
+ * Presentation flags (`SOFT_FLAGS`) are only ever warned about. Returns `exit`
+ * unchanged when nothing is judged.
+ */
+export function settleUnreadFlags(input) {
+    const write = input.write ?? ((text) => void process.stderr.write(text));
+    const undocumented = input.unread.filter((key) => !isFlagDocumented(key, input.documentation));
+    if (undocumented.length === 0)
+        return input.exit;
+    const group = input.groupDocumentation;
+    const siblingOnly = new Set(group ? undocumented.filter((key) => isFlagDocumented(key, group)) : []);
+    const dropped = undocumented.filter((key) => !SOFT_FLAGS.has(key));
+    const droppedNowhere = dropped.filter((key) => !siblingOnly.has(key));
+    const droppedSibling = dropped.filter((key) => siblingOnly.has(key));
+    const code = usageExitFor(input.path);
+    // A flag the invocation's documentation does not name is a dropped input
+    // whether NO subverb documents it or only a SIBLING does — both are "not a
+    // flag of this command": a `0` over it is refused on every verb. On a
+    // verdict verb a sibling-only flag refuses a `2` too (a NOT VERIFIED that
+    // silently dropped `--allow-empty` reads as the verb's own answer).
+    const refuse = input.exit !== code &&
+        ((input.exit === ExitCode.VerifiedPass && dropped.length > 0) ||
+            (droppedSibling.length > 0 && isGateVerb(input.path) && input.exit !== ExitCode.Failure));
+    const final = refuse ? code : input.exit;
+    const documentedOn = {};
+    for (const key of siblingOnly) {
+        const owners = input.documentedOn?.(key) ?? [];
+        if (owners.length > 0)
+            documentedOn[key] = owners;
+    }
+    write(unknownFlagRefusal({
+        label: input.path,
+        flags: undocumented,
+        known: documentedFlagNames(input.documentation),
+        documentedOn,
+        ...(input.argv !== undefined ? { argv: input.argv } : {}),
+        exitCode: final,
+        mode: refuse ? UnknownFlagRefusalMode.RefusedAfterRun : UnknownFlagRefusalMode.WarnedAfterRun,
+    }).message);
+    return final;
+}

package/dist/dispatch/verdict-valve-flag.d.ts

@@ -0,0 +1,21 @@
+/**
+ * The VERDICT-VALVE flags (round 13, K1) — the closed set of flags that change
+ * what a verdict verb's exit MEANS: a gap it accepts (`--allow-empty`,
+ * `--min-referenced`) or a unit it fails on (`--fail-on-dead-units`,
+ * `--fail-on`). None is a global flag.
+ *
+ * A valve flag the resolved subverb does not document is refused BEFORE the run
+ * (`refuseSiblingValveFlags`, inside the one `judgeInvocation`): a run that
+ * ignored a valve reads as the verb's own answer — `shrk check
+ * --fail-on-dead-units` printed the whole sweep and only then exited 3. Every
+ * other sibling-documented flag keeps the post-run judgement, because whether
+ * a subverb's code reads a shared option is not static knowledge; a valve is
+ * the one kind whose reader is always the documenting verb.
+ */
+export declare enum VerdictValveFlag {
+    FailOnDeadUnits = "fail-on-dead-units",
+    AllowEmpty = "allow-empty",
+    MinReferenced = "min-referenced",
+    FailOn = "fail-on"
+}
+//# sourceMappingURL=verdict-valve-flag.d.ts.map

package/dist/dispatch/verdict-valve-flag.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"verdict-valve-flag.d.ts","sourceRoot":"","sources":["../../src/dispatch/verdict-valve-flag.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AACH,oBAAY,gBAAgB;IAC1B,eAAe,uBAAuB;IACtC,UAAU,gBAAgB;IAC1B,aAAa,mBAAmB;IAChC,MAAM,YAAY;CACnB"}

package/dist/dispatch/verdict-valve-flag.js

@@ -0,0 +1,21 @@
+/**
+ * The VERDICT-VALVE flags (round 13, K1) — the closed set of flags that change
+ * what a verdict verb's exit MEANS: a gap it accepts (`--allow-empty`,
+ * `--min-referenced`) or a unit it fails on (`--fail-on-dead-units`,
+ * `--fail-on`). None is a global flag.
+ *
+ * A valve flag the resolved subverb does not document is refused BEFORE the run
+ * (`refuseSiblingValveFlags`, inside the one `judgeInvocation`): a run that
+ * ignored a valve reads as the verb's own answer — `shrk check
+ * --fail-on-dead-units` printed the whole sweep and only then exited 3. Every
+ * other sibling-documented flag keeps the post-run judgement, because whether
+ * a subverb's code reads a shared option is not static knowledge; a valve is
+ * the one kind whose reader is always the documenting verb.
+ */
+export var VerdictValveFlag;
+(function (VerdictValveFlag) {
+    VerdictValveFlag["FailOnDeadUnits"] = "fail-on-dead-units";
+    VerdictValveFlag["AllowEmpty"] = "allow-empty";
+    VerdictValveFlag["MinReferenced"] = "min-referenced";
+    VerdictValveFlag["FailOn"] = "fail-on";
+})(VerdictValveFlag || (VerdictValveFlag = {}));

package/dist/dispatch/walk-declared-subverbs.d.ts

@@ -0,0 +1,14 @@
+import type { ICommandHandler } from '../command-registry.js';
+import type { IDeclaredInvocation } from './i-declared-invocation.js';
+/**
+ * Walk `positional` through the subverbs `handler` DECLARES (nested ones
+ * included): each positional naming a declared subverb (or one of its aliases)
+ * descends one level; the first that does not stops the walk. The declared flag
+ * sets met on the way are unioned — `graph` declares none, `graph cycles`
+ * declares its own, so `graph cycles --x` is judged against the cycles set.
+ *
+ * Pure; the dispatcher guard, the help topic and the post-run detector all
+ * read the same walk, so they cannot disagree about which subverb ran.
+ */
+export declare function walkDeclaredSubverbs(handler: ICommandHandler, matchedPath: readonly string[], positional: readonly string[]): IDeclaredInvocation;
+//# sourceMappingURL=walk-declared-subverbs.d.ts.map

package/dist/dispatch/walk-declared-subverbs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"walk-declared-subverbs.d.ts","sourceRoot":"","sources":["../../src/dispatch/walk-declared-subverbs.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AAC9D,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,4BAA4B,CAAC;AAEtE;;;;;;;;;GASG;AACH,wBAAgB,oBAAoB,CAClC,OAAO,EAAE,eAAe,EACxB,WAAW,EAAE,SAAS,MAAM,EAAE,EAC9B,UAAU,EAAE,SAAS,MAAM,EAAE,GAC5B,mBAAmB,CAiBrB"}

package/dist/dispatch/walk-declared-subverbs.js

@@ -0,0 +1,28 @@
+/**
+ * Walk `positional` through the subverbs `handler` DECLARES (nested ones
+ * included): each positional naming a declared subverb (or one of its aliases)
+ * descends one level; the first that does not stops the walk. The declared flag
+ * sets met on the way are unioned — `graph` declares none, `graph cycles`
+ * declares its own, so `graph cycles --x` is judged against the cycles set.
+ *
+ * Pure; the dispatcher guard, the help topic and the post-run detector all
+ * read the same walk, so they cannot disagree about which subverb ran.
+ */
+export function walkDeclaredSubverbs(handler, matchedPath, positional) {
+    const path = [...matchedPath];
+    let level = handler;
+    let flags = handler.flags ? new Set(handler.flags) : undefined;
+    let consumed = 0;
+    while (consumed < positional.length) {
+        const token = positional[consumed];
+        const match = (level.subverbs ?? []).find((s) => s.name === token || (s.aliases ?? []).includes(token));
+        if (!match)
+            break;
+        path.push(match.name);
+        level = match;
+        if (match.flags)
+            flags = new Set([...(flags ?? []), ...match.flags]);
+        consumed += 1;
+    }
+    return { path, level, consumed, ...(flags ? { flags } : {}) };
+}

package/dist/exit-codes.d.ts

@@ -62,13 +62,51 @@ export declare function argvHasStrict(argv: readonly string[]): boolean;
  * channel the pipe can't swallow. See {@link emitPipeExitSignal}.
  */
 export declare function argvHasExitTrailer(argv: readonly string[]): boolean;
+/**
+ * THE verdict-verb registry: command paths (space-joined, as `runCli` derives
+ * them with `extractCommandPath(argv, VERDICT_PATH_TOKENS)` — at most THREE
+ * leading positional tokens) whose exit code is an HONEST verdict an agent
+ * chains on — the set for which a masked exit is a real hazard.
+ *
+ * Register the SHORTEST path that is a verdict and nothing wider: `docs
+ * references check` is three tokens because its siblings `docs references
+ * list` / `explain` are informational, and registering `docs references` would
+ * make them verdict verbs too (the trailer would print `shrk-exit: 0` for a
+ * listing). A two-token entry covers every deeper path under it.
+ *
+ * Membership enables {@link emitPipeExitSignal}'s stderr note and the
+ * `--exit-trailer` line, never behaviour. It is also the list the round-11
+ * contract test iterates: every entry must have a row in
+ * `r75-verdict-coverage-contract.test.ts`, every verb that builds a gate
+ * envelope must be in here, and every CLI file that settles a verdict through
+ * `settleVerdict(` names its verbs (each registered) or a reasoned exemption in
+ * that test's two-way settle-site ledger. A NEW verdict verb therefore adds itself here, or
+ * CI fails — the registry and the contract cannot drift apart.
+ */
+export declare const GATE_VERB_PATHS: ReadonlySet<string>;
+/**
+ * How many leading positional tokens `runCli` reads to decide whether a verb is
+ * a verdict verb — the deepest {@link GATE_VERB_PATHS} entry. (Usage logging
+ * keeps its own two-token paths; this only feeds {@link emitPipeExitSignal}.)
+ */
+export declare const VERDICT_PATH_TOKENS = 3;
 /**
  * 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.
+ * / `finish` / `docs references check`) a gate/verify verb whose exit code
+ * carries a chained verdict? Matches the exact path or any of its one-, two- or
+ * three-token prefixes — so `check boundaries --json`, a bare `finish` and
+ * `graph why a b` all resolve, while `docs references list` does not.
  */
 export declare function isGateVerb(commandPath: string): boolean;
+/**
+ * The exit code for a malformed invocation of `commandPath` — an unknown
+ * subcommand, an unknown flag, a verb-shaped token that is no subverb and no
+ * file, an input the command silently ignored. THE documented split: `3`
+ * (UsageError) on a verdict verb, whose `2` must keep meaning "ran but proved
+ * nothing"; `2` everywhere else. The dispatcher guard and the post-run
+ * unknown-flag detector both read it, so one invocation mistake exits one way.
+ */
+export declare function usageExitFor(commandPath: string): number;
 /**
  * True when the argv carries the global `--no-hints` (before the `--`
  * sentinel). Suppresses advisory one-liners like the piped-exit note while

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;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,oBAAY,QAAQ;IAClB,YAAY,IAAI;IAChB,OAAO,IAAI;IACX,WAAW,IAAI;IACf,UAAU,IAAI;CACf;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;;;;;;GAMG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,GAAG,OAAO,CAM/D;AASD,qDAAqD;AACrD,wBAAgB,kBAAkB,IAAI,IAAI,CAEzC;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,8EAA8E;IAC9E,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,CAAC;IAC3B,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,CAgBN"}
+{"version":3,"file":"exit-codes.d.ts","sourceRoot":"","sources":["../src/exit-codes.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,oBAAY,QAAQ;IAClB,YAAY,IAAI;IAChB,OAAO,IAAI;IACX,WAAW,IAAI;IACf,UAAU,IAAI;CACf;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;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,eAAO,MAAM,eAAe,EAAE,WAAW,CAAC,MAAM,CA4H9C,CAAC;AAEH;;;;GAIG;AACH,eAAO,MAAM,mBAAmB,IAAI,CAAC;AAErC;;;;;;GAMG;AACH,wBAAgB,UAAU,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAOvD;AAED;;;;;;;GAOG;AACH,wBAAgB,YAAY,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,CAExD;AAED;;;;;;GAMG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,GAAG,OAAO,CAM/D;AASD,qDAAqD;AACrD,wBAAgB,kBAAkB,IAAI,IAAI,CAEzC;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,8EAA8E;IAC9E,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,CAAC;IAC3B,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,CAgBN"}