dw-sdlc 0.20.0 → 0.21.1

package/README.md

@@ -65,19 +65,19 @@ line; a `gate.checks.run` entry takes a `hint` beside `name` and `command`.
 Under `gate.checks`, a Check is `true` for its defaults, an object of its options, or `false`. The
 schema's description of each one names its options and defaults.
 
-| Check                | fails                                                                       | reads first               |
-| -------------------- | --------------------------------------------------------------------------- | ------------------------- |
-| `markdown-refs`      | a relative link or image whose path or heading anchor does not resolve      | nothing                   |
-| `temporal-language`  | a changelog phrase in a durable document, outside code                      | nothing                   |
-| `comment-budget`     | a comment block over 3 lines of prose in JS, TS or shell                    | nothing                   |
-| `disable-directives` | a linter or type-checker disable comment with no reason                     | nothing                   |
-| `agents-map`         | an `AGENTS.md` over budget, missing the Gate command or pointing at nothing | `AGENTS.md`               |
-| `primitives`         | a catalogue entry out of step with the tree, or a file no entry owns        | `.ai/primitives.json`     |
-| `routed-docs`        | a document under `docs/` no Task Router row or Primitive leads to           | the map, the catalogue    |
-| `markdown-budget`    | a markdown file over the byte budget of its glob                            | the files its globs match |
-| `decision-records`   | a decision record misnamed, misnumbered or without a valid status           | a records directory       |
-| `file-size-ratchet`  | a code file over its line limit that the baseline does not allow            | its baseline              |
-| `skill-sections`     | a README section a skill copies that differs from its source                | the catalogue             |
+| Check                | fails                                                                          | reads first               |
+| -------------------- | ------------------------------------------------------------------------------ | ------------------------- |
+| `markdown-refs`      | a relative link, image or repository URL whose path or anchor does not resolve | nothing                   |
+| `temporal-language`  | a changelog phrase in a durable document, outside code                         | nothing                   |
+| `comment-budget`     | a comment block over 3 lines of prose in JS, TS or shell                       | nothing                   |
+| `disable-directives` | a linter or type-checker disable comment with no reason                        | nothing                   |
+| `agents-map`         | an `AGENTS.md` over budget, missing the Gate command or pointing at nothing    | `AGENTS.md`               |
+| `primitives`         | a catalogue entry out of step with the tree, or a file no entry owns           | `.ai/primitives.json`     |
+| `routed-docs`        | a document under `docs/` no Task Router row or Primitive leads to              | the map, the catalogue    |
+| `markdown-budget`    | a markdown file over the byte budget of its glob                               | the files its globs match |
+| `decision-records`   | a decision record misnamed, misnumbered or without a valid status              | a records directory       |
+| `file-size-ratchet`  | a code file over its line limit that the baseline does not allow               | its baseline              |
+| `skill-sections`     | a README section a skill copies that differs from its source                   | the catalogue             |
 
 Each Check's options and defaults:
 [its description in the schema](https://github.com/dominikwozniak/dw-sdlc/blob/main/packages/dw-sdlc/config/agentic.config.schema.json).

package/config/agentic.config.schema.json

@@ -264,7 +264,7 @@
               "additionalProperties": false
             },
             "markdown-refs": {
-              "description": "Every relative link and image in the markdown files resolves: its path to a file or directory git tracks or would track, its heading anchor to a heading of the markdown file it names, and `#anchor` alone to a heading of its own file. A link with a scheme, such as `https:`, and a link inside code are not judged.",
+              "description": "Every relative link and image in the markdown files resolves: its path to a file or directory git tracks or would track, its heading anchor to a heading of the markdown file it names, and `#anchor` alone to a heading of its own file. A URL into the GitHub repository `origin` names, at its default branch (the one `origin/HEAD` names, else `main`), as a `blob`, `tree` or raw file URL, resolves the same way, inside code too. Any other link with a scheme, such as `https:`, and a relative link inside code are not judged.",
               "type": ["boolean", "object"],
               "properties": {
                 "files": {

package/dist/agentic-config.d.ts

@@ -8,6 +8,7 @@ export type CommitConvention = (typeof COMMIT_CONVENTIONS)[number];
 export type NodePackageManager = "pnpm" | "npm" | "yarn" | "bun";
 export type ForcePush = "deny" | "ask" | "lease";
 export type CommitOnProtected = "deny" | "allow";
+export type FilteredOutput = "deny" | "allow";
 export type EnvPolicy = "deny" | "git";
 /** Which env files may be read: `deny` list, then `allow` list, then `policy` for the rest. */
 export type EnvFiles = {
@@ -47,6 +48,7 @@ export type WorkerConfig = {
 export type Guardrails = {
     forcePush: ForcePush;
     commitOnProtected: CommitOnProtected;
+    filteredOutput: FilteredOutput;
     envFiles: EnvFiles;
     protectedBranches: string[];
 };
@@ -159,6 +161,7 @@ export type Resolution = {
 export declare const STRICTNESS: {
     readonly forcePush: readonly ["deny", "ask", "lease"];
     readonly commitOnProtected: readonly ["deny", "allow"];
+    readonly filteredOutput: readonly ["deny", "allow"];
     readonly envFiles: readonly ["deny", "git"];
     readonly merge: readonly ["ask", "auto"];
     readonly review: readonly ["full", "auto", "light", "off"];
@@ -206,8 +209,21 @@ export declare function mainCheckout(root: string): string | undefined;
  * one, and `resolveConfig` fills `commit.pattern` from it when no layer sets a pattern.
  */
 export declare function inferConfig(root: string): ResolvedConfig;
+type CommitRules = {
+    commit: {
+        convention?: string;
+        pattern?: string;
+        trailer?: string;
+    };
+};
+/**
+ * What a report says is in force while a layer is invalid: the strictest guardrails, and no commit
+ * rule where no valid layer sets a convention, pattern or trailer, since the inferred layer names none.
+ */
+export declare function invalidLayerEffect({ commit }: CommitRules): string;
 /**
  * Local over committed over inferred, for the repository at `root`. A linked worktree reads a layer it
  * lacks from its main checkout, where a repository that keeps `.ai/` out of git has the only copy.
  */
 export declare function resolveConfig(root: string): Resolution;
+export {};

package/dist/agentic-config.js

@@ -3,7 +3,8 @@
 // `hooks/config.jq` is the same merge for the guards; this file is the reference, and the tests run both.
 import { existsSync, readFileSync } from "node:fs";
 import { dirname, join } from "node:path";
-import { exec } from "./exec.js";
+import { messageOf } from "./cannot-run.js";
+import { asked, gitDirs } from "./git.js";
 import { validate } from "./json-schema.js";
 export const COMMITTED_FILE = ".ai/agentic.config.json";
 export const LOCAL_FILE = ".ai/agentic.config.local.json";
@@ -27,6 +28,7 @@ export function stepHint(step) {
 export const STRICTNESS = {
     forcePush: ["deny", "ask", "lease"],
     commitOnProtected: ["deny", "allow"],
+    filteredOutput: ["deny", "allow"],
     envFiles: ["deny", "git"],
     merge: ["ask", "auto"],
     review: ["full", "auto", "light", "off"]
@@ -35,6 +37,7 @@ export const STRICTNESS = {
 export const STRICTEST_GUARDRAILS = {
     forcePush: "deny",
     commitOnProtected: "deny",
+    filteredOutput: "deny",
     envFiles: { policy: "deny", allow: [], deny: [] },
     protectedBranches: ["master", "main", "production"]
 };
@@ -53,6 +56,7 @@ const DEFAULT_WORKER = { command: "claude", model: "sonnet", effort: "high" };
 export const DEFAULT_GUARDRAILS = {
     forcePush: "lease",
     commitOnProtected: "allow",
+    filteredOutput: "deny",
     envFiles: { policy: "git", allow: ["**/.env.example", "**/.env.sample", "**/.env.template"], deny: [] },
     protectedBranches: ["master", "main", "production"]
 };
@@ -60,6 +64,7 @@ function cloneGuardrails(source) {
     return {
         forcePush: source.forcePush,
         commitOnProtected: source.commitOnProtected,
+        filteredOutput: source.filteredOutput,
         envFiles: { policy: source.envFiles.policy, allow: [...source.envFiles.allow], deny: [...source.envFiles.deny] },
         protectedBranches: [...source.protectedBranches]
     };
@@ -99,9 +104,6 @@ const NODE_LOCKFILES = [
     ["bun.lock", "bun"],
     ["bun.lockb", "bun"]
 ];
-function messageOf(error) {
-    return error instanceof Error ? error.message : String(error);
-}
 function show(value) {
     return JSON.stringify(value);
 }
@@ -151,8 +153,7 @@ function readLayer(checkouts, file) {
 }
 /** The top level of the repository holding `dir`, or undefined outside one. */
 export function findRepository(dir) {
-    const toplevel = exec("git", ["-C", dir, "rev-parse", "--show-toplevel"]);
-    return toplevel.status === 0 ? toplevel.stdout.trim() : undefined;
+    return asked(dir, ["rev-parse", "--show-toplevel"]);
 }
 /** The top level of the repository holding `dir`, or `dir` itself outside one. */
 export function repositoryRoot(dir) {
@@ -163,13 +164,8 @@ export function repositoryRoot(dir) {
  * repository: a linked worktree's git dir differs from the common one, which sits in the main checkout.
  */
 export function mainCheckout(root) {
-    const args = ["-C", root, "rev-parse", "--path-format=absolute", "--git-dir", "--git-common-dir"];
-    const result = exec("git", args);
-    if (result.status !== 0) {
-        return undefined;
-    }
-    const [gitDir, commonDir] = result.stdout.trim().split("\n");
-    return gitDir === undefined || commonDir === undefined || gitDir === commonDir ? undefined : dirname(commonDir);
+    const dirs = gitDirs(root);
+    return dirs === undefined || dirs.gitDir === dirs.commonDir ? undefined : dirname(dirs.commonDir);
 }
 function inferPackageManagers(root) {
     const managers = {};
@@ -245,24 +241,24 @@ function rank(key, value) {
     return order.indexOf(value);
 }
 const LOOSENS = "the local file may tighten guardrails, never loosen them";
+/** The guardrails that hold one value, each ranked under its own name in `STRICTNESS`. */
+const RANKED_GUARDRAILS = ["forcePush", "commitOnProtected", "filteredOutput"];
 /**
  * Every guardrail the local layer sets less strictly than what it would override: a lower-ranked
- * `forcePush`, `commitOnProtected` or `envFiles.policy`, an added `envFiles.allow` entry, a dropped
- * `envFiles.deny` entry, a dropped protected branch.
+ * `forcePush`, `commitOnProtected`, `filteredOutput` or `envFiles.policy`, an added `envFiles.allow`
+ * entry, a dropped `envFiles.deny` entry, a dropped protected branch.
  */
 function loosenings(base, local) {
     if (local === undefined) {
         return [];
     }
     const problems = [];
-    if (local.forcePush !== undefined && rank("forcePush", local.forcePush) > rank("forcePush", base.forcePush)) {
-        const message = `${show(local.forcePush)} loosens ${show(base.forcePush)}; ${LOOSENS}`;
-        problems.push({ file: LOCAL_FILE, path: "guardrails.forcePush", message });
-    }
-    if (local.commitOnProtected !== undefined &&
-        rank("commitOnProtected", local.commitOnProtected) > rank("commitOnProtected", base.commitOnProtected)) {
-        const message = `${show(local.commitOnProtected)} loosens ${show(base.commitOnProtected)}; ${LOOSENS}`;
-        problems.push({ file: LOCAL_FILE, path: "guardrails.commitOnProtected", message });
+    for (const key of RANKED_GUARDRAILS) {
+        const value = local[key];
+        if (value !== undefined && rank(key, value) > rank(key, base[key])) {
+            const message = `${show(value)} loosens ${show(base[key])}; ${LOOSENS}`;
+            problems.push({ file: LOCAL_FILE, path: `guardrails.${key}`, message });
+        }
     }
     const policy = local.envFiles?.policy;
     if (policy !== undefined && rank("envFiles", policy) > rank("envFiles", base.envFiles.policy)) {
@@ -318,6 +314,15 @@ function finalize(merged) {
     }
     return { ...merged, commit: { ...merged.commit, pattern: COMMIT_PATTERNS[convention] } };
 }
+/**
+ * What a report says is in force while a layer is invalid: the strictest guardrails, and no commit
+ * rule where no valid layer sets a convention, pattern or trailer, since the inferred layer names none.
+ */
+export function invalidLayerEffect({ commit }) {
+    const strictest = "the guards run on the strictest defaults";
+    const unchecked = commit.convention === undefined && commit.pattern === undefined && commit.trailer === undefined;
+    return unchecked ? `${strictest} and the commit rules are off` : strictest;
+}
 /**
  * Local over committed over inferred, for the repository at `root`. A linked worktree reads a layer it
  * lacks from its main checkout, where a repository that keeps `.ai/` out of git has the only copy.

package/dist/cannot-run.d.ts

@@ -0,0 +1,27 @@
+import { parseArgs, type ParseArgsConfig } from "node:util";
+/** Where the problem sits, and what the bin prints below its line. */
+export type Detail = {
+    /** The file, and its line, of an input a Check reads. */
+    file?: string;
+    line?: number;
+    /** Lines the bin prints below the problem's, as a command's usage. */
+    after?: string;
+};
+export declare class CannotRun extends Error {
+    readonly remedy: string | undefined;
+    readonly detail: Detail;
+    constructor(message: string, remedy?: string, detail?: Detail);
+    /** The same problem, with `remedy` where it names none. */
+    orRemedy(remedy: string): CannotRun;
+}
+/** What an error says, whatever was thrown. */
+export declare function messageOf(error: unknown): string;
+/** A command line the command cannot read: the problem, then its usage after an empty line. */
+export declare function usageError(problem: string, usage: string): CannotRun;
+/** `parseArgs` over a command line; one it cannot read stops the command with its usage. */
+export declare function readArgs<T extends ParseArgsConfig>(config: T, usage: string): ReturnType<typeof parseArgs<T>>;
+/**
+ * The directory `--root` names, or the current one without it. A `--root` that names no directory
+ * stops the command, which would otherwise read the empty repository a typo leaves.
+ */
+export declare function rootDir(root: string | undefined): string;

package/dist/cannot-run.js

@@ -0,0 +1,48 @@
+// What stops a command before it reaches a verdict: exit 2, one problem and, where there is one, its
+// remedy. The bin alone prints it, as `dw-sdlc <command>: <problem> — <remedy>`; the Gate reports a
+// Check's as one of its failures. A command line the command cannot read carries its usage below.
+import { statSync } from "node:fs";
+import { parseArgs } from "node:util";
+export class CannotRun extends Error {
+    remedy;
+    detail;
+    constructor(message, remedy, detail = {}) {
+        super(message);
+        this.remedy = remedy;
+        this.detail = detail;
+    }
+    /** The same problem, with `remedy` where it names none. */
+    orRemedy(remedy) {
+        return this.remedy === undefined ? new CannotRun(this.message, remedy, this.detail) : this;
+    }
+}
+/** What an error says, whatever was thrown. */
+export function messageOf(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+/** A command line the command cannot read: the problem, then its usage after an empty line. */
+export function usageError(problem, usage) {
+    return new CannotRun(problem, undefined, { after: `\n${usage}` });
+}
+/** `parseArgs` over a command line; one it cannot read stops the command with its usage. */
+export function readArgs(config, usage) {
+    try {
+        return parseArgs(config);
+    }
+    catch (error) {
+        throw usageError(messageOf(error), usage);
+    }
+}
+/**
+ * The directory `--root` names, or the current one without it. A `--root` that names no directory
+ * stops the command, which would otherwise read the empty repository a typo leaves.
+ */
+export function rootDir(root) {
+    if (root === undefined) {
+        return process.cwd();
+    }
+    if (statSync(root, { throwIfNoEntry: false })?.isDirectory() !== true) {
+        throw new CannotRun(`--root ${root} is not a directory`, "pass --root a directory inside the repository");
+    }
+    return root;
+}

package/dist/catalogue.js

@@ -3,6 +3,7 @@
 // says and `dw-sdlc primitives --paths` answers from it.
 import { existsSync, readFileSync } from "node:fs";
 import { join } from "node:path";
+import { messageOf } from "./cannot-run.js";
 import { validate } from "./json-schema.js";
 /** Where a repository keeps its catalogue unless its config says otherwise. */
 export const CATALOGUE_FILE = ".ai/primitives.json";
@@ -41,7 +42,7 @@ export function parseCatalogue(text) {
         parsed = JSON.parse(text);
     }
     catch (error) {
-        return { state: "invalid", problems: [`not JSON: ${error instanceof Error ? error.message : String(error)}`] };
+        return { state: "invalid", problems: [`not JSON: ${messageOf(error)}`] };
     }
     const problems = validate(SCHEMA, parsed).map(({ path: at, message }) => (at === "" ? message : `${at}: ${message}`));
     if (problems.length > 0) {

package/dist/checks/agents-map.js

@@ -3,9 +3,9 @@
 // Claude Code reads it, and the skills directory, its lock and its links in step.
 import { existsSync, globSync, lstatSync, readdirSync, readFileSync, readlinkSync, realpathSync, statSync } from "node:fs";
 import { join, normalize } from "node:path";
-import { resolveConfig } from "../agentic-config.js";
+import { CannotRun, messageOf } from "../cannot-run.js";
 import { codeSpans, tableRows } from "../markdown.js";
-import { CannotRun, optionsOf } from "./check.js";
+import { optionsOf } from "./check.js";
 import { overBudget } from "./markdown-budget.js";
 import { catalogueFile } from "./primitives.js";
 const ROUTER = "Task Router";
@@ -45,9 +45,8 @@ export function routes(text) {
     }));
 }
 /** The budget, the Gate command, the row to the catalogue and every path the Task Router points at. */
-function judgeMap(root, { file, ...budget }, text) {
+function judgeMap(root, { file, ...budget }, text, gate) {
     const findings = overBudget(text, budget).map((message) => ({ file, message, remedy: REMEDIES.budget }));
-    const { gate } = resolveConfig(root).config;
     if (gate.command === undefined) {
         findings.push({ message: "the Gate has no command for the map to name", remedy: REMEDIES.noCommand });
     }
@@ -110,7 +109,7 @@ function lockedSkills(root) {
         lock = JSON.parse(readFileSync(join(root, LOCK), "utf8"));
     }
     catch (error) {
-        return { problem: `not JSON: ${error instanceof Error ? error.message : String(error)}` };
+        return { problem: `not JSON: ${messageOf(error)}` };
     }
     if (typeof lock !== "object" || lock === null || !("skills" in lock)) {
         return { problem: "it has no skills object" };
@@ -180,13 +179,13 @@ function linksTo(link, target) {
 export function readMap(root, file) {
     const path = join(root, file);
     if (!existsSync(path)) {
-        throw new CannotRun({ file, message: "the map does not exist", remedy: REMEDIES.missing });
+        throw new CannotRun("the map does not exist", REMEDIES.missing, { file });
     }
     return readFileSync(path, "utf8");
 }
-function run(root, options) {
+function run(root, options, gate) {
     return [
-        ...judgeMap(root, options, readMap(root, options.file)),
+        ...judgeMap(root, options, readMap(root, options.file), gate),
         ...judgeLink(root, options.file),
         ...judgeSkills(root)
     ];

package/dist/checks/check.d.ts

@@ -1,11 +1,10 @@
+import type { Gate } from "../agentic-config.ts";
+import type { CannotRun } from "../cannot-run.ts";
 import type { Failure } from "../report.ts";
 /** A failure as a Check finds it: the file and line where it has one, what is wrong, the remedy. */
 export type Finding = Omit<Failure, "rule">;
-/** An input the Check needs is missing or unreadable, so the Gate cannot run: exit 2, not 1. */
-export declare class CannotRun extends Error {
-    finding: Finding;
-    constructor(finding: Finding);
-}
+/** What a Check reports when it cannot judge: the input it lacks, in the file it names, and the remedy. */
+export declare function findingOf({ message, remedy, detail }: CannotRun, fallback: string): Finding;
 /**
  * A Ratchet's committed baseline: its file, and its refresh from the tree, which writes it tighter or
  * records it where there is none, says what it did, and throws `CannotRun` when it cannot.
@@ -18,12 +17,15 @@ export type Check<Options extends object> = {
     /** The Check's key under `gate.checks`. */
     name: string;
     defaults: Options;
-    /** Every failure of the tree at `root`, none when it passes; throws `CannotRun` when it cannot judge. */
-    run: (root: string, options: Options) => Finding[];
+    /**
+     * Every failure of the tree at `root`, none when it passes; throws `CannotRun` when it cannot judge.
+     * `gate` is the resolved Gate it runs under, where it reads another Check's setting.
+     */
+    run: (root: string, options: Options, gate: Gate) => Finding[];
     /** Present on a Ratchet. */
     baseline?: Baseline<Options>;
     /** Present on a Check that derives files from their sources: writes them, says what it wrote. */
-    write?: (root: string, options: Options) => string;
+    write?: (root: string, options: Options, gate: Gate) => string;
 };
 /** The options `setting` turns the Check on with: the defaults under `true`, an object over them, else off. */
 export declare function optionsOf<Options extends object>(check: Check<Options>, setting: unknown): Options | undefined;

package/dist/checks/check.js

@@ -1,12 +1,14 @@
 // What every Check the package ships is: a name, the options `true` stands for, and a run over the
 // tree that answers with its failures. The Gate names the Check as each failure's rule.
-/** An input the Check needs is missing or unreadable, so the Gate cannot run: exit 2, not 1. */
-export class CannotRun extends Error {
-    finding;
-    constructor(finding) {
-        super(finding.message);
-        this.finding = finding;
-    }
+/** What a Check reports when it cannot judge: the input it lacks, in the file it names, and the remedy. */
+export function findingOf({ message, remedy, detail }, fallback) {
+    const { file, line } = detail;
+    return {
+        ...(file === undefined ? {} : { file }),
+        ...(line === undefined ? {} : { line }),
+        message,
+        remedy: remedy ?? fallback
+    };
 }
 /** The options `setting` turns the Check on with: the defaults under `true`, an object over them, else off. */
 export function optionsOf(check, setting) {

package/dist/checks/decision-records.js

@@ -3,8 +3,9 @@
 // a frontmatter status from the allowed set and the frontmatter fields the config turns on.
 import { existsSync, readFileSync, statSync } from "node:fs";
 import { join, matchesGlob, posix } from "node:path";
+import { CannotRun } from "../cannot-run.js";
 import { frontmatter, frontmatterList, headings } from "../markdown.js";
-import { CannotRun } from "./check.js";
+import {} from "./check.js";
 import { directoriesOf, treeFiles } from "./tree.js";
 /** The frontmatter fields beyond `status` a record can be held to, in the order they are judged. */
 const FIELDS = ["date", "touches", "superseded-by", "amended-by"];
@@ -201,7 +202,7 @@ function judge(root, dir, { statuses, fields }, tree) {
 function run(root, options) {
     const present = options.dirs.filter((dir) => isDirectory(join(root, dir)));
     if (present.length === 0) {
-        throw new CannotRun({ message: `none of ${options.dirs.join(", ")} exists`, remedy: REMEDIES.missing });
+        throw new CannotRun(`none of ${options.dirs.join(", ")} exists`, REMEDIES.missing);
     }
     let cached;
     const tree = () => {

package/dist/checks/file-size-ratchet.js

@@ -2,8 +2,9 @@
 // within the count recorded there. A refresh only tightens the baseline: it lowers and drops, and adds no file.
 import { existsSync, mkdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
 import { dirname, join, matchesGlob } from "node:path";
-import { exec } from "../exec.js";
-import { CannotRun } from "./check.js";
+import { CannotRun, messageOf } from "../cannot-run.js";
+import { asked } from "../git.js";
+import {} from "./check.js";
 import { matching, treeFiles } from "./tree.js";
 const BASELINE = ".ai/file-size-ratchet.baseline.json";
 const REFRESH = "dw-sdlc gate --update-baseline";
@@ -15,11 +16,11 @@ const REMEDIES = {
     unreadable: "fix the failures it names"
 };
 /** A committed baseline gone from the tree: recording a new one would let every grown file back in. */
-const DELETED = {
-    file: BASELINE,
-    message: "the baseline is committed but gone from the tree",
-    remedy: `restore it with git restore ${BASELINE}`
-};
+function deleted() {
+    return new CannotRun("the baseline is committed but gone from the tree", `restore it with git restore ${BASELINE}`, {
+        file: BASELINE
+    });
+}
 function show(value) {
     return JSON.stringify(value);
 }
@@ -58,7 +59,7 @@ function keyLines(text, path) {
 function readBaseline(root) {
     const path = join(root, BASELINE);
     if (!existsSync(path)) {
-        const committed = exec("git", ["-C", root, "cat-file", "-e", `HEAD:${BASELINE}`]).status === 0;
+        const committed = asked(root, ["cat-file", "-e", `HEAD:${BASELINE}`]) !== undefined;
         return { state: "missing", committed };
     }
     const text = readFileSync(path, "utf8");
@@ -67,7 +68,7 @@ function readBaseline(root) {
         parsed = JSON.parse(text);
     }
     catch (error) {
-        const message = `not JSON: ${error instanceof Error ? error.message : String(error)}`;
+        const message = `not JSON: ${messageOf(error)}`;
         return { state: "invalid", findings: [{ file: BASELINE, message, remedy: REMEDIES.shape }] };
     }
     if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
@@ -110,8 +111,7 @@ function contradictions(entries, groups) {
 function run(root, { groups }) {
     const read = readBaseline(root);
     if (read.state === "missing") {
-        const missing = { file: BASELINE, message: "the baseline does not exist", remedy: REMEDIES.record };
-        throw new CannotRun(read.committed ? DELETED : missing);
+        throw read.committed ? deleted() : new CannotRun("the baseline does not exist", REMEDIES.record, { file: BASELINE });
     }
     if (read.state === "invalid") {
         return read.findings;
@@ -142,14 +142,10 @@ function write(root, entries) {
 function refresh(root, { groups }) {
     const read = readBaseline(root);
     if (read.state === "invalid") {
-        throw new CannotRun({
-            file: BASELINE,
-            message: "it is not a baseline the Ratchet can read",
-            remedy: REMEDIES.unreadable
-        });
+        throw new CannotRun("it is not a baseline the Ratchet can read", REMEDIES.unreadable, { file: BASELINE });
     }
     if (read.state === "missing" && read.committed) {
-        throw new CannotRun(DELETED);
+        throw deleted();
     }
     const measured = measure(root, groups);
     if (read.state === "missing") {

package/dist/checks/index.d.ts

@@ -1,5 +1,6 @@
+import type { Gate } from "../agentic-config.ts";
 import { type Finding } from "./check.ts";
-/** A Check turned on by its setting, ready to judge a tree, and to refresh its baseline if it is a Ratchet. */
+/** A Check turned on by its setting in a Gate, ready to judge a tree, and to refresh its baseline if it is a Ratchet. */
 export type EnabledCheck = {
     name: string;
     run: (root: string) => Finding[];
@@ -11,7 +12,7 @@ export type EnabledCheck = {
 };
 /** 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;
+/** Every shipped Check the resolved `gate` turns on with `true` or its options under `gate.checks`. */
+export declare function enabledChecks(gate: Gate): EnabledCheck[];
+/** The shipped Check `name` on the setting `gate` gives it, or on its defaults where the setting leaves it off. */
+export declare function shippedCheck(name: string, gate: Gate): EnabledCheck | undefined;

package/dist/checks/index.js

@@ -15,19 +15,19 @@ import { temporalLanguage } from "./temporal-language.js";
 function ship(check) {
     return {
         name: check.name,
-        enable: (setting) => {
+        enable: (setting, gate) => {
             const options = optionsOf(check, setting);
             if (options === undefined) {
                 return undefined;
             }
-            const enabled = { name: check.name, run: (root) => check.run(root, options) };
+            const enabled = { name: check.name, run: (root) => check.run(root, options, gate) };
             const { baseline } = check;
             if (baseline !== undefined) {
                 enabled.baseline = { file: baseline.file, refresh: (root) => baseline.refresh(root, options) };
             }
             const { write } = check;
             if (write !== undefined) {
-                enabled.write = (root) => write(root, options);
+                enabled.write = (root) => write(root, options, gate);
             }
             return enabled;
         }
@@ -48,12 +48,13 @@ const SHIPPED = [
 ];
 /** 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]) ?? []);
+/** Every shipped Check the resolved `gate` turns on with `true` or its options under `gate.checks`. */
+export function enabledChecks(gate) {
+    return SHIPPED.flatMap(({ name, enable }) => enable(gate.checks[name], gate) ?? []);
 }
-/** The shipped Check `name` on `setting`, or on its defaults where `setting` leaves it off. */
-export function shippedCheck(name, setting) {
+/** The shipped Check `name` on the setting `gate` gives it, or on its defaults where the setting leaves it off. */
+export function shippedCheck(name, gate) {
+    const setting = gate.checks[name];
     const on = setting === false || setting === undefined ? true : setting;
-    return SHIPPED.find((check) => check.name === name)?.enable(on);
+    return SHIPPED.find((check) => check.name === name)?.enable(on, gate);
 }