dw-sdlc 0.0.0-stage → 0.1.0

package/dist/checks/primitives.js

@@ -0,0 +1,128 @@
+// `primitives`: the catalogue says what is true of the tree. Unique ids, a known group, a one-line
+// summary, every code and docs path on disk with its anchor resolving, and every file under the roots
+// named by a Primitive.
+import { spawnSync } from "node:child_process";
+import { existsSync, readFileSync, statSync } from "node:fs";
+import { join } from "node:path";
+import { CATALOGUE_FILE, primitivesNaming, readCatalogue } from "../catalogue.js";
+import { headings } from "../markdown.js";
+import { CannotRun, optionsOf } from "./check.js";
+const MAX_SUMMARY = 120;
+/** A file a test runs, never shipped: under a test directory, or named as a test. */
+const TEST_FILE = /(^|\/)(test|tests|__tests__)\/|\.(test|spec)\.[^/]+$/;
+const REMEDIES = {
+    missing: "create it, or point gate.checks.primitives.file at the catalogue",
+    shape: "give it the catalogue's shape: version 1, groups of id and name, primitives of id, name, group, summary, code and docs",
+    duplicate: "give each Primitive an id of its own",
+    group: "add the group to groups, or move the Primitive into one listed there",
+    summary: `keep the summary to one line of ${MAX_SUMMARY} characters or fewer`,
+    path: "fix the path or drop it",
+    anchor: "point the entry at a heading the file has",
+    notGit: "run the Gate inside a git repository"
+};
+function show(value) {
+    return JSON.stringify(value);
+}
+/** The line of the `nth` (0-based) `"id": "<id>"` under the `primitives` key, where a Primitive is declared. */
+function lineOf(text, id, nth) {
+    const start = Math.max(0, text.indexOf('"primitives"'));
+    const pattern = new RegExp(`"id"\\s*:\\s*${JSON.stringify(id).replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}`, "g");
+    const match = Array.from(text.slice(start).matchAll(pattern))[nth];
+    return match?.index === undefined ? undefined : text.slice(0, start + match.index).split("\n").length;
+}
+/** The anchors of the headings of `path`; none when it is not a file. */
+function anchorsOf(root, path, cache) {
+    let anchors = cache.get(path);
+    if (anchors === undefined) {
+        const full = join(root, path);
+        anchors = new Set(statSync(full).isFile() ? headings(readFileSync(full, "utf8")).map(({ anchor }) => anchor) : []);
+        cache.set(path, anchors);
+    }
+    return anchors;
+}
+/** What is wrong with one Primitive, declared at `at`: its group, its summary, each code and docs entry. */
+function judge(root, catalogue, primitive, at, cache) {
+    const { id, group, summary, code, docs } = primitive;
+    const findings = [];
+    const fail = (message, remedy) => findings.push({ ...at, message, remedy });
+    if (!catalogue.groups.some((known) => known.id === group)) {
+        fail(`${show(id)} is in group ${show(group)}, which groups does not list`, REMEDIES.group);
+    }
+    const summaryLines = summary.split("\n").length;
+    if (summaryLines > 1) {
+        fail(`the summary of ${show(id)} runs over ${summaryLines} lines`, REMEDIES.summary);
+    }
+    else if ([...summary].length > MAX_SUMMARY) {
+        fail(`the summary of ${show(id)} is ${[...summary].length} characters, over ${MAX_SUMMARY}`, REMEDIES.summary);
+    }
+    for (const entry of code.filter((path) => !existsSync(join(root, path)))) {
+        fail(`${show(id)} names code at ${show(entry)}, which does not exist`, REMEDIES.path);
+    }
+    for (const entry of docs) {
+        const [path = "", anchor] = entry.split("#", 2);
+        if (!existsSync(join(root, path))) {
+            fail(`${show(id)} names the doc ${show(entry)}, which does not exist`, REMEDIES.path);
+        }
+        else if (anchor !== undefined && !anchorsOf(root, path, cache).has(anchor)) {
+            fail(`${show(id)} names the doc ${show(entry)}, which has no heading with that anchor`, REMEDIES.anchor);
+        }
+    }
+    return findings;
+}
+/** Every file under `roots` that git tracks or would track, and that is on disk. */
+function filesUnder(root, roots) {
+    const args = ["-C", root, "ls-files", "-z", "--cached", "--others", "--exclude-standard", "--", ...roots];
+    const listed = spawnSync("git", args, { encoding: "utf8" });
+    if (listed.status !== 0) {
+        throw new CannotRun({
+            message: `cannot list the files under ${roots.join(", ")}: not a git repository`,
+            remedy: REMEDIES.notGit
+        });
+    }
+    return [...new Set(listed.stdout.split("\0").filter((path) => path !== ""))]
+        .filter((path) => existsSync(join(root, path)))
+        .toSorted();
+}
+function run(root, { file, roots }) {
+    const read = readCatalogue(root, file);
+    if (read.state === "missing") {
+        throw new CannotRun({ file, message: "the catalogue does not exist", remedy: REMEDIES.missing });
+    }
+    if (read.state === "invalid") {
+        return read.problems.map((message) => ({ file, message, remedy: REMEDIES.shape }));
+    }
+    const { catalogue, text } = read;
+    const findings = [];
+    const seen = new Map();
+    const cache = new Map();
+    for (const primitive of catalogue.primitives) {
+        const nth = seen.get(primitive.id) ?? 0;
+        seen.set(primitive.id, nth + 1);
+        const line = lineOf(text, primitive.id, nth);
+        const at = line === undefined ? { file } : { file, line };
+        if (nth > 0) {
+            findings.push({
+                ...at,
+                message: `id ${show(primitive.id)} is taken by an earlier Primitive`,
+                remedy: REMEDIES.duplicate
+            });
+        }
+        findings.push(...judge(root, catalogue, primitive, at, cache));
+    }
+    for (const path of filesUnder(root, roots)) {
+        if (!TEST_FILE.test(path) && primitivesNaming(catalogue, path).length === 0) {
+            const remedy = `name it, or a directory above it, in the code of a Primitive in ${file}`;
+            findings.push({ file: path, message: "no Primitive names this file", remedy });
+        }
+    }
+    return findings;
+}
+export const primitives = {
+    name: "primitives",
+    defaults: { file: CATALOGUE_FILE, roots: ["packages", "plugins", "scripts", "src"] },
+    run
+};
+/** The catalogue a resolved `gate.checks` points at: the `primitives` Check's file, on or off. */
+export function catalogueFile(checks) {
+    return (optionsOf(primitives, checks.primitives) ?? primitives.defaults).file;
+}

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -0,0 +1,43 @@
+#!/usr/bin/env node
+// The `dw-sdlc` bin: one row per subcommand, each a module under `commands/`. A plugin's hook or skill
+// reaches it through the plugin's `dw-sdlc` link.
+import * as config from "./commands/config.js";
+import * as doctor from "./commands/doctor.js";
+import * as gate from "./commands/gate.js";
+import * as primitives from "./commands/primitives.js";
+import * as referencesSetup from "./commands/references-setup.js";
+import * as referencesSync from "./commands/references-sync.js";
+import * as setup from "./commands/setup.js";
+const COMMANDS = new Map([
+    ["gate", gate],
+    ["primitives", primitives],
+    ["setup", setup],
+    ["doctor", doctor],
+    ["config", config],
+    ["references sync", referencesSync],
+    ["references setup", referencesSetup]
+]);
+function usage() {
+    const width = Math.max(...[...COMMANDS.keys()].map((name) => name.length)) + 2;
+    const rows = [...COMMANDS].map(([name, { summary }]) => `  ${name.padEnd(width)}${summary}`);
+    return `Usage: dw-sdlc <command> [options]\n\nCommands:\n${rows.join("\n")}\n\nRun dw-sdlc <command> --help for its options.`;
+}
+async function main(argv) {
+    const [first, second] = argv;
+    if (first === "--help" || first === "-h") {
+        process.stdout.write(`${usage()}\n`);
+        return 0;
+    }
+    // A two-word name, as `references sync`, before its first word alone.
+    const words = second !== undefined && COMMANDS.has(`${first} ${second}`) ? 2 : 1;
+    const command = COMMANDS.get(argv.slice(0, words).join(" "));
+    if (command === undefined) {
+        const problem = first === undefined ? "no command given" : `unknown command ${JSON.stringify(first)}`;
+        process.stderr.write(`dw-sdlc: ${problem}\n\n${usage()}\n`);
+        return 2;
+    }
+    return command.run(argv.slice(words));
+}
+if (import.meta.main) {
+    process.exitCode = await main(process.argv.slice(2));
+}

package/dist/commands/config.d.ts

@@ -0,0 +1,2 @@
+export declare const summary = "resolve the repository's agentic config, or validate one file against the schema";
+export declare function run(argv: string[]): number;

package/dist/commands/config.js

@@ -0,0 +1,76 @@
+// `dw-sdlc config`, the config check: resolves a repository's agentic config, or validates one file
+// against the schema, and prints what the guards see.
+import { readFileSync } from "node:fs";
+import { parseArgs } from "node:util";
+import { COMMITTED_FILE, findRepository, LOCAL_FILE, repositoryRoot, resolveConfig, validateDocument } from "../agentic-config.js";
+export const summary = "resolve the repository's agentic config, or validate one file against the schema";
+const USAGE = `Usage: dw-sdlc config [--root <dir>] [file]
+  or:  pnpm agentic:check [--root <dir>] [file], in a checkout of dw-sdlc
+
+Without a file: resolves the agentic config of the repository holding --root (default: the current
+directory) — local over committed over inferred — and prints what the guards see. With a file:
+validates that one document against the schema. Exit 1 on any problem.`;
+function messageOf(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+function fail(message, code) {
+    console.error(`agentic:check: ${message}`);
+    process.exit(code);
+}
+function parseCli(argv) {
+    try {
+        const { values, positionals } = parseArgs({
+            args: argv,
+            allowPositionals: true,
+            options: { help: { type: "boolean", short: "h" }, root: { type: "string" } }
+        });
+        if (positionals.length > 1) {
+            throw new Error("at most one file");
+        }
+        return { help: values.help === true, root: values.root, file: positionals[0] };
+    }
+    catch (error) {
+        fail(`${messageOf(error)}\n\n${USAGE}`, 2);
+    }
+}
+function report(problems) {
+    for (const { file, path, message } of problems) {
+        console.error(path === "" ? `${file}: ${message}` : `${file}: ${path}: ${message}`);
+    }
+}
+export function run(argv) {
+    const cli = parseCli(argv);
+    if (cli.help) {
+        console.log(USAGE);
+        return 0;
+    }
+    if (cli.file !== undefined) {
+        let text;
+        try {
+            text = readFileSync(cli.file, "utf8");
+        }
+        catch (error) {
+            fail(messageOf(error), 1);
+        }
+        const result = validateDocument(cli.file, text);
+        if ("problems" in result) {
+            report(result.problems);
+            return 1;
+        }
+        console.log(`${cli.file}: valid`);
+        return 0;
+    }
+    const root = cli.root === undefined
+        ? (findRepository(process.cwd()) ?? fail("not inside a git repository; pass --root <dir>", 1))
+        : repositoryRoot(cli.root);
+    const { config, problems, layers, sources } = resolveConfig(root);
+    const from = (source) => source === undefined || source === root ? "" : `, from ${source}`;
+    console.log(`committed  ${COMMITTED_FILE}  ${layers.committed}${from(sources.committed)}`);
+    console.log(`local      ${LOCAL_FILE}  ${layers.local}${from(sources.local)}`);
+    console.log(JSON.stringify(config, null, 2));
+    if (problems.length > 0) {
+        report(problems);
+        fail(`${problems.length} problem(s) above; the guards run on the strictest defaults until the file is fixed`, 1);
+    }
+    return 0;
+}

package/dist/commands/doctor.d.ts

@@ -0,0 +1,57 @@
+export type Level = "PASS" | "WARN" | "FAIL" | "INFO";
+export type Check = {
+    name: string;
+    level: Level;
+    detail: string;
+};
+/** What the doctor asks the machine; the tests answer from canned data. */
+export type Probe = {
+    /** A command run directly, from `cwd` when given, with its exit status and stdout. */
+    run(command: string, args: string[], cwd?: string): {
+        status: number;
+        stdout: string;
+    };
+    /** A file's text, or undefined when it is absent. */
+    read(path: string): string | undefined;
+    /** One line of `command -v <tool>` from a non-interactive login shell, the shell the agent gets. */
+    shell(script: string): string;
+};
+export type RepositoryConfig = {
+    config: {
+        commit: {
+            convention: string;
+        };
+    };
+    problems: string[];
+    /** The checkout each layer was read from, as `resolveConfig` reports it. */
+    sources?: {
+        committed: string | undefined;
+        local: string | undefined;
+    };
+};
+export type Inputs = {
+    root: string;
+    home: string;
+    /** Claude Code's config dir; `<home>/.claude` when absent. */
+    claudeDir?: string;
+    probe: Probe;
+    /** Undefined when no repository holds `root`. */
+    config: RepositoryConfig | undefined;
+};
+/** Claude Code's config dir: `$CLAUDE_CONFIG_DIR` when set, the way Claude Code reads it, else `~/.claude`. */
+export declare function claudeConfigDir(env: Record<string, string | undefined>, home: string): string;
+/** The marketplace Claude Code registers this repository under, and the plugin id inside it. */
+export declare const MARKETPLACE = "dw-sdlc";
+export declare const PLUGIN_ID = "guardrails@dw-sdlc";
+/** rtk find passes -exec through verbatim from this release; before it, `rtk find … -exec` exits 1. */
+export declare const RTK_FIND_EXEC_FIXED = "0.46.0";
+export declare const PNPM_MINIMUM_RELEASE_AGE = 10080;
+export declare const realProbe: Probe;
+/** rtk's config.toml: Application Support on macOS, XDG or ~/.config elsewhere. */
+export declare function rtkConfigPath(home: string, platform?: string, env?: Record<string, string | undefined>): string;
+/** The `exclude_commands` list of an rtk config.toml, read with a regex: the file is small and ours. */
+export declare function rtkExcludes(toml: string | undefined): string[];
+export declare function diagnose(inputs: Inputs): Check[];
+export declare function render(checks: Check[]): string;
+export declare const summary = "one PASS / WARN / FAIL line per machine check the guardrails rely on";
+export declare function run(argv: string[]): number;

package/dist/commands/doctor.js

@@ -0,0 +1,341 @@
+// `dw-sdlc doctor`: one PASS / WARN / FAIL line per machine check the guardrails rely on, read-only.
+// It diagnoses 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 that
+// is missing or loose (Safe Chain, the pnpm cooldown, signing, rtk excludes), INFO a check that does
+// not apply here. Every probe goes through one interface, so the tests fake each answer. The
+// machine-wide values are asked from the home directory: from a checkout, its own
+// pnpm-workspace.yaml would answer for the machine.
+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` };
+}
+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;