@sdd-method/maintain-cli 0.0.0-stage → 0.1.0

package/dist/maintain-program.js

@@ -0,0 +1,91 @@
+// Fourth entrypoint: the MAINTAIN surface — M-ADR 0218.
+//
+// A binary that brings an SDD current and rebuilds its derived model, and cannot change
+// what the SDD says. It is to unattended sync waves what sdd-verify is to CI.
+//
+// A verb is here when everything it writes is DERIVED or METHOD-MANAGED, deterministically
+// (M-ADR 0218 §4.2–4.3): the method payload, lock, CI block and briefing (`sync`,
+// `generate-briefing`), the derived model (`catalogue build | aggregate | graph | diff`), an
+// output the caller names (`pack build`, `render screen`), and a code repository's briefing
+// (`context pull`). Plus the whole verify surface, because the personas nest.
+//
+// ⚠ As with sdd-verify, the boundary is ABSENCE, not a menu: the package ships only the import
+// closure of maintain-bin.js, so authoring verbs (init, scaffold, plan, mcp, conformance,
+// contracts, api-surface, snapshot, metamodel, migration-map) are not present to be reached.
+// That is why every registration below imports a per-subcommand registrar, never a barrel.
+// Unclassified verbs default to AUTHOR (M-ADR 0218 §4.2) and stay out until classified.
+import { Command, CommanderError } from "commander";
+import { getPackageVersion } from "./lib/package-version.js";
+import { registerVerifySurface, rejectOutsideSurface, VERIFY_SURFACE } from "./verify-program.js";
+import { registerCatalogueAggregate, registerCatalogueBuild, registerCatalogueDiff, registerCatalogueGraph } from "./verbs/catalogue-maintain.js";
+import { registerContext } from "./verbs/context.js";
+import { registerGenerateBriefing } from "./verbs/generate-briefing.js";
+import { registerPackBuild } from "./verbs/pack-build.js";
+import { registerRender } from "./verbs/render.js";
+import { registerSync } from "./verbs/sync.js";
+const SPEC_URL = "https://github.com/tomfosteruk/sdd-method/blob/main/docs/method/cli/sdd-cli-specification.md";
+/** The verbs maintain adds to verify, as `<verb>` or `<verb> <subcommand>`. Asserted by test. */
+export const MAINTAIN_ONLY_SURFACE = [
+    "sync",
+    "generate-briefing",
+    "context pull",
+    "catalogue build",
+    "catalogue aggregate",
+    "catalogue graph",
+    "catalogue diff",
+    "pack build",
+    "render screen",
+];
+/** The full surface: verify's, plus maintain's own. */
+export const MAINTAIN_SURFACE = [...VERIFY_SURFACE, ...MAINTAIN_ONLY_SURFACE];
+const OUTSIDE = "is not part of sdd-maintain, which can bring a repository current and rebuild its derived model but cannot author specification content. " +
+    "Authoring verbs are in @sdd-method/sdd-cli.";
+export async function runMaintain(argv) {
+    const program = buildMaintainProgram();
+    if (argv.length === 0) {
+        program.outputHelp();
+        return;
+    }
+    rejectOutsideSurface(program, argv, OUTSIDE);
+    try {
+        await program.parseAsync([...argv], { from: "user" });
+    }
+    catch (err) {
+        if (err instanceof CommanderError) {
+            if (err.code === "commander.help" || err.code === "commander.helpDisplayed" || err.code === "commander.version") {
+                return;
+            }
+        }
+        throw err;
+    }
+}
+export function buildMaintainProgram() {
+    const program = new Command();
+    program
+        .name("sdd-maintain")
+        .description("Bring an SDD repository current and rebuild its derived model — sync, briefing, catalogue build and aggregate, pack build, context pull — plus every read-only verify verb. Cannot author specification content.")
+        .version(getPackageVersion(), "-v, --version")
+        .addHelpText("after", `\nSpec: ${SPEC_URL}\nAuthoring verbs (init, scaffold, plan, mcp, conformance, …) are in @sdd-method/sdd-cli.`)
+        .exitOverride()
+        .configureOutput({
+        writeOut: (str) => process.stdout.write(str),
+        writeErr: (str) => process.stderr.write(str),
+    });
+    // The verify surface first, from verify's own registration: the nesting is structural.
+    registerVerifySurface(program);
+    registerSync(program);
+    registerGenerateBriefing(program);
+    registerContext(program);
+    registerRender(program);
+    const catalogue = program.commands.find((c) => c.name() === "catalogue");
+    catalogue.description("Build, aggregate, validate and query per-SDD catalogues (ADR 0134) — the derived model");
+    registerCatalogueBuild(catalogue);
+    registerCatalogueAggregate(catalogue);
+    registerCatalogueGraph(catalogue);
+    registerCatalogueDiff(catalogue);
+    const pack = program.commands.find((c) => c.name() === "pack");
+    pack.description("Build and validate adopter-shipped context-pack bundles (ADR 0151)");
+    registerPackBuild(pack);
+    return program;
+}
+//# sourceMappingURL=maintain-program.js.map

package/dist/maintain-version.json

@@ -0,0 +1,4 @@
+{
+  "version": "0.1.0",
+  "built_against_sdd_cli": "1.42.0"
+}

package/dist/verbs/catalogue-maintain.js

@@ -0,0 +1,110 @@
+// The catalogue subcommands that write the derived model — MAINTAIN under M-ADR 0218 §4.4:
+// a deterministic function of the committed specs, written only under catalogues/,
+// catalogues-aggregated/ and the graph projection beside them. One registrar per
+// subcommand, importing each run* from its OWN module and never the catalogue barrel
+// (which also re-exports migration-map), so the maintain package's import closure
+// carries exactly these and no authoring module.
+import { resolve } from "node:path";
+import { runCatalogueBuild } from "../lib/catalogue/build.js";
+import { runCatalogueAggregate } from "../lib/catalogue/aggregate.js";
+import { runCatalogueGraph } from "../lib/catalogue/graph-run.js";
+import { runCatalogueDiff } from "../lib/snapshot/catalogue-diff.js";
+import { checkCataloguesFresh } from "../lib/catalogue/freshness.js";
+export function registerCatalogueBuild(catalogue) {
+    catalogue
+        .command("build")
+        .description("Build catalogues for the current SDD repo from method-defined sources")
+        .option("--sdd-path <path>", "Path to the SDD repo root (defaults to cwd)")
+        .option("--out <path>", "Output directory for catalogues/ (defaults to <sdd-path>/catalogues)")
+        .option("--strict", "Treat findings as failures (default: only internal FK FAIL exits non-zero)")
+        .option("--snapshot-store <dir>", "Snapshot store root the binding's snapshot_area is relative to (default: $SDD_SNAPSHOT_STORE; M-ADR 0214)")
+        .option("--check", "Freshness check: build into a temporary directory, compare with the committed catalogues/, write nothing; exit 1 listing every stale file (M-ADR 0218 §5)")
+        .action(async (opts) => {
+        const snapshotStore = opts.snapshotStore ?? process.env.SDD_SNAPSHOT_STORE;
+        if (opts.check === true) {
+            if (opts.out !== undefined) {
+                process.stderr.write("--check builds into a temporary directory; it cannot be combined with --out\n");
+                process.exit(2);
+            }
+            const r = await checkCataloguesFresh(resolve(opts.sddPath ?? process.cwd()), {
+                ...(opts.strict !== undefined ? { strict: opts.strict } : {}),
+                ...(snapshotStore !== undefined ? { snapshotStore } : {}),
+            }, (s) => process.stdout.write(s));
+            if (r.exitCode !== 0)
+                process.exit(r.exitCode);
+            return;
+        }
+        const result = await runCatalogueBuild({
+            ...(opts.sddPath !== undefined ? { sddPath: opts.sddPath } : {}),
+            ...(opts.out !== undefined ? { outDir: opts.out } : {}),
+            ...(opts.strict !== undefined ? { strict: opts.strict } : {}),
+            ...(snapshotStore !== undefined ? { snapshotStore } : {}),
+        }, (s) => process.stdout.write(s));
+        if (result.exitCode !== 0)
+            process.exit(result.exitCode);
+    });
+}
+export function registerCatalogueAggregate(catalogue) {
+    catalogue
+        .command("aggregate")
+        .description("Aggregate sibling SDD catalogues into a single ecosystem catalogue")
+        .option("--sdd-path <path>", "Path to the ecosystem-root SDD repo (defaults to cwd)")
+        .option("--manifest <path>", "Path to the aggregation manifest (defaults to orchestration/aggregation-manifest.yaml)")
+        .option("--out <path>", "Output directory for aggregated catalogues/ (defaults to <sdd-path>/catalogues-aggregated)")
+        .option("--strict", "Treat findings as failures")
+        .action(async (opts) => {
+        const result = await runCatalogueAggregate({
+            ...(opts.sddPath !== undefined ? { sddPath: opts.sddPath } : {}),
+            ...(opts.manifest !== undefined
+                ? { manifestPath: opts.manifest }
+                : {}),
+            ...(opts.out !== undefined ? { outDir: opts.out } : {}),
+            ...(opts.strict !== undefined ? { strict: opts.strict } : {}),
+        }, (s) => process.stdout.write(s));
+        if (result.exitCode !== 0)
+            process.exit(result.exitCode);
+    });
+}
+export function registerCatalogueDiff(catalogue) {
+    catalogue
+        .command("diff")
+        .description("Build the catalogues at a git ref and at the working tree in ONE process (so one CLI), and attribute the change at file grain: every SDD source file changed since the ref must be a target of some delta.yaml finding. Exit 1 on any unattributed change. Writes nothing into the SDD.")
+        .requiredOption("--from <ref>", "the git ref of the SDD before the snapshot update")
+        .requiredOption("--attribute <delta.yaml>", "the snapshot's delta.yaml, whose findings' targets attribute the change")
+        .option("--sdd-path <path>", "Path to the SDD repo root (defaults to cwd)")
+        .action(async (opts) => {
+        const r = await runCatalogueDiff({ sddPath: resolve(opts.sddPath ?? process.cwd()), from: opts.from, attribute: resolve(opts.attribute) }, (s) => process.stdout.write(s));
+        if (r.exitCode !== 0)
+            process.exit(r.exitCode);
+    });
+}
+export function registerCatalogueGraph(catalogue) {
+    catalogue
+        .command("graph")
+        .description("Emit the graph projection (typed node/edge JSON Lines) derived from built catalogues (M-ADR 0205 §4.6) — regenerated every run, digest-stamped, never committed")
+        .option("--sdd-path <path>", "Path to the SDD repo root (defaults to cwd)")
+        .option("--catalogues-dir <dir>", "Catalogues directory relative to the SDD root (default: catalogues, or catalogues-aggregated at --tier aggregate)")
+        .option("--tier <tier>", "Tier, explicit never inferred (member | aggregate; default member)")
+        .option("--out <path>", "Output file (default <catalogues-dir>-graph.jsonl beside the catalogues directory)")
+        .action(async (opts) => {
+        if (opts.tier !== undefined &&
+            opts.tier !== "member" &&
+            opts.tier !== "aggregate") {
+            process.stderr.write(`--tier must be 'member' or 'aggregate' (got: ${opts.tier})\n`);
+            process.exit(2);
+        }
+        const result = await runCatalogueGraph({
+            ...(opts.sddPath !== undefined ? { sddPath: opts.sddPath } : {}),
+            ...(opts.cataloguesDir !== undefined
+                ? { cataloguesDir: opts.cataloguesDir }
+                : {}),
+            ...(opts.tier !== undefined
+                ? { tier: opts.tier }
+                : {}),
+            ...(opts.out !== undefined ? { out: opts.out } : {}),
+        }, (s) => process.stdout.write(s));
+        if (result.exitCode !== 0)
+            process.exit(result.exitCode);
+    });
+}
+//# sourceMappingURL=catalogue-maintain.js.map

package/dist/verbs/catalogue-verify.js

@@ -0,0 +1,114 @@
+// The read-only `catalogue` subcommands — validate (incl. --coverage), impact,
+// baseline-check, version — split from `catalogue.ts` so a program can register
+// them without importing the catalogue BUILD path. The verify-only CLI ships
+// these and must not ship code that writes the derived model (M-ADR 0212 §4.3b).
+// `registerCatalogue` calls each at its original position, so sdd-cli's
+// `catalogue` surface and help order are unchanged.
+//
+// ⚠ Import each run* from its own module, NEVER from `../lib/catalogue/index.js`:
+// that barrel re-exports the build and aggregate paths, and one convenience
+// import from it would silently put authoring code back into the verify package.
+import { runBaselineCheck } from "../lib/catalogue/baseline-check.js";
+import { runCatalogueCoverage } from "../lib/catalogue/coverage-run.js";
+import { runCatalogueImpact } from "../lib/catalogue/impact-run.js";
+import { runCatalogueValidate } from "../lib/catalogue/validate.js";
+import { runCatalogueVersion } from "../lib/catalogue/version.js";
+export function registerCatalogueValidate(catalogue) {
+    catalogue
+        .command("validate")
+        .description("Re-run column-shape + FK validation against existing catalogues/ (no rebuild)")
+        .option("--sdd-path <path>", "Path to the SDD repo root (defaults to cwd)")
+        .option("--strict", "Treat findings as failures")
+        .option("--coverage", "Coverage mode: run the engine coverage predicates instead (same lines the gate scripts printed; exit 0 — gating stays the baseline's job)")
+        .option("--tier <tier>", "Coverage tier, explicit never inferred (member | aggregate; default member)")
+        .option("--catalogues-dir <dir>", "Coverage mode: catalogues directory relative to the SDD root (default catalogues)")
+        .action(async (opts) => {
+        if (opts.coverage === true) {
+            if (opts.tier !== undefined &&
+                opts.tier !== "member" &&
+                opts.tier !== "aggregate") {
+                process.stderr.write(`--tier must be 'member' or 'aggregate' (got: ${opts.tier})\n`);
+                process.exit(2);
+            }
+            const result = await runCatalogueCoverage({
+                ...(opts.sddPath !== undefined ? { sddPath: opts.sddPath } : {}),
+                ...(opts.cataloguesDir !== undefined
+                    ? { cataloguesDir: opts.cataloguesDir }
+                    : {}),
+                ...(opts.tier !== undefined
+                    ? { tier: opts.tier }
+                    : {}),
+            }, (s) => process.stdout.write(s));
+            if (result.exitCode !== 0)
+                process.exit(result.exitCode);
+            return;
+        }
+        const result = await runCatalogueValidate({
+            ...(opts.sddPath !== undefined ? { sddPath: opts.sddPath } : {}),
+            ...(opts.strict !== undefined ? { strict: opts.strict } : {}),
+        }, (s) => process.stdout.write(s));
+        if (result.exitCode !== 0)
+            process.exit(result.exitCode);
+    });
+}
+export function registerCatalogueImpact(catalogue) {
+    catalogue
+        .command("impact")
+        .description("Change-impact closure of a node (M-ADR 0206): each relationship is traversed per its declared impact-flow from the rubric-coverage-map — dependency edges reach their consumers, membership edges propagate part-to-whole only, xref/lineage records are inert — computed by recursive SQL on the embedded engine, with the co-directionality invariant asserted on every run")
+        .requiredOption("--of <node-id>", 'Node to compute impact of, in the projection\'s "<catalogue>/<id>" form (e.g. contracts/orders-api)')
+        .option("--sdd-path <path>", "Path to the SDD repo root (defaults to cwd)")
+        .option("--catalogues-dir <dir>", "Catalogues directory relative to the SDD root (default: catalogues, or catalogues-aggregated at --tier aggregate)")
+        .option("--tier <tier>", "Tier, explicit never inferred (member | aggregate; default member)")
+        .action(async (opts) => {
+        if (opts.tier !== undefined &&
+            opts.tier !== "member" &&
+            opts.tier !== "aggregate") {
+            process.stderr.write(`--tier must be 'member' or 'aggregate' (got: ${opts.tier})\n`);
+            process.exit(2);
+        }
+        const result = await runCatalogueImpact({
+            of: opts.of,
+            ...(opts.sddPath !== undefined ? { sddPath: opts.sddPath } : {}),
+            ...(opts.cataloguesDir !== undefined
+                ? { cataloguesDir: opts.cataloguesDir }
+                : {}),
+            ...(opts.tier !== undefined
+                ? { tier: opts.tier }
+                : {}),
+        }, (s) => process.stdout.write(s));
+        if (result.exitCode !== 0)
+            process.exit(result.exitCode);
+    });
+}
+export function registerCatalogueBaselineCheck(catalogue) {
+    catalogue
+        .command("baseline-check")
+        .description("Compare emitted findings against the repo's findings baseline BY IDENTITY (M-ADR 0132 §9) — a reworded finding reports as reworded, not as one closed and one new")
+        .option("--sdd-path <path>", "Path to the SDD repo root (defaults to cwd)")
+        .option("--findings <path>", "File of findings to compare (defaults to stdin, so it composes with `catalogue validate --coverage`)")
+        .option("--baseline <path>", "Baseline file (defaults to <sdd-path>/orchestration/catalogue-findings-baseline.txt)")
+        .action(async (opts) => {
+        const result = await runBaselineCheck({
+            ...(opts.sddPath !== undefined ? { sddPath: opts.sddPath } : {}),
+            ...(opts.findings !== undefined ? { findings: opts.findings } : {}),
+            ...(opts.baseline !== undefined ? { baseline: opts.baseline } : {}),
+            stdin: async () => {
+                const chunks = [];
+                for await (const c of process.stdin)
+                    chunks.push(Buffer.from(c));
+                return Buffer.concat(chunks).toString("utf-8");
+            },
+        }, (s) => process.stdout.write(s));
+        if (result.exitCode !== 0)
+            process.exit(result.exitCode);
+    });
+}
+export function registerCatalogueVersion(catalogue) {
+    catalogue
+        .command("version")
+        .description("Print the catalogue schema version + sdd-cli version pin")
+        .action(async () => {
+        await runCatalogueVersion((s) => process.stdout.write(s));
+    });
+}
+//# sourceMappingURL=catalogue-verify.js.map

package/dist/verbs/context.js

@@ -0,0 +1,39 @@
+import { resolvePathOption } from "./path-option.js";
+import { AGENT_HARNESSES, resolveAgentHarness } from "../lib/agent-harness.js";
+import { runContextPull } from "../lib/context-pull/index.js";
+const collect = (value, previous = []) => [...previous, resolvePathOption(value)];
+export function registerContext(program) {
+    const context = program
+        .command("context")
+        .description("Briefing for a code repository an SDD specifies (M-ADR 0128 §1, M-ADR 0150 §4.4)");
+    context
+        .command("pull")
+        .description("Write agent-instructions.md, the harness wrapper's method-managed block and MCP_SETUP.md into this code repository, rendered from the templates its upstream SDD carries. The SDD is found by looking this repository up in the catalogues/repositories.csv of the SDDs beside it. Writes nothing else.")
+        .option("--target-repo <dir>", "the code repository to write into", resolvePathOption, process.cwd())
+        .option("--sdd <dir>", "the upstream SDD, skipping discovery", resolvePathOption)
+        .option("--repo <id>", "this repository's id in the SDD's catalogue (default: its git top-level directory name)")
+        .option("--search <dir>", "discover SDDs under this directory (repeatable; default: the code repository's parent)", collect)
+        .option("--agent-harness <name>", `target agent harness. Default: claude-code. Supported: ${AGENT_HARNESSES.join(", ")}`)
+        .option("--allow-overwrite", "replace a harness wrapper that has no method-managed markers")
+        .action(async (opts) => {
+        let agentHarness;
+        try {
+            agentHarness = resolveAgentHarness(opts.agentHarness);
+        }
+        catch (err) {
+            process.stderr.write(`[FAIL] ${err.message}\n`);
+            process.exit(1);
+        }
+        const { exitCode } = await runContextPull({
+            codeRepo: opts.targetRepo,
+            agentHarness,
+            allowOverwrite: opts.allowOverwrite === true,
+            sddPath: opts.sdd,
+            repoName: opts.repo,
+            searchRoots: opts.search,
+        });
+        if (exitCode !== 0)
+            process.exit(exitCode);
+    });
+}
+//# sourceMappingURL=context.js.map

package/dist/verbs/generate-briefing.js

@@ -0,0 +1,29 @@
+import { resolvePathOption } from "./path-option.js";
+import { AGENT_HARNESSES, resolveAgentHarness, } from "../lib/agent-harness.js";
+import { runGenerateBriefing } from "../lib/generate-briefing/index.js";
+export function registerGenerateBriefing(program) {
+    program
+        .command("generate-briefing")
+        .description("Regenerate agent-instructions.md + the harness wrapper for an existing SDD repository (no bundle sync)")
+        .option("--target-dir <dir>", "target SDD repo", resolvePathOption, process.cwd())
+        .option("--agent-harness <name>", `target agent harness. Default: claude-code. Supported: ${AGENT_HARNESSES.join(", ")}`)
+        .option("--allow-overwrite", "accept overwrites of locally-modified wrapper files")
+        .action(async (opts) => {
+        let agentHarness;
+        try {
+            agentHarness = resolveAgentHarness(opts.agentHarness);
+        }
+        catch (err) {
+            process.stderr.write(`[FAIL] ${err.message}\n`);
+            process.exit(1);
+        }
+        const { exitCode } = await runGenerateBriefing({
+            targetDir: opts.targetDir,
+            agentHarness,
+            allowOverwrite: opts.allowOverwrite === true,
+        });
+        if (exitCode !== 0)
+            process.exit(exitCode);
+    });
+}
+//# sourceMappingURL=generate-briefing.js.map

package/dist/verbs/list.js

@@ -0,0 +1,45 @@
+import { runList } from "../lib/list/index.js";
+const VALID_PROFILES = [
+    "platform",
+    "application",
+    "integration",
+];
+export function registerList(program) {
+    program
+        .command("list")
+        .description("Enumerate SDD repositories discoverable in the current workspace, including adopter pack provenance (ADR 0151)")
+        .option("--profile <profile>", "filter by profile: platform | application | integration")
+        .option("--workspace-root <path>", "workspace directory to walk (repeatable; defaults to cwd)", collectRoots, [])
+        .option("--format <format>", "output format: text | json", "text")
+        .option("--verbose", "show managed_path counts per bundle (text format)")
+        .action(async (opts) => {
+        const profileFilter = parseProfile(opts.profile);
+        const format = parseFormat(opts.format);
+        const { exitCode } = await runList({
+            workspaceRoots: opts.workspaceRoot ?? [],
+            format,
+            verbose: opts.verbose === true,
+            ...(profileFilter ? { profileFilter } : {}),
+        }, (s) => process.stdout.write(s));
+        if (exitCode !== 0)
+            process.exit(exitCode);
+    });
+}
+function collectRoots(value, prior) {
+    prior.push(value);
+    return prior;
+}
+function parseProfile(value) {
+    if (value === undefined)
+        return undefined;
+    if (!VALID_PROFILES.includes(value)) {
+        throw new Error(`Unknown --profile "${value}". Expected one of: ${VALID_PROFILES.join(", ")}`);
+    }
+    return value;
+}
+function parseFormat(value) {
+    if (value === "text" || value === "json")
+        return value;
+    throw new Error(`Unknown --format "${value}". Expected "text" or "json".`);
+}
+//# sourceMappingURL=list.js.map

package/dist/verbs/pack-build.js

@@ -0,0 +1,31 @@
+// `pack build` alone — MAINTAIN under M-ADR 0218 §4.4: it publishes a tarball to an output
+// path, outside the producer's tracked content. Its own module, so the maintain package can
+// carry it without the rest of the full CLI.
+import { resolvePathOption } from "./path-option.js";
+import { runPackBuild } from "../lib/pack/index.js";
+export function registerPackBuild(pack) {
+    pack
+        .command("build")
+        .description("Build a context-pack tarball from a seed file. Runs producer-side leakage check before emit.")
+        .requiredOption("--seed <path>", "path to the seed file (orchestration/distribution/{name}-seed.yaml)")
+        .option("--producer-repo <dir>", "adopter repo root (managed_paths are resolved relative to this; defaults to cwd)", process.cwd())
+        .option("--out-dir <dir>", "output directory for the tarball (defaults to <producer-repo>/dist/<pack-name>/)", resolvePathOption)
+        .option("--forward-base-managed-paths <path>", "path to forward-base MANAGED_PATHS.txt for the leakage check (defaults to extracting from method-baseline.lock)")
+        .option("--publish-transform", "apply the point-in-time / producer-agnostic publish transform (ADR 0183/0184): drop non-Accepted ADRs, strip lineage + stripped-class fields, flatten cross-repo refs, fail closed on leaks. For producer-published bundles.")
+        .option("--origin-prefix", "with the publish transform, apply the range-aware origin prefix (ADR 0140 §4.1): 0NNN→M-ADR, 9NNN→RA-ADR, adopter 1NNN stays ADR; ADR files renamed to match. Implies --publish-transform. The RA-ADR bundle cutover switch.")
+        .action(async (opts) => {
+        const { exitCode } = await runPackBuild({
+            seedPath: opts.seed,
+            producerRepo: opts.producerRepo ?? process.cwd(),
+            ...(opts.outDir && { outDir: opts.outDir }),
+            ...(opts.forwardBaseManagedPaths && {
+                forwardBaseManagedPathsFile: opts.forwardBaseManagedPaths,
+            }),
+            ...(opts.publishTransform && { publishTransform: true }),
+            ...(opts.originPrefix && { originPrefix: true }),
+        });
+        if (exitCode !== 0)
+            process.exit(exitCode);
+    });
+}
+//# sourceMappingURL=pack-build.js.map

package/dist/verbs/pack-validate.js

@@ -0,0 +1,17 @@
+// `pack validate` registration, split from `pack.ts` so a program can register
+// it without importing `runPackBuild` — the verify-only CLI must not ship the
+// code that writes a pack (M-ADR 0212 §4.3b). `registerPack` calls this, so
+// sdd-cli's `pack` surface and help order are unchanged.
+import { runPackValidate } from "../lib/pack/validate.js";
+export function registerPackValidate(pack) {
+    pack
+        .command("validate")
+        .description("Validate a context-pack seed file against the canonical schema. Fast feedback for authoring.")
+        .requiredOption("--seed <path>", "path to the seed file (orchestration/distribution/{name}-seed.yaml)")
+        .action(async (opts) => {
+        const { exitCode } = await runPackValidate({ seedPath: opts.seed });
+        if (exitCode !== 0)
+            process.exit(exitCode);
+    });
+}
+//# sourceMappingURL=pack-validate.js.map

package/dist/verbs/path-option.js

@@ -0,0 +1,25 @@
+import { resolve } from "node:path";
+/**
+ * Commander parse-arg coercion for an option naming a DIRECTORY ON DISK.
+ *
+ * Resolves the operand to an absolute path ONCE, at the option boundary, before
+ * any verb sees it. That placement is the fix, not a detail: B6 was a relative
+ * `--target-repo` that resolved far enough to succeed at the first read and
+ * then failed at every later one.
+ *
+ * `validate` read `.sdd-repo-kind` relative to the process cwd — which WORKS,
+ * so the run announced the correct profile and dispatched the full validator
+ * set — then handed the same unresolved string to bash validators running from
+ * a different working directory, which reported `App root not found` and exit
+ * 127. A healthy repo came back `passed=0 failed=5`, so the operator saw a
+ * broken REPO rather than a bad ARGUMENT. Repairing those messages would have
+ * been the wrong fix; the path is what is wrong, and it is wrong exactly once.
+ *
+ * Resolving at the boundary also means a verb cannot forget: there is no
+ * per-consumer `resolve()` to omit, and a new consumer of the option inherits
+ * an absolute path by construction.
+ */
+export function resolvePathOption(value) {
+    return resolve(value);
+}
+//# sourceMappingURL=path-option.js.map

package/dist/verbs/render.js

@@ -0,0 +1,87 @@
+import { readFile, writeFile } from "node:fs/promises";
+import { basename, dirname, join, resolve } from "node:path";
+import { existsSync } from "node:fs";
+import { parse as parseYaml } from "yaml";
+import { renderWireframe } from "../lib/catalogue/archetype/wireframe.js";
+import { loadScreenValidationConfig } from "../lib/catalogue/screen-validation-loader.js";
+export function registerRender(program) {
+    const render = program
+        .command("render")
+        .description("Render method artefacts to visual form");
+    render
+        .command("screen <file>")
+        .description("Render a screen-spec's openui-lang block to a structural wireframe SVG (ADR 0169). " +
+        "Platform comes from the `platform:` frontmatter; an adopter overlay is read from " +
+        ".sdd/screen-validation.yaml when present.")
+        .option("--out <file>", "write the SVG to a file (default: stdout)")
+        .action(async (file, opts) => {
+        let text;
+        try {
+            text = await readFile(file, "utf-8");
+        }
+        catch (err) {
+            process.stderr.write(`[FAIL] cannot read ${file}: ${err.message}\n`);
+            process.exit(1);
+            return;
+        }
+        const block = extractBlock(text);
+        if (block === null) {
+            process.stderr.write(`[FAIL] ${file} has no \`\`\`openui-lang block\n`);
+            process.exit(1);
+            return;
+        }
+        const fm = parseFrontmatter(text);
+        const platform = typeof fm.platform === "string" ? fm.platform : undefined;
+        const title = typeof fm.screen === "string" ? fm.screen : basename(file).replace(/\.md$/i, "");
+        // An overlay lives in the SDD's .sdd/; when the file sits under screens/,
+        // the SDD root is its grandparent. Best-effort — absent → no overlay.
+        const overlay = platform !== undefined ? await loadOverlay(file, platform) : undefined;
+        const svg = renderWireframe({ block, platform, overlay, title });
+        if (opts.out !== undefined) {
+            await writeFile(opts.out, svg, "utf-8");
+            process.stdout.write(`[OK] wrote ${opts.out}\n`);
+        }
+        else {
+            process.stdout.write(svg + "\n");
+        }
+    });
+}
+function extractBlock(text) {
+    const m = /```openui-lang\r?\n([\s\S]*?)```/.exec(text);
+    return m ? (m[1] ?? "") : null;
+}
+function parseFrontmatter(text) {
+    const m = /^---\r?\n([\s\S]*?)\r?\n---/.exec(text);
+    if (!m)
+        return {};
+    try {
+        const parsed = parseYaml(m[1] ?? "");
+        return parsed && typeof parsed === "object" ? parsed : {};
+    }
+    catch {
+        return {};
+    }
+}
+export async function loadOverlay(file, platform) {
+    // The overlay lives in the SDD's .sdd/. Screens may sit directly under
+    // screens/ or in a subfolder (screens/<group>/<file>.md per the grouping
+    // convention), so walk up from the file to the nearest ancestor that
+    // contains a .sdd/ directory. Best-effort — absent → no overlay.
+    let dir = dirname(resolve(file));
+    for (let depth = 0; depth < 16; depth++) {
+        if (existsSync(join(dir, ".sdd")))
+            break;
+        const parent = dirname(dir);
+        if (parent === dir)
+            break;
+        dir = parent;
+    }
+    try {
+        const cfg = await loadScreenValidationConfig(dir);
+        return cfg?.archetypeOverlays.get(platform);
+    }
+    catch {
+        return undefined;
+    }
+}
+//# sourceMappingURL=render.js.map