spec-controller 0.1.0-alpha.2 → 0.1.0-alpha.20

package/README.md

@@ -11,15 +11,17 @@ Requires Node ≥ 22. ESM only.
 ## Install
 
 ```
-npm install -g spec-controller
+npm install -g spec-controller@alpha
 ```
 
 Or without installing anything:
 
 ```
-npx spec-controller balance --help
+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:
@@ -30,6 +32,20 @@ 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:
 
 ```
@@ -51,9 +67,12 @@ A scenario tagged `@unit` names an obligation — a unit test must exist and pas
 | `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 |
+| `6` | no verdict — spec-controller was asked something it cannot answer, such as a command it does not have, so it reached no verdict about your corpus |
 
 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
@@ -83,7 +102,7 @@ spec-controller balance --features ./features \
 ## 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)
+- **Bringing a check you already have under the reconciliation** — [`doc/adopting-fitness-checks.md`](https://github.com/3f-consulting/spec-controller/blob/main/doc/adopting-fitness-checks.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.
 

package/dist/cli-args.d.ts

@@ -51,7 +51,7 @@ export declare function parseArgs(argv: readonly string[]): Record<string, strin
  * 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-SLF-008).
+ * 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
@@ -65,6 +65,9 @@ export declare function parseArgs(argv: readonly string[]): Record<string, strin
  * 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.
  *
+ * EXCEPT FOR A FLAG THE COMMAND HAS RETIRED, where the bump is false advice: `retiredFlagRefusal`
+ * below names the retirement and its replacement instead (3F-3528).
+ *
  * 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.

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;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAe,MAAM,mBAAmB,CAAC;AAElE;;;;;;;;;;;GAWG;AACH,wBAAgB,SAAS,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAgBzE;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;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,CA2Bf"}

package/dist/cli-args.js

@@ -67,7 +67,7 @@ export function parseArgs(argv) {
  * 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-SLF-008).
+ * 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
@@ -81,6 +81,9 @@ export function parseArgs(argv) {
  * 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.
  *
+ * EXCEPT FOR A FLAG THE COMMAND HAS RETIRED, where the bump is false advice: `retiredFlagRefusal`
+ * below names the retirement and its replacement instead (3F-3528).
+ *
  * 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.
@@ -102,13 +105,31 @@ export function checkUnknownFlags(args, registry, command, toolVersion) {
     // 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;
 }
+/**
+ * THE REFUSAL FOR A FLAG THE COMMAND HAS RETIRED (@SCN-CLI-023, 3F-3528), or `undefined` when the
+ * flag is merely unregistered. The drift advice above is true of a flag newer than the pin and
+ * false of a retired one: every earlier version accepts it and no later one will, so the only pin
+ * that satisfies "bump the pin to a version that accepts it" is a downgrade back onto the route
+ * the retirement removed. So this names the retirement and the replacement, and offers no pin.
+ */
+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

@@ -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.
  */

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;AAuCD,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,CAsR/C"}
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../../src/cli-balance/cli.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAgDH;;;;;;;;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"}

package/dist/cli-balance/cli.js

@@ -13,7 +13,7 @@
  */
 import { existsSync, readFileSync } from "node:fs";
 import { dirname } from "node:path";
-import { runReconcile, readEvidenceObligations, readFeatureNames, featureCorpusParseErrors, featureCorpusDuplicateScnIds, } from "../ingest/ingestQualityChecks.js";
+import { runReconcile, readEvidenceObligations, readFeatureNames, featureCorpusParseErrors, } from "../ingest/ingestQualityChecks.js";
 import { planOutput } from "./emit/format.js";
 import { writeOutputs } from "./emit/writer.js";
 import { renderReportFromJson, isBalanced, hasPendingItems, hasBrokenEvidence, hasNothingToReconcile, } from "@3f-consulting/spec-controller-core";
@@ -72,23 +72,6 @@ export function checkLegacyJson(args) {
 export function sourceTarget(args) {
     return args["target"] ?? "unknown-target";
 }
-/**
- * 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
- * `runBalance` (the shared typed-error surface) — else null. An OMITTED flag is not an
- * error (legitimately optional: simply no evidence of that kind).
- */
 /**
  * The parsed args, as the reconciler's input paths — the one place a `--flag` name becomes a
  * `ReconcileOptions` key.
@@ -104,16 +87,32 @@ function reconcileInputsOf(args) {
         cucumber: args["cucumber"],
         ci: args["ci"],
         packageJson: args["package-json"],
-        measurements: args["measurements"],
         ciSteps: args["ci-steps"],
     };
 }
+/**
+ * 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 function checkInputsExist(args, exists) {
     // The input flags in a fixed order — the FIRST supplied-but-absent one is the
     // reported error (deterministic; the operator fixes and re-runs). Keys are the
     // parseArgs form (the `--` stripped); the message names the flag WITH its dashes.
     const flags = [
-        "vitest", "cucumber", "features", "ci", "package-json", "measurements", "ci-steps",
+        "vitest", "cucumber", "features", "ci", "package-json", "ci-steps",
     ];
     for (const flag of flags) {
         const path = args[flag];
@@ -130,7 +129,7 @@ export function checkInputsExist(args, exists) {
  * process, and on garbage both reconcile normally (verified, 3F-1742 Discovery).
  */
 const JSON_INPUT_FLAGS = [
-    "vitest", "cucumber", "package-json", "measurements", "ci-steps",
+    "vitest", "cucumber", "package-json", "ci-steps",
 ];
 /**
  * Guard the READABILITY of the supplied JSON inputs at the CLI edge (@SCN-CLI-014).
@@ -143,7 +142,7 @@ const JSON_INPUT_FLAGS = [
  *
  * 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.
  */
@@ -217,13 +216,8 @@ export function runBalance(argv) {
     // guard's typed error is routed to stderr + a non-zero exit, exactly as planOutput's error
     // is below (the shared typed-error surface).
     const legacyJsonError = checkLegacyJson(args);
-    if (legacyJsonError) {
-        process.stderr.write(legacyJsonError + "\n");
-        // Usage/config error → exit 2 (the enumerated usage code, @SCN-CLI-002), distinct
-        // from the out-of-balance verdict code 1 (@SCN-CLI-004): an out-of-balance run must
-        // never masquerade as a usage error, nor the reverse.
-        process.exit(2);
-    }
+    if (legacyJsonError)
+        exitUsage(legacyJsonError);
     // Registry-bounded parse (@SCN-CLI-009): `balance` accepts ONLY the flags its registry
     // scope LISTS. An unregistered flag — a typo `--strcit`, a stray `--bogus` — is a
     // USAGE error: name it on stderr, set process.exitCode = 2 (the enumerated usage code,
@@ -238,97 +232,9 @@ export function runBalance(argv) {
         process.exitCode = 2;
         return;
     }
-    // Render-from-saved-JSON mode (@SCN-RMD-007): regenerate the human markdown from a
-    // banked spec-reconciliation.json ALONE — no reconcile, no live inputs, no RunContext. Reads
-    // the file, JSON.parses it back into the whole-document report model, renders the markdown via
-    // renderReport, and writes it to stdout (the same trailing-newline convention as the writer's
-    // stdout path). The load-bearing proof that the JSON IS the model — returns before any reconcile.
-    // Saved-report READABILITY guard (@SCN-CLI-015). This branch RETURNS before the input
-    // guards below 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. The missing-path case was a live violation of @SCN-CLI-002's own
-    // shipped principle, which the CLI enforced for the five evidence flags and not for this
-    // one. The guard therefore runs INSIDE this branch, ahead of the read (3F-1764).
-    const unreadableSavedReportError = checkRenderFromJson(args, (path) => readFileSync(path, "utf8"));
-    if (unreadableSavedReportError) {
-        process.stderr.write(unreadableSavedReportError + "\n");
-        process.exit(2);
-    }
-    const rehydratePath = args["render-from-json"];
-    if (rehydratePath !== undefined) {
-        const savedReport = readFileSync(rehydratePath, "utf8");
-        process.stdout.write(renderReportFromJson(savedReport) + "\n");
+    if (renderSavedReport(args))
         return;
-    }
-    // Input-existence guard (@SCN-CLI-002): a supplied input-file/dir flag pointing at a
-    // non-existent path is a HARD ERROR — halt BEFORE reconciling, with a typed message
-    // naming the flag + path, never the silent zero-evidence all-red report a mistyped
-    // path used to produce (the dogfooding fault). Routed to stderr + a non-zero exit,
-    // exactly as the legacy-`--json` guard above (the shared typed-error surface). An
-    // omitted flag is legitimately optional and passes through untouched.
-    const missingInputError = checkInputsExist(args, existsSync);
-    if (missingInputError) {
-        process.stderr.write(missingInputError + "\n");
-        // Usage/input error → exit 2 (@SCN-CLI-002), distinct from the out-of-balance
-        // verdict code 1 (@SCN-CLI-004).
-        process.exit(2);
-    }
-    // Input-READABILITY guard (@SCN-CLI-014): existence is not enough. A report that is
-    // PRESENT but UNPARSEABLE (`--vitest /dev/null`, truncated JSON, non-JSON) used to throw
-    // mid-parse inside reconcileWithCensus, uncaught — and Node's default exit code is 1, the
-    // code reserved for a genuine OUT-OF-BALANCE verdict (@SCN-CLI-004). So a tool that
-    // CRASHED before reconciling was indistinguishable, by exit code, from an honest
-    // disagreement (3F-1742). Runs immediately after the existence guard and BEFORE any
-    // reconcile, routing to the same stderr + exit 2 lane: an input the tool cannot read is a
-    // usage fault, sibling to a missing path and an unrecognised flag — never a verdict.
-    const unparseableInputError = checkInputsParse(args, (path) => readFileSync(path, "utf8"));
-    if (unparseableInputError) {
-        process.stderr.write(unparseableInputError + "\n");
-        process.exit(2);
-    }
-    // The FEATURE-CORPUS integrity checkpoint (@SCN-CLI-016, 3F-1767). The feature corpus is an
-    // input too — the ledger's DEBIT side — and it was read by a hand-rolled TAG-LINE SCAN that
-    // never consulted a parser. So a malformed tag line simply stopped being a tag line and its
-    // scenario CEASED TO EXIST: one stray character deleted a failing row and turned an
-    // out-of-balance run (exit 1) into a clean BALANCED (exit 0). A dropped scenario cannot even
-    // reconcile `missing`, because it was never RAISED to be missing — the run read cleaner than
-    // reality, the exact false-green this tool exists to prevent.
-    //
-    // Validated with the REAL Gherkin parser (cucumber's own), so a file the tool would reconcile is
-    // at least a file cucumber would RUN. A file it rejects is an input we CANNOT READ: exit 2,
-    // halting BEFORE any reconcile, naming the file and the parse failure — the same Rule as
-    // @SCN-CLI-014 and @SCN-CLI-015 ("an input the tool cannot read is a usage error, never a
-    // verdict"), now on the obligation side. Never a verdict, and never a green.
-    //
-    // The corpus is EXTRACTED from the same real AST (@SCN-LDG-020), so what the tool reconciles is
-    // what cucumber runs — Feature/Rule tag inheritance included. This guard decides whether the file
-    // can be read at all; parseScenarios then reads it exactly as cucumber would.
-    const featureParseErrors = featureCorpusParseErrors(args["features"]);
-    if (featureParseErrors.length > 0) {
-        for (const { file, message } of featureParseErrors) {
-            process.stderr.write(`The --features corpus contains a feature file that could not be parsed: ${file}\n${message}\n`);
-        }
-        process.exit(2);
-    }
-    // AMBIGUOUS-CORPUS guard (@SCN-LDG-020's guardrail, 3F-1775). An @SCN identifies exactly ONE
-    // scenario — that is the whole basis of attributing evidence to it. Tag inheritance makes a
-    // DUPLICATE reachable: an @SCN hoisted to a Feature:/Rule: is inherited by every scenario
-    // beneath it (cucumber does this, so we do). One passing test would then mark EVERY scenario
-    // sharing that id `balanced` — including scenarios nothing proves — a BALANCED-WHEN-BROKEN run
-    // at exit 0. A new silent false-green, introduced by the very fix that closed the last one.
-    //
-    // So the corpus is REFUSED, not reconciled: the tool cannot know which scenario a citing test
-    // proves, and any verdict over it would be a guess. Same Rule as @SCN-CLI-014/015/016 — an input
-    // the tool cannot read is a usage error, never a verdict.
-    const duplicateScnIds = featureCorpusDuplicateScnIds(args["features"]);
-    if (duplicateScnIds.length > 0) {
-        process.stderr.write(`The --features corpus names the same @SCN on more than one scenario: ` +
-            `${duplicateScnIds.join(", ")}.\n` +
-            `An @SCN identifies exactly one scenario — evidence citing a duplicated id cannot be ` +
-            `attributed, so no verdict over this corpus would be trustworthy. (An @SCN on a Feature: ` +
-            `or Rule: line is inherited by every scenario beneath it — name it on the scenario.)\n`);
-        process.exit(2);
-    }
+    refuseUnreadableInputs(args);
     const inputs = reconcileInputsOf(args);
     // Reconcile the obligation-vs-observation evidence into the Ledger. The runtime evidence-observation
     // views (Test volume, the evidence grid) are FOLDS the renderers derive off this Ledger's posted
@@ -348,31 +254,7 @@ export function runBalance(argv) {
     // — the by-feature cut's full-name labels. The 5th sibling, threaded to the MARKDOWN
     // renderer via writeOutputs only (markdown-only; the by-feature cut isn't on JSON).
     const featureNames = readFeatureNames(args["features"]);
-    // Build the run provenance ONCE (project design §1) — a sibling RunContext, the
-    // Ledger staying pure — reusing the existing runStart. The target is the
-    // operator's --target VERBATIM (unknown-target on omit; Fork A — no
-    // resolution, no basename guessing). Source SHA via the read-only target read, with
-    // --source-sha as the override (resolveSourceSha).
-    const ctx = {
-        target: sourceTarget(args),
-        inputs,
-        runStart,
-        sourceSha: resolveSourceSha({
-            sourceSha: args["source-sha"],
-            targetDir: args["features"] !== undefined ? dirname(args["features"]) : undefined,
-        }),
-        // The TARGET repo root the recorded input paths are made portable against (fixed to
-        // the target root, not the run cwd, by @SCN-RPT-016) — the SAME
-        // root readEvidenceObservations passes to countRuntimeEvidenceObservationKinds, derived from
-        // --features, so a cross-repo reconcile records inputs relative (`features`) rather
-        // than leaking the target's absolute path.
-        root: resolveTargetRoot({ features: inputs.features }),
-        // The TOOL's own identity (@SCN-RPT-026, 3F-1916) — which spec-controller produced
-        // this run, distinct from the target's sourceSha. Read from the tool's OWN dir, never
-        // cwd (which is the target). One call, spread into the ctx; the same identity feeds
-        // the run.yaml manifest.
-        ...resolveToolIdentity(),
-    };
+    const ctx = runContextOf(args, inputs, runStart);
     // Plan the outputs from the --format specs (no flag → md→stdout) and write them via
     // the writer — the pure plan / impure writer split (@SCN-FMT-001). The plan
     // parse+validate is pure; the writer is the only IO for the emitted report. This is
@@ -380,12 +262,8 @@ export function runBalance(argv) {
     // legacy runs/<target>/<ISO>/ auto-archive was removed with @SCN-RUN-001, the
     // caller now routes stored runs (spec-controller's run-management layer).
     const planResult = planOutput(collectFormatSpecs(argv));
-    if (!planResult.ok) {
-        process.stderr.write(planResult.error + "\n");
-        // Usage/config error (bad --format spec) → exit 2 (@SCN-CLI-002), distinct from the
-        // out-of-balance verdict code 1 (@SCN-CLI-004).
-        process.exit(2);
-    }
+    if (!planResult.ok)
+        exitUsage(planResult.error);
     writeOutputs(planResult.plan, { balance, ctx, evidenceObligations, withRuntimeObservations: true, withStaticChecks: true, featureNames });
     // The CI gate (@SCN-CLI-004): `balance` is a GATE, not just a reporter. AFTER the report
     // is written in full, map the whole-run verdict to the process exit code. Out-of-balance
@@ -449,12 +327,126 @@ export function runBalance(argv) {
     // credits HAS a row — its suspense row — and is an ordinary out-of-balance report at exit 1
     // (@SCN-CLI-020). @SCN-CLI-004/005/010/012 are BYSTANDERS: every one of their fixtures carries
     // rows, so none reaches this branch.
-    const code = verdictExitCode(balance.ledger, args["strict"] !== undefined);
+    const verdict = verdictExitCode(balance.ledger, args["strict"] !== undefined);
+    const code = args["exit-zero"] !== undefined ? exitZeroStatus(verdict) : verdict;
     // Assigned only when NON-ZERO, so a balanced run still LEAVES process.exitCode at its default
     // rather than writing a 0 over it — the distinction @SCN-CLI-005 and @SCN-CLI-010 both rest on.
     if (code !== 0)
         process.exitCode = code;
 }
+/**
+ * A usage or input fault: the message on stderr, then exit 2 — the enumerated usage code
+ * (@SCN-CLI-002), distinct from the out-of-balance verdict code 1 (@SCN-CLI-004). An
+ * out-of-balance run must never masquerade as a usage error, nor the reverse.
+ */
+function exitUsage(message) {
+    process.stderr.write(message + "\n");
+    process.exit(2);
+}
+/**
+ * Render-from-saved-JSON mode (@SCN-RMD-007): regenerate the human markdown from a
+ * banked spec-reconciliation.json ALONE — no reconcile, no live inputs, no RunContext. Reads
+ * the file, JSON.parses it back into the whole-document report model, renders the markdown via
+ * renderReport, and writes it to stdout (the same trailing-newline convention as the writer's
+ * stdout path). The load-bearing proof that the JSON IS the model — true when it answered the
+ * run, so `runBalance` returns before any reconcile.
+ */
+function renderSavedReport(args) {
+    // Saved-report READABILITY guard (@SCN-CLI-015). This mode RETURNS before
+    // `refuseUnreadableInputs` ever runs, so it honoured NEITHER of its guards: 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. The missing-path case was a live violation of @SCN-CLI-002's own
+    // shipped principle, which the CLI enforced for the five evidence flags and not for this
+    // one. The guard therefore runs INSIDE this mode, ahead of the read (3F-1764).
+    const unreadableSavedReportError = checkRenderFromJson(args, (path) => readFileSync(path, "utf8"));
+    if (unreadableSavedReportError)
+        exitUsage(unreadableSavedReportError);
+    const rehydratePath = args["render-from-json"];
+    if (rehydratePath === undefined)
+        return false;
+    const savedReport = readFileSync(rehydratePath, "utf8");
+    process.stdout.write(renderReportFromJson(savedReport) + "\n");
+    return true;
+}
+/**
+ * The live-input guards, in the order they run: each halts at exit 2 BEFORE any reconcile,
+ * because an input the tool cannot read is a usage error, never a verdict.
+ */
+function refuseUnreadableInputs(args) {
+    // Input-existence guard (@SCN-CLI-002): a supplied input-file/dir flag pointing at a
+    // non-existent path is a HARD ERROR — halt BEFORE reconciling, with a typed message
+    // naming the flag + path, never the silent zero-evidence all-red report a mistyped
+    // path used to produce (the dogfooding fault). Routed to stderr + a non-zero exit,
+    // exactly as the legacy-`--json` guard (the shared typed-error surface). An
+    // omitted flag is legitimately optional and passes through untouched.
+    const missingInputError = checkInputsExist(args, existsSync);
+    if (missingInputError)
+        exitUsage(missingInputError);
+    // Input-READABILITY guard (@SCN-CLI-014): existence is not enough. A report that is
+    // PRESENT but UNPARSEABLE (`--vitest /dev/null`, truncated JSON, non-JSON) used to throw
+    // mid-parse inside reconcileWithCensus, uncaught — and Node's default exit code is 1, the
+    // code reserved for a genuine OUT-OF-BALANCE verdict (@SCN-CLI-004). So a tool that
+    // CRASHED before reconciling was indistinguishable, by exit code, from an honest
+    // disagreement (3F-1742). Runs immediately after the existence guard and BEFORE any
+    // reconcile, routing to the same stderr + exit 2 lane: an input the tool cannot read is a
+    // usage fault, sibling to a missing path and an unrecognised flag — never a verdict.
+    const unparseableInputError = checkInputsParse(args, (path) => readFileSync(path, "utf8"));
+    if (unparseableInputError)
+        exitUsage(unparseableInputError);
+    // The FEATURE-CORPUS integrity checkpoint (@SCN-CLI-016, 3F-1767). The feature corpus is an
+    // input too — the ledger's DEBIT side — and it was read by a hand-rolled TAG-LINE SCAN that
+    // never consulted a parser. So a malformed tag line simply stopped being a tag line and its
+    // scenario CEASED TO EXIST: one stray character deleted a failing row and turned an
+    // out-of-balance run (exit 1) into a clean BALANCED (exit 0). A dropped scenario cannot even
+    // reconcile `missing`, because it was never RAISED to be missing — the run read cleaner than
+    // reality, the exact false-green this tool exists to prevent.
+    //
+    // Validated with the REAL Gherkin parser (cucumber's own), so a file the tool would reconcile is
+    // at least a file cucumber would RUN. A file it rejects is an input we CANNOT READ: exit 2,
+    // halting BEFORE any reconcile, naming the file and the parse failure — the same Rule as
+    // @SCN-CLI-014 and @SCN-CLI-015 ("an input the tool cannot read is a usage error, never a
+    // verdict"), now on the obligation side. Never a verdict, and never a green.
+    //
+    // The corpus is EXTRACTED from the same real AST (@SCN-LDG-020), so what the tool reconciles is
+    // what cucumber runs — Feature/Rule tag inheritance included. This guard decides whether the file
+    // can be read at all; parseScenarios then reads it exactly as cucumber would.
+    const featureParseErrors = featureCorpusParseErrors(args["features"]);
+    if (featureParseErrors.length > 0) {
+        for (const { file, message } of featureParseErrors) {
+            process.stderr.write(`The --features corpus contains a feature file that could not be parsed: ${file}\n${message}\n`);
+        }
+        process.exit(2);
+    }
+}
+/**
+ * Build the run provenance ONCE (project design §1) — a sibling RunContext, the
+ * Ledger staying pure — reusing the existing runStart. The target is the
+ * operator's --target VERBATIM (unknown-target on omit; Fork A — no
+ * resolution, no basename guessing). Source SHA via the read-only target read, with
+ * --source-sha as the override (resolveSourceSha).
+ */
+function runContextOf(args, inputs, runStart) {
+    return {
+        target: sourceTarget(args),
+        inputs,
+        runStart,
+        sourceSha: resolveSourceSha({
+            sourceSha: args["source-sha"],
+            targetDir: args["features"] !== undefined ? dirname(args["features"]) : undefined,
+        }),
+        // The TARGET repo root the recorded input paths are made portable against (fixed to
+        // the target root, not the run cwd, by @SCN-RPT-016) — the SAME
+        // root readEvidenceObservations passes to countRuntimeEvidenceObservationKinds, derived from
+        // --features, so a cross-repo reconcile records inputs relative (`features`) rather
+        // than leaking the target's absolute path.
+        root: resolveTargetRoot({ features: inputs.features }),
+        // The TOOL's own identity (@SCN-RPT-026, 3F-1916) — which spec-controller produced
+        // this run, distinct from the target's sourceSha. Read from the tool's OWN dir, never
+        // cwd (which is the target). One call, spread into the ctx; the same identity feeds
+        // the run.yaml manifest.
+        ...resolveToolIdentity(),
+    };
+}
 /**
  * THE DOMINANCE LADDER — the whole-run verdict as the enumerated status a consumer's CI branches
  * on, and the ONE place the order argued for above is written down. Extracted from `runBalance`
@@ -475,6 +467,16 @@ function verdictExitCode(ledger, strict) {
         return 3;
     return 0;
 }
+/**
+ * The codes `--exit-zero` moves to 0 (@SCN-CLI-021, 3F-3100): the two VERDICTS on the target —
+ * out-of-balance and pending-under-`--strict`. Enumerated rather than "anything non-zero", because
+ * unsound (4) and nothing-to-reconcile (5) are not verdicts but the absence of a trustworthy one,
+ * and suppressing a verdict never suppresses that. Usage (2) exits before the ladder is reached.
+ */
+const VERDICT_CODES = new Set([1, 3]);
+function exitZeroStatus(code) {
+    return VERDICT_CODES.has(code) ? 0 : code;
+}
 // Only run the balance command when this module is executed directly
 // (`tsx cli-balance/cli.ts`), NOT when imported by the top-level `spec-controller`
 // bin dispatcher or by a test that exercises the pure edge guards.