dw-sdlc 0.0.0-stage → 0.2.0

package/dist/commands/doctor.js

@@ -0,0 +1,341 @@
+// `dw-sdlc doctor`: one PASS / WARN / FAIL line per machine check the guardrails rely on, for the
+// repository holding --root and the user's home; it installs nothing. FAIL is a guard that does not guard
+// (no jq, plugin absent or disabled, an invalid config), WARN a layer missing or loose, INFO one that does not apply.
+import { spawnSync } from "node:child_process";
+import { existsSync, readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { parseArgs } from "node:util";
+import { findRepository, resolveConfig } from "../agentic-config.js";
+/** Claude Code's config dir: `$CLAUDE_CONFIG_DIR` when set, the way Claude Code reads it, else `~/.claude`. */
+export function claudeConfigDir(env, home) {
+    return env.CLAUDE_CONFIG_DIR ?? join(home, ".claude");
+}
+/** The marketplace Claude Code registers this repository under, and the plugin id inside it. */
+export const MARKETPLACE = "dw-sdlc";
+export const PLUGIN_ID = `guardrails@${MARKETPLACE}`;
+/** rtk find passes -exec through verbatim from this release; before it, `rtk find … -exec` exits 1. */
+export const RTK_FIND_EXEC_FIXED = "0.46.0";
+export const PNPM_MINIMUM_RELEASE_AGE = 10080;
+export const realProbe = {
+    run(command, args, cwd) {
+        const result = spawnSync(command, args, { cwd, encoding: "utf8" });
+        return { status: result.status ?? 127, stdout: result.stdout ?? "" };
+    },
+    read(path) {
+        return existsSync(path) ? readFileSync(path, "utf8") : undefined;
+    },
+    shell(script) {
+        const shell = process.env.SHELL ?? "/bin/sh";
+        const result = spawnSync(shell, ["-l", "-c", script], { encoding: "utf8" });
+        return (result.stdout ?? "").trim().split("\n")[0] ?? "";
+    }
+};
+function isObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function parseJson(text) {
+    if (text === undefined) {
+        return undefined;
+    }
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return undefined;
+    }
+}
+function checkJq(probe) {
+    const { status, stdout } = probe.run("jq", ["--version"]);
+    if (status === 0) {
+        return { name: "jq", level: "PASS", detail: stdout.trim() };
+    }
+    return { name: "jq", level: "FAIL", detail: "missing: every guard is silent without it. brew install jq" };
+}
+/** Where the plugin's hooks run: live from the checkout for a marketplace added from a directory, a
+ *  cached snapshot for one added from git. A marker placed in only one of the two settled it. */
+/** The checkout a directory marketplace runs the plugin from, or undefined for a snapshot. */
+function liveCheckout(probe, claude) {
+    const known = parseJson(probe.read(join(claude, "plugins", "known_marketplaces.json")));
+    const entry = isObject(known) && isObject(known[MARKETPLACE]) ? known[MARKETPLACE] : undefined;
+    const source = entry !== undefined && isObject(entry.source) ? entry.source : undefined;
+    return source?.source === "directory" && typeof source.path === "string" ? source.path : undefined;
+}
+function pluginOrigin(probe, claude, installPath) {
+    const checkout = liveCheckout(probe, claude);
+    if (checkout !== undefined) {
+        return `runs live from ${checkout}/plugins/guardrails; a change there is in the next session`;
+    }
+    return `installed at ${installPath}; a change reaches it through claude plugin update`;
+}
+/** The directory whose hooks run on this machine: the checkout of a directory marketplace, else the installed snapshot. */
+function runningPluginRoot(probe, claude) {
+    const checkout = liveCheckout(probe, claude);
+    if (checkout !== undefined) {
+        return join(checkout, "plugins", "guardrails");
+    }
+    const { status, stdout } = probe.run("claude", ["plugin", "list", "--json"]);
+    const list = status === 0 ? parseJson(stdout) : undefined;
+    if (!Array.isArray(list)) {
+        return undefined;
+    }
+    const entry = list.find((item) => isObject(item) && item.id === PLUGIN_ID);
+    return entry !== undefined && typeof entry.installPath === "string" ? entry.installPath : undefined;
+}
+function checkPlugin(probe, claude) {
+    const { status, stdout } = probe.run("claude", ["plugin", "list", "--json"]);
+    const list = status === 0 ? parseJson(stdout) : undefined;
+    if (!Array.isArray(list)) {
+        return { name: "plugin", level: "FAIL", detail: "claude plugin list did not answer; is Claude Code installed?" };
+    }
+    const entry = list.find((item) => isObject(item) && item.id === PLUGIN_ID);
+    if (entry === undefined) {
+        return {
+            name: "plugin",
+            level: "FAIL",
+            detail: `${PLUGIN_ID} is not installed. claude plugin marketplace add dominikwozniak/dw-sdlc --sparse .claude-plugin plugins packages && claude plugin install ${PLUGIN_ID} --scope user`
+        };
+    }
+    const version = typeof entry.version === "string" ? entry.version : "?";
+    if (entry.enabled !== true) {
+        return {
+            name: "plugin",
+            level: "FAIL",
+            detail: `${version} installed but disabled, so no guard runs. claude plugin enable ${PLUGIN_ID}`
+        };
+    }
+    return {
+        name: "plugin",
+        level: "PASS",
+        detail: `${version} enabled; ${pluginOrigin(probe, claude, String(entry.installPath ?? ""))}`
+    };
+}
+/** Every hook command string in a settings file, whatever the event and matcher. */
+function hookCommands(settings) {
+    if (!isObject(settings) || !isObject(settings.hooks)) {
+        return [];
+    }
+    const commands = [];
+    for (const groups of Object.values(settings.hooks)) {
+        if (!Array.isArray(groups)) {
+            continue;
+        }
+        for (const group of groups) {
+            if (!isObject(group) || !Array.isArray(group.hooks)) {
+                continue;
+            }
+            for (const hook of group.hooks) {
+                if (isObject(hook) && typeof hook.command === "string") {
+                    commands.push(hook.command);
+                }
+            }
+        }
+    }
+    return commands;
+}
+/** rtk's config.toml: Application Support on macOS, XDG or ~/.config elsewhere. */
+export function rtkConfigPath(home, platform = process.platform, env = process.env) {
+    if (platform === "darwin") {
+        return join(home, "Library", "Application Support", "rtk", "config.toml");
+    }
+    return join(env.XDG_CONFIG_HOME ?? join(home, ".config"), "rtk", "config.toml");
+}
+/** The `exclude_commands` list of an rtk config.toml, read with a regex: the file is small and ours. */
+export function rtkExcludes(toml) {
+    const match = /^\s*exclude_commands\s*=\s*\[([^\]]*)\]/m.exec(toml ?? "");
+    if (match === null) {
+        return [];
+    }
+    return [...(match[1] ?? "").matchAll(/"([^"]*)"/g)].map((entry) => entry[1] ?? "");
+}
+function versionBefore(version, threshold) {
+    const a = version.split(".").map((part) => Number.parseInt(part, 10));
+    const b = threshold.split(".").map((part) => Number.parseInt(part, 10));
+    for (let i = 0; i < Math.max(a.length, b.length); i += 1) {
+        const x = a[i] ?? 0;
+        const y = b[i] ?? 0;
+        if (x !== y) {
+            return x < y;
+        }
+    }
+    return false;
+}
+// The plugin's rtk-rewrite.sh is the one wiring of `rtk hook claude`; a second one in the user
+// settings rewrites again, and in a linked worktree that copy is what the isolation check refuses.
+function checkRtk(probe, home, claude) {
+    const rtk = probe.shell("command -v rtk");
+    if (rtk === "") {
+        return { name: "rtk", level: "PASS", detail: "no rtk on this machine, the plugin's rewrite hook stays silent" };
+    }
+    const settingsPath = join(claude, "settings.json");
+    const settings = parseJson(probe.read(settingsPath));
+    const byHand = hookCommands(settings).find((command) => /\brtk\b/.test(command));
+    const root = runningPluginRoot(probe, claude);
+    if (root === undefined || probe.read(join(root, "hooks", "rtk-rewrite.sh")) === undefined) {
+        const meanwhile = byHand === undefined ? "nothing rewrites" : `the hand-wired ${byHand} carries it until then`;
+        return {
+            name: "rtk",
+            level: "WARN",
+            detail: `rtk at ${rtk} but the plugin running here has no hooks/rtk-rewrite.sh: claude plugin update; ${meanwhile}`
+        };
+    }
+    if (byHand !== undefined) {
+        return {
+            name: "rtk",
+            level: "FAIL",
+            detail: `${settingsPath} wires rtk by hand (${byHand}), and the plugin's rtk-rewrite.sh already runs it: remove that hook, or every git command in a linked worktree is refused by the isolation check`
+        };
+    }
+    // The filters that misbehave on the installed release have to sit in exclude_commands.
+    const version = probe.run("rtk", ["--version"]).stdout.trim().split(/\s+/)[1] ?? "0";
+    const excludes = rtkExcludes(probe.read(rtkConfigPath(home)));
+    const missing = [];
+    if (versionBefore(version, RTK_FIND_EXEC_FIXED) && !excludes.includes("find")) {
+        missing.push(`find (rtk ${version} refuses find -exec; fixed in ${RTK_FIND_EXEC_FIXED})`);
+    }
+    if (missing.length > 0) {
+        return {
+            name: "rtk",
+            level: "WARN",
+            detail: `rtk ${version} behind the plugin's rewrite hook, but [hooks] exclude_commands lacks ${missing.join("; ")}`
+        };
+    }
+    return {
+        name: "rtk",
+        level: "PASS",
+        detail: `rtk ${version} behind the plugin's rewrite hook; exclude_commands: ${excludes.join(", ") || "none"}`
+    };
+}
+function checkSafeChain(probe) {
+    const binary = probe.shell("command -v safe-chain");
+    if (binary === "") {
+        return {
+            name: "safe chain",
+            level: "WARN",
+            detail: "absent: the agent shell reaches the registry without Aikido's blocklist. github.com/AikidoSec/safe-chain"
+        };
+    }
+    const npm = probe.shell("command -v npm");
+    // The --ci shims put a wrapper on PATH; the laptop install defines a shell function, which
+    // `command -v` reports as the bare name.
+    const through = npm === "npm" || npm.includes(".safe-chain");
+    if (!through) {
+        return {
+            name: "safe chain",
+            level: "WARN",
+            detail: `installed (${binary}) but npm resolves to ${npm}, not through it; the shell function or the --ci shims are not on this shell's PATH`
+        };
+    }
+    return { name: "safe chain", level: "PASS", detail: `${binary}, npm goes through it` };
+}
+/**
+ * pnpm's global `minimumReleaseAge`, asked from the home directory: from a checkout, its own
+ * pnpm-workspace.yaml would answer for the machine.
+ */
+function checkPnpmReleaseAge(probe, home) {
+    if (probe.shell("command -v pnpm") === "") {
+        return { name: "pnpm release age", level: "INFO", detail: "no pnpm in the shell" };
+    }
+    const { stdout } = probe.run("pnpm", ["config", "get", "minimumReleaseAge"], home);
+    const minutes = Number.parseInt(stdout.trim(), 10);
+    if (Number.isNaN(minutes) || minutes < PNPM_MINIMUM_RELEASE_AGE) {
+        const state = Number.isNaN(minutes) ? "unset" : `${minutes} minutes`;
+        return {
+            name: "pnpm release age",
+            level: "WARN",
+            detail: `${state} globally: below the ${PNPM_MINIMUM_RELEASE_AGE}-minute baseline. pnpm config set --global minimumReleaseAge ${PNPM_MINIMUM_RELEASE_AGE}`
+        };
+    }
+    return { name: "pnpm release age", level: "PASS", detail: `${minutes} minutes globally` };
+}
+function checkCommitSigning(probe) {
+    const { status, stdout } = probe.run("git", ["config", "--global", "commit.gpgsign"]);
+    if (status === 0 && stdout.trim() === "true") {
+        return { name: "commit signing", level: "PASS", detail: "commit.gpgsign true" };
+    }
+    return {
+        name: "commit signing",
+        level: "WARN",
+        detail: "commit.gpgsign is off, so commits go out unsigned. git config --global commit.gpgsign true"
+    };
+}
+function checkConfig(config, root) {
+    if (config === undefined) {
+        return { name: "config", level: "INFO", detail: `no repository found at ${root}; run from one or pass --root` };
+    }
+    if (config.problems.length > 0) {
+        return {
+            name: "config",
+            level: "FAIL",
+            detail: `the guards run on the strictest defaults: ${config.problems.join("; ")}`
+        };
+    }
+    // A worktree that lacks a layer reads the main checkout's; say so, since the file is not here.
+    const borrowed = Object.entries(config.sources ?? {})
+        .filter((entry) => entry[1] !== undefined && entry[1] !== root)
+        .map(([layer, source]) => `; ${layer} layer from ${source}`);
+    return {
+        name: "config",
+        level: "PASS",
+        detail: `commit ${config.config.commit.convention}${borrowed.join("")}`
+    };
+}
+export function diagnose(inputs) {
+    const { probe, home } = inputs;
+    const claude = inputs.claudeDir ?? join(home, ".claude");
+    return [
+        checkJq(probe),
+        checkPlugin(probe, claude),
+        checkRtk(probe, home, claude),
+        checkSafeChain(probe),
+        checkPnpmReleaseAge(probe, home),
+        checkCommitSigning(probe),
+        checkConfig(inputs.config, inputs.root)
+    ];
+}
+export function render(checks) {
+    return checks.map((check) => `${check.level.padEnd(5)} ${check.name.padEnd(17)} ${check.detail}`).join("\n");
+}
+export const summary = "one PASS / WARN / FAIL line per machine check the guardrails rely on";
+const USAGE = `Usage: dw-sdlc doctor [--root <dir>] [--home <dir>]
+  or:  pnpm guardrails:doctor [--root <dir>] [--home <dir>], in a checkout of dw-sdlc
+
+One PASS / WARN / FAIL line per machine check the guardrails rely on; read-only. Exit 1 when any
+check fails. Claude Code's settings are read from $CLAUDE_CONFIG_DIR, or ~/.claude without it; a
+--home reads <home>/.claude.`;
+function repositoryConfig(root) {
+    const resolution = resolveConfig(root);
+    return {
+        config: resolution.config,
+        problems: resolution.problems.map(({ file, path, message }) => path === "" ? `${file}: ${message}` : `${file}: ${path}: ${message}`),
+        sources: resolution.sources
+    };
+}
+export function run(argv) {
+    let values;
+    try {
+        values = parseArgs({
+            args: argv,
+            options: { help: { type: "boolean", short: "h" }, root: { type: "string" }, home: { type: "string" } }
+        }).values;
+    }
+    catch (error) {
+        console.error(`guardrails:doctor: ${error instanceof Error ? error.message : String(error)}\n\n${USAGE}`);
+        return 2;
+    }
+    if (values.help === true) {
+        console.log(USAGE);
+        return 0;
+    }
+    const dir = values.root ?? process.cwd();
+    const root = findRepository(dir);
+    const checks = diagnose({
+        root: root ?? dir,
+        home: values.home ?? homedir(),
+        claudeDir: values.home === undefined ? claudeConfigDir(process.env, homedir()) : join(values.home, ".claude"),
+        probe: realProbe,
+        config: root === undefined ? undefined : repositoryConfig(root)
+    });
+    console.log(render(checks));
+    return checks.some((check) => check.level === "FAIL") ? 1 : 0;
+}

package/dist/commands/gate.d.ts

@@ -0,0 +1,2 @@
+export declare const summary = "run the Gate: the Steps of gate.steps in order, then every Check under gate.checks";
+export declare function run(argv: string[]): number;

package/dist/commands/gate.js

@@ -0,0 +1,231 @@
+// `dw-sdlc gate`: the Gate of a repository, from the `gate` key of its resolved agentic config.
+import { spawnSync } from "node:child_process";
+import { parseArgs } from "node:util";
+import { repositoryRoot, resolveConfig } from "../agentic-config.js";
+import { CannotRun } from "../checks/check.js";
+import { enabledChecks } from "../checks/index.js";
+import { annotation, failureJson, failureLine } from "../report.js";
+export const summary = "run the Gate: the Steps of gate.steps in order, then every Check under gate.checks";
+const USAGE = `Usage: dw-sdlc gate [--json] [--root <dir>] [--update-baseline]
+
+Runs the Gate of the repository holding --root (default: the current directory): each Step of
+gate.steps in order from the repository root, its output passed through, stopping at the first that
+fails; then every Check under gate.checks, the run scripts and then the Checks the package ships,
+none stopping the next. Prints one line per failure: the file where there is one, the rule, the
+remedy; under GitHub Actions each line is also a workflow annotation. --json prints one document
+instead and sends the commands' own output to stderr.
+
+--update-baseline then rewrites the baseline of each Ratchet, only when every Step and every other
+Check passed, and only tighter: a file now within its limit leaves it and no file joins. Where there
+is no baseline, it records one. The Ratchet is judged again on what it wrote.
+
+Exit 0 when everything passes, 1 when a Step or a Check fails, 2 when the Gate cannot run: an
+invalid config layer, a Step or Check whose command the shell cannot find or execute, or a Check
+missing an input it reads.`;
+const EXIT_CODES = { pass: 0, fail: 1, error: 2 };
+/** What the shell answers for a command it cannot find, and for one it cannot execute. */
+const NOT_RUNNABLE = { 127: "was not found", 126: "could not be executed" };
+const SKIPPED = { status: "skipped", exitCode: null };
+const REMEDIES = {
+    invalidLayer: "fix the file; the Gate runs once every layer is valid",
+    failed: "fix what it printed above",
+    stepNotRunnable: "install the command or fix gate.steps in the agentic config",
+    checkNotRunnable: "install the command or fix gate.checks.run in the agentic config",
+    checkStopped: "fix what stopped it, or report it to dw-sdlc"
+};
+function plural(count, noun) {
+    return `${count} ${noun}${count === 1 ? "" : "s"}`;
+}
+function parseCli(argv) {
+    try {
+        const { values } = parseArgs({
+            args: argv,
+            options: {
+                help: { type: "boolean", short: "h" },
+                json: { type: "boolean" },
+                root: { type: "string" },
+                "update-baseline": { type: "boolean" }
+            }
+        });
+        return {
+            help: values.help === true,
+            json: values.json === true,
+            root: values.root,
+            updateBaseline: values["update-baseline"] === true
+        };
+    }
+    catch (error) {
+        return { error: error instanceof Error ? error.message : String(error) };
+    }
+}
+function configFailure({ file, path, message }) {
+    const where = path === "" ? message : `${path}: ${message}`;
+    return { file, rule: "config", message: where, remedy: REMEDIES.invalidLayer };
+}
+/**
+ * Runs `command` through `sh -c` from `root`, stdin closed and stderr passed through; stdout too, or
+ * onto stderr when `--json` keeps stdout for the document. `detail` says what went wrong, when it did.
+ */
+function runCommand(command, root, json) {
+    const result = spawnSync(command, { shell: true, cwd: root, stdio: ["ignore", json ? 2 : "inherit", "inherit"] });
+    if (result.error !== undefined) {
+        return { status: "error", exitCode: null, detail: `could not start: ${result.error.message}` };
+    }
+    if (result.status === 0) {
+        return { status: "pass", exitCode: 0 };
+    }
+    if (result.status === null) {
+        return { status: "fail", exitCode: null, detail: `was stopped by ${result.signal ?? "a signal"}` };
+    }
+    const notRunnable = NOT_RUNNABLE[result.status];
+    if (notRunnable !== undefined) {
+        return { status: "error", exitCode: result.status, detail: `${notRunnable} (exit ${result.status})` };
+    }
+    return { status: "fail", exitCode: result.status, detail: `exited ${result.status}` };
+}
+/** What a Check that threw reports: the input it lacks, or what stopped it. */
+function erred(check, error) {
+    const finding = error instanceof CannotRun
+        ? error.finding
+        : { message: `stopped: ${error instanceof Error ? error.message : String(error)}`, remedy: REMEDIES.checkStopped };
+    return {
+        check,
+        outcome: { status: "error", exitCode: EXIT_CODES.error },
+        failures: [{ rule: check.name, ...finding }]
+    };
+}
+/** Runs one Check the package ships, its failures named by the Check; one it cannot judge is an error. */
+function runShipped(check, root) {
+    try {
+        const failures = check.run(root).map((finding) => ({ rule: check.name, ...finding }));
+        const status = failures.length === 0 ? "pass" : "fail";
+        return { check, outcome: { status, exitCode: EXIT_CODES[status] }, failures };
+    }
+    catch (error) {
+        return erred(check, error);
+    }
+}
+/**
+ * Rewrites the baseline of each Ratchet while every Step, every run Check in `others` and every other
+ * shipped Check passed, and judges the Ratchet again on what it wrote.
+ */
+function refreshBaselines(judged, others, root, log) {
+    if (!judged.some(({ check }) => check.baseline !== undefined)) {
+        log.write("gate: no Ratchet is turned on, so no baseline to refresh\n");
+        return;
+    }
+    for (const [index, { check }] of judged.entries()) {
+        if (check.baseline === undefined) {
+            continue;
+        }
+        const { file, refresh } = check.baseline;
+        const rest = [...others, ...judged.filter((_, at) => at !== index).map(({ outcome }) => outcome)];
+        if (rest.some(({ status }) => status !== "pass")) {
+            log.write(`gate: baseline ${file} not refreshed — a Step or another Check did not pass\n`);
+            continue;
+        }
+        try {
+            log.write(`gate: baseline ${file} ${refresh(root)}\n`);
+            judged[index] = runShipped(check, root);
+        }
+        catch (error) {
+            if (error instanceof CannotRun) {
+                log.write(`gate: baseline ${file} not refreshed — ${error.finding.message}; ${error.finding.remedy}\n`);
+            }
+            else {
+                judged[index] = erred(check, error);
+            }
+        }
+    }
+}
+function worst(outcomes) {
+    const statuses = new Set(outcomes.map(({ status }) => status));
+    return statuses.has("error") ? "error" : statuses.has("fail") ? "fail" : "pass";
+}
+function runGate(root, json, updateBaseline) {
+    const log = json ? process.stderr : process.stdout;
+    const { config, problems } = resolveConfig(root);
+    const gateCommand = config.gate.command ?? null;
+    if (problems.length > 0) {
+        return { status: "error", command: gateCommand, steps: [], checks: [], failures: problems.map(configFailure) };
+    }
+    const failures = [];
+    /** Runs one Step or Check and records its failure under `rule`, if it has one. */
+    const runOne = (command, rule, notRunnable) => {
+        const { detail, ...outcome } = runCommand(command, root, json);
+        if (detail !== undefined) {
+            const remedy = outcome.status === "error" ? notRunnable : REMEDIES.failed;
+            failures.push({ rule, message: `${JSON.stringify(command)} ${detail}`, remedy });
+        }
+        return outcome;
+    };
+    const steps = [];
+    let stopped = false;
+    for (const step of config.gate.steps) {
+        if (stopped) {
+            steps.push({ command: step, ...SKIPPED });
+            continue;
+        }
+        log.write(`gate: step ${step}\n`);
+        const outcome = runOne(step, "step", REMEDIES.stepNotRunnable);
+        steps.push({ command: step, ...outcome });
+        stopped = outcome.status !== "pass";
+    }
+    const checks = [];
+    for (const check of config.gate.checks.run) {
+        if (stopped) {
+            checks.push({ ...check, ...SKIPPED });
+            continue;
+        }
+        log.write(`gate: check ${check.name}\n`);
+        checks.push({ ...check, ...runOne(check.command, check.name, REMEDIES.checkNotRunnable) });
+    }
+    const judged = enabledChecks(config.gate.checks).map((check) => {
+        if (stopped) {
+            return { check, outcome: SKIPPED, failures: [] };
+        }
+        log.write(`gate: check ${check.name}\n`);
+        return runShipped(check, root);
+    });
+    if (updateBaseline) {
+        refreshBaselines(judged, [...steps, ...checks], root, log);
+    }
+    for (const { check, outcome, failures: found } of judged) {
+        failures.push(...found);
+        checks.push({ name: check.name, command: null, ...outcome });
+    }
+    return { status: worst([...steps, ...checks]), command: gateCommand, steps, checks, failures };
+}
+function verdict(report) {
+    if (report.status === "pass") {
+        return `gate: green — ${plural(report.steps.length, "step")}, ${plural(report.checks.length, "check")}`;
+    }
+    const failures = plural(report.failures.length, "failure");
+    return report.status === "fail" ? `gate: failed — ${failures}` : `gate: cannot run — ${failures}`;
+}
+export function run(argv) {
+    const cli = parseCli(argv);
+    if ("error" in cli) {
+        process.stderr.write(`dw-sdlc gate: ${cli.error}\n\n${USAGE}\n`);
+        return 2;
+    }
+    if (cli.help) {
+        process.stdout.write(`${USAGE}\n`);
+        return 0;
+    }
+    const report = runGate(repositoryRoot(cli.root ?? process.cwd()), cli.json, cli.updateBaseline);
+    const actions = process.env.GITHUB_ACTIONS === "true";
+    if (cli.json) {
+        const document = { ...report, failures: report.failures.map(failureJson) };
+        process.stdout.write(`${JSON.stringify(document, null, 2)}\n`);
+        // The runner reads workflow commands from stderr as from stdout, so stdout stays one document.
+        for (const failure of actions ? report.failures : []) {
+            process.stderr.write(`${annotation(failure)}\n`);
+        }
+    }
+    else {
+        const lines = report.failures.flatMap((failure) => actions ? [failureLine(failure), annotation(failure)] : [failureLine(failure)]);
+        process.stdout.write(`${[...lines, verdict(report)].join("\n")}\n`);
+    }
+    return EXIT_CODES[report.status];
+}

package/dist/commands/primitives.d.ts

@@ -0,0 +1,2 @@
+export declare const summary = "name the Primitives that own each path, with their summaries and documents";
+export declare function run(argv: string[]): number;

package/dist/commands/primitives.js

@@ -0,0 +1,106 @@
+// `dw-sdlc primitives --paths <files>`: for each path, the Primitives of the catalogue that name it,
+// with their summaries and the documents to read, or that none does.
+import { existsSync, realpathSync } from "node:fs";
+import { basename, dirname, join, relative, resolve } from "node:path";
+import { parseArgs } from "node:util";
+import { repositoryRoot, resolveConfig } from "../agentic-config.js";
+import { primitivesNaming, readCatalogue } from "../catalogue.js";
+import { catalogueFile } from "../checks/primitives.js";
+export const summary = "name the Primitives that own each path, with their summaries and documents";
+const USAGE = `Usage: dw-sdlc primitives --paths <file>... [--json] [--root <dir>]
+
+Prints, for each path, the Primitives of the catalogue whose code names it, the file itself or the
+nearest directory above it: the id, the name, the summary and the documents to read; or that no
+Primitive names it. A path is read from the current directory. The catalogue is the one the
+primitives Check reads, in the repository holding --root (default: the current directory). --json
+prints one document instead.
+
+Exit 0 with an answer for every path, 2 when there is no catalogue to read or it is not one.`;
+const REMEDIES = {
+    missing: "create it, or point gate.checks.primitives.file at the catalogue",
+    invalid: "fix the catalogue; dw-sdlc gate names each problem under the primitives Check"
+};
+function parseCli(argv) {
+    try {
+        const { values, positionals } = parseArgs({
+            args: argv,
+            allowPositionals: true,
+            options: {
+                help: { type: "boolean", short: "h" },
+                json: { type: "boolean" },
+                paths: { type: "boolean" },
+                root: { type: "string" }
+            }
+        });
+        const cli = {
+            help: values.help === true,
+            json: values.json === true,
+            paths: values.paths === true,
+            files: positionals,
+            root: values.root
+        };
+        return cli.help || cli.paths ? cli : { error: "name the paths with --paths" };
+    }
+    catch (error) {
+        return { error: error instanceof Error ? error.message : String(error) };
+    }
+}
+/**
+ * `path` with every symbolic link in it resolved, as git reports the root: the nearest part on disk
+ * resolved and the rest kept, so a deleted file still maps into the repository.
+ */
+function realPath(path) {
+    if (existsSync(path)) {
+        return realpathSync(path);
+    }
+    const parent = dirname(path);
+    return parent === path ? path : join(realPath(parent), basename(path));
+}
+function brief({ id, name, summary: what, docs }) {
+    return { id, name, summary: what, docs };
+}
+function plain(path, primitives) {
+    if (primitives.length === 0) {
+        return [`${path}: no Primitive names this path`];
+    }
+    return primitives.flatMap(({ id, name, summary: what, docs }) => [
+        `${path}: ${id} (${name}) — ${what}`,
+        `  read: ${docs.join(", ")}`
+    ]);
+}
+export function run(argv) {
+    const cli = parseCli(argv);
+    if ("error" in cli) {
+        process.stderr.write(`dw-sdlc primitives: ${cli.error}\n\n${USAGE}\n`);
+        return 2;
+    }
+    if (cli.help) {
+        process.stdout.write(`${USAGE}\n`);
+        return 0;
+    }
+    const root = repositoryRoot(cli.root ?? process.cwd());
+    const file = catalogueFile(resolveConfig(root).config.gate.checks);
+    const read = readCatalogue(root, file);
+    if (read.state !== "valid") {
+        const problems = read.state === "missing"
+            ? [`the catalogue does not exist — ${REMEDIES.missing}`]
+            : read.problems.map((problem) => `${problem} — ${REMEDIES.invalid}`);
+        process.stderr.write(problems.map((problem) => `dw-sdlc primitives: ${file}: ${problem}\n`).join(""));
+        return 2;
+    }
+    const answers = cli.files.map((path) => {
+        const fromRoot = relative(root, realPath(resolve(path)));
+        return { path, primitives: primitivesNaming(read.catalogue, fromRoot) };
+    });
+    if (cli.json) {
+        const paths = answers.map(({ path, primitives }) => ({ path, primitives: primitives.map(brief) }));
+        process.stdout.write(`${JSON.stringify({ paths }, null, 2)}\n`);
+    }
+    else {
+        process.stdout.write(answers
+            .flatMap(({ path, primitives }) => plain(path, primitives))
+            .map((line) => `${line}\n`)
+            .join(""));
+    }
+    return 0;
+}