spec-controller 0.1.0-alpha.1

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

@@ -0,0 +1,60 @@
+/**
+ * The output PLAN — the pure app-layer parse+validate of the `--format <fmt>[:<path>]`
+ * grammar (the three-layer split). Given the raw
+ * `--format` specs (in argv order; empty when no flag was passed), `planOutput` returns
+ * either an `OutputPlan` — an ordered list of `{ fmt, dest }` outputs — or a typed error.
+ *
+ * PURE: no IO. The plan describes WHAT to emit and WHERE; the writer (`writer.ts`) is the
+ * only layer that performs the IO. This split lets `planOutput` be proven in isolation
+ * (`@unit`, no subprocess) while the writer's real stdout/file effect is the `@integration`
+ * arm — the anti-watermelon rule (each integration arm asserts the real IO, never a
+ * planOutput re-run).
+ *
+ * FMT-001 (`@SCN-FMT-001`) establishes the skeleton: no flag — and an explicit `md` —
+ * plan a single markdown output bound for stdout. Later sub-issues extend `planOutput`
+ * with json (FMT-002), file dests (`<fmt>:<path>`, FMT-002/003), the at-most-one-to-stdout
+ * invariant (FMT-005), the legacy-`--json` rejection (FMT-006), and unknown-format
+ * rejection (FMT-007) — each landing on the `OutputPlan` type + typed `PlanResult` error
+ * surface designed here.
+ *
+ * Parent: @SCN-FMT-001 — the output-dispatch rework.
+ */
+/** A supported output format. FMT-001 plans `md`; `json` is wired in FMT-002. */
+export type OutputFormat = "md" | "json";
+/** Where a planned output is written — stdout, or a caller-given file path. */
+export type OutputDest = {
+    readonly kind: "stdout";
+} | {
+    readonly kind: "file";
+    readonly path: string;
+};
+/** One planned output: a format routed to a destination. */
+export interface PlannedOutput {
+    readonly fmt: OutputFormat;
+    readonly dest: OutputDest;
+}
+/** The plan: the ordered outputs a single invocation will emit. */
+export interface OutputPlan {
+    readonly outputs: readonly PlannedOutput[];
+}
+/**
+ * The result of planning — either the plan, or a typed error carrying the operator-facing
+ * message (later sub-issues raise these for the stdout-collision, legacy-flag, and
+ * unknown-format cases). A discriminated union so the CLI branches on `ok`.
+ */
+export type PlanResult = {
+    readonly ok: true;
+    readonly plan: OutputPlan;
+} | {
+    readonly ok: false;
+    readonly error: string;
+};
+/**
+ * Parse + validate the `--format` specs into an `OutputPlan` (or a typed error).
+ *
+ * FMT-001: no specs (no `--format` flag) defaults to a single `md`; an explicit `md`
+ * plans the same. Each planned output is markdown bound for stdout — the default human
+ * report, like vitest/cucumber.
+ */
+export declare function planOutput(formatSpecs: readonly string[]): PlanResult;
+//# sourceMappingURL=format.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"format.d.ts","sourceRoot":"","sources":["../../../src/cli-balance/emit/format.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,iFAAiF;AACjF,MAAM,MAAM,YAAY,GAAG,IAAI,GAAG,MAAM,CAAC;AAczC,+EAA+E;AAC/E,MAAM,MAAM,UAAU,GAClB;IAAE,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAA;CAAE,GAC3B;IAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC;AAErD,4DAA4D;AAC5D,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,GAAG,EAAE,YAAY,CAAC;IAC3B,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAC;CAC3B;AAED,mEAAmE;AACnE,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,OAAO,EAAE,SAAS,aAAa,EAAE,CAAC;CAC5C;AAED;;;;GAIG;AACH,MAAM,MAAM,UAAU,GAClB;IAAE,QAAQ,CAAC,EAAE,EAAE,IAAI,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAA;CAAE,GAChD;IAAE,QAAQ,CAAC,EAAE,EAAE,KAAK,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC;AAEnD;;;;;;GAMG;AACH,wBAAgB,UAAU,CAAC,WAAW,EAAE,SAAS,MAAM,EAAE,GAAG,UAAU,CAwDrE"}

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

@@ -0,0 +1,90 @@
+/**
+ * The output PLAN — the pure app-layer parse+validate of the `--format <fmt>[:<path>]`
+ * grammar (the three-layer split). Given the raw
+ * `--format` specs (in argv order; empty when no flag was passed), `planOutput` returns
+ * either an `OutputPlan` — an ordered list of `{ fmt, dest }` outputs — or a typed error.
+ *
+ * PURE: no IO. The plan describes WHAT to emit and WHERE; the writer (`writer.ts`) is the
+ * only layer that performs the IO. This split lets `planOutput` be proven in isolation
+ * (`@unit`, no subprocess) while the writer's real stdout/file effect is the `@integration`
+ * arm — the anti-watermelon rule (each integration arm asserts the real IO, never a
+ * planOutput re-run).
+ *
+ * FMT-001 (`@SCN-FMT-001`) establishes the skeleton: no flag — and an explicit `md` —
+ * plan a single markdown output bound for stdout. Later sub-issues extend `planOutput`
+ * with json (FMT-002), file dests (`<fmt>:<path>`, FMT-002/003), the at-most-one-to-stdout
+ * invariant (FMT-005), the legacy-`--json` rejection (FMT-006), and unknown-format
+ * rejection (FMT-007) — each landing on the `OutputPlan` type + typed `PlanResult` error
+ * surface designed here.
+ *
+ * Parent: @SCN-FMT-001 — the output-dispatch rework.
+ */
+/**
+ * The formats `planOutput` accepts; any other `--format` token is rejected (FMT-007 /
+ * @SCN-FMT-007). The single source of truth the unknown-format guard checks against AND
+ * lists in its hint, so a future format (html, sarif) is added in exactly one place.
+ */
+const SUPPORTED_FORMATS = ["md", "json"];
+/** Runtime narrowing of a parsed `--format` token to a supported `OutputFormat`. */
+function isSupportedFormat(fmt) {
+    return SUPPORTED_FORMATS.includes(fmt);
+}
+/**
+ * Parse + validate the `--format` specs into an `OutputPlan` (or a typed error).
+ *
+ * FMT-001: no specs (no `--format` flag) defaults to a single `md`; an explicit `md`
+ * plans the same. Each planned output is markdown bound for stdout — the default human
+ * report, like vitest/cucumber.
+ */
+export function planOutput(formatSpecs) {
+    // No --format flag defaults to a single "md" spec — the default human report.
+    const specs = formatSpecs.length === 0 ? ["md"] : formatSpecs;
+    const outputs = specs.map((spec) => {
+        // Grammar: "<fmt>[:<path>]". Split on the FIRST colon — the fmt is everything before
+        // it; a ":<path>" tail routes that format to the file at <path> (FMT-002/003), where
+        // the path is everything after the first colon (so a path may itself contain colons).
+        // No colon keeps the bare-fmt → stdout default (FMT-001). The at-most-one-to-stdout /
+        // unknown-format validation (FMT-005/007) lands on this same parse and the typed
+        // PlanResult error surface.
+        const colon = spec.indexOf(":");
+        const fmt = (colon === -1 ? spec : spec.slice(0, colon));
+        const dest = colon === -1 ? { kind: "stdout" } : { kind: "file", path: spec.slice(colon + 1) };
+        return { fmt, dest };
+    });
+    // The unknown-format guard (FMT-007 / @SCN-FMT-007): a
+    // --format naming an unsupported format (e.g. `xml`, or a typo) is rejected fast on the
+    // shared typed PlanResult error surface (the same surface FMT-005/006 use) — rather than
+    // silently rendering as markdown (the writer's default render branch) and exiting 0. The
+    // error LISTS the supported formats so the operator knows what to use — basic public-CLI
+    // robustness. Checked BEFORE the stdout-collision count so an unroutable format is
+    // reported as such (an unknown format can't meaningfully collide on stdout).
+    const unknown = outputs.filter((o) => !isSupportedFormat(o.fmt));
+    if (unknown.length > 0) {
+        const bad = [...new Set(unknown.map((o) => o.fmt))].join(", ");
+        return {
+            ok: false,
+            error: `Unknown --format ${bad}. Supported formats are ${SUPPORTED_FORMATS.join(", ")} ` +
+                `(e.g. --format md, --format json:report.json).`,
+        };
+    }
+    // The stdout invariant (FMT-005 / @SCN-FMT-005): AT MOST
+    // ONE output may route to stdout, so a captured stdout never carries two interleaved
+    // documents. This is a COUNT check on the stdout-destined outputs (≤ 1) — NOT a
+    // "distinct formats > 1" check — so `--format md --format md` (the same format twice,
+    // both stdout) is rejected just as `--format md --format json` is; a distinct-formats
+    // check would wrongly pass the former. Rejected with a typed error on the shared
+    // PlanResult surface (the same surface FMT-006/007 raise), carrying the hint to give one
+    // of the colliding outputs a `:<path>` so it writes to a file instead.
+    const stdoutBound = outputs.filter((o) => o.dest.kind === "stdout");
+    if (stdoutBound.length > 1) {
+        const fmts = stdoutBound.map((o) => o.fmt).join(", ");
+        return {
+            ok: false,
+            error: `More than one output routes to stdout (${fmts}); at most one may. ` +
+                `Give one of them a :<path> to write it to a file instead ` +
+                `(e.g. --format json:report.json).`,
+        };
+    }
+    return { ok: true, plan: { outputs } };
+}
+//# sourceMappingURL=format.js.map

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

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

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

@@ -0,0 +1,45 @@
+/**
+ * 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.
+ */
+import type { FeatureNames } from "@3f-consulting/spec-controller-core";
+import type { OutputPlan } from "./format.js";
+import type { RunContext } from "@3f-consulting/spec-controller-core";
+import type { EvidenceObligations } from "@3f-consulting/spec-controller-core";
+import type { EvidenceReconciliation } from "@3f-consulting/spec-controller-core";
+/**
+ * The reconciliation payloads the writer renders — the balance plus its sibling reads
+ * (ctx / corpus / guards / featureNames), exactly the arguments the pure renderers take. Threaded
+ * from `cli.ts` (built once, rendered per planned output). `withRuntimeObservations` and
+ * `withStaticChecks` are the GATES for the two observation axes (Test volume + the evidence grid;
+ * the Static checks cut): the renderers fold BOTH off the Ledger themselves (3F-2103 / 3F-2118 —
+ * the parallel censuses are retired), so the writer threads only whether each axis is in play,
+ * never a census object.
+ */
+export interface OutputPayloads {
+    readonly balance: EvidenceReconciliation;
+    readonly ctx: RunContext;
+    readonly evidenceObligations?: EvidenceObligations;
+    readonly withRuntimeObservations?: boolean;
+    readonly withStaticChecks?: boolean;
+    readonly featureNames?: 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.
+ */
+export declare function writeOutputs(plan: OutputPlan, payloads: OutputPayloads): void;
+//# sourceMappingURL=writer.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"writer.d.ts","sourceRoot":"","sources":["../../../src/cli-balance/emit/writer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAKH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,qCAAqC,CAAC;AACxE,OAAO,KAAK,EAAgB,UAAU,EAAE,MAAM,aAAa,CAAC;AAC5D,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,qCAAqC,CAAC;AACtE,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,qCAAqC,CAAC;AAC/E,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,qCAAqC,CAAC;AAElF;;;;;;;;GAQG;AACH,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,OAAO,EAAE,sBAAsB,CAAC;IACzC,QAAQ,CAAC,GAAG,EAAE,UAAU,CAAC;IACzB,QAAQ,CAAC,mBAAmB,CAAC,EAAE,mBAAmB,CAAC;IACnD,QAAQ,CAAC,uBAAuB,CAAC,EAAE,OAAO,CAAC;IAC3C,QAAQ,CAAC,gBAAgB,CAAC,EAAE,OAAO,CAAC;IACpC,QAAQ,CAAC,YAAY,CAAC,EAAE,YAAY,CAAC;CACtC;AAWD;;;GAGG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,UAAU,EAAE,QAAQ,EAAE,cAAc,GAAG,IAAI,CAc7E"}

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

@@ -0,0 +1,48 @@
+/**
+ * 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.
+ */
+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. */
+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.
+ */
+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;
+        }
+    }
+}
+//# sourceMappingURL=writer.js.map

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

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

package/dist/cli-registry.d.ts

@@ -0,0 +1,68 @@
+/**
+ * The data-driven command/flag registry — the single source the CLI answers `--help`
+ * from (@SCN-CLI-006). Two scopes mirror the two help surfaces:
+ *
+ *   - `global`   — the host modifiers recognised BEFORE the command (`--store`,
+ *                  `--run-id`), consumed by the top-level dispatcher; rendered by
+ *                  `spec-controller --help` (the sibling @SCN-CLI-007 surface).
+ *   - `commands` — the per-command scopes; `balance`'s 9 flags (+ `--help`/`-h`),
+ *                  rendered by `balance --help`.
+ *
+ * A flag exists ⇒ a registry entry ⇒ it appears in help, by construction — the
+ * single-source discipline the completeness guard (@SCN-CLI-008) will enforce and the
+ * registry-bounded parser (@SCN-CLI-009) will reject against. Flag descriptions are
+ * migrated from doc/how_to_use.md's flag table, which the registry now supersedes as the
+ * source of truth. Registry + renderers live in the CLI/app layer, never the domain.
+ */
+/** One flag in a scope: its canonical name, optional aliases, value placeholder, help. */
+export interface FlagSpec {
+    /** The canonical flag with dashes (e.g. "--features", "--help"). */
+    name: string;
+    /** Alternate spellings rendered after the name (e.g. ["-h"]); omit when none. */
+    aliases?: string[];
+    /** The value placeholder (e.g. "<dir>"); omit for boolean flags like `--help`. */
+    arg?: string;
+    /** True when the flag may be given more than once (`--format`); omit otherwise. */
+    repeatable?: boolean;
+    /** One-line help text — the description migrated from doc/how_to_use.md. */
+    description: string;
+}
+/** A command: its token, a one-line summary, and its per-command flag scope. */
+export interface CommandSpec {
+    /** The command token (e.g. "balance"). */
+    name: string;
+    /** One-line summary for the top-level `spec-controller --help` (the CLI-007 surface). */
+    summary: string;
+    /** The command's per-command flag scope. */
+    flags: FlagSpec[];
+}
+/** The two-scope registry: the global host-modifier scope, and the per-command scopes. */
+export interface CliRegistry {
+    /** Host modifiers recognised before the command — the global scope (CLI-007). */
+    global: FlagSpec[];
+    /** The per-command scopes. */
+    commands: CommandSpec[];
+}
+/**
+ * The registry singleton — the single source both help surfaces render from.
+ */
+export declare const cliRegistry: CliRegistry;
+/**
+ * Render the `balance` command's per-command scope as help text: one line per registered
+ * flag (name + arg-placeholder + description), driven BY the registry — so a flag that
+ * exists is a flag that appears, by construction. Returns the help block WITHOUT a
+ * trailing newline (the caller adds it, matching the writer's stdout convention).
+ */
+export declare function renderBalanceHelp(registry: CliRegistry): string;
+/**
+ * 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
+ * (each global-scope flag: name + arg-placeholder + one-line description). The global-scope
+ * half of the two-scope registry — the counterpart to `renderBalanceHelp`'s per-command
+ * half — so the top-level usage no longer hand-keeps (and can no longer silently drift
+ * from) the command set or the host modifiers; both are sourced from `cliRegistry`.
+ * Summaries and descriptions render on a single line (no wrapping) so a registered string
+ * appears verbatim. Returns the block WITHOUT a trailing newline (the caller adds it).
+ */
+export declare function renderTopLevelHelp(registry: CliRegistry): string;
+//# sourceMappingURL=cli-registry.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"cli-registry.d.ts","sourceRoot":"","sources":["../src/cli-registry.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;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,gFAAgF;AAChF,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;CACnB;AAED,0FAA0F;AAC1F,MAAM,WAAW,WAAW;IAC1B,iFAAiF;IACjF,MAAM,EAAE,QAAQ,EAAE,CAAC;IACnB,8BAA8B;IAC9B,QAAQ,EAAE,WAAW,EAAE,CAAC;CACzB;AAsFD;;GAEG;AACH,eAAO,MAAM,WAAW,EAAE,WAUzB,CAAC;AAQF;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,WAAW,GAAG,MAAM,CA2B/D;AAED;;;;;;;;;GASG;AACH,wBAAgB,kBAAkB,CAAC,QAAQ,EAAE,WAAW,GAAG,MAAM,CA0BhE"}

package/dist/cli-registry.js

@@ -0,0 +1,181 @@
+/**
+ * The data-driven command/flag registry — the single source the CLI answers `--help`
+ * from (@SCN-CLI-006). Two scopes mirror the two help surfaces:
+ *
+ *   - `global`   — the host modifiers recognised BEFORE the command (`--store`,
+ *                  `--run-id`), consumed by the top-level dispatcher; rendered by
+ *                  `spec-controller --help` (the sibling @SCN-CLI-007 surface).
+ *   - `commands` — the per-command scopes; `balance`'s 9 flags (+ `--help`/`-h`),
+ *                  rendered by `balance --help`.
+ *
+ * A flag exists ⇒ a registry entry ⇒ it appears in help, by construction — the
+ * single-source discipline the completeness guard (@SCN-CLI-008) will enforce and the
+ * registry-bounded parser (@SCN-CLI-009) will reject against. Flag descriptions are
+ * migrated from doc/how_to_use.md's flag table, which the registry now supersedes as the
+ * source of truth. Registry + renderers live in the CLI/app layer, never the domain.
+ */
+import { DEFAULT_DEFERRAL_TAGS } from "./deferralTags.js";
+/**
+ * The `balance` command's per-command scope — its 9 reconciliation flags plus `--help`/
+ * `-h`. Descriptions migrated from doc/how_to_use.md's flag table (the registry now the
+ * source of truth; the doc is reconciled against it by @SCN-CLI-007/008).
+ */
+const balanceFlags = [
+    {
+        name: "--features",
+        arg: "<dir>",
+        description: "Directory of Gherkin .feature files — the scenarios.",
+    },
+    {
+        name: "--vitest",
+        arg: "<report.json>",
+        description: "A Vitest JSON report — runtime test evidence.",
+    },
+    {
+        name: "--cucumber",
+        arg: "<report.json>",
+        description: "A Cucumber JSON report — runtime test evidence.",
+    },
+    {
+        name: "--ci",
+        arg: "<ci.yml>",
+        description: "Your CI workflow — used to check whether @lint guards actually run over the real source.",
+    },
+    {
+        name: "--package-json",
+        arg: "<path>",
+        description: "package.json — used to check a named guard's script exists.",
+    },
+    {
+        name: "--measurements",
+        arg: "<report.json>",
+        description: "A measurement report — the number each measured check posted, evidence for the measured fitness checks.",
+    },
+    {
+        name: "--target",
+        arg: "<name>",
+        description: "A name recorded verbatim in the report's provenance (which project this run reconciled).",
+    },
+    {
+        name: "--source-sha",
+        arg: "<sha>",
+        description: "Override the git commit SHA recorded in provenance (defaults to the resolved HEAD).",
+    },
+    {
+        name: "--format",
+        arg: "<fmt>[:<path>]",
+        repeatable: true,
+        description: "Where to send output (md or json, optionally :<path> to write to a file). Repeatable.",
+    },
+    {
+        name: "--render-from-json",
+        arg: "<path>",
+        description: "Re-render Markdown from a previously saved Evidence Reconciliation JSON — no reconcile, no live inputs.",
+    },
+    {
+        name: "--strict",
+        description: "Fail the run (exit 3) when it carries Pending Items — the opt-in that escalates otherwise-run-neutral deferred obligations.",
+    },
+    {
+        name: "--help",
+        aliases: ["-h"],
+        description: "Show this help and exit.",
+    },
+];
+/** The global host-modifier scope — recognised before the command; the CLI-007 surface. */
+const globalFlags = [
+    {
+        name: "--store",
+        arg: "<root>",
+        description: "Store the run: write <root>/<target>/<run-id>/ with the reconciliation outputs + a run.yaml manifest. Required to store; there is no default (a default would write inside the repo).",
+    },
+    {
+        name: "--run-id",
+        arg: "<id>",
+        description: "Name the stored run (default: an ISO-8601 UTC timestamp).",
+    },
+];
+/**
+ * The registry singleton — the single source both help surfaces render from.
+ */
+export const cliRegistry = {
+    global: globalFlags,
+    commands: [
+        {
+            name: "balance",
+            summary: "Reconcile Gherkin scenarios against test/CI evidence and emit the Evidence Reconciliation (Markdown to stdout by default).",
+            flags: balanceFlags,
+        },
+    ],
+};
+/** The display label for a flag: its name, any aliases, then its arg-placeholder. */
+function flagLabel(flag) {
+    const names = [flag.name, ...(flag.aliases ?? [])].join(", ");
+    return flag.arg !== undefined ? `${names} ${flag.arg}` : names;
+}
+/**
+ * Render the `balance` command's per-command scope as help text: one line per registered
+ * flag (name + arg-placeholder + description), driven BY the registry — so a flag that
+ * exists is a flag that appears, by construction. Returns the help block WITHOUT a
+ * trailing newline (the caller adds it, matching the writer's stdout convention).
+ */
+export function renderBalanceHelp(registry) {
+    const command = registry.commands.find((c) => c.name === "balance");
+    const flags = command?.flags ?? [];
+    const gutter = 2;
+    const labelWidth = Math.max(0, ...flags.map((f) => flagLabel(f).length));
+    const lines = flags.map((flag) => `  ${flagLabel(flag).padEnd(labelWidth + gutter)}${flag.description}`);
+    // The `specController.deferralTags` config field, with its recognised starter set SINGLE-SOURCED
+    // from DEFAULT_DEFERRAL_TAGS (@SCN-PND-021 / the 3F-1405 completeness discipline — the render reads
+    // the constant, never a hand-kept copy, so the documented set cannot drift from the recognised one).
+    const starterSet = DEFAULT_DEFERRAL_TAGS.map((tag) => `@${tag}`).join(", ");
+    const configLines = [
+        "Configuration (in the target repo's package.json):",
+        "  specController.deferralTags: string[]",
+        "      Extra recognised deferral tags. A scenario carrying one defers every obligation it",
+        "      names to a Pending Item, extending (never replacing) the built-in set.",
+        `      Built-in deferral tags: ${starterSet}`,
+    ];
+    return [
+        `spec-controller balance — ${command?.summary ?? ""}`,
+        "",
+        "Options:",
+        ...lines,
+        "",
+        ...configLines,
+    ].join("\n");
+}
+/**
+ * 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
+ * (each global-scope flag: name + arg-placeholder + one-line description). The global-scope
+ * half of the two-scope registry — the counterpart to `renderBalanceHelp`'s per-command
+ * half — so the top-level usage no longer hand-keeps (and can no longer silently drift
+ * from) the command set or the host modifiers; both are sourced from `cliRegistry`.
+ * Summaries and descriptions render on a single line (no wrapping) so a registered string
+ * appears verbatim. Returns the block WITHOUT a trailing newline (the caller adds it).
+ */
+export function renderTopLevelHelp(registry) {
+    const commandGutter = 4;
+    const commandWidth = Math.max(0, ...registry.commands.map((c) => c.name.length));
+    const commandLines = registry.commands.map((command) => `  ${command.name.padEnd(commandWidth + commandGutter)}${command.summary}`);
+    const modifierGutter = 3;
+    const modifierWidth = Math.max(0, ...registry.global.map((f) => flagLabel(f).length));
+    const modifierLines = registry.global.map((flag) => `  ${flagLabel(flag).padEnd(modifierWidth + modifierGutter)}${flag.description}`);
+    const modifierUsage = registry.global.map((flag) => `[${flagLabel(flag)}]`).join(" ");
+    return [
+        "spec-controller — reconcile scenarios against observed evidence",
+        "",
+        "Usage:",
+        `  spec-controller ${modifierUsage} <command> [command-args]`,
+        "",
+        "Commands:",
+        ...commandLines,
+        "",
+        "Host modifiers (before the command):",
+        ...modifierLines,
+        "",
+        "Full flags, examples, and CI wiring: doc/how_to_use.md.",
+    ].join("\n");
+}
+//# sourceMappingURL=cli-registry.js.map

package/dist/cli-registry.js.map

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

package/dist/cli.d.ts

@@ -0,0 +1,22 @@
+#!/usr/bin/env node
+/**
+ * The `spec-controller` binary — the top-level command host + dispatcher.
+ *
+ * Usage:
+ *   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). 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
+ * scaffold — a named `<root>/<target>/<run-id>/` directory, the command's outputs routed
+ * in, and a `run.yaml` manifest — and hands the command its own clean args, unchanged. So
+ * `balance` stays emit-only (its default, no-store output is byte-identical); the store
+ * opinion lives at the host, injected via `--store` (required — there is no default, a
+ * default would write inside the repo). `--run-id` defaults to a timestamp.
+ */
+export {};
+//# sourceMappingURL=cli.d.ts.map

package/dist/cli.d.ts.map

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

package/dist/cli.js

@@ -0,0 +1,82 @@
+#!/usr/bin/env node
+/**
+ * The `spec-controller` binary — the top-level command host + dispatcher.
+ *
+ * Usage:
+ *   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). 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
+ * scaffold — a named `<root>/<target>/<run-id>/` directory, the command's outputs routed
+ * in, and a `run.yaml` manifest — and hands the command its own clean args, unchanged. So
+ * `balance` stays emit-only (its default, no-store output is byte-identical); the store
+ * opinion lives at the host, injected via `--store` (required — there is no default, a
+ * default would write inside the repo). `--run-id` defaults to a timestamp.
+ */
+import { dirname } from "node:path";
+import { runBalance } from "./cli-balance/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 { cliRegistry, renderTopLevelHelp } from "./cli-registry.js";
+/** Dispatch a command to its handler with the given (clean or store-wrapped) argv. */
+function runCommand(command, argv) {
+    switch (command) {
+        case "balance":
+            runBalance(argv);
+            return;
+        default:
+            process.stderr.write(`spec-controller: unknown command "${command}".\n\n${renderTopLevelHelp(cliRegistry)}\n`);
+            process.exit(1);
+    }
+}
+function main(hostArgv) {
+    const inv = parseHostInvocation(hostArgv);
+    const command = inv.command;
+    if (command === undefined || command === "help" || command === "--help" || command === "-h") {
+        process.stdout.write(renderTopLevelHelp(cliRegistry) + "\n");
+        return;
+    }
+    // No store directive → dispatch the command directly; its output is unchanged.
+    if (inv.store === undefined) {
+        runCommand(command, inv.commandArgs);
+        return;
+    }
+    // Store directive → wrap the command via keptRun. The scaffold makes the run dir, hands
+    // the injected route the two store-dir `--format` specs, and stamps run.yaml. The route
+    // dispatches the command with its own clean args PLUS those specs, so the command's own
+    // writer produces the stored artefacts (byte-identical to a bare `--format` run). The
+    // host peeks the conventional provenance flags off the command args to name the dir +
+    // stamp the manifest, without consuming them (the command still sees them).
+    const runId = resolveRunId({ runId: inv.runId, now: new Date() });
+    const target = peekFlag(inv.commandArgs, "target") ?? "unknown-target";
+    const features = peekFlag(inv.commandArgs, "features");
+    const sourceSha = resolveSourceSha({
+        sourceSha: peekFlag(inv.commandArgs, "source-sha"),
+        targetDir: features !== undefined ? dirname(features) : undefined,
+    }) ?? "unknown";
+    const spec = { storeRoot: inv.store, target, runId };
+    // `mode` is the command's run kind; only `balance` ships today (analyse/migrate are the
+    // private engine's, added when it lands).
+    // The TOOL's own identity (3F-1916) — which spec-controller produced this run, read
+    // from the tool's OWN dir (never cwd, which is the target). "unknown" for a null SHA,
+    // matching sourceSha's own fallback so run.yaml is internally consistent.
+    const toolIdentity = resolveToolIdentity();
+    const meta = {
+        sourceSha,
+        toolSha: toolIdentity.toolSha ?? "unknown",
+        toolVersion: toolIdentity.toolVersion,
+        mode: "balance",
+        date: new Date().toISOString(),
+    };
+    const plan = executeKeptRun(spec, meta, (formatSpecs) => runCommand(command, wrapCommandArgv(inv.commandArgs, [...formatSpecs])));
+    // The command's stdout was routed into the run dir, so tell the operator where it landed.
+    process.stdout.write(plan.runDir + "\n");
+}
+main(process.argv.slice(2));
+//# sourceMappingURL=cli.js.map

package/dist/cli.js.map

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