spec-controller 0.1.0-alpha.5 → 0.1.0-alpha.50

package/dist/cli-allocate/unreadable.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"unreadable.js","sourceRoot":"","sources":["../../src/cli-allocate/unreadable.ts"],"names":[],"mappings":"AAAA,MAAM,OAAO,eAAgB,SAAQ,KAAK;IAI7B;IACA;IACA;IALO,IAAI,GAAG,iBAAiB,CAAC;IAE3C,YACW,OAAe,EACf,IAAY,EACZ,MAAc;QAEvB,KAAK,CAAC,IAAI,KAAK,EAAE,CAAC,CAAC,CAAC,GAAG,OAAO,uBAAuB,MAAM,GAAG,CAAC,CAAC,CAAC,GAAG,OAAO,uBAAuB,IAAI,KAAK,MAAM,GAAG,CAAC,CAAC;QAJ7G,YAAO,GAAP,OAAO,CAAQ;QACf,SAAI,GAAJ,IAAI,CAAQ;QACZ,WAAM,GAAN,MAAM,CAAQ;IAGzB,CAAC;CACF;AAED,MAAM,UAAU,YAAY,CAAI,OAAe,EAAE,IAAY,EAAE,IAAa;IAC1E,IAAI,CAAC;QACH,OAAO,IAAI,EAAE,CAAC;IAChB,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,OAAO,MAAM,CAAC,OAAO,EAAE,IAAI,EAAE,GAAG,CAAC,CAAC;IACpC,CAAC;AACH,CAAC;AAED,MAAM,UAAU,MAAM,CAAC,OAAe,EAAE,IAAY,EAAE,GAAY;IAChE,MAAM,KAAK,GAAG,GAA4B,CAAC;IAC3C,IAAI,CAAC,CAAC,GAAG,YAAY,KAAK,CAAC,IAAI,OAAO,KAAK,CAAC,IAAI,KAAK,QAAQ;QAAE,MAAM,GAAG,CAAC;IACzE,MAAM,IAAI,eAAe,CAAC,OAAO,EAAE,KAAK,CAAC,IAAI,IAAI,IAAI,EAAE,GAAG,CAAC,OAAO,CAAC,CAAC;AACtE,CAAC;AAED,MAAM,UAAU,WAAW,CAAC,OAAwB;IAClD,OAAO,2CAA2C,OAAO,CAAC,OAAO,EAAE,CAAC;AACtE,CAAC"}

package/dist/cli-args.d.ts

@@ -1,73 +1,15 @@
-/**
- * THE ONE READING OF A COMMAND'S ARGV, and the one bounding of it against the registry.
- *
- * WHY IT IS ITS OWN MODULE (3F-3300). Both halves lived inside `cli-balance/cli.ts` while
- * `balance` was the only command — `parseArgs` private to it, `checkUnknownFlags` exported for
- * its own `@unit` arm. A second command needs both, and the two ways of giving it them were
- * worse than moving them: copying `parseArgs` would put a second reading of argv in a tree whose
- * whole subject is second readings, and importing them from `cli-balance/cli.ts` would have the
- * corpus command pull the entire reconcile ingest chain into memory to answer a question about
- * feature files.
- *
- * THE BOUNDING IS PER-COMMAND, which is what makes "accepted = registry = help" hold for every
- * command rather than for the one this code was written beside. `checkUnknownFlags` took the
- * registry and looked `balance` up inside itself; the command is a parameter now, exactly as it
- * became one for `renderCommandHelp` (3F-3298). @SCN-CLI-009's scenario is unchanged and still
- * asks about `balance`: what a second command gets is the same bounding BY CONSTRUCTION, and the
- * residual — that an unregistered flag to `tags` is unproven by a scenario of its own — is named
- * on 3F-3286 rather than left silent.
- */
-import type { CliRegistry } from "./cli-registry.js";
-/**
- * Parse `--flag value` pairs from a command's argv into a record, keys with the `--` stripped.
- *
- * A flag whose next token is another flag (or absent) records the string `"true"`, which is how
- * the boolean flags — `--strict`, `--help` — are recognised: presence is what matters, so callers
- * read them with `!== undefined`.
- *
- * PERMISSIVE BY ITSELF, AND BOUNDED BY THE CALLER. It records whatever it is given, including a
- * flag no registry names; `checkUnknownFlags` below is what turns that into a usage error. The
- * split is deliberate — the parse has no opinion about which command it is reading for, and the
- * bounding has nothing else to do.
- */
+import type { CliRegistry, FlagSpec } from "./cli-registry.js";
+export declare function asksForHelp(argv: readonly string[]): boolean;
 export declare function parseArgs(argv: readonly string[]): Record<string, string>;
-/**
- * The registry-bounded flag check at a command's CLI edge (@SCN-CLI-009). A command accepts ONLY
- * the flags its per-command registry scope LISTS (by `name` or `alias`); an unregistered flag — a
- * typo like `--strcit`, a stray `--bogus` — is a usage error, NOT silently swallowed the way the
- * permissive parse above would leave it. This is the structural teeth behind "accepted = registry
- * = help": a flag cannot affect behaviour without a registry entry, and so (by @SCN-CLI-008's
- * guard) without appearing in that command's help.
- *
- * PURE and `@unit`-testable: the parsed args (keys already `--`-stripped) plus the registry and
- * the command to bound against, returning the FIRST unregistered flag as a typed usage error
- * naming it WITH its dashes — routed to stderr and the enumerated usage status 2 by the caller,
- * never 1, never a silent run — else null. The global `--store`/`--run-id` modifiers never reach
- * here: the top-level dispatcher consumes them BEFORE any command is dispatched, so a bounded
- * parse sees only the command's own args.
- *
- * A COMMAND THE REGISTRY DOES NOT NAME ACCEPTS NOTHING, which is the honest reading rather than a
- * degenerate one: an unregistered command has no scope, so every flag given to it is outside it.
- * The dispatcher refuses such a command before this is ever reached, so the case is unreachable
- * today and stated here so it cannot become a silent "accept everything" later.
- *
- * IT NAMES THE VERSION THAT REFUSED, AND THAT IS FOR THE PINNED READER (3F-3105, @SCN-CLI-009).
- * A consumer pins spec-controller and then moves their own tree; the pinned reader is handed argv
- * it was published too early — or too late — to understand, and an unadorned "unknown flag" is
- * indistinguishable from a typo. Naming the running version makes version skew legible from the CI
- * log alone, and naming the bump says what to do about it. `toolVersion` is a PARAMETER rather than
- * a read performed here so this stays pure and `@unit`-testable; the callers pass
- * `resolveToolIdentity().toolVersion`, the same value the report provenance carries.
- *
- * WHY THE PRODUCT SAYS THIS AND NOT THE CONSUMER. spec-controller's own repository is a consumer of
- * its published self, and the ruling there is that it does NOT wrap itself — a dependency, a `run:`
- * step, and the verdict its exit code gives. A consumer-side translator turning exit 2 into a skew
- * refusal is exactly that forbidden wrapper, and no other adopter could write one either. So the
- * refusal is the tool's own, which makes it universal rather than local.
- *
- * THE STATUS DOES NOT MOVE. The caller still routes this to stderr and exit 2. A mistyped `--strcit`
- * is still a usage fault, and giving skew its own status would cost every adopter the ordinary
- * reading to serve the rarer one.
- */
+export declare function valueFlagsOf(flags: readonly FlagSpec[]): Map<string, FlagSpec>;
+export declare function isMissingValue(next: string | undefined): boolean;
+export declare function checkMissingValues(argv: readonly string[], registry: CliRegistry, command: string): string | null;
+export declare function missingValueRefusal(given: string, flag: FlagSpec, scope: string): string;
+export declare function checkArgvShape(argv: readonly string[], registry: CliRegistry, command: string): string | null;
+export declare function positionalArguments(argv: readonly string[], registry: CliRegistry, command: string): string[];
+export declare function givenTwiceRefusal(given: string, scope: string): string;
+export declare function isEqualsForm(token: string): boolean;
+export declare function equalsFormRefusal(token: string, flags: ReadonlyMap<string, FlagSpec>, scope: string): string;
+export declare function checkMisplacedHostModifiers(args: Record<string, string>, registry: CliRegistry, command: string): string | null;
 export declare function checkUnknownFlags(args: Record<string, string>, registry: CliRegistry, command: string, toolVersion: string): string | null;
 //# sourceMappingURL=cli-args.d.ts.map

package/dist/cli-args.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cli-args.d.ts","sourceRoot":"","sources":["../src/cli-args.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAErD;;;;;;;;;;;GAWG;AACH,wBAAgB,SAAS,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAgBzE;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AACH,wBAAgB,iBAAiB,CAC/B,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EAC5B,QAAQ,EAAE,WAAW,EACrB,OAAO,EAAE,MAAM,EACf,WAAW,EAAE,MAAM,GAClB,MAAM,GAAG,IAAI,CA0Bf"}
+{"version":3,"file":"cli-args.d.ts","sourceRoot":"","sources":["../src/cli-args.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAe,QAAQ,EAAkB,MAAM,mBAAmB,CAAC;AAE5F,wBAAgB,WAAW,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,GAAG,OAAO,CAE5D;AAED,wBAAgB,SAAS,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAgBzE;AAED,wBAAgB,YAAY,CAAC,KAAK,EAAE,SAAS,QAAQ,EAAE,GAAG,GAAG,CAAC,MAAM,EAAE,QAAQ,CAAC,CAO9E;AAED,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,GAAG,OAAO,CAEhE;AAED,wBAAgB,kBAAkB,CAChC,IAAI,EAAE,SAAS,MAAM,EAAE,EACvB,QAAQ,EAAE,WAAW,EACrB,OAAO,EAAE,MAAM,GACd,MAAM,GAAG,IAAI,CAUf;AAED,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,QAAQ,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAKxF;AAED,wBAAgB,cAAc,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,EAAE,QAAQ,EAAE,WAAW,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAW7G;AAaD,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,EAAE,QAAQ,EAAE,WAAW,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,EAAE,CAS7G;AA2BD,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAKtE;AAcD,wBAAgB,YAAY,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAEnD;AAED,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,WAAW,CAAC,MAAM,EAAE,QAAQ,CAAC,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAW5G;AAsCD,wBAAgB,2BAA2B,CACzC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EAC5B,QAAQ,EAAE,WAAW,EACrB,OAAO,EAAE,MAAM,GACd,MAAM,GAAG,IAAI,CASf;AAED,wBAAgB,iBAAiB,CAC/B,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EAC5B,QAAQ,EAAE,WAAW,EACrB,OAAO,EAAE,MAAM,EACf,WAAW,EAAE,MAAM,GAClB,MAAM,GAAG,IAAI,CAoBf"}

package/dist/cli-args.js

@@ -1,34 +1,6 @@
-/**
- * THE ONE READING OF A COMMAND'S ARGV, and the one bounding of it against the registry.
- *
- * WHY IT IS ITS OWN MODULE (3F-3300). Both halves lived inside `cli-balance/cli.ts` while
- * `balance` was the only command — `parseArgs` private to it, `checkUnknownFlags` exported for
- * its own `@unit` arm. A second command needs both, and the two ways of giving it them were
- * worse than moving them: copying `parseArgs` would put a second reading of argv in a tree whose
- * whole subject is second readings, and importing them from `cli-balance/cli.ts` would have the
- * corpus command pull the entire reconcile ingest chain into memory to answer a question about
- * feature files.
- *
- * THE BOUNDING IS PER-COMMAND, which is what makes "accepted = registry = help" hold for every
- * command rather than for the one this code was written beside. `checkUnknownFlags` took the
- * registry and looked `balance` up inside itself; the command is a parameter now, exactly as it
- * became one for `renderCommandHelp` (3F-3298). @SCN-CLI-009's scenario is unchanged and still
- * asks about `balance`: what a second command gets is the same bounding BY CONSTRUCTION, and the
- * residual — that an unregistered flag to `tags` is unproven by a scenario of its own — is named
- * on 3F-3286 rather than left silent.
- */
-/**
- * Parse `--flag value` pairs from a command's argv into a record, keys with the `--` stripped.
- *
- * A flag whose next token is another flag (or absent) records the string `"true"`, which is how
- * the boolean flags — `--strict`, `--help` — are recognised: presence is what matters, so callers
- * read them with `!== undefined`.
- *
- * PERMISSIVE BY ITSELF, AND BOUNDED BY THE CALLER. It records whatever it is given, including a
- * flag no registry names; `checkUnknownFlags` below is what turns that into a usage error. The
- * split is deliberate — the parse has no opinion about which command it is reading for, and the
- * bounding has nothing else to do.
- */
+export function asksForHelp(argv) {
+    return argv.includes("--help") || argv.includes("-h");
+}
 export function parseArgs(argv) {
     const args = {};
     for (let i = 0; i < argv.length; i++) {
@@ -47,49 +19,146 @@ export function parseArgs(argv) {
     }
     return args;
 }
-/**
- * The registry-bounded flag check at a command's CLI edge (@SCN-CLI-009). A command accepts ONLY
- * the flags its per-command registry scope LISTS (by `name` or `alias`); an unregistered flag — a
- * typo like `--strcit`, a stray `--bogus` — is a usage error, NOT silently swallowed the way the
- * permissive parse above would leave it. This is the structural teeth behind "accepted = registry
- * = help": a flag cannot affect behaviour without a registry entry, and so (by @SCN-CLI-008's
- * guard) without appearing in that command's help.
- *
- * PURE and `@unit`-testable: the parsed args (keys already `--`-stripped) plus the registry and
- * the command to bound against, returning the FIRST unregistered flag as a typed usage error
- * naming it WITH its dashes — routed to stderr and the enumerated usage status 2 by the caller,
- * never 1, never a silent run — else null. The global `--store`/`--run-id` modifiers never reach
- * here: the top-level dispatcher consumes them BEFORE any command is dispatched, so a bounded
- * parse sees only the command's own args.
- *
- * A COMMAND THE REGISTRY DOES NOT NAME ACCEPTS NOTHING, which is the honest reading rather than a
- * degenerate one: an unregistered command has no scope, so every flag given to it is outside it.
- * The dispatcher refuses such a command before this is ever reached, so the case is unreachable
- * today and stated here so it cannot become a silent "accept everything" later.
- *
- * IT NAMES THE VERSION THAT REFUSED, AND THAT IS FOR THE PINNED READER (3F-3105, @SCN-CLI-009).
- * A consumer pins spec-controller and then moves their own tree; the pinned reader is handed argv
- * it was published too early — or too late — to understand, and an unadorned "unknown flag" is
- * indistinguishable from a typo. Naming the running version makes version skew legible from the CI
- * log alone, and naming the bump says what to do about it. `toolVersion` is a PARAMETER rather than
- * a read performed here so this stays pure and `@unit`-testable; the callers pass
- * `resolveToolIdentity().toolVersion`, the same value the report provenance carries.
- *
- * WHY THE PRODUCT SAYS THIS AND NOT THE CONSUMER. spec-controller's own repository is a consumer of
- * its published self, and the ruling there is that it does NOT wrap itself — a dependency, a `run:`
- * step, and the verdict its exit code gives. A consumer-side translator turning exit 2 into a skew
- * refusal is exactly that forbidden wrapper, and no other adopter could write one either. So the
- * refusal is the tool's own, which makes it universal rather than local.
- *
- * THE STATUS DOES NOT MOVE. The caller still routes this to stderr and exit 2. A mistyped `--strcit`
- * is still a usage fault, and giving skew its own status would cost every adopter the ordinary
- * reading to serve the rarer one.
- */
+export function valueFlagsOf(flags) {
+    const valueFlags = new Map();
+    for (const flag of flags) {
+        if (flag.arg === undefined)
+            continue;
+        for (const name of [flag.name, ...(flag.aliases ?? [])])
+            valueFlags.set(name, flag);
+    }
+    return valueFlags;
+}
+export function isMissingValue(next) {
+    return next === undefined || next === "" || next.startsWith("--");
+}
+export function checkMissingValues(argv, registry, command) {
+    const entry = registry.commands.find((c) => c.name === command);
+    const valueFlags = valueFlagsOf(entry?.flags ?? []);
+    for (let i = 0; i < argv.length; i++) {
+        const flag = valueFlags.get(argv[i] ?? "");
+        if (flag !== undefined && isMissingValue(argv[i + 1])) {
+            return missingValueRefusal(argv[i] ?? flag.name, flag, `spec-controller ${command}`);
+        }
+    }
+    return null;
+}
+export function missingValueRefusal(given, flag, scope) {
+    return (`The ${given} flag of '${scope}' needs a value — ${given} ${flag.arg ?? ""} — and was given none.\n` +
+        `Run '${scope} --help' to see the flags this version accepts and the values they take.`);
+}
+export function checkArgvShape(argv, registry, command) {
+    const scope = flagScopeOf(registry, command);
+    const seen = new Set();
+    const positionals = positionalsOf(registry, command);
+    const walk = { scope, seen, positionals, slotsLeft: positionals.length };
+    for (let i = 0; i < argv.length; i++) {
+        const read = readToken(argv, i, walk, command);
+        if (typeof read === "string")
+            return read;
+        i += read;
+    }
+    return null;
+}
+function positionalsOf(registry, command) {
+    return registry.commands.find((c) => c.name === command)?.positionals ?? [];
+}
+export function positionalArguments(argv, registry, command) {
+    const scope = flagScopeOf(registry, command);
+    const words = [];
+    for (let i = 0; i < argv.length; i++) {
+        const token = argv[i] ?? "";
+        if (!isFlagShaped(token))
+            words.push(token);
+        else if (scope.get(token)?.arg !== undefined)
+            i++;
+    }
+    return words;
+}
+function readToken(argv, i, walk, command) {
+    const token = argv[i] ?? "";
+    const next = argv[i + 1];
+    if (isEqualsForm(token))
+        return equalsFormRefusal(token, walk.scope, `spec-controller ${command}`);
+    if (!isFlagShaped(token) && !walk.scope.has(token))
+        return positionalRead(token, walk, command);
+    const flag = walk.scope.get(token);
+    if (flag === undefined)
+        return valueTokensAfter(undefined, next);
+    return registeredFlagRefusal(flag, token, next, walk, command) ?? valueTokensAfter(flag, next);
+}
+function registeredFlagRefusal(flag, token, next, walk, command) {
+    if (walk.seen.has(flag) && flag.repeatable !== true)
+        return givenTwiceRefusal(token, `spec-controller ${command}`);
+    walk.seen.add(flag);
+    if (flag.arg === undefined && next !== undefined && !isFlagShaped(next) && !walk.scope.has(next) && walk.slotsLeft === 0) {
+        return takesNoValueRefusal(token, next, command);
+    }
+    return undefined;
+}
+export function givenTwiceRefusal(given, scope) {
+    return (`The ${given} flag of '${scope}' was given more than once, and is read once: give it once.\n` +
+        `Run '${scope} --help' to see the flags this version accepts.`);
+}
+function flagScopeOf(registry, command) {
+    const scope = new Map();
+    for (const flag of registry.commands.find((c) => c.name === command)?.flags ?? []) {
+        for (const name of [flag.name, ...(flag.aliases ?? [])])
+            scope.set(name, flag);
+    }
+    return scope;
+}
+function isFlagShaped(token) {
+    return token.startsWith("--");
+}
+export function isEqualsForm(token) {
+    return isFlagShaped(token) && token.includes("=");
+}
+export function equalsFormRefusal(token, flags, scope) {
+    const at = token.indexOf("=");
+    const name = token.slice(0, at);
+    const value = token.slice(at + 1);
+    const flag = flags.get(name);
+    const spelling = flag !== undefined && flag.arg === undefined ? name : `${name} ${value === "" ? (flag?.arg ?? "<value>") : value}`;
+    return (`The ${token} form is not read by '${scope}': a flag and its value are two arguments, as in '${spelling}'.\n` +
+        `Run '${scope} --help' to see the flags this version accepts.`);
+}
+function valueTokensAfter(flag, next) {
+    if (next === undefined || isFlagShaped(next))
+        return 0;
+    return flag === undefined || flag.arg !== undefined ? 1 : 0;
+}
+function takesNoValueRefusal(flag, value, command) {
+    return (`The ${flag} flag of 'spec-controller ${command}' takes no value, and was given one: '${value}'.\n` +
+        `Run 'spec-controller ${command} --help' to see the flags this version accepts and the values they take.`);
+}
+function positionalRead(token, walk, command) {
+    if (walk.slotsLeft === 0) {
+        return walk.positionals.length === 0 ? notAFlagRefusal(token, command) : extraPositionalRefusal(token, walk, command);
+    }
+    walk.slotsLeft--;
+    return 0;
+}
+function extraPositionalRefusal(token, walk, command) {
+    const takes = walk.positionals.map((positional) => positional.name).join(" ");
+    return (`The argument '${token}' is more than 'spec-controller ${command}' takes: it takes ${takes} once, and its flags.\n` +
+        `Run 'spec-controller ${command} --help' to see what this version accepts.`);
+}
+function notAFlagRefusal(token, command) {
+    return (`The argument '${token}' is not a flag, nor the value of the flag before it: ` +
+        `'spec-controller ${command}' takes only flags and their values.\n` +
+        `Run 'spec-controller ${command} --help' to see the flags this version accepts.`);
+}
+export function checkMisplacedHostModifiers(args, registry, command) {
+    const modifiers = new Set(registry.global.map((flag) => flag.name.replace(/^-+/, "")));
+    const key = Object.keys(args).find((k) => modifiers.has(k));
+    if (key === undefined)
+        return null;
+    return (`The --${key} flag is a host modifier: it goes before the command, as in ` +
+        `'spec-controller --${key} <value> ${command} …', never after it.\n` +
+        `Run 'spec-controller --help' to see the host modifiers this version accepts.`);
+}
 export function checkUnknownFlags(args, registry, command, toolVersion) {
-    // The accepted set: every flag name AND alias in THIS command's scope, with the leading dashes
-    // stripped so it compares against the parse's `--`-stripped keys (e.g. "--features" and "-h"
-    // become "features" and "h"). Built from the registry alone — the single source — so
-    // "accepted = registry" holds by construction.
     const entry = registry.commands.find((c) => c.name === command);
     const accepted = new Set();
     for (const flag of entry?.flags ?? []) {
@@ -97,18 +166,26 @@ export function checkUnknownFlags(args, registry, command, toolVersion) {
         for (const alias of flag.aliases ?? [])
             accepted.add(alias.replace(/^-+/, ""));
     }
-    // The FIRST parsed flag not in the accepted set is the reported error (Object.keys is argv
-    // order, so this is deterministic). The message names the flag WITH its dashes, and the command
-    // whose scope refused it — a consumer running two commands needs to know which help to open.
     for (const key of Object.keys(args)) {
         if (!accepted.has(key)) {
-            return (`Unknown flag --${key} for 'spec-controller ${command}' — this is spec-controller ` +
-                `${toolVersion}, and that flag is not in its ${command} scope.\n` +
-                `If this version is pinned, the pin and the tree it is reading have drifted apart: ` +
-                `bump the pin to a version whose '${command}' accepts --${key}.\n` +
-                `Otherwise run 'spec-controller ${command} --help' to see the flags this version accepts.`);
+            return (retiredFlagRefusal(entry, key, command, toolVersion) ??
+                `Unknown flag --${key} for 'spec-controller ${command}' — this is spec-controller ` +
+                    `${toolVersion}, and that flag is not in its ${command} scope.\n` +
+                    `If this version is pinned, the pin and the tree it is reading have drifted apart: ` +
+                    `bump the pin to a version whose '${command}' accepts --${key}.\n` +
+                    `Otherwise run 'spec-controller ${command} --help' to see the flags this version accepts.`);
         }
     }
     return null;
 }
+function retiredFlagRefusal(entry, key, command, toolVersion) {
+    const retired = entry?.retiredFlags?.find((flag) => flag.name.replace(/^-+/, "") === key);
+    if (retired === undefined)
+        return undefined;
+    return (`Retired flag ${retired.name} for 'spec-controller ${command}' — retired in spec-controller ` +
+        `${retired.retiredIn}, and no later version accepts it (this is spec-controller ${toolVersion}).\n` +
+        `Do not pin an earlier version to get it back: that restores the route it was retired with. ` +
+        `${retired.replacement}\n` +
+        `Run 'spec-controller ${command} --help' to see the flags this version accepts.`);
+}
 //# sourceMappingURL=cli-args.js.map

package/dist/cli-args.js.map

@@ -1 +1 @@
-{"version":3,"file":"cli-args.js","sourceRoot":"","sources":["../src/cli-args.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAIH;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,SAAS,CAAC,IAAuB;IAC/C,MAAM,IAAI,GAA2B,EAAE,CAAC;IACxC,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,IAAI,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QACrC,MAAM,CAAC,GAAG,IAAI,CAAC,CAAC,CAAC,CAAC;QAClB,IAAI,CAAC,KAAK,SAAS,IAAI,CAAC,CAAC,UAAU,CAAC,IAAI,CAAC,EAAE,CAAC;YAC1C,MAAM,GAAG,GAAG,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;YACvB,MAAM,KAAK,GAAG,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;YAC1B,IAAI,KAAK,KAAK,SAAS,IAAI,CAAC,KAAK,CAAC,UAAU,CAAC,IAAI,CAAC,EAAE,CAAC;gBACnD,IAAI,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC;gBAClB,CAAC,EAAE,CAAC;YACN,CAAC;iBAAM,CAAC;gBACN,IAAI,CAAC,GAAG,CAAC,GAAG,MAAM,CAAC;YACrB,CAAC;QACH,CAAC;IACH,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AACH,MAAM,UAAU,iBAAiB,CAC/B,IAA4B,EAC5B,QAAqB,EACrB,OAAe,EACf,WAAmB;IAEnB,+FAA+F;IAC/F,6FAA6F;IAC7F,qFAAqF;IACrF,+CAA+C;IAC/C,MAAM,KAAK,GAAG,QAAQ,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,OAAO,CAAC,CAAC;IAChE,MAAM,QAAQ,GAAG,IAAI,GAAG,EAAU,CAAC;IACnC,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,KAAK,IAAI,EAAE,EAAE,CAAC;QACtC,QAAQ,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC,CAAC;QAC3C,KAAK,MAAM,KAAK,IAAI,IAAI,CAAC,OAAO,IAAI,EAAE;YAAE,QAAQ,CAAC,GAAG,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC,CAAC;IACjF,CAAC;IACD,2FAA2F;IAC3F,gGAAgG;IAChG,6FAA6F;IAC7F,KAAK,MAAM,GAAG,IAAI,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC;QACpC,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,CAAC;YACvB,OAAO,CACL,kBAAkB,GAAG,yBAAyB,OAAO,8BAA8B;gBACnF,GAAG,WAAW,iCAAiC,OAAO,WAAW;gBACjE,oFAAoF;gBACpF,oCAAoC,OAAO,eAAe,GAAG,KAAK;gBAClE,kCAAkC,OAAO,iDAAiD,CAC3F,CAAC;QACJ,CAAC;IACH,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC"}
+{"version":3,"file":"cli-args.js","sourceRoot":"","sources":["../src/cli-args.ts"],"names":[],"mappings":"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"}

package/dist/cli-balance/cli.d.ts

@@ -1,87 +1,7 @@
-/**
- * The balance CLI — thin wiring over the reconciler seams. The orchestration half of
- * the old cli.ts: arg parsing, the render-from-JSON mode, and the reconcile →
- * census → provenance → plan → write sequence. The impure file reads it calls
- * (runReconcile + the read* siblings) live in ingest/ingestQualityChecks.ts; the output
- * plan/write in ./emit; the git-derived run inputs in run-management/resolveRunInputs.ts.
- *
- * Usage:
- *   pnpm reconcile [--features <dir>] [--vitest <report.json>]
- *                  [--cucumber <report.json>] [--ci-steps <record.json>]
- *                  [--ci <ci.yml>]
- *                  [--format <fmt>[:<path>]]
- */
-/**
- * The legacy-`--json` guard at the CLI edge (@SCN-FMT-006). The earlier
- * `--json <path>` flag is removed; supplying it must fail fast with a migration hint to
- * `--format json:<path>`, so the removed flag never silently no-ops and drops output. PURE
- * and `@unit`-testable: the removed flag is NOT a `--format` spec (planOutput never sees
- * it), so the guard reads the parsed args directly and returns the typed migration-hint
- * error message when `--json` is present — routed to stderr + a non-zero exit by main(),
- * the same handling planOutput's typed error gets (the shared error surface) — else null.
- */
 export declare function checkLegacyJson(args: Record<string, string>): string | null;
-/**
- * Source the provenance "Target repo:" name for a run (@SCN-RPT-001 Update —
- * Fork A). The operator's `--target` is recorded VERBATIM — no resolution — defaulting to
- * `"unknown-target"` when omitted (parallel to `sourceSha`'s `"unknown"`; the facts
- * artefact is self-describing, so the line always renders). PURE and `@unit`-testable at
- * the CLI edge, like `checkLegacyJson`. It never inspects `--features`: the prior
- * `basename(dirname(--features))` resolution (the deleted `resolveTarget`) and its
- * degenerate `.` are impossible now — the target is only ever the given value or the
- * explicit default.
- */
 export declare function sourceTarget(args: Record<string, string>): string;
-/**
- * Guard the supplied input-file/dir flags at the CLI edge (@SCN-CLI-002). A
- * mistyped `--vitest` / `--cucumber` / `--features` / `--ci` / `--package-json`
- * pointing at a non-existent path used to reconcile silently against ZERO evidence —
- * a terrifying false all-red report meaning "you forgot the reports", not "your code
- * is broken" (the dogfooding fault). These flags are Examples of ONE boundary
- * rule: a supplied-but-absent input path is a hard error, and a flag added to the set
- * inherits it rather than restating it. Scope is existence only
- * (readability / file-vs-dir type-correctness out of scope; `exists` covers the dir
- * flag and the file flags alike).
- *
- * PURE and `@unit`-testable like `checkLegacyJson` / `sourceTarget`: reads the parsed
- * args + an injected `exists` fn (no fs), returns the FIRST supplied-but-absent
- * `(flag, path)` as a typed error naming both — routed to stderr + a non-zero exit by
- * `refuseUnreadableInputs` (the shared typed-error surface) — else null. An OMITTED flag is not an
- * error (legitimately optional: simply no evidence of that kind).
- */
 export declare function checkInputsExist(args: Record<string, string>, exists: (path: string) => boolean): string | null;
-/**
- * Guard the READABILITY of the supplied JSON inputs at the CLI edge (@SCN-CLI-014).
- * `checkInputsExist` already guards their PRESENCE — but a path that is present yet
- * UNPARSEABLE fell straight through it: the reader threw mid-parse, nothing caught it, and
- * the process hit Node's default exit 1 — the code reserved for a genuine OUT-OF-BALANCE
- * verdict. A crashed invocation was therefore indistinguishable, by exit code, from an
- * honest disagreement (3F-1742). An input the tool cannot read is a USAGE fault: exit 2,
- * sibling to a missing path (@SCN-CLI-002) and an unrecognised flag (@SCN-CLI-009).
- *
- * PURE and `@unit`-testable like its sibling guards: reads the parsed args + an injected
- * `read` fn (no fs), returns the FIRST supplied-but-unparseable `(flag, path, failure)` as
- * a typed error naming all three — routed to stderr + exit 2 by `refuseUnreadableInputs` — else null.
- * An omitted flag is not an error, and an unreadable file (a race after the existence
- * check) reports as the same input fault rather than escaping as a crash.
- */
 export declare function checkInputsParse(args: Record<string, string>, read: (path: string) => string): string | null;
-/**
- * Guard the readability of `--render-from-json` at the CLI edge (@SCN-CLI-015). The
- * render-from-saved-JSON branch RETURNS before the input guards ever run, so it honoured
- * NEITHER: a missing path crashed to `ENOENT` and a malformed file to `SyntaxError`, both
- * landing on Node's default exit 1 — the out-of-balance code (3F-1764).
- *
- * The missing-path case was a live violation of @SCN-CLI-002's own shipped principle: a
- * supplied input path that does not exist is a hard error at exit 2, enforced for the five
- * evidence flags and not for this one. The CLI shipped a guard that half-honoured its Rule.
- *
- * MISSING and UNPARSEABLE are two Examples of one boundary rule — an input the tool cannot
- * read is a usage error, never a verdict — so one guard covers both. PURE and
- * `@unit`-testable like its siblings: the parsed args + an injected `read` (no fs), which
- * throws for an absent/unreadable path exactly as `readFileSync` does. An OMITTED flag is
- * not an error (the ordinary reconcile path).
- */
 export declare function checkRenderFromJson(args: Record<string, string>, read: (path: string) => string): string | null;
-export declare function runBalance(argv: string[]): void;
+export declare function runBalance(argv: string[]): boolean;
 //# sourceMappingURL=cli.d.ts.map

package/dist/cli-balance/cli.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../../src/cli-balance/cli.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAiDH;;;;;;;;GAQG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,MAAM,GAAG,IAAI,CAS3E;AAED;;;;;;;;;GASG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,MAAM,CAEjE;AAqBD;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,gBAAgB,CAC9B,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EAC5B,MAAM,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,GAChC,MAAM,GAAG,IAAI,CAcf;AAYD;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,gBAAgB,CAC9B,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EAC5B,IAAI,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,MAAM,GAC7B,MAAM,GAAG,IAAI,CAef;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,mBAAmB,CACjC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EAC5B,IAAI,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,MAAM,GAC7B,MAAM,GAAG,IAAI,CAcf;AAED,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,IAAI,CAiJ/C"}
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../../src/cli-balance/cli.ts"],"names":[],"mappings":"AAmDA,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,MAAM,GAAG,IAAI,CAS3E;AAED,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,MAAM,CAEjE;AAaD,wBAAgB,gBAAgB,CAC9B,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EAC5B,MAAM,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,GAChC,MAAM,GAAG,IAAI,CAWf;AAMD,wBAAgB,gBAAgB,CAC9B,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EAC5B,IAAI,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,MAAM,GAC7B,MAAM,GAAG,IAAI,CAkBf;AAMD,wBAAgB,mBAAmB,CACjC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EAC5B,IAAI,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,MAAM,GAC7B,MAAM,GAAG,IAAI,CAWf;AAED,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAElD"}