spec-controller 0.1.0-alpha.3 → 0.1.0-alpha.31

package/dist/cli-balance/emit/writer.js

@@ -1,48 +1,40 @@
 /**
- * The output WRITER — the impure app-layer that realises an `OutputPlan` (the
- * three-layer split). For each planned output it renders
- * the payload via the PURE renderers (`renderMarkdown` / `renderJson` in `src/render/`)
- * and performs the IO: stdout, or a file.
- *
- * This is the ONLY layer that performs IO — the renderers stay pure (`model → string`)
- * and `planOutput` stays pure (parse+validate). So the writer carries the `@integration`
- * evidence: its real stdout/file effect is asserted directly (the anti-watermelon rule),
- * never a re-run of the `planOutput` `@unit`.
- *
- * FMT-001 (`@SCN-FMT-001`) writes markdown to stdout. The `json` format (FMT-002) and the
- * file destination (FMT-002/003) are wired on the same `render` + `dest` switch below as
- * later sub-issues plan them.
- *
- * Parent: @SCN-FMT-001 — the output-dispatch rework.
+ * The output writer: renders each planned output through the pure renderers and performs the only
+ * IO in the pipeline, to stdout or to a file.
  */
 import { writeFileSync } from "node:fs";
 import { renderMarkdown } from "@3f-consulting/spec-controller-core";
 import { renderJson } from "@3f-consulting/spec-controller-core";
-/** Render one format from the payloads via the matching pure renderer. */
+import { probeWritable, writeOrRefuse } from "../../outputLocation.js";
 function render(fmt, p) {
-    // The axis gates moved onto the concept's factory (3F-2233) — by the time a payload reaches a
-    // renderer the totals are already folded, so there is nothing left here to switch on.
     return fmt === "json"
         ? renderJson(p.balance, p.ctx, p.evidenceObligations, p.featureNames)
         : renderMarkdown(p.balance, p.ctx, p.evidenceObligations, p.featureNames);
 }
 /**
- * Realise the plan: render each planned output and write it to its destination. The only
- * IO in the pipeline. FMT-001 exercises the markdown→stdout path.
+ * Every file destination is proved writable before any output is emitted, so a refused run never
+ * leaves a report behind, on stdout or in a file, whose headline names an exit the process does not
+ * take. Writing files first and stdout last would not do: an earlier file would still be written.
  */
 export function writeOutputs(plan, payloads) {
-    for (const output of plan.outputs) {
-        const rendered = render(output.fmt, payloads);
-        switch (output.dest.kind) {
-            case "stdout":
-                // Trailing newline so the report ends cleanly on a terminal — FMT-001's path.
-                process.stdout.write(rendered + "\n");
-                break;
-            case "file":
-                // The file destination (FMT-002/003) — same rendered bytes, to a caller path.
-                writeFileSync(output.dest.path, rendered + "\n", "utf8");
-                break;
-        }
+    const emissions = plan.outputs.map((output) => ({ output, text: render(output.fmt, payloads) + "\n" }));
+    for (const { output } of emissions) {
+        const dest = output.dest;
+        if (dest.kind === "file")
+            writeOrRefuse(refusalSubject(output), dest.path, () => probeWritable(dest.path));
     }
+    for (const { output, text } of emissions)
+        emit(output, text);
+}
+function refusalSubject(output) {
+    return `The ${output.fmt} report could not be written`;
+}
+function emit(output, text) {
+    const dest = output.dest;
+    if (dest.kind === "stdout") {
+        process.stdout.write(text);
+        return;
+    }
+    writeOrRefuse(refusalSubject(output), dest.path, () => writeFileSync(dest.path, text, "utf8"));
 }
 //# sourceMappingURL=writer.js.map

package/dist/cli-balance/emit/writer.js.map

@@ -1 +1 @@
-{"version":3,"file":"writer.js","sourceRoot":"","sources":["../../../src/cli-balance/emit/writer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AACxC,OAAO,EAAE,cAAc,EAAE,MAAM,qCAAqC,CAAC;AACrE,OAAO,EAAE,UAAU,EAAE,MAAM,qCAAqC,CAAC;AAyBjE,0EAA0E;AAC1E,SAAS,MAAM,CAAC,GAAiB,EAAE,CAAiB;IAClD,8FAA8F;IAC9F,sFAAsF;IACtF,OAAO,GAAG,KAAK,MAAM;QACnB,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC,GAAG,EAAE,CAAC,CAAC,mBAAmB,EAAE,CAAC,CAAC,YAAY,CAAC;QACrE,CAAC,CAAC,cAAc,CAAC,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC,GAAG,EAAE,CAAC,CAAC,mBAAmB,EAAE,CAAC,CAAC,YAAY,CAAC,CAAC;AAC9E,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,YAAY,CAAC,IAAgB,EAAE,QAAwB;IACrE,KAAK,MAAM,MAAM,IAAI,IAAI,CAAC,OAAO,EAAE,CAAC;QAClC,MAAM,QAAQ,GAAG,MAAM,CAAC,MAAM,CAAC,GAAG,EAAE,QAAQ,CAAC,CAAC;QAC9C,QAAQ,MAAM,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC;YACzB,KAAK,QAAQ;gBACX,8EAA8E;gBAC9E,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,QAAQ,GAAG,IAAI,CAAC,CAAC;gBACtC,MAAM;YACR,KAAK,MAAM;gBACT,8EAA8E;gBAC9E,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,IAAI,EAAE,QAAQ,GAAG,IAAI,EAAE,MAAM,CAAC,CAAC;gBACzD,MAAM;QACV,CAAC;IACH,CAAC;AACH,CAAC"}
+{"version":3,"file":"writer.js","sourceRoot":"","sources":["../../../src/cli-balance/emit/writer.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AACxC,OAAO,EAAE,cAAc,EAAE,MAAM,qCAAqC,CAAC;AACrE,OAAO,EAAE,UAAU,EAAE,MAAM,qCAAqC,CAAC;AAMjE,OAAO,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,yBAAyB,CAAC;AAiBvE,SAAS,MAAM,CAAC,GAAiB,EAAE,CAAiB;IAClD,OAAO,GAAG,KAAK,MAAM;QACnB,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC,GAAG,EAAE,CAAC,CAAC,mBAAmB,EAAE,CAAC,CAAC,YAAY,CAAC;QACrE,CAAC,CAAC,cAAc,CAAC,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC,GAAG,EAAE,CAAC,CAAC,mBAAmB,EAAE,CAAC,CAAC,YAAY,CAAC,CAAC;AAC9E,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,YAAY,CAAC,IAAgB,EAAE,QAAwB;IACrE,MAAM,SAAS,GAAG,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,CAAC,MAAM,CAAC,GAAG,EAAE,QAAQ,CAAC,GAAG,IAAI,EAAE,CAAC,CAAC,CAAC;IACxG,KAAK,MAAM,EAAE,MAAM,EAAE,IAAI,SAAS,EAAE,CAAC;QACnC,MAAM,IAAI,GAAG,MAAM,CAAC,IAAI,CAAC;QACzB,IAAI,IAAI,CAAC,IAAI,KAAK,MAAM;YAAE,aAAa,CAAC,cAAc,CAAC,MAAM,CAAC,EAAE,IAAI,CAAC,IAAI,EAAE,GAAG,EAAE,CAAC,aAAa,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC;IAC7G,CAAC;IACD,KAAK,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,IAAI,SAAS;QAAE,IAAI,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC;AAC/D,CAAC;AAED,SAAS,cAAc,CAAC,MAAqB;IAC3C,OAAO,OAAO,MAAM,CAAC,GAAG,8BAA8B,CAAC;AACzD,CAAC;AAED,SAAS,IAAI,CAAC,MAAqB,EAAE,IAAY;IAC/C,MAAM,IAAI,GAAG,MAAM,CAAC,IAAI,CAAC;IACzB,IAAI,IAAI,CAAC,IAAI,KAAK,QAAQ,EAAE,CAAC;QAC3B,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;QAC3B,OAAO;IACT,CAAC;IACD,aAAa,CAAC,cAAc,CAAC,MAAM,CAAC,EAAE,IAAI,CAAC,IAAI,EAAE,GAAG,EAAE,CAAC,aAAa,CAAC,IAAI,CAAC,IAAI,EAAE,IAAI,EAAE,MAAM,CAAC,CAAC,CAAC;AACjG,CAAC"}

package/dist/cli-registry.d.ts

@@ -35,6 +35,13 @@ export interface FlagSpec {
     /** One-line help text — the description migrated from doc/how_to_use.md. */
     description: string;
 }
+/** A positional argument a command takes: its placeholder, and what it is. */
+export interface PositionalSpec {
+    /** The placeholder as help shows it (e.g. "<FFF>"). */
+    name: string;
+    /** One-line help text. */
+    description: string;
+}
 /** A command: its token, a one-line summary, its per-command flag scope, and any config it reads. */
 export interface CommandSpec {
     /** The command token (e.g. "balance"). */
@@ -43,6 +50,10 @@ export interface CommandSpec {
     summary: string;
     /** The command's per-command flag scope. */
     flags: FlagSpec[];
+    /** The positional arguments the command takes, in order, each once. Omit when it takes flags only. */
+    positionals?: PositionalSpec[];
+    /** False for a command that keeps no run, so the host refuses `--store`/`--run-id` before it. Omit otherwise. */
+    acceptsHostModifiers?: false;
     /**
      * Trailing help lines documenting `package.json` config THIS command reads, rendered
      * verbatim after the flag list. It lives on the command's entry rather than in the
@@ -51,6 +62,23 @@ export interface CommandSpec {
      * every later command, a field that command does not read (3F-3298). Omit when none.
      */
     configHelp?: string[];
+    /**
+     * Flags this command once accepted and no longer does (3F-3528). Refused like any flag
+     * outside `flags`, but as retired: a flag every earlier version accepts and no later one will
+     * cannot be cured by bumping a pin, only by moving to what replaced it. Never read by the help
+     * renderers, so a retired flag cannot reach `--help` or become accepted by being listed here.
+     * APPEND-ONLY. Omit when none.
+     */
+    retiredFlags?: RetiredFlagSpec[];
+}
+/** A flag a command has retired: what it was, the first version to refuse it, and its successor. */
+export interface RetiredFlagSpec {
+    /** The retired flag with dashes (e.g. "--measurements"). */
+    name: string;
+    /** The first published version whose command no longer accepted it. */
+    retiredIn: string;
+    /** One sentence naming what a consumer does instead. */
+    replacement: string;
 }
 /** The two-scope registry: the global host-modifier scope, and the per-command scopes. */
 export interface CliRegistry {

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

@@ -1 +1 @@
-{"version":3,"file":"cli-registry.d.ts","sourceRoot":"","sources":["../src/cli-registry.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAIH,0FAA0F;AAC1F,MAAM,WAAW,QAAQ;IACvB,oEAAoE;IACpE,IAAI,EAAE,MAAM,CAAC;IACb,iFAAiF;IACjF,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;IACnB,kFAAkF;IAClF,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,mFAAmF;IACnF,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,4EAA4E;IAC5E,WAAW,EAAE,MAAM,CAAC;CACrB;AAED,qGAAqG;AACrG,MAAM,WAAW,WAAW;IAC1B,0CAA0C;IAC1C,IAAI,EAAE,MAAM,CAAC;IACb,yFAAyF;IACzF,OAAO,EAAE,MAAM,CAAC;IAChB,4CAA4C;IAC5C,KAAK,EAAE,QAAQ,EAAE,CAAC;IAClB;;;;;;OAMG;IACH,UAAU,CAAC,EAAE,MAAM,EAAE,CAAC;CACvB;AAED,0FAA0F;AAC1F,MAAM,WAAW,WAAW;IAC1B,iFAAiF;IACjF,MAAM,EAAE,QAAQ,EAAE,CAAC;IACnB,8BAA8B;IAC9B,QAAQ,EAAE,WAAW,EAAE,CAAC;CACzB;AAgJD;;GAEG;AACH,eAAO,MAAM,WAAW,EAAE,WAiBzB,CAAC;AAQF;;;;;;;;;;;;GAYG;AACH,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,WAAW,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CAgBhF;AAED;;;;;;;;;GASG;AACH,wBAAgB,kBAAkB,CAAC,QAAQ,EAAE,WAAW,GAAG,MAAM,CA0BhE"}
+{"version":3,"file":"cli-registry.d.ts","sourceRoot":"","sources":["../src/cli-registry.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAIH,0FAA0F;AAC1F,MAAM,WAAW,QAAQ;IACvB,oEAAoE;IACpE,IAAI,EAAE,MAAM,CAAC;IACb,iFAAiF;IACjF,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;IACnB,kFAAkF;IAClF,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,mFAAmF;IACnF,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,4EAA4E;IAC5E,WAAW,EAAE,MAAM,CAAC;CACrB;AAED,8EAA8E;AAC9E,MAAM,WAAW,cAAc;IAC7B,uDAAuD;IACvD,IAAI,EAAE,MAAM,CAAC;IACb,0BAA0B;IAC1B,WAAW,EAAE,MAAM,CAAC;CACrB;AAED,qGAAqG;AACrG,MAAM,WAAW,WAAW;IAC1B,0CAA0C;IAC1C,IAAI,EAAE,MAAM,CAAC;IACb,yFAAyF;IACzF,OAAO,EAAE,MAAM,CAAC;IAChB,4CAA4C;IAC5C,KAAK,EAAE,QAAQ,EAAE,CAAC;IAClB,sGAAsG;IACtG,WAAW,CAAC,EAAE,cAAc,EAAE,CAAC;IAC/B,iHAAiH;IACjH,oBAAoB,CAAC,EAAE,KAAK,CAAC;IAC7B;;;;;;OAMG;IACH,UAAU,CAAC,EAAE,MAAM,EAAE,CAAC;IACtB;;;;;;OAMG;IACH,YAAY,CAAC,EAAE,eAAe,EAAE,CAAC;CAClC;AAED,oGAAoG;AACpG,MAAM,WAAW,eAAe;IAC9B,4DAA4D;IAC5D,IAAI,EAAE,MAAM,CAAC;IACb,uEAAuE;IACvE,SAAS,EAAE,MAAM,CAAC;IAClB,wDAAwD;IACxD,WAAW,EAAE,MAAM,CAAC;CACrB;AAED,0FAA0F;AAC1F,MAAM,WAAW,WAAW;IAC1B,iFAAiF;IACjF,MAAM,EAAE,QAAQ,EAAE,CAAC;IACnB,8BAA8B;IAC9B,QAAQ,EAAE,WAAW,EAAE,CAAC;CACzB;AA0HD;;GAEG;AACH,eAAO,MAAM,WAAW,EAAE,WA6BzB,CAAC;AAQF;;;;;;;;;;;;GAYG;AACH,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,WAAW,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CAiBhF;AAeD;;;;;;;;;GASG;AACH,wBAAgB,kBAAkB,CAAC,QAAQ,EAAE,WAAW,GAAG,MAAM,CA0BhE"}

package/dist/cli-registry.js

@@ -52,12 +52,7 @@ const balanceFlags = [
     {
         name: "--package-json",
         arg: "<path>",
-        description: "The target's package.json — its `scripts`, and its specController.fitnessChecks rows: each names a scenario's @SCN, a characteristic, and the command that is the check.",
-    },
-    {
-        name: "--measurements",
-        arg: "<report.json>",
-        description: "A measurement report — the number each measured check posted, evidence for the measured fitness checks.",
+        description: "The target's package.json — its `scripts`, and its specController.runners, specController.notChecks and specController.deferralTags. A fitness check is declared by its @fitness scenario and the CI step whose id: is that scenario's @SCN; no manifest key names one.",
     },
     {
         name: "--ci-steps",
@@ -89,6 +84,10 @@ const balanceFlags = [
         name: "--strict",
         description: "Fail the run (exit 3) when it carries Pending Items — the opt-in that escalates otherwise-run-neutral deferred obligations.",
     },
+    {
+        name: "--exit-zero",
+        description: "Print the same report but exit 0 on an out-of-balance or scenario-code-error (1) or --strict pending (3) verdict — the on-ramp before gating. Usage (2), unsound (4) and nothing-to-reconcile (5) still fail.",
+    },
     {
         name: "--help",
         aliases: ["-h"],
@@ -111,33 +110,14 @@ const balanceConfigHelp = [
     `      Built-in deferral tags: ${DEFAULT_DEFERRAL_TAGS.map((tag) => `@${tag}`).join(", ")}`,
 ];
 /**
- * The `tags` command's per-command scope (3F-3300). Two input flags and `--help`/`-h`, and the
- * two are `balance`'s own spellings on purpose: a consumer pointing one command at a corpus and a
- * manifest should not have to learn a second name for each when they point the other at the same
- * two files. The descriptions are this command's — what it reads them FOR is not what `balance`
- * reads them for — but the flags are the same flags.
- *
- * NO `configHelp`. A command's config block documents the `package.json` fields THAT command
- * reads, and `tags` reads none yet: the check-tag union and the recognised deferral set arrive
- * with the grammar rules (3F-3302 onward), and the entry gains its block then. Appending
- * `balance`'s block here would document, under this command, fields this command does not read —
- * which is the fault 3F-3298 moved that block onto a command entry to prevent.
+ * The flags `balance` has retired. `--measurements` left with the measured route at 3F-3506: no
+ * number reaches the ledger, and a fitness check is credited by its own CI step's outcome.
  */
-const tagsFlags = [
-    {
-        name: "--features",
-        arg: "<dir>",
-        description: "Directory of Gherkin .feature files — the corpus these rules are asked about (default ./features).",
-    },
+const balanceRetiredFlags = [
     {
-        name: "--package-json",
-        arg: "<path>",
-        description: "The target's package.json — its specController block, from which the words that name a check and the tags that park a scenario are resolved (default ./package.json).",
-    },
-    {
-        name: "--help",
-        aliases: ["-h"],
-        description: "Show this help and exit.",
+        name: "--measurements",
+        retiredIn: "0.1.0-alpha.5",
+        replacement: "A fitness check is credited by the outcome of its own CI step: put the check's @SCN on that step's `id:` and hand balance the run's step record with --ci-steps.",
     },
 ];
 /** The global host-modifier scope — recognised before the command; the CLI-007 surface. */
@@ -164,11 +144,22 @@ export const cliRegistry = {
             summary: "Reconcile Gherkin scenarios against test/CI evidence and emit the Evidence Reconciliation (Markdown to stdout by default).",
             flags: balanceFlags,
             configHelp: balanceConfigHelp,
+            retiredFlags: balanceRetiredFlags,
         },
         {
-            name: "tags",
-            summary: "Police the @SCN scheme over your Gherkin corpus — the rules the scheme itself imposes on the tags and header codes a feature file carries (exit 1 on findings, 2 on a corpus that cannot be read).",
-            flags: tagsFlags,
+            name: "allocate",
+            summary: "Print the next @SCN code for a feature part: one past the highest the repository has ever carried, the code alone on stdout.",
+            acceptsHostModifiers: false,
+            positionals: [
+                { name: "<FFF>", description: "The feature part: a feature file's header code, two to five of A-Z and 0-9." },
+            ],
+            flags: [
+                {
+                    name: "--new",
+                    description: "Start a part no feature file's header carries yet: its first code, or one past any number the repository already carries for it.",
+                },
+                { name: "--help", aliases: ["-h"], description: "Show this help and exit." },
+            ],
         },
     ],
 };
@@ -199,12 +190,26 @@ export function renderCommandHelp(registry, command) {
     const configHelp = entry?.configHelp ?? [];
     return [
         `spec-controller ${command} — ${entry?.summary ?? ""}`,
+        ...positionalHelp(command, entry?.positionals ?? []),
         "",
         "Options:",
         ...lines,
         ...(configHelp.length > 0 ? ["", ...configHelp] : []),
     ].join("\n");
 }
+/** A command's usage line and its arguments, one line each; nothing for a command that takes flags only. */
+function positionalHelp(command, positionals) {
+    if (positionals.length === 0)
+        return [];
+    const width = Math.max(...positionals.map((positional) => positional.name.length));
+    return [
+        "",
+        `Usage: spec-controller ${command} ${positionals.map((positional) => positional.name).join(" ")} [options]`,
+        "",
+        "Arguments:",
+        ...positionals.map((positional) => `  ${positional.name.padEnd(width + 2)}${positional.description}`),
+    ];
+}
 /**
  * Render the top-level `spec-controller --help` surface (@SCN-CLI-007) FROM the registry:
  * a Commands section (each command's name + one-line summary) and a Host modifiers section

package/dist/cli-registry.js.map

@@ -1 +1 @@
-{"version":3,"file":"cli-registry.js","sourceRoot":"","sources":["../src/cli-registry.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"cli-registry.js","sourceRoot":"","sources":["../src/cli-registry.ts"],"names":[],"mappings":"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"}

package/dist/cli.d.ts

@@ -6,11 +6,10 @@
  *   spec-controller [--store <root>] [--run-id <id>] <command> [command-args]
  *
  * Commands: `balance` — the deterministic reconciliation of scenarios against
- * observed evidence, standalone on the public core + app layer (no engine); `tags` — the
- * @SCN scheme policing itself over the same corpus, which is a fault about the corpus rather
- * than a verdict about its evidence, and so has its own status ladder rather than a fifth
- * meaning on balance's. The `analyse` / `migrate` capabilities are a separate, closed offering
- * built on the same core.
+ * observed evidence, standalone on the public core + app layer (no engine). It also polices the
+ * corpus's own scenario codes (3F-3635). `allocate` — a query, not a verdict: the next scenario code
+ * for a feature part, which keeps no run and so takes no host modifier. The
+ * `analyse` / `migrate` capabilities are a separate, closed offering built on the same core.
  *
  * Storage is a CROSS-CUTTING host modifier, not a command. A leading `--store <root>`
  * turns any command into a STORED run: the host wraps the command via the kept-run

package/dist/cli.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AACA;;;;;;;;;;;;;;;;;;;;GAoBG"}
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AACA;;;;;;;;;;;;;;;;;;;GAmBG"}

package/dist/cli.js

@@ -6,11 +6,10 @@
  *   spec-controller [--store <root>] [--run-id <id>] <command> [command-args]
  *
  * Commands: `balance` — the deterministic reconciliation of scenarios against
- * observed evidence, standalone on the public core + app layer (no engine); `tags` — the
- * @SCN scheme policing itself over the same corpus, which is a fault about the corpus rather
- * than a verdict about its evidence, and so has its own status ladder rather than a fifth
- * meaning on balance's. The `analyse` / `migrate` capabilities are a separate, closed offering
- * built on the same core.
+ * observed evidence, standalone on the public core + app layer (no engine). It also polices the
+ * corpus's own scenario codes (3F-3635). `allocate` — a query, not a verdict: the next scenario code
+ * for a feature part, which keeps no run and so takes no host modifier. The
+ * `analyse` / `migrate` capabilities are a separate, closed offering built on the same core.
  *
  * Storage is a CROSS-CUTTING host modifier, not a command. A leading `--store <root>`
  * turns any command into a STORED run: the host wraps the command via the kept-run
@@ -22,10 +21,10 @@
  */
 import { dirname } from "node:path";
 import { runBalance } from "./cli-balance/cli.js";
-import { runTags } from "./corpus/cli.js";
+import { runAllocate } from "./cli-allocate/cli.js";
 import { resolveSourceSha, resolveToolIdentity } from "./run-management/resolveRunInputs.js";
 import { executeKeptRun, resolveRunId, } from "./run-management/keptRun.js";
-import { parseHostInvocation, wrapCommandArgv, peekFlag } from "./host.js";
+import { parseHostInvocation, wrapCommandArgv, peekFlag, answerUnknownCommand, modifiersNotTakenRefusal, } from "./host.js";
 import { cliRegistry, renderTopLevelHelp } from "./cli-registry.js";
 /** Dispatch a command to its handler with the given (clean or store-wrapped) argv. */
 function runCommand(command, argv) {
@@ -33,16 +32,31 @@ function runCommand(command, argv) {
         case "balance":
             runBalance(argv);
             return;
-        case "tags":
-            runTags(argv);
+        case "allocate":
+            runAllocate(argv);
             return;
-        default:
-            process.stderr.write(`spec-controller: unknown command "${command}".\n\n${renderTopLevelHelp(cliRegistry)}\n`);
-            process.exit(1);
+        default: {
+            const answer = answerUnknownCommand(command, renderTopLevelHelp(cliRegistry));
+            process.stderr.write(answer.stderr);
+            process.exit(answer.exitCode);
+        }
     }
 }
+/**
+ * Refuse, at the usage status, what the leading tokens get wrong, before any command or stored run
+ * starts, so nothing is written anywhere: a usage fault among them (@SCN-CLI-059), or modifiers
+ * that would keep a run given to a command that keeps none.
+ */
+function refuseLeadingFaults(inv) {
+    const refusal = inv.refusal ?? modifiersNotTakenRefusal(inv);
+    if (refusal === undefined)
+        return;
+    process.stderr.write(refusal + "\n");
+    process.exit(2);
+}
 function main(hostArgv) {
     const inv = parseHostInvocation(hostArgv);
+    refuseLeadingFaults(inv);
     const command = inv.command;
     if (command === undefined || command === "help" || command === "--help" || command === "-h") {
         process.stdout.write(renderTopLevelHelp(cliRegistry) + "\n");

package/dist/cli.js.map

@@ -1 +1 @@
-{"version":3,"file":"cli.js","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"cli.js","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"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"}

package/dist/deferralTags.d.ts

@@ -5,8 +5,8 @@
  * established Cucumber deferral conventions.
  *
  * This is **product policy, not a core-domain invariant** — an evolvable list of tag
- * strings, so it lives in the application layer, NOT on the frozen v1 core barrel
- * (@SCN-API-001). The core `parseScenarios` recognises only the deferral set it is
+ * strings, so it lives in the application layer, NOT on the v1 core barrel.
+ * The core `parseScenarios` recognises only the deferral set it is
  * handed (its default is `[]`, a policy-free pure core); the app is the single source
  * of the starter policy and always passes the resolved set (starter ∪ configured) into
  * the parser at the ingest edge. Both `resolveDeferralTags` (the `@SCN-PND-021` config

package/dist/deferralTags.js

@@ -5,8 +5,8 @@
  * established Cucumber deferral conventions.
  *
  * This is **product policy, not a core-domain invariant** — an evolvable list of tag
- * strings, so it lives in the application layer, NOT on the frozen v1 core barrel
- * (@SCN-API-001). The core `parseScenarios` recognises only the deferral set it is
+ * strings, so it lives in the application layer, NOT on the v1 core barrel.
+ * The core `parseScenarios` recognises only the deferral set it is
  * handed (its default is `[]`, a policy-free pure core); the app is the single source
  * of the starter policy and always passes the resolved set (starter ∪ configured) into
  * the parser at the ingest edge. Both `resolveDeferralTags` (the `@SCN-PND-021` config

package/dist/host.d.ts

@@ -12,6 +12,7 @@
  *
  * @SCN-RMG-004 — features/run-management.feature.
  */
+import { type CommandSpec, type FlagSpec } from "./cli-registry.js";
 /** A parsed host invocation: leading global options, then the command and its clean args. */
 export interface HostInvocation {
     /** The injected store root from a leading `--store <root>`, or undefined (no store). */
@@ -22,6 +23,11 @@ export interface HostInvocation {
     command?: string;
     /** The command's own args — everything after the command token, verbatim. */
     commandArgs: string[];
+    /**
+     * The usage fault in the leading tokens, when there is one: the host refuses it at exit 2 before
+     * any command or stored run starts (@SCN-CLI-059).
+     */
+    refusal?: string;
 }
 /**
  * Parse the host argv into its leading global options (`--store`, `--run-id`) and the
@@ -31,8 +37,9 @@ export interface HostInvocation {
  * --features f` yields the store + `balance` + `[--features, f]`, while `balance --store
  * /s` leaves `--store` in the command's args (a `--store` AFTER the command is the
  * command's own arg, never a host store directive) — the "global before command" contract.
+ * A modifier with nothing after it is refused (@SCN-CLI-067); an empty argv is the bare help.
  */
-export declare function parseHostInvocation(argv: readonly string[]): HostInvocation;
+export declare function parseHostInvocation(argv: readonly string[], globalFlags?: readonly FlagSpec[], commands?: readonly string[]): HostInvocation;
 /**
  * Build the wrapped command argv: the command's clean args followed by a repeated
  * `--format <spec>` per store-dir output spec. Pure — the impure runner hands the result
@@ -47,4 +54,21 @@ export declare function wrapCommandArgv(commandArgs: readonly string[], formatSp
  * them in its own args. Returns undefined when the flag is absent or has no value.
  */
 export declare function peekFlag(argv: readonly string[], name: string): string | undefined;
+/** The host's answer to a command it does not know: what goes to stderr, and the status. */
+export interface UnknownCommandAnswer {
+    exitCode: number;
+    stderr: string;
+}
+/**
+ * Answer a command the registry does not carry. It is given the command token and the rendered
+ * help, never the command's args, so no flag after the command can change the answer.
+ *
+ * An unknown command is a usage fault, so it exits 2, the published usage code
+ * (packages/spec-controller/README.md), which `--exit-zero` never masks (3F-3649).
+ *
+ * @SCN-CLI-056 @SCN-CLI-057 — features/cli-balance.feature.
+ */
+export declare function answerUnknownCommand(command: string, help: string): UnknownCommandAnswer;
+/** The refusal for host modifiers given before a command that takes none, else undefined. */
+export declare function modifiersNotTakenRefusal(inv: HostInvocation, commands?: readonly CommandSpec[]): string | undefined;
 //# sourceMappingURL=host.d.ts.map

package/dist/host.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"host.d.ts","sourceRoot":"","sources":["../src/host.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,6FAA6F;AAC7F,MAAM,WAAW,cAAc;IAC7B,wFAAwF;IACxF,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,2FAA2F;IAC3F,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,4EAA4E;IAC5E,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,6EAA6E;IAC7E,WAAW,EAAE,MAAM,EAAE,CAAC;CACvB;AAED;;;;;;;;GAQG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,GAAG,cAAc,CAmB3E;AAED;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,WAAW,EAAE,SAAS,MAAM,EAAE,EAAE,WAAW,EAAE,SAAS,MAAM,EAAE,GAAG,MAAM,EAAE,CAExG;AAED;;;;;GAKG;AACH,wBAAgB,QAAQ,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CASlF"}
+{"version":3,"file":"host.d.ts","sourceRoot":"","sources":["../src/host.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAUH,OAAO,EAAe,KAAK,WAAW,EAAE,KAAK,QAAQ,EAAE,MAAM,mBAAmB,CAAC;AAEjF,6FAA6F;AAC7F,MAAM,WAAW,cAAc;IAC7B,wFAAwF;IACxF,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,2FAA2F;IAC3F,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,4EAA4E;IAC5E,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,6EAA6E;IAC7E,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED;;;;;;;;;GASG;AACH,wBAAgB,mBAAmB,CACjC,IAAI,EAAE,SAAS,MAAM,EAAE,EACvB,WAAW,GAAE,SAAS,QAAQ,EAAuB,EACrD,QAAQ,GAAE,SAAS,MAAM,EAAwD,GAChF,cAAc,CA2BhB;AAyFD;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,WAAW,EAAE,SAAS,MAAM,EAAE,EAAE,WAAW,EAAE,SAAS,MAAM,EAAE,GAAG,MAAM,EAAE,CAExG;AAED;;;;;GAKG;AACH,wBAAgB,QAAQ,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CASlF;AAED,4FAA4F;AAC5F,MAAM,WAAW,oBAAoB;IACnC,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;CAChB;AAED;;;;;;;;GAQG;AACH,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,oBAAoB,CAKxF;AAED,6FAA6F;AAC7F,wBAAgB,wBAAwB,CACtC,GAAG,EAAE,cAAc,EACnB,QAAQ,GAAE,SAAS,WAAW,EAAyB,GACtD,MAAM,GAAG,SAAS,CAUpB"}