dw-sdlc 0.3.0 → 0.4.0

package/README.md

@@ -17,7 +17,8 @@ pnpm add -D dw-sdlc
 
 `dw-sdlc gate` runs the Steps under `gate.steps` in order from the repository root, then every Check
 under `gate.checks`. It exits 0 when everything passes, 1 when a Step or a Check fails, and 2 when the
-Gate cannot run. `--json` prints the result as one document.
+Gate cannot run. `--json` prints the result as one document. `dw-sdlc check <name>` runs one Check
+alone, with the same lines, exit codes and document.
 
 ```json
 {
@@ -38,6 +39,7 @@ Gate cannot run. `--json` prints the result as one document.
 | command            | what it does                                                                        |
 | ------------------ | ----------------------------------------------------------------------------------- |
 | `gate`             | the Steps of `gate.steps` in order, then every Check under `gate.checks`            |
+| `check <name>`     | one Check of the Gate by its name, without the Steps and the other Checks           |
 | `primitives`       | the Primitives that own each path, with their summaries and documents               |
 | `setup`            | this machine's local config layer, the git excludes and the permission rules        |
 | `doctor`           | one PASS / WARN / FAIL line per machine check the guardrails rely on                |

package/dist/checks/index.d.ts

@@ -8,5 +8,9 @@ export type EnabledCheck = {
         refresh: (root: string) => string;
     };
 };
+/** The name of every Check the package ships, in the order the Gate runs them. */
+export declare const CHECK_NAMES: readonly string[];
 /** Every shipped Check a resolved `gate.checks` turns on with `true` or its options. */
 export declare function enabledChecks(checks: Record<string, unknown>): EnabledCheck[];
+/** The shipped Check `name` on `setting`, or on its defaults where `setting` leaves it off. */
+export declare function shippedCheck(name: string, setting: unknown): EnabledCheck | undefined;

package/dist/checks/index.js

@@ -36,7 +36,14 @@ const SHIPPED = [
     ship(fileSizeRatchet),
     ship(commentBudget)
 ];
+/** The name of every Check the package ships, in the order the Gate runs them. */
+export const CHECK_NAMES = SHIPPED.map(({ name }) => name);
 /** Every shipped Check a resolved `gate.checks` turns on with `true` or its options. */
 export function enabledChecks(checks) {
     return SHIPPED.flatMap(({ name, enable }) => enable(checks[name]) ?? []);
 }
+/** The shipped Check `name` on `setting`, or on its defaults where `setting` leaves it off. */
+export function shippedCheck(name, setting) {
+    const on = setting === false || setting === undefined ? true : setting;
+    return SHIPPED.find((check) => check.name === name)?.enable(on);
+}

package/dist/cli.js

@@ -1,6 +1,7 @@
 #!/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 check from "./commands/check.js";
 import * as config from "./commands/config.js";
 import * as doctor from "./commands/doctor.js";
 import * as gate from "./commands/gate.js";
@@ -10,6 +11,7 @@ import * as referencesSync from "./commands/references-sync.js";
 import * as setup from "./commands/setup.js";
 const COMMANDS = new Map([
     ["gate", gate],
+    ["check", check],
     ["primitives", primitives],
     ["setup", setup],
     ["doctor", doctor],

package/dist/commands/check.d.ts

@@ -0,0 +1,2 @@
+export declare const summary = "run one Check of the Gate by its name, without the Steps and the other Checks";
+export declare function run(argv: string[]): number;

package/dist/commands/check.js

@@ -0,0 +1,59 @@
+// `dw-sdlc check <name>`: one Check of the Gate by its name, without the Steps and the other Checks.
+import { parseArgs } from "node:util";
+import { repositoryRoot } from "../agentic-config.js";
+import { CHECK_NAMES } from "../checks/index.js";
+import { printReport, runGate } from "./gate.js";
+export const summary = "run one Check of the Gate by its name, without the Steps and the other Checks";
+const USAGE = `Usage: dw-sdlc check <name> [--json] [--root <dir>]
+
+Runs the Check named <name> in the Gate of the repository holding --root (default: the current
+directory): a script under gate.checks.run, or a Check the package ships, one of
+${CHECK_NAMES.join(", ")}. A name both carry runs both, as the Gate does. A
+shipped Check runs on the setting gate.checks gives it, and on its defaults where the config sets it
+false or leaves it out. No Step runs. Prints one line per failure, as the Gate does; --json prints
+the Gate's document, with no Step.
+
+A Ratchet's baseline is refreshed by dw-sdlc gate --update-baseline, which needs every other Check to
+pass.
+
+Exit 0 when the Check passes, 1 when it fails, 2 when it cannot run: no Check of that name, an
+invalid config layer, a command the shell cannot find or execute, or an input the Check reads
+missing.`;
+function parseCli(argv) {
+    try {
+        const { values, positionals } = parseArgs({
+            args: argv,
+            allowPositionals: true,
+            options: {
+                help: { type: "boolean", short: "h" },
+                json: { type: "boolean" },
+                root: { type: "string" }
+            }
+        });
+        if (positionals.length > 1) {
+            return { error: `one Check at a time, not ${positionals.map((name) => JSON.stringify(name)).join(" and ")}` };
+        }
+        return { help: values.help === true, json: values.json === true, root: values.root, name: positionals[0] };
+    }
+    catch (error) {
+        return { error: error instanceof Error ? error.message : String(error) };
+    }
+}
+export function run(argv) {
+    const cli = parseCli(argv);
+    if ("error" in cli) {
+        process.stderr.write(`dw-sdlc check: ${cli.error}\n\n${USAGE}\n`);
+        return 2;
+    }
+    if (cli.help) {
+        process.stdout.write(`${USAGE}\n`);
+        return 0;
+    }
+    if (cli.name === undefined) {
+        process.stderr.write(`dw-sdlc check: name the Check to run\n\n${USAGE}\n`);
+        return 2;
+    }
+    const { json, name } = cli;
+    const report = runGate(repositoryRoot(cli.root ?? process.cwd()), { json, only: name });
+    return printReport(report, json, `check ${name}`);
+}

package/dist/commands/gate.d.ts

@@ -1,2 +1,38 @@
+import { type Failure } from "../report.ts";
 export declare const summary = "run the Gate: the Steps of gate.steps in order, then every Check under gate.checks";
+type Status = "pass" | "fail" | "error";
+type Outcome = {
+    status: Status | "skipped";
+    exitCode: number | null;
+};
+type StepReport = Outcome & {
+    command: string;
+};
+/** A Check the package ships runs in this process: it has no command. */
+type CheckReport = Outcome & {
+    name: string;
+    command: string | null;
+};
+type GateReport = {
+    status: Status;
+    command: string | null;
+    steps: StepReport[];
+    checks: CheckReport[];
+    failures: Failure[];
+};
+/** A run of the whole Gate, or of the Checks named `only` alone: no Step, no progress line, no refresh. */
+type RunOptions = {
+    json: boolean;
+} & ({
+    updateBaseline: boolean;
+} | {
+    only: string;
+});
+export declare function runGate(root: string, options: RunOptions): GateReport;
+/**
+ * Prints `report`: a line per failure and the verdict under `label`, or one document under `json`; under
+ * GitHub Actions each failure is also an annotation. Returns the exit code.
+ */
+export declare function printReport(report: GateReport, json: boolean, label: string): number;
 export declare function run(argv: string[]): number;
+export {};

package/dist/commands/gate.js

@@ -1,9 +1,10 @@
-// `dw-sdlc gate`: the Gate of a repository, from the `gate` key of its resolved agentic config.
+// `dw-sdlc gate`: the Gate of a repository, from the `gate` key of its resolved agentic config. The
+// run and the report serve `dw-sdlc check` too, which judges one Check of it.
 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 { CHECK_NAMES, enabledChecks, shippedCheck } 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]
@@ -26,6 +27,8 @@ 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 };
+/** One Check run by name says nothing before its result. */
+const QUIET = { write: () => true };
 const REMEDIES = {
     invalidLayer: "fix the file; the Gate runs once every layer is valid",
     failed: "fix what it printed above",
@@ -142,13 +145,36 @@ 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;
+/**
+ * Every Step and Check of `gate`, or with `only` no Step and the Checks of that name: the run Checks
+ * and the shipped one, which runs on its defaults where the config leaves it off. No Check of that
+ * name is a failure.
+ */
+function select(gate, only) {
+    if (only === undefined) {
+        return { steps: gate.steps, run: gate.checks.run, shipped: enabledChecks(gate.checks) };
+    }
+    const scripts = gate.checks.run.filter((check) => check.name === only);
+    const shipped = shippedCheck(only, gate.checks[only]);
+    if (scripts.length === 0 && shipped === undefined) {
+        const names = [...gate.checks.run.map((check) => check.name), ...CHECK_NAMES].join(", ");
+        return { rule: "check", message: `no Check is named ${JSON.stringify(only)}`, remedy: `name one of ${names}` };
+    }
+    return { steps: [], run: scripts, shipped: shipped === undefined ? [] : [shipped] };
+}
+export function runGate(root, options) {
+    const { json } = options;
+    const only = "only" in options ? options.only : undefined;
+    const log = only !== undefined ? QUIET : 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 selected = select(config.gate, only);
+    if ("rule" in selected) {
+        return { status: "error", command: gateCommand, steps: [], checks: [], failures: [selected] };
+    }
     const failures = [];
     /** Runs one Step or Check and records its failure under `rule`, if it has one. */
     const runOne = (command, rule, notRunnable) => {
@@ -161,7 +187,7 @@ function runGate(root, json, updateBaseline) {
     };
     const steps = [];
     let stopped = false;
-    for (const step of config.gate.steps) {
+    for (const step of selected.steps) {
         if (stopped) {
             steps.push({ command: step, ...SKIPPED });
             continue;
@@ -172,7 +198,7 @@ function runGate(root, json, updateBaseline) {
         stopped = outcome.status !== "pass";
     }
     const checks = [];
-    for (const check of config.gate.checks.run) {
+    for (const check of selected.run) {
         if (stopped) {
             checks.push({ ...check, ...SKIPPED });
             continue;
@@ -180,14 +206,14 @@ function runGate(root, json, updateBaseline) {
         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) => {
+    const judged = selected.shipped.map((check) => {
         if (stopped) {
             return { check, outcome: SKIPPED, failures: [] };
         }
         log.write(`gate: check ${check.name}\n`);
         return runShipped(check, root);
     });
-    if (updateBaseline) {
+    if ("updateBaseline" in options && options.updateBaseline) {
         refreshBaselines(judged, [...steps, ...checks], root, log);
     }
     for (const { check, outcome, failures: found } of judged) {
@@ -196,26 +222,21 @@ function runGate(root, json, updateBaseline) {
     }
     return { status: worst([...steps, ...checks]), command: gateCommand, steps, checks, failures };
 }
-function verdict(report) {
+/** The last line, after `label`: green with what ran, or failed or cannot run with how many failures. */
+function verdict(label, report) {
     if (report.status === "pass") {
-        return `gate: green — ${plural(report.steps.length, "step")}, ${plural(report.checks.length, "check")}`;
+        return `${label}: 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}`;
+    return report.status === "fail" ? `${label}: failed — ${failures}` : `${label}: 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);
+/**
+ * Prints `report`: a line per failure and the verdict under `label`, or one document under `json`; under
+ * GitHub Actions each failure is also an annotation. Returns the exit code.
+ */
+export function printReport(report, json, label) {
     const actions = process.env.GITHUB_ACTIONS === "true";
-    if (cli.json) {
+    if (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.
@@ -225,7 +246,20 @@ export function run(argv) {
     }
     else {
         const lines = report.failures.flatMap((failure) => actions ? [failureLine(failure), annotation(failure)] : [failureLine(failure)]);
-        process.stdout.write(`${[...lines, verdict(report)].join("\n")}\n`);
+        process.stdout.write(`${[...lines, verdict(label, report)].join("\n")}\n`);
     }
     return EXIT_CODES[report.status];
 }
+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 { json, updateBaseline } = cli;
+    return printReport(runGate(repositoryRoot(cli.root ?? process.cwd()), { json, updateBaseline }), json, "gate");
+}

package/dist/commands/references-setup.js

@@ -5,7 +5,8 @@ import { spawnSync } from "node:child_process";
 import { existsSync, lstatSync, mkdirSync, readFileSync, symlinkSync, writeFileSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { parseArgs } from "node:util";
-import { CONFIG, isObject, readReferences } from "../references-key.js";
+import { appendKey, parseObject, render } from "../json-text.js";
+import { CONFIG, readReferences } from "../references-key.js";
 import { renderBlock, withBlock } from "../router-block.js";
 const ROUTER = "references/AGENTS.md";
 /** A symlink to the Router, so Claude Code loads it. */
@@ -45,20 +46,6 @@ function fail(message) {
     console.error(`references:setup: ${message}`);
     process.exit(2);
 }
-function render(value) {
-    return `${JSON.stringify(value, null, 2)}\n`;
-}
-/** The JSON object `text` holds, or undefined when it holds anything else. */
-function parseObject(text) {
-    let parsed;
-    try {
-        parsed = JSON.parse(text);
-    }
-    catch {
-        return undefined;
-    }
-    return isObject(parsed) ? parsed : undefined;
-}
 class Writer {
     steps = [];
     root;
@@ -138,13 +125,7 @@ function withEmptyKey(current) {
     if (config === undefined) {
         return { refusal: "is not a JSON object; fix it by hand first" };
     }
-    if (Object.hasOwn(config, "references")) {
-        return { text: current };
-    }
-    const close = current.lastIndexOf("}");
-    const body = current.slice(0, close).trimEnd();
-    const comma = body.endsWith("{") ? "" : ",";
-    return { text: `${body}${comma}\n  "references": []\n${current.slice(close)}` };
+    return { text: Object.hasOwn(config, "references") ? current : appendKey(current, "references", []) };
 }
 /** The repository `dir` sits in, or `dir` itself outside one. */
 function toplevel(dir) {

package/dist/commands/setup.d.ts

@@ -1,5 +1,6 @@
 import { type CommitConvention, type CommitOnProtected, type ForcePush } from "../agentic-config.ts";
-export type Outcome = "wrote" | "unchanged" | "refused";
+/** `by hand` is an edit the setup names and leaves to the user. */
+export type Outcome = "wrote" | "unchanged" | "refused" | "by hand";
 export type Step = {
     file: string;
     outcome: Outcome;
@@ -18,8 +19,10 @@ export type SetupOptions = {
     forcePush?: ForcePush | undefined;
     /** Pins `guardrails.commitOnProtected` in the local layer; refused where it loosens the committed value. */
     commitOnProtected?: CommitOnProtected | undefined;
+    /** The owner's yes to pinning dw-sdlc as a devDependency where package.json lacks it. */
+    addPackage?: boolean;
 };
-export declare const summary = "write this machine's local config layer, the git excludes and the permission rules";
+export declare const summary = "adopt the Gate where asked, and write this machine's local config layer, the git excludes and the permission rules";
 /**
  * What the machine's layer points `$schema` at: the marketplace clone's schema as a `file://` URL, as an
  * editor cannot fetch the `$id` from a private repository and the clone, unlike the install cache, keeps

package/dist/commands/setup.js

@@ -1,18 +1,20 @@
-// `dw-sdlc setup` sets a repository and this machine up for the sdlc plugin: the four files its USAGE
-// names, each written only when its content would change, so a run is safe to repeat. Existing content is
-// merged, never replaced: other keys stay, and a settings file that is not JSON is refused.
+// `dw-sdlc setup` sets a repository and this machine up for the sdlc plugin: the files its USAGE names,
+// each written only when its content would change, so a run is safe to repeat. Existing content is
+// merged, never replaced: other keys stay, and a file that is not a JSON object is refused.
 import { spawnSync } from "node:child_process";
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { dirname, join, relative } from "node:path";
 import { pathToFileURL } from "node:url";
 import { parseArgs } from "node:util";
-import { COMMIT_CONVENTIONS, COMMITTED_FILE, DEFAULT_GUARDRAILS, LOCAL_FILE, SCHEMA_FILE, STRICTNESS, inferConfig, repositoryRoot, schemaId, validateDocument } from "../agentic-config.js";
+import { COMMIT_CONVENTIONS, COMMITTED_FILE, DEFAULT_GUARDRAILS, LOCAL_FILE, SCHEMA_FILE, STRICTNESS, inferConfig, repositoryRoot, resolveConfig, schemaId, validateDocument } from "../agentic-config.js";
+import { isObject, parseObject, render } from "../json-text.js";
+import { withGate, withPackage } from "../setup-gate.js";
 import { GLOBAL_DENY, LEASE_RULE, RETIRED_DENY, repositoryDeny } from "../setup-rules.js";
-export const summary = "write this machine's local config layer, the git excludes and the permission rules";
+export const summary = "adopt the Gate where asked, and write this machine's local config layer, the git excludes and the permission rules";
 const USAGE = `Usage: dw-sdlc setup [--root <dir>] [--home <dir>]
        [--convention <preset>] [--force-push deny|ask|lease] [--commit-on-protected deny|allow]
-       [--force] [--dry-run]
+       [--add-package] [--force] [--dry-run]
   or:  pnpm guardrails:setup with the same flags, in a checkout of dw-sdlc
 
 Writes .ai/agentic.config.local.json from inference, excludes it in .git/info/exclude, generates
@@ -23,7 +25,14 @@ written only when it would change; --convention ticket-key | conventional pins c
 the local config, and a run without it keeps the pin as it is; a guardrails block in the local config
 is kept, and --force-push and --commit-on-protected pin those two keys in it, refused where they would
 loosen what the committed config sets; --force overwrites a local config that differs in anything
-else; --dry-run reports without writing.`;
+else; --dry-run reports without writing.
+
+Where the repository has a package.json, the setup adopts the Gate. --add-package pins dw-sdlc
+there as a devDependency, at the version running the setup; a new dependency needs the owner's yes,
+so without the flag the file is refused. Once the package is there, .ai/agentic.config.json gains
+the gate key when it has none, and the file is created when absent. Both files go to the repository
+holding --root, a linked worktree included. The agent map is never written. Settings that still
+enable guardrails@dw-sdlc or references@dw-sdlc get a "by hand" line naming the enabledPlugins edit.`;
 function isConvention(value) {
     return COMMIT_CONVENTIONS.some((preset) => preset === value);
 }
@@ -38,9 +47,8 @@ const MARKETPLACE = "dw-sdlc";
 const PLUGIN = "sdlc";
 /** The plugin's link to the dw-sdlc package, which carries the schema. */
 const PACKAGE_LINK = "dw-sdlc";
-function isObject(value) {
-    return typeof value === "object" && value !== null && !Array.isArray(value);
-}
+/** The two plugins the sdlc plugin replaced, which the marketplace does not list (ADR 0010). */
+const RETIRED_PLUGINS = ["guardrails", "references"].map((name) => `${name}@${MARKETPLACE}`);
 /** A read-only git command, the one thing the setup runs in the repository. */
 function git(root, args) {
     const result = spawnSync("git", ["-C", root, ...args], { encoding: "utf8" });
@@ -169,24 +177,8 @@ function union(existing, additions) {
     }
     return list;
 }
-function readJsonText(text) {
-    try {
-        const parsed = JSON.parse(text);
-        return parsed;
-    }
-    catch {
-        return undefined;
-    }
-}
 function readJson(path) {
-    if (!existsSync(path)) {
-        return undefined;
-    }
-    const parsed = readJsonText(readFileSync(path, "utf8"));
-    return isObject(parsed) ? parsed : "invalid";
-}
-function render(value) {
-    return JSON.stringify(value, null, 2) + "\n";
+    return existsSync(path) ? (parseObject(readFileSync(path, "utf8")) ?? "invalid") : undefined;
 }
 class Writer {
     steps = [];
@@ -194,8 +186,8 @@ class Writer {
     constructor(dryRun) {
         this.dryRun = dryRun;
     }
-    /** Writes when the text differs from what is on disk; records the outcome under `label`. */
-    put(label, path, text) {
+    /** Writes when the text differs from what is on disk; records the outcome under `label`, with what the write does. */
+    put(label, path, text, detail) {
         const current = existsSync(path) ? readFileSync(path, "utf8") : undefined;
         if (current === text) {
             this.steps.push({ file: label, outcome: "unchanged" });
@@ -205,11 +197,36 @@ class Writer {
             mkdirSync(dirname(path), { recursive: true });
             writeFileSync(path, text);
         }
-        this.steps.push({ file: label, outcome: "wrote" });
+        this.steps.push(detail === undefined ? { file: label, outcome: "wrote" } : { file: label, outcome: "wrote", detail });
     }
     refuse(label, detail) {
         this.steps.push({ file: label, outcome: "refused", detail });
     }
+    /** The step's file as `change` leaves it: written, unchanged or refused. */
+    apply(label, path, change) {
+        if ("refusal" in change) {
+            this.refuse(label, change.refusal);
+        }
+        else {
+            this.put(label, path, change.text, change.detail);
+        }
+    }
+    byHand(label, detail) {
+        this.steps.push({ file: label, outcome: "by hand", detail });
+    }
+}
+/** The enabledPlugins edit settings that still enable a retired plugin need; none where they enable neither. */
+function enabledPluginsEdit(settings) {
+    const enabled = isObject(settings.enabledPlugins) ? settings.enabledPlugins : {};
+    const retired = RETIRED_PLUGINS.filter((id) => enabled[id] === true);
+    if (retired.length === 0) {
+        return undefined;
+    }
+    const id = `${PLUGIN}@${MARKETPLACE}`;
+    const remove = `enabledPlugins: remove ${retired.map((name) => JSON.stringify(name)).join(" and ")}, which the marketplace does not list`;
+    return enabled[id] === true
+        ? remove
+        : `${remove}, and add "${id}": true after claude plugin install ${id} --scope user`;
 }
 /**
  * Where the repository's files live: the main checkout for a linked worktree, since every worktree reads
@@ -231,7 +248,7 @@ export function setup(options) {
     // the guardrails block the file holds, with the keys the flags pin.
     const localPath = join(checkout, LOCAL_FILE);
     const localCurrent = existsSync(localPath) ? readFileSync(localPath, "utf8") : undefined;
-    const existing = localCurrent === undefined ? undefined : readJsonText(localCurrent);
+    const existing = localCurrent === undefined ? undefined : parseObject(localCurrent);
     const convention = options.convention ?? pinnedConvention(existing);
     const pinned = pinnedGuardrails(keptGuardrails(existing), committedConfig(checkout), options);
     if ("refusal" in pinned) {
@@ -292,6 +309,23 @@ export function setup(options) {
         const permissions = isObject(settings.permissions) ? settings.permissions : {};
         settings.permissions = { ...permissions, deny: union(permissions.deny, GLOBAL_DENY) };
         writer.put(userLabel, userPath, render(settings));
+        const edit = enabledPluginsEdit(settings);
+        if (edit !== undefined) {
+            writer.byHand(userLabel, edit);
+        }
+    }
+    // 5. The Gate, where the repository has a package.json: the pinned package, then the gate key once the
+    // package is there. Both are committed, so they go to the repository holding --root, never the main
+    // checkout, and stay on the branch the setup runs on.
+    const manifestPath = join(root, "package.json");
+    if (existsSync(manifestPath)) {
+        const manager = resolveConfig(root).config.packageManagers.node ?? "pnpm";
+        const pin = withPackage(readFileSync(manifestPath, "utf8"), options.addPackage === true, manager);
+        writer.apply("package.json", manifestPath, pin);
+        if (!("refusal" in pin)) {
+            const configPath = join(root, COMMITTED_FILE);
+            writer.apply(COMMITTED_FILE, configPath, withGate(existsSync(configPath) ? readFileSync(configPath, "utf8") : undefined));
+        }
     }
     return writer.steps;
 }
@@ -311,6 +345,7 @@ export function run(argv) {
                 convention: { type: "string" },
                 "force-push": { type: "string" },
                 "commit-on-protected": { type: "string" },
+                "add-package": { type: "boolean" },
                 force: { type: "boolean" },
                 "dry-run": { type: "boolean" }
             }
@@ -342,7 +377,8 @@ export function run(argv) {
         dryRun: values["dry-run"] === true,
         convention: values.convention,
         forcePush,
-        commitOnProtected
+        commitOnProtected,
+        addPackage: values["add-package"] === true
     });
     for (const step of steps) {
         const verb = step.outcome === "wrote" && values["dry-run"] === true ? "would write" : step.outcome;

package/dist/json-text.d.ts

@@ -0,0 +1,7 @@
+export type JsonObject = Record<string, unknown>;
+export declare function isObject(value: unknown): value is JsonObject;
+/** The JSON object `text` holds, or undefined when it holds anything else. */
+export declare function parseObject(text: string): JsonObject | undefined;
+export declare function render(value: unknown): string;
+/** `text`, a JSON object, with `key` set to `value` after its last key, two spaces in. */
+export declare function appendKey(text: string, key: string, value: unknown): string;

package/dist/json-text.js

@@ -0,0 +1,26 @@
+// The text of a JSON object file as the setup commands read and write it: parsed only when it holds an
+// object, rendered two spaces in, and a key appended so a hand-formatted file keeps its layout.
+export function isObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/** The JSON object `text` holds, or undefined when it holds anything else. */
+export function parseObject(text) {
+    try {
+        const parsed = JSON.parse(text);
+        return isObject(parsed) ? parsed : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+export function render(value) {
+    return `${JSON.stringify(value, null, 2)}\n`;
+}
+/** `text`, a JSON object, with `key` set to `value` after its last key, two spaces in. */
+export function appendKey(text, key, value) {
+    const close = text.lastIndexOf("}");
+    const body = text.slice(0, close).trimEnd();
+    const comma = body.endsWith("{") ? "" : ",";
+    const rendered = JSON.stringify(value, null, 2).replaceAll("\n", "\n  ");
+    return `${body}${comma}\n  ${JSON.stringify(key)}: ${rendered}\n${text.slice(close)}`;
+}

package/dist/setup-gate.d.ts

@@ -0,0 +1,15 @@
+import type { NodePackageManager } from "./agentic-config.ts";
+/** A file's text after the setup and what writing it does, or why the setup leaves the file alone. */
+export type Change = {
+    text: string;
+    detail?: string;
+} | {
+    refusal: string;
+};
+/**
+ * package.json with the package pinned exactly as a devDependency, in name order, where neither list
+ * names it. A new dependency needs the owner's yes, so without `add` the file is refused.
+ */
+export declare function withPackage(current: string, add: boolean, manager: NodePackageManager): Change;
+/** The committed config with the `gate` key when it has none, the file created when absent; a key it has stays. */
+export declare function withGate(current: string | undefined): Change;

package/dist/setup-gate.js

@@ -0,0 +1,82 @@
+// What `dw-sdlc setup` changes to adopt the Gate, in files the repository commits: the `dw-sdlc`
+// devDependency in package.json, pinned to the version that runs the setup, and the `gate` key of the
+// committed config. Each answers with the file's next text, or why the file stays as it is.
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { CHECK_NAMES } from "./checks/index.js";
+import { appendKey, isObject, parseObject, render } from "./json-text.js";
+const PACKAGE = "dw-sdlc";
+/**
+ * The Checks a new `gate` key turns on: each judges a tree as it is, the agent map aside, which the
+ * setup never writes and the first Gate names. The rest read an input a repository adds first, a
+ * catalogue, a records directory, docs a glob matches or a Ratchet's baseline, so they start `false`.
+ */
+const ON_BY_DEFAULT = new Set(["agents-map", "markdown-refs", "temporal-language", "comment-budget"]);
+/** Where a committed config the setup creates points `$schema`: the schema the pinned package installs. */
+const SCHEMA = `../node_modules/${PACKAGE}/config/agentic.config.schema.json`;
+const NOT_AN_OBJECT = "is not a JSON object; fix it by hand first";
+/** This package's version, the one a pin names, so the plugin and the repository run the same code. */
+function packageVersion() {
+    const manifest = parseObject(readFileSync(join(import.meta.dirname, "..", "package.json"), "utf8"));
+    if (typeof manifest?.version !== "string") {
+        throw new Error(`${PACKAGE}'s package.json names no version`);
+    }
+    return manifest.version;
+}
+/** `a`, `a and b`, `a, b and c`. */
+function list(items) {
+    return items.length < 2 ? items.join("") : `${items.slice(0, -1).join(", ")} and ${items.at(-1)}`;
+}
+/** Whether either dependency list names the package, at any spec: a pin is the doctor's to judge. */
+function dependsOn(manifest) {
+    return ["dependencies", "devDependencies"].some((key) => {
+        const section = manifest[key];
+        return isObject(section) && Object.hasOwn(section, PACKAGE);
+    });
+}
+/**
+ * package.json with the package pinned exactly as a devDependency, in name order, where neither list
+ * names it. A new dependency needs the owner's yes, so without `add` the file is refused.
+ */
+export function withPackage(current, add, manager) {
+    const manifest = parseObject(current);
+    if (manifest === undefined) {
+        return { refusal: NOT_AN_OBJECT };
+    }
+    if (dependsOn(manifest)) {
+        return { text: current };
+    }
+    const version = packageVersion();
+    if (!add) {
+        return {
+            refusal: `no ${PACKAGE} devDependency, and a new one needs your yes: --add-package pins ${PACKAGE} ${version}`
+        };
+    }
+    const { devDependencies = {} } = manifest;
+    if (!isObject(devDependencies)) {
+        return { refusal: "devDependencies is not an object; fix it by hand first" };
+    }
+    const entries = Object.entries(devDependencies);
+    const at = entries.findIndex(([name]) => name > PACKAGE);
+    entries.splice(at === -1 ? entries.length : at, 0, [PACKAGE, version]);
+    // A manifest is JSON.stringify's layout, as package managers write it, at the indent the file opens with.
+    const indent = /^\{\r?\n([ \t]+)"/.exec(current)?.[1] ?? "  ";
+    const next = { ...manifest, devDependencies: Object.fromEntries(entries) };
+    return {
+        text: JSON.stringify(next, null, indent) + (current.endsWith("\n") ? "\n" : ""),
+        detail: `pins ${PACKAGE} ${version} as a devDependency; ${manager} install brings it in`
+    };
+}
+/** The committed config with the `gate` key when it has none, the file created when absent; a key it has stays. */
+export function withGate(current) {
+    const gate = { checks: Object.fromEntries(CHECK_NAMES.map((name) => [name, ON_BY_DEFAULT.has(name)])) };
+    const detail = `the gate key, ${list(CHECK_NAMES.filter((name) => ON_BY_DEFAULT.has(name)))} on and the other Checks off`;
+    if (current === undefined) {
+        return { text: render({ $schema: SCHEMA, version: 1, gate }), detail };
+    }
+    const config = parseObject(current);
+    if (config === undefined) {
+        return { refusal: NOT_AN_OBJECT };
+    }
+    return Object.hasOwn(config, "gate") ? { text: current } : { text: appendKey(current, "gate", gate), detail };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dw-sdlc",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "The Gate and the agentic config of a repository: the dw-sdlc bin with the Gate, the setup, the doctor, the config check, and the Sync and setup of References; the resolver of the config's layers, its JSON Schema and the validator that reads it.",
   "license": "MIT",
   "repository": {