dw-sdlc 0.1.0 → 0.3.0

package/dist/commands/doctor.js

@@ -1,23 +1,22 @@
-// `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.
+// `dw-sdlc doctor`: one PASS / WARN / FAIL line per machine check the sdlc plugin relies 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, loose or out of step, 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";
+import { EXACT_VERSION, parseCatalog, parsePins } from "../pins.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. */
+/** The marketplace Claude Code registers this repository under, the plugin in it, and the package the plugin links to. */
 export const MARKETPLACE = "dw-sdlc";
-export const PLUGIN_ID = `guardrails@${MARKETPLACE}`;
+export const PLUGIN = "sdlc";
+export const PLUGIN_ID = `${PLUGIN}@${MARKETPLACE}`;
+export const PACKAGE = "dw-sdlc";
 /** 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;
@@ -68,7 +67,7 @@ function liveCheckout(probe, claude) {
 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 `runs live from ${checkout}/plugins/${PLUGIN}; a change there is in the next session`;
     }
     return `installed at ${installPath}; a change reaches it through claude plugin update`;
 }
@@ -76,7 +75,7 @@ function pluginOrigin(probe, claude, installPath) {
 function runningPluginRoot(probe, claude) {
     const checkout = liveCheckout(probe, claude);
     if (checkout !== undefined) {
-        return join(checkout, "plugins", "guardrails");
+        return join(checkout, "plugins", PLUGIN);
     }
     const { status, stdout } = probe.run("claude", ["plugin", "list", "--json"]);
     const list = status === 0 ? parseJson(stdout) : undefined;
@@ -114,6 +113,57 @@ function checkPlugin(probe, claude) {
         detail: `${version} enabled; ${pluginOrigin(probe, claude, String(entry.installPath ?? ""))}`
     };
 }
+/** The `version` of the package.json in `dir`, or undefined when there is none. */
+function manifestVersion(probe, dir) {
+    const manifest = parseJson(probe.read(join(dir, "package.json")));
+    return isObject(manifest) && typeof manifest.version === "string" ? manifest.version : undefined;
+}
+/** Whether the plugin's hooks and skills run the dw-sdlc the repository pins, the one its Gate runs. */
+function checkPackage(probe, claude, root) {
+    const name = "package";
+    const manifest = root === undefined ? undefined : probe.read(join(root, "package.json"));
+    if (root === undefined || manifest === undefined) {
+        return { name, level: "INFO", detail: `no package.json here to pin ${PACKAGE}` };
+    }
+    let spec;
+    try {
+        spec = parsePins(manifest, parseCatalog(probe.read(join(root, "pnpm-workspace.yaml")) ?? ""))[PACKAGE];
+    }
+    catch {
+        return { name, level: "INFO", detail: `${join(root, "package.json")} is not JSON` };
+    }
+    if (spec === undefined) {
+        return { name, level: "INFO", detail: `the repository does not pin ${PACKAGE}` };
+    }
+    // `workspace:` or a range names no one version: the copy installed under node_modules is the one that runs.
+    const pinned = EXACT_VERSION.test(spec) ? spec : manifestVersion(probe, join(root, "node_modules", PACKAGE));
+    if (pinned === undefined) {
+        return { name, level: "WARN", detail: `the repository pins ${PACKAGE} ${spec}, not installed: pnpm install` };
+    }
+    const plugin = runningPluginRoot(probe, claude);
+    if (plugin === undefined) {
+        return { name, level: "INFO", detail: `no ${PLUGIN_ID} runs here to compare with the pinned ${pinned}` };
+    }
+    const linked = manifestVersion(probe, join(plugin, PACKAGE));
+    if (linked === undefined) {
+        return {
+            name,
+            level: "WARN",
+            detail: `the plugin at ${plugin} carries no ${PACKAGE}: an install from GitHub needs packages in its --sparse set`
+        };
+    }
+    if (linked !== pinned) {
+        const remedy = versionBefore(linked, pinned)
+            ? `claude plugin update ${PLUGIN_ID}`
+            : `pnpm add --save-dev --save-exact ${PACKAGE}@${linked}`;
+        return {
+            name,
+            level: "WARN",
+            detail: `drift: the plugin runs ${PACKAGE} ${linked} and the repository pins ${pinned}, so its hooks and skills run other code than the Gate. ${remedy}`
+        };
+    }
+    return { name, level: "PASS", detail: `${PACKAGE} ${linked} in the plugin and in the repository` };
+}
 /** Every hook command string in a settings file, whatever the event and matcher. */
 function hookCommands(settings) {
     if (!isObject(settings) || !isObject(settings.hooks)) {
@@ -232,6 +282,10 @@ function checkSafeChain(probe) {
     }
     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" };
@@ -286,6 +340,7 @@ export function diagnose(inputs) {
     return [
         checkJq(probe),
         checkPlugin(probe, claude),
+        checkPackage(probe, claude, inputs.config === undefined ? undefined : inputs.root),
         checkRtk(probe, home, claude),
         checkSafeChain(probe),
         checkPnpmReleaseAge(probe, home),
@@ -296,11 +351,11 @@ export function diagnose(inputs) {
 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";
+export const summary = "one PASS / WARN / FAIL line per machine check the sdlc plugin relies 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
+One PASS / WARN / FAIL line per machine check the sdlc plugin relies 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) {

package/dist/commands/gate.js

@@ -6,7 +6,7 @@ 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>]
+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
@@ -15,6 +15,10 @@ none stopping the next. Prints one line per failure: the file where there is one
 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.`;
@@ -36,9 +40,19 @@ function parseCli(argv) {
     try {
         const { values } = parseArgs({
             args: argv,
-            options: { help: { type: "boolean", short: "h" }, json: { type: "boolean" }, root: { type: "string" } }
+            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 };
+        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) };
@@ -69,28 +83,66 @@ function runCommand(command, root, json) {
     }
     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 { status, exitCode: EXIT_CODES[status], failures };
+        return { check, outcome: { status, exitCode: EXIT_CODES[status] }, failures };
     }
     catch (error) {
-        const finding = error instanceof CannotRun
-            ? error.finding
-            : {
-                message: `stopped: ${error instanceof Error ? error.message : String(error)}`,
-                remedy: REMEDIES.checkStopped
-            };
-        return { status: "error", exitCode: EXIT_CODES.error, failures: [{ rule: check.name, ...finding }] };
+        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) {
+function runGate(root, json, updateBaseline) {
     const log = json ? process.stderr : process.stdout;
     const { config, problems } = resolveConfig(root);
     const gateCommand = config.gate.command ?? null;
@@ -128,13 +180,17 @@ function runGate(root, json) {
         log.write(`gate: check ${check.name}\n`);
         checks.push({ ...check, ...runOne(check.command, check.name, REMEDIES.checkNotRunnable) });
     }
-    for (const check of enabledChecks(config.gate.checks)) {
+    const judged = enabledChecks(config.gate.checks).map((check) => {
         if (stopped) {
-            checks.push({ name: check.name, command: null, ...SKIPPED });
-            continue;
+            return { check, outcome: SKIPPED, failures: [] };
         }
         log.write(`gate: check ${check.name}\n`);
-        const { failures: found, ...outcome } = runShipped(check, root);
+        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 });
     }
@@ -157,7 +213,7 @@ export function run(argv) {
         process.stdout.write(`${USAGE}\n`);
         return 0;
     }
-    const report = runGate(repositoryRoot(cli.root ?? process.cwd()), cli.json);
+    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) };

package/dist/commands/references-setup.js

@@ -1,18 +1,6 @@
-// `dw-sdlc references setup` sets a repository up to declare References. Five files, each written only
-// when it would change, so a repeat with nothing changed writes nothing:
-//
-//   references/AGENTS.md       the Router, from templates/router.md when there is none; on every run the
-//                              block between its two markers, a table of each Reference's dir and when
-//                              from the key, while the text around the block stays the author's
-//   references/CLAUDE.md       a symlink to AGENTS.md, so Claude Code loads the Router; written once
-//   .claude/settings.json      claudeMdExcludes for the clones' own CLAUDE.md and AGENTS.md
-//   .gitignore                 references/* and the two exceptions that keep the Router tracked
-//   .ai/agentic.config.json    an empty references key when the config has none
-//
-// Existing content stays: a list gains the entries it lacks at its end, and nothing is removed or
-// reordered. A settings file or a config that is not a JSON object is refused, not rewritten, and so
-// is an ignore file that ignores references/ itself and a Router with one marker and not the other,
-// or whose key fails the parser. --check writes nothing and exits 1 when any file would change.
+// `dw-sdlc references setup` sets a repository up to declare References: the five files its USAGE names,
+// each written only when it would change. Existing content stays: a list gains the entries it lacks at
+// its end, nothing is removed or reordered, and a file the step cannot read as it expects is refused.
 import { spawnSync } from "node:child_process";
 import { existsSync, lstatSync, mkdirSync, readFileSync, symlinkSync, writeFileSync } from "node:fs";
 import { dirname, join } from "node:path";
@@ -20,6 +8,7 @@ import { parseArgs } from "node:util";
 import { CONFIG, isObject, 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. */
 const ROUTER_LINK = "references/CLAUDE.md";
 const SETTINGS = ".claude/settings.json";
 const IGNORE = ".gitignore";
@@ -36,7 +25,7 @@ const IGNORED = "references/*";
 const TRACKED = ["!references/AGENTS.md", "!references/CLAUDE.md"];
 /** Lines that ignore references/ itself: git never looks inside it, so no exception tracks the Router. */
 const WHOLE = new Set(["references", "references/", "/references", "/references/"]);
-const IGNORE_COMMENT = "# References are cloned on each machine by the references plugin; only the Router is tracked.";
+const IGNORE_COMMENT = "# References are cloned on each machine by the sdlc plugin; only the Router is tracked.";
 export const summary = "set a repository up to declare References: the Router, its table and the ignore rules";
 const USAGE = `Usage: dw-sdlc references setup [--root <dir>] [--dry-run | --check]
   or:  pnpm references:setup with the same flags, in a checkout of dw-sdlc

package/dist/commands/references-sync.js

@@ -1,12 +1,6 @@
-// `dw-sdlc references sync`, the Sync: brings every Reference the `references` key of
-// .ai/agentic.config.json declares to its ref under references/<dir> — a missing one cloned, an
-// existing one moved to a branch's head or to a tag.
-// Each clone is shallow and blobless, detached at what was fetched, and sparse when its entry names
-// only some paths or skips some. Only the committed config is read. A key the parser refuses syncs
-// nothing; an entry that fails to resolve fails alone. One Sync runs in a checkout at a time: a
-// second one waits on the lock under references/. When the Router or its table is missing or behind
-// the key, one line names the setup to run. A repository that declares no References gets no output
-// at all.
+// `dw-sdlc references sync`, the Sync: every Reference the committed config declares brought to its ref
+// under references/<dir>, each clone shallow, blobless, detached and sparse where its entry says. An
+// entry that fails fails alone, and a repository that declares no References gets no output at all.
 import { spawnSync } from "node:child_process";
 import { existsSync, linkSync, mkdirSync, readdirSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
 import { extname, join } from "node:path";

package/dist/commands/setup.d.ts

@@ -21,10 +21,9 @@ export type SetupOptions = {
 };
 export declare const summary = "write this machine's local config layer, the git excludes and the permission rules";
 /**
- * What the machine's layer points `$schema` at: the schema in the marketplace's clone as a `file://`
- * URL, since the `$id` sits in a private repository an editor cannot fetch. The clone keeps its path
- * across plugin updates, where the install cache moves with every version. No registered clone
- * holding the schema falls back to the `$id`.
+ * 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
+ * its path across plugin updates. Without a registered clone holding the schema, the `$id`.
  */
 export declare function schemaReference(claudeDir: string): string;
 export declare function setup(options: SetupOptions): Step[];

package/dist/commands/setup.js

@@ -1,28 +1,6 @@
-// `dw-sdlc setup` sets a repository and this machine up for the guardrails plugin. Four files, each
-// written only when its content would change, so a repeat with nothing changed is silent and a run is
-// safe to repeat:
-//
-//   .ai/agentic.config.local.json   the machine's layer, from inference: the Node package manager when
-//                                   the committed config leaves it unset, $schema at the marketplace
-//                                   clone's schema, commit.convention when --convention names one
-//                                   or the file already pins one, and the guardrails block the file
-//                                   holds, as it is. Refused when one exists with other content than
-//                                   those, unless --force.
-//   .git/info/exclude               keeps that file and .claude/settings.local.json out of git without
-//                                   touching the repository's tracked .gitignore
-//   .claude/settings.local.json     permissions.deny as the jq-less backstop for the hooks: the
-//                                   destructive git and gh sets in plain and rtk form, and Read/Edit
-//                                   rules for every env file the resolved guardrails.envFiles refuses:
-//                                   listed in deny, or ignored by git and not listed in allow
-//   ~/.claude/settings.json         autoMode.allow plus the lease-push exception ("$defaults" opens a
-//                                   list this run creates), and permissions.deny with the irreversible set;
-//                                   under $CLAUDE_CONFIG_DIR when it is set, as Claude Code reads it
-//
-// Existing content is merged, never replaced: lists grow by the entries they lack, the repository's
-// deny list loses the rules RETIRED_DENY names, other keys stay. A settings file that is not JSON is
-// refused, not rewritten. From a linked worktree all three repository files go to the main checkout:
-// every worktree reads the local config from there when it has none of its own, and Claude Code reads
-// the local settings there. The only thing run in the repository is read-only git.
+// `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.
 import { spawnSync } from "node:child_process";
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
@@ -57,12 +35,13 @@ function isCommitOnProtected(value) {
 }
 /** Where Claude Code registers the plugin: the marketplace name and the plugin's name inside it. */
 const MARKETPLACE = "dw-sdlc";
-const PLUGIN = "guardrails";
+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);
 }
+/** 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" });
     return result.status === 0 ? result.stdout.trim() : undefined;
@@ -77,10 +56,9 @@ function committedConfig(root) {
     return "value" in result ? result.value : {};
 }
 /**
- * What the machine's layer points `$schema` at: the schema in the marketplace's clone as a `file://`
- * URL, since the `$id` sits in a private repository an editor cannot fetch. The clone keeps its path
- * across plugin updates, where the install cache moves with every version. No registered clone
- * holding the schema falls back to the `$id`.
+ * 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
+ * its path across plugin updates. Without a registered clone holding the schema, the `$id`.
  */
 export function schemaReference(claudeDir) {
     const registry = readJson(join(claudeDir, "plugins", "known_marketplaces.json"));
@@ -157,12 +135,8 @@ function sameContent(existing, config) {
     return isObject(existing) && render(unowned(existing)) === render(unowned(config));
 }
 /**
- * The machine's layer: what inference finds, minus every key the committed config already sets, plus
- * the `guardrails` block the file already holds. The local layer outranks the committed one, so an
- * inferred key written here would override it. The commit convention is written only when one is
- * asked for, by `--convention` or by the pin the file already holds: inference always gives the
- * `conventional` default, and pinning it here overrides a convention the repository commits later,
- * so that is a choice, never a guess.
+ * The machine's layer: what inference finds, minus every key the committed config already sets, which an
+ * inferred key here would override, plus the `guardrails` block the file holds and the convention asked for.
  */
 function localConfig(root, claudeDir, convention, guardrails) {
     const inferred = inferConfig(root);
@@ -178,11 +152,14 @@ function localConfig(root, claudeDir, convention, guardrails) {
     if (guardrails !== undefined) {
         config.guardrails = guardrails;
     }
+    // Only one asked for, by `--convention` or the file's pin: inference always gives `conventional`, and
+    // pinning it here would override a convention the repository commits later.
     if (convention !== undefined) {
         config.commit = { convention };
     }
     return config;
 }
+/** `existing` with the entries of `additions` it lacks appended: a list grows and never loses one. */
 function union(existing, additions) {
     const list = Array.isArray(existing) ? existing.filter((item) => typeof item === "string") : [];
     for (const rule of additions) {
@@ -234,7 +211,10 @@ class Writer {
         this.steps.push({ file: label, outcome: "refused", detail });
     }
 }
-/** Where the repository's files live: the main checkout for a linked worktree. */
+/**
+ * Where the repository's files live: the main checkout for a linked worktree, since every worktree reads
+ * the local config from there when it has none of its own, and Claude Code reads the local settings there.
+ */
 function mainCheckout(root) {
     const common = git(root, ["rev-parse", "--path-format=absolute", "--git-common-dir"]);
     if (common === undefined) {
@@ -266,7 +246,8 @@ export function setup(options) {
             writer.put(LOCAL_FILE, localPath, render(local));
         }
     }
-    // 2. The exclude entries, appended to whatever the file holds.
+    // 2. The exclude entries, appended to whatever the file holds: they keep both local files out of git
+    // without touching the repository's tracked .gitignore.
     const excludePath = join(gitDir, "info", "exclude");
     const excludeText = existsSync(excludePath) ? readFileSync(excludePath, "utf8") : "";
     const lines = excludeText.split("\n");
@@ -279,7 +260,8 @@ export function setup(options) {
         const separator = excludeText === "" || excludeText.endsWith("\n") ? "" : "\n";
         writer.put(excludeLabel, excludePath, excludeText + separator + missing.join("\n") + "\n");
     }
-    // 3. The repository's deny rules, merged into the main checkout's local settings.
+    // 3. The repository's deny rules, the backstop for the hooks where jq is missing, merged into the main
+    // checkout's local settings.
     const localSettingsPath = join(checkout, ".claude", "settings.local.json");
     const localSettings = readJson(localSettingsPath);
     if (localSettings === "invalid") {
@@ -292,7 +274,8 @@ export function setup(options) {
         settings.permissions = { ...permissions, deny };
         writer.put(".claude/settings.local.json", localSettingsPath, render(settings));
     }
-    // 4. The user file: the lease exception, "$defaults" kept, and the irreversible non-git set.
+    // 4. The user file, under $CLAUDE_CONFIG_DIR when it is set: the lease exception, "$defaults" kept, and
+    // the irreversible non-git set.
     const userPath = join(claudeDir, "settings.json");
     const userLabel = options.claudeDir === undefined ? "~/.claude/settings.json" : userPath;
     const userSettings = readJson(userPath);

package/dist/json-schema.js

@@ -1,10 +1,6 @@
 // The subset of JSON Schema draft 2020-12 the shipped schemas use, validated without a dependency: Node
 // has no validator built in, and a config file does not justify pulling one in. A keyword outside the
 // subset throws instead of passing silently, so a schema never promises more than this file enforces.
-// `format` is enforced, not annotative: `regex` is the one format, compiled with `RegExp` and refused
-// when it holds a construct POSIX ERE lacks, because `grep -E` runs the pattern and BSD and GNU grep
-// read those differently. `enum` and `const` compare by JSON text, exact for the scalars and arrays
-// the schemas use.
 export class SchemaError extends Error {
 }
 const ANNOTATIONS = new Set(["$schema", "$id", "$comment", "title", "description", "default", "examples"]);
@@ -14,6 +10,7 @@ function isObject(value) {
 function show(value) {
     return value === undefined ? "undefined" : JSON.stringify(value);
 }
+/** Equal by JSON text, as `enum` and `const` compare: exact for the scalars and arrays the schemas use. */
 function sameJson(a, b) {
     return JSON.stringify(a) === JSON.stringify(b);
 }
@@ -194,6 +191,8 @@ function checkKeyword(schema, keyword, operand, value, path, problems) {
             }
             return;
         }
+        // Enforced, not annotative: `regex` compiles with `RegExp` and refuses a construct POSIX ERE lacks,
+        // because `grep -E` runs the pattern and BSD and GNU grep read those differently.
         case "format": {
             operandMust(operand === "regex", path, keyword, '"regex", the one format enforced here');
             if (typeof value !== "string") {

package/dist/markdown.d.ts

@@ -8,6 +8,10 @@ export type Row = {
     cells: string[];
     line: number;
 };
+export type Link = {
+    target: string;
+    line: number;
+};
 /** Every ATX heading in `text`, a repeated anchor numbered `-1`, `-2` as GitHub numbers it. */
 export declare function headings(text: string): Heading[];
 /**
@@ -17,3 +21,11 @@ export declare function headings(text: string): Heading[];
 export declare function tableRows(text: string, title: string): Row[];
 /** Every backticked span in `text`, without its backticks. */
 export declare function codeSpans(text: string): string[];
+/** `text` with each fenced line and each code span blanked to spaces, so every offset and line is kept. */
+export declare function prose(text: string): string;
+/** Every link target in the prose of `text`, its angle brackets dropped, with its 1-based line. */
+export declare function links(text: string): Link[];
+/** The anchors of each markdown file read so far, by path. */
+export type Anchors = Map<string, Set<string>>;
+/** The anchors of the headings of `path` under `root`; none when it is not a file. */
+export declare function anchorsOf(root: string, path: string, cache: Anchors): Set<string>;

package/dist/markdown.js

@@ -1,6 +1,10 @@
 // The parts of a markdown file the Checks read: its ATX headings with the anchors GitHub gives them,
-// and the rows of a table under a heading. A line inside a fenced code block is never either.
-const FENCE = /^ {0,3}(`{3,}|~{3,})/;
+// the rows of a table under a heading, its links, and its prose with the code masked; and the anchors
+// of a file on disk. A line inside a fenced code block is never any of them.
+import { readFileSync, statSync } from "node:fs";
+import { join } from "node:path";
+/** A code fence at any indent, so one inside a list item counts. */
+const FENCE = /^[ \t]*(`{3,}|~{3,})/;
 const ATX = /^ {0,3}(#{1,6})[ \t]+(.*?)(?:[ \t]+#+)?[ \t]*$/;
 /** Each line with its 1-based number, `fenced` when a code fence opens, closes or encloses it. */
 function scan(text) {
@@ -75,3 +79,37 @@ export function tableRows(text, title) {
 export function codeSpans(text) {
     return Array.from(text.matchAll(/`([^`]+)`/g), ([, span = ""]) => span);
 }
+/** A code span: a run of backticks, then the text up to the next run of as many. */
+const CODE_SPAN = /(?<!`)(`+)(?!`).*?(?<!`)\1(?!`)/g;
+/** `text` with each fenced line and each code span blanked to spaces, so every offset and line is kept. */
+export function prose(text) {
+    return scan(text)
+        .map(({ text: line, fenced }) => fenced ? " ".repeat(line.length) : line.replace(CODE_SPAN, (span) => " ".repeat(span.length)))
+        .join("\n");
+}
+/** The target of an inline link or image, `<…>` or up to a space or `)`, and of a link definition, `[label]: target`. */
+const INLINE_TARGET = /\]\(\s*(<[^>]*>|[^\s)]+)/g;
+const DEFINITION = /^ {0,3}\[(?!\^)[^\]]+\]:[ \t]*(<[^>]*>|\S+)/;
+/** Every link target in the prose of `text`, its angle brackets dropped, with its 1-based line. */
+export function links(text) {
+    return prose(text)
+        .split("\n")
+        .flatMap((line, index) => {
+        const definition = DEFINITION.exec(line)?.[1];
+        const targets = [
+            ...Array.from(line.matchAll(INLINE_TARGET), ([, target = ""]) => target),
+            ...(definition === undefined ? [] : [definition])
+        ];
+        return targets.map((target) => ({ target: target.replace(/^<(.*)>$/, "$1"), line: index + 1 }));
+    });
+}
+/** The anchors of the headings of `path` under `root`; none when it is not a file. */
+export 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;
+}

package/dist/pins.d.ts

@@ -1,5 +1,7 @@
 /** Versions by package name: what package.json pins, or what a catalog lists. */
 export type Pins = Record<string, string>;
+/** A pin that names one version: `x.y.z`, a pre-release tag allowed. */
+export declare const EXACT_VERSION: RegExp;
 /**
  * The default catalog in pnpm-workspace.yaml's text: each `name: version` line of its top-level
  * `catalog:` block, a comment after the key allowed. Without the block, it is empty.

package/dist/pins.js

@@ -1,10 +1,10 @@
 // The exact version a repository pins for a package, for a ref that names one: the root package.json's
-// dependencies and devDependencies, a `catalog:` or `catalog:default` pin read through the default
-// catalog in pnpm-workspace.yaml. A ref without `{name}` reads neither file, so a broken manifest
-// fails only the References that name a package.
+// dependencies and devDependencies, a catalog pin read through pnpm-workspace.yaml's default catalog. A
+// ref without `{name}` reads neither file, so a broken manifest fails only the References that name one.
 import { existsSync, readFileSync } from "node:fs";
 import { join } from "node:path";
-const EXACT_VERSION = /^\d+\.\d+\.\d+(?:-[\w.]+)?$/;
+/** A pin that names one version: `x.y.z`, a pre-release tag allowed. */
+export const EXACT_VERSION = /^\d+\.\d+\.\d+(?:-[\w.]+)?$/;
 /** The two ways a pin names the default catalog: by its name, or by pnpm's shorthand. */
 const DEFAULT_CATALOG = new Set(["catalog:", "catalog:default"]);
 /**

package/dist/references-key.js

@@ -1,7 +1,6 @@
 // The strict parser of the `references` key, the authority at runtime, and the reader of the committed
 // config that holds it. `config/references.schema.json` documents the same contract, and
-// `test/references-key.test.ts` runs one case list through both. The first problem stops the
-// parse: a key that fails it syncs nothing.
+// `test/references-key.test.ts` runs one case list through both. The first problem stops the parse.
 import { existsSync, readFileSync } from "node:fs";
 import { join } from "node:path";
 /** The committed config, the only file the key is read from. */