spec-controller 0.1.0-alpha.1 → 0.1.0-alpha.10

package/README.md

@@ -0,0 +1,112 @@
+# spec-controller
+
+**One command, `balance`, that reconciles the behaviour your scenarios name against the evidence that actually ran.**
+
+You hand it your Gherkin scenarios and the reports your tools already produce — a Vitest report, a Cucumber report, your CI run's own record of what its steps did — and it prints one table: which scenarios have living evidence, which do not, and which evidence ran that no scenario asked for.
+
+It runs nothing itself. It reads what your pipeline already wrote.
+
+Requires Node ≥ 22. ESM only.
+
+## Install
+
+```
+npm install -g spec-controller@alpha
+```
+
+Or without installing anything:
+
+```
+npx spec-controller@alpha balance --help
+```
+
+`@alpha` is not optional until `0.1.0` publishes: a bare install resolves `latest`, which npm set to `0.1.0-alpha.1` on the first publish, and that version has neither `tags` nor `--ci-steps`.
+
+## Your first run
+
+Point it at your scenarios and give it nothing else:
+
+```
+spec-controller balance --features ./features
+```
+
+Every scenario comes back as a row whether or not any evidence exists for it, so on this first run the ones you have supplied no reports for read **missing** and the run comes back out-of-balance. That is the shape of the tool rather than a fault in your repository: the reconciliation starts from what you specified, not from what a tool happened to find, and there is no input for which the right answer is silence.
+
+**`balance` fails your build out of the box.** An out-of-balance run exits `1`, so the first run above reds any pipeline you put it in. That is a deliberate departure from two tools it sits beside: Stryker's `thresholds.break` defaults to `null` (*"never let your build fail"*), and the Sonar scanner exits `0` whatever its quality gate says unless you set `sonar.qualitygate.wait`. Both make you opt in to gating. `balance` makes you opt out.
+
+### Report first, gate later
+
+To bring it into a pipeline you already have without redding it on day one, add `--exit-zero`:
+
+```
+spec-controller balance --features ./features --vitest ./vitest-report.json --exit-zero
+```
+
+The report is byte for byte the one the gate prints: the same rows, the same out-of-balance count, and the same headline naming the code the gate would give. Only the exit status moves. Out-of-balance (`1`) and pending under `--strict` (`3`) exit `0`. Usage (`2`), unsound (`4`) and nothing to reconcile (`5`) still fail, because each means the run could not give a verdict at all, and a flag that suppresses verdicts does not suppress that.
+
+Work the out-of-balance rows down, then delete `--exit-zero`, and the gate is on. Don't wrap the step in `continue-on-error` or `|| true` instead: those swallow the codes that mean the run could not be trusted, and they leave nothing in the command to say the gate is off.
+
+Now give it the evidence:
+
+```
+spec-controller balance \
+  --features ./features \
+  --vitest ./vitest-report.json \
+  --cucumber ./cucumber-report.json
+```
+
+A scenario tagged `@unit` names an obligation — a unit test must exist and pass — and the evidence posts back by citing the scenario's `@SCN` code in its test name. Where the two agree the row is **balanced**. Where they do not, the row says which way: evidence missing, evidence failing, or evidence that cites a scenario nobody wrote.
+
+## What the exit code tells your pipeline
+
+| Exit | What it says |
+| --- | --- |
+| `0` | balanced — every obligation has evidence, and it holds |
+| `1` | out-of-balance — the two records disagree, and the report says where |
+| `2` | usage — the invocation was wrong |
+| `3` | balanced, but carrying Pending Items, and you asked for `--strict` |
+| `4` | unsound — a proving suite failed to collect, so the ledger could not be trusted to disagree |
+| `5` | nothing to reconcile — no scenario was declared and no evidence was produced, so the run had no basis for a verdict |
+
+The whole report is written before the code is set, so a failing run still tells you why.
+
+`--exit-zero` moves `1` and `3` to `0` and leaves every other code alone: see *Report first, gate later*.
+
+**Node's default is never one of these.** A run that cannot reconcile ends on an enumerated code of
+its own rather than falling out of the process — a crash that exits `1` would be indistinguishable,
+by status, from an honest disagreement. **An input the tool cannot read is part of `2`**: a mistyped
+path, an unparseable report or a corpus the Gherkin parser rejects are all the invocation being
+wrong, never a verdict about your code.
+
+**The enumeration is open at the top, and that is the one thing to design your pipeline around.** A
+state that is genuinely none of the above gets a **new** code rather than being folded into the
+nearest one — `5` is the most recent, added when a run over a target that had declared nothing and
+produced nothing was found reporting `0`. So **treat an unrecognised non-zero code as a failure you
+have not seen before**, not as a synonym for `1`. Matching `1` exactly is unaffected by a code being
+added; treating *non-zero* as a red build is already correct, and only imprecise about why.
+
+## On CI
+
+```
+spec-controller balance --features ./features \
+  --vitest ./vitest-report.json \
+  --format md:$GITHUB_STEP_SUMMARY \
+  --format json:reconciliation.json
+```
+
+`--format` is repeatable and takes an optional `:<path>`. On GitHub Actions, writing Markdown to `$GITHUB_STEP_SUMMARY` puts the reconciliation on the run's summary page — the report is a table and that is the channel GitHub provides for one. No action, no plugin, no permission.
+
+`spec-controller balance --help` lists every flag with a line each.
+
+## Where to go next
+
+- **Full flags, worked examples and CI wiring** — [`doc/how_to_use.md`](https://github.com/3f-consulting/spec-controller/blob/main/doc/how_to_use.md)
+- **Bringing a check you already have under the reconciliation** — [`doc/converting-a-fitness-check.md`](https://github.com/3f-consulting/spec-controller/blob/main/doc/converting-a-fitness-check.md)
+- **Why `0.x` promises nothing, and what changes at `1.0`** — [`doc/compatibility.md`](https://github.com/3f-consulting/spec-controller/blob/main/doc/compatibility.md)
+- **Building your own tooling on the engine instead of running a command** — [`@3f-consulting/spec-controller-core`](https://www.npmjs.com/package/@3f-consulting/spec-controller-core), the same reconciliation logic as a pure library with no CLI and no I/O.
+
+Source, issues and history: [github.com/3f-consulting/spec-controller](https://github.com/3f-consulting/spec-controller).
+
+## Licence
+
+MIT — see `LICENSE`, which travels in this package. © 2026 3F Consulting Ltd.

package/dist/cli-args.d.ts

@@ -0,0 +1,73 @@
+/**
+ * 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.
+ */
+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 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

@@ -0,0 +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"}

package/dist/cli-args.js

@@ -0,0 +1,114 @@
+/**
+ * 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 parseArgs(argv) {
+    const args = {};
+    for (let i = 0; i < argv.length; i++) {
+        const a = argv[i];
+        if (a !== undefined && a.startsWith("--")) {
+            const key = a.slice(2);
+            const value = argv[i + 1];
+            if (value !== undefined && !value.startsWith("--")) {
+                args[key] = value;
+                i++;
+            }
+            else {
+                args[key] = "true";
+            }
+        }
+    }
+    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 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 ?? []) {
+        accepted.add(flag.name.replace(/^-+/, ""));
+        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 null;
+}
+//# sourceMappingURL=cli-args.js.map

package/dist/cli-args.js.map

@@ -0,0 +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"}

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

@@ -7,10 +7,10 @@
  *
  * Usage:
  *   pnpm reconcile [--features <dir>] [--vitest <report.json>]
- *                  [--cucumber <report.json>] [--ci <ci.yml>]
+ *                  [--cucumber <report.json>] [--ci-steps <record.json>]
+ *                  [--ci <ci.yml>]
  *                  [--format <fmt>[:<path>]]
  */
-import type { CliRegistry } from "../cli-registry.js";
 /**
  * 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
@@ -32,6 +32,23 @@ export declare function checkLegacyJson(args: Record<string, string>): string |
  * 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).
@@ -44,7 +61,7 @@ export declare function checkInputsExist(args: Record<string, string>, exists: (
  *
  * 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 `runBalance` — else null.
+ * 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.
  */
@@ -66,22 +83,5 @@ export declare function checkInputsParse(args: Record<string, string>, read: (pa
  * not an error (the ordinary reconcile path).
  */
 export declare function checkRenderFromJson(args: Record<string, string>, read: (path: string) => string): string | null;
-/**
- * The registry-bounded flag check at the CLI edge (@SCN-CLI-009). `balance` 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 old permissive `parseArgs` did. This is the structural teeth behind
- * "accepted = registry = help": a flag can't affect behaviour without a registry entry (and
- * so, by CLI-008's guard, without appearing in help).
- *
- * PURE and `@unit`-testable like `checkLegacyJson` / `checkInputsExist`: reads the parsed
- * args (keys are the `--`-stripped flag names) + the registry, returns the FIRST unregistered
- * flag as a typed usage error naming it WITH its dashes — routed to stderr + exit 2 by
- * `runBalance` (per 3F-1414's `0` balanced / `1` out-of-balance / `2` usage taxonomy),
- * never exit 1, never a silent reconcile — else null. The global `--store`/`--run-id`
- * modifiers never reach here: the top-level dispatcher (`parseHostInvocation`) consumes them
- * BEFORE `balance` is dispatched, so the bounded parser sees only the command's own args.
- */
-export declare function checkUnknownFlags(args: Record<string, string>, registry: CliRegistry): string | null;
 export declare function runBalance(argv: string[]): void;
 //# 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;;;;;;;;;;;GAWG;AAsBH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AA0CtD;;;;;;;;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;AAqCD,wBAAgB,gBAAgB,CAC9B,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EAC5B,MAAM,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,GAChC,MAAM,GAAG,IAAI,CAYf;AAUD;;;;;;;;;;;;;;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;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EAAE,QAAQ,EAAE,WAAW,GAAG,MAAM,GAAG,IAAI,CAmBpG;AAED,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,IAAI,CA8P/C"}
+{"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,CAkJ/C"}