dw-sdlc 0.6.0 → 0.9.0

package/README.md

@@ -1,8 +1,8 @@
 # dw-sdlc
 
 The Gate and the agentic config of a repository. `.ai/agentic.config.json` declares how a repository
-works for an agent: its package manager, protected branches, env-file policy, commit convention and
-the Gate. The package ships the `dw-sdlc` bin that runs on that file, its JSON Schema, and the
+works for an agent: its package manager, protected branches, env-file policy, commit convention, the
+Gate and who merges a pull request. The package ships the `dw-sdlc` bin that runs on that file, its JSON Schema, and the
 resolver of its layers.
 
 ## Install
@@ -16,9 +16,14 @@ pnpm add -D dw-sdlc
 ## The Gate
 
 `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. `dw-sdlc check <name>` runs one Check
-alone, with the same lines, exit codes and document.
+under `gate.checks`. It prints one line per Step and per Check, and the last 50 lines of a command
+that fails; `--verbose` streams every command's output instead. A Step that creates, changes or
+deletes a file git tracks or would track fails the Gate as Drift, unless `gate.drift` is `"allow"`.
+It exits 0 when everything passes, 1 when a Step or a Check fails or a Step drifts, and 2 when the
+Gate cannot run. `--json` prints the result as one document. `--cache` skips the run when the
+working tree and the resolved Gate match the last green run in that checkout, so a pre-push hook
+costs nothing on an unchanged tree. `dw-sdlc check <name>` runs one Check alone, with the same
+lines, exit codes and document.
 
 ```json
 {
@@ -38,6 +43,32 @@ Under `gate.checks`, a Check the package ships is `true` for its defaults or an
 `comment-budget` holds each comment block in the JavaScript, TypeScript and shell (`.sh`) files under
 its `roots` to `maxProseLines` lines of prose, 3 by default.
 
+## The Ship script
+
+`dw-sdlc pr ship [<n>] [-R owner/name]` reads one pull request through an authenticated `gh` and
+answers the one Action it needs next, as a line or, with `--json`, one document. The exit code says
+whose turn it is: 0 done, 10 the agent's, 20 wait, 30 the dev's, 2 it cannot run. The script
+performs its own Actions: it updates a branch behind its base, marks the head reviewed when the
+Review depth is `off`, marks a draft ready once nothing else holds it back, and squash merges a pull
+request that is green, reviewed and opened by the `gh` account, when the merge is its own. `--dry-run` performs nothing: it answers the first Action the
+script would perform as the dev's. It never deletes a branch; a merged pull request answers with
+the delete command for the dev.
+
+`pr.merge` in the committed `.ai/agentic.config.json` says who merges: the script under `auto`, the
+dev under `ask`, the default. `pr.review` says how closely a head no one has reviewed is read: the
+agent reviews it under `full`, the default, and no one does under `off`. The local layer may tighten
+either and never loosen it; `--merge` acts as `auto` and `--review full|off` sets the depth for one
+call. A pull request the `gh` account did not open is always the dev's to merge.
+
+```json
+{ "pr": { "merge": "auto", "review": "full" } }
+```
+
+`pr ship` answers `review`, its depth under `details`, until the head carries the commit status
+`dw-sdlc/review`, which `dw-sdlc pr reviewed <n> --head <sha>` posts after a clean review. It posts
+nothing and exits 2 once a push moved the head, so a new head needs a fresh review. Under `off` the
+script posts that status itself, its description saying why, and goes on.
+
 ## Commands
 
 | command            | what it does                                                                        |
@@ -50,6 +81,8 @@ its `roots` to `maxProseLines` lines of prose, 3 by default.
 | `config`           | the resolved agentic config, or one file validated against the schema               |
 | `references sync`  | every declared Reference brought to its ref under `references/`                     |
 | `references setup` | the Router, its table and the ignore rules a repository needs to declare References |
+| `pr ship [<n>]`    | the Action one pull request needs next, performing the script's own                 |
+| `pr reviewed <n>`  | a clean review pinned to the head it read, as a commit status                       |
 
 `dw-sdlc <command> --help` gives each one's options.
 

package/config/agentic.config.schema.json

@@ -2,7 +2,7 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://raw.githubusercontent.com/dominikwozniak/dw-sdlc/main/plugins/guardrails/config/agentic.config.schema.json",
   "title": "agentic.config",
-  "description": "How a repository works for an agent. `.ai/agentic.config.json` is committed; `.ai/agentic.config.local.json` overrides it on one machine and may tighten `guardrails` but never loosen it. A key neither file sets is inferred: the Node package manager from the lockfile, the `conventional` commit preset, and `gate.command` from the manifest's `check` script. Unknown top-level keys are tolerated so other tool families can share the file; the keys named here refuse unknown children.",
+  "description": "How a repository works for an agent. `.ai/agentic.config.json` is committed; `.ai/agentic.config.local.json` overrides it on one machine and may tighten `guardrails` and `pr.merge` but never loosen them. A key neither file sets is inferred: the Node package manager from the lockfile, the `conventional` commit preset, and `gate.command` from the manifest's `check` script. Unknown top-level keys are tolerated so other tool families can share the file; the keys named here refuse unknown children.",
   "type": "object",
   "properties": {
     "$schema": {
@@ -114,13 +114,18 @@
           "minLength": 1
         },
         "steps": {
-          "description": "The Steps: toolchain commands run in order from the repository root through `sh -c`, each one's output passed through; the first that fails ends the Gate and no Check runs. A command the shell cannot find (exit 127) or execute (126) means the Gate cannot run.",
+          "description": "The Steps: toolchain commands run in order from the repository root through `sh -c`; the first that does not pass ends the Gate and no Check runs. Each one's output is captured, and its last 50 lines are printed when it does not pass; `--verbose` passes the output through instead. A command the shell cannot find (exit 127) or execute (126) means the Gate cannot run.",
           "type": "array",
           "items": {
             "type": "string",
             "minLength": 1
           }
         },
+        "drift": {
+          "description": "Whether a Step may write the tree. `fail`, the default, watches every Step for Drift: before and after each Step the Gate records the content of every file git tracks or would track, and each file the Step created, changed or deleted is one failure, `\"<step>\" created it`, `changed it` or `deleted it`, without stopping the Steps after it. Ignored files and edits made before the run never drift. A tree the Gate cannot record, outside a git checkout, means the Gate cannot run. `allow` turns the watch off.",
+          "enum": ["fail", "allow"],
+          "default": "fail"
+        },
         "checks": {
           "description": "The Checks the Gate runs after its steps, every one even when another fails: the `run` scripts first, then the Checks the package ships, in the order listed here. A Check the package ships is `true` for its defaults, an options object over them, or `false` to stay off. A key names a Check the package ships, and a name it does not ship is refused.",
           "type": "object",
@@ -167,7 +172,7 @@
               "additionalProperties": false
             },
             "agents-map": {
-              "description": "The agent map: within its line and byte budget, naming the resolved `gate.command`, carrying a Task Router row to the Primitives catalogue where there is one, every path the Task Router points at existing, and the skills directory, `skills-lock.json` and the `.claude/skills` links in step where the repository has them.",
+              "description": "The agent map: within its byte budget, naming the resolved `gate.command`, carrying a Task Router row to the Primitives catalogue where there is one, every path the Task Router points at existing, `CLAUDE.md` a symbolic link to the map unless the map is `CLAUDE.md`, and the skills directory, `skills-lock.json` and the `.claude/skills` links in step where the repository has them.",
               "type": ["boolean", "object"],
               "properties": {
                 "file": {
@@ -175,25 +180,45 @@
                   "type": "string",
                   "minLength": 1
                 },
-                "maxLines": {
-                  "description": "Default 150.",
-                  "type": "integer",
-                  "minimum": 1
-                },
                 "maxBytes": {
-                  "description": "Default 10240.",
+                  "description": "The map's budget in bytes. Default 10240.",
                   "type": "integer",
                   "minimum": 1
                 }
               },
               "additionalProperties": false
             },
+            "routed-docs": {
+              "description": "Every document a task leads to: each file `files` matches and `exempt` does not is reached by a Task Router row of the agent map, through a code span in a cell after the first naming it, a directory above it or a glob that matches it, or by the `docs` of a Primitive in the catalogue naming it, its heading anchor dropped; a path reads from the root, `./` or `/` before it or not. The map is the file `agents-map` reads and the catalogue the one `primitives` reads, each Check on or off; a catalogue that is missing or invalid reaches nothing. A map with no Task Router table fails once on the map, and a missing map leaves the Gate unable to run.",
+              "type": ["boolean", "object"],
+              "properties": {
+                "files": {
+                  "description": "Globs of the documents, against the files git tracks or would track; `*` and `**` skip a name that starts with a dot. Default `docs/**/*.md`.",
+                  "type": "array",
+                  "items": {
+                    "type": "string",
+                    "minLength": 1
+                  },
+                  "uniqueItems": true
+                },
+                "exempt": {
+                  "description": "Globs of the documents left out. Default `docs/research/**`: a research note is read through the spec it backs. A list replaces the default.",
+                  "type": "array",
+                  "items": {
+                    "type": "string",
+                    "minLength": 1
+                  },
+                  "uniqueItems": true
+                }
+              },
+              "additionalProperties": false
+            },
             "markdown-budget": {
-              "description": "Each file a glob of `budgets` matches within that glob's `maxLines` and `maxBytes`, and every glob matching a file. A glob matches the files git tracks or would track, a symbolic link left out when the file it points at is matched too; `*` and `**` skip a name that starts with a dot.",
+              "description": "Each file a glob of `budgets` matches within that glob's `maxBytes`, and every glob matching a file. A glob matches the files git tracks or would track, a symbolic link left out when the file it points at is matched too; `*` and `**` skip a name that starts with a dot.",
               "type": ["boolean", "object"],
               "properties": {
                 "budgets": {
-                  "description": "Default `docs/agents/*.md` within 100 lines and 6144 bytes; a list replaces the default.",
+                  "description": "Default `docs/agents/*.md` within 6144 bytes; a list replaces the default, such as one that adds `GLOSSARY.md` at a budget of its own.",
                   "type": "array",
                   "items": {
                     "type": "object",
@@ -202,16 +227,12 @@
                         "type": "string",
                         "minLength": 1
                       },
-                      "maxLines": {
-                        "type": "integer",
-                        "minimum": 1
-                      },
                       "maxBytes": {
                         "type": "integer",
                         "minimum": 1
                       }
                     },
-                    "required": ["glob", "maxLines", "maxBytes"],
+                    "required": ["glob", "maxBytes"],
                     "additionalProperties": false
                   }
                 }
@@ -289,16 +310,24 @@
                     "minLength": 1
                   },
                   "uniqueItems": true
+                },
+                "fields": {
+                  "description": "The frontmatter fields each record is held to beyond `status`; none by default. `date`: every record carries the day it was decided, `YYYY-MM-DD`. `touches`: a record in force, its status `accepted` or `active`, names the paths it governs. Each is a file or directory git tracks or would track, or a glob that matches such a file. A `superseded` record names none. `superseded-by`: a `superseded` record names the number of each record that replaces it. `amended-by`: each number it names is the number of a record. A number names a record in the same directory. A list is comma-separated after its key, or one `- ` item a line under it.",
+                  "type": "array",
+                  "items": {
+                    "enum": ["date", "touches", "superseded-by", "amended-by"]
+                  },
+                  "uniqueItems": true
                 }
               },
               "additionalProperties": false
             },
             "file-size-ratchet": {
-              "description": "The file-size Ratchet: each file git tracks or would track within the line limit of its group, or, where `.ai/file-size-ratchet.baseline.json` lists it, within the count recorded there. A file belongs to the first group with a glob that matches it; a file no group matches has no limit, and a symbolic link is left out when the file it points at is matched too. The baseline is committed and lists the files over their limit; one that lists a file twice, at a count within its group's limit or in no group fails the Check. `dw-sdlc gate --update-baseline` records it where there is none and otherwise only tightens it, and only when every Step and every other Check passes: a file within its limit leaves it, a count that shrank is lowered, and no file joins.",
+              "description": "The file-size Ratchet, which holds code: each file git tracks or would track within the line limit of its group, or, where `.ai/file-size-ratchet.baseline.json` lists it, within the count recorded there. A file belongs to the first group with a glob that matches it; a file no group matches has no limit, and a symbolic link is left out when the file it points at is matched too. The baseline is committed and lists the files over their limit; one that lists a file twice, at a count within its group's limit or in no group fails the Check. `dw-sdlc gate --update-baseline` records it where there is none and otherwise only tightens it, and only when every Step and every other Check passes: a file within its limit leaves it, a count that shrank is lowered, and no file joins.",
               "type": ["boolean", "object"],
               "properties": {
                 "groups": {
-                  "description": "Default, in this order: `tests`, 2000 lines, a file under a `test`, `tests` or `__tests__` directory or named `*.test.*` or `*.spec.*`; `agent-docs`, 120 lines, `AGENTS.md`, `CLAUDE.md` and `GLOSSARY.md` anywhere and the markdown under `docs/agents`; `source`, 500 lines, JavaScript, TypeScript and shell.",
+                  "description": "Default, in this order: `tests`, 2000 lines, a file under a `test`, `tests` or `__tests__` directory or named `*.test.*` or `*.spec.*`; `source`, 500 lines, JavaScript, TypeScript and shell. No default group holds markdown: `agents-map` and `markdown-budget` hold it to byte budgets.",
                   "type": "array",
                   "items": {
                     "type": "object",
@@ -357,6 +386,26 @@
       },
       "additionalProperties": false
     },
+    "pr": {
+      "description": "How the Ship script, `dw-sdlc pr ship`, ends a pull request. The local override may tighten `merge` and `review` and never loosen them.",
+      "type": "object",
+      "properties": {
+        "merge": {
+          "description": "Who merges a pull request that is green, reviewed and authored by the account `gh` runs as. `auto`: the script squash merges it, naming the head it read. `ask`: it parks with the merge command for the dev. Default `ask`, which an invalid layer runs too. Strictest first: ask, auto.",
+          "enum": ["ask", "auto"]
+        },
+        "review": {
+          "description": "The Review depth of a head the Ship script finds unreviewed, which the dev's `--review` overrides for one call. `full`: the agent reviews the changes. `off`: the script posts the `dw-sdlc/review` success itself and no one reads them. Default `full`, which an invalid layer runs too. Strictest first: full, off.",
+          "enum": ["full", "off"]
+        },
+        "reviewCommand": {
+          "description": "The slash command a `full` Review runs over the pull request's changes, as `/pr-review-toolkit:review-pr code errors`. Default `/code-review`. No strictness order: the local override sets it freely.",
+          "type": "string",
+          "minLength": 1
+        }
+      },
+      "additionalProperties": false
+    },
     "worktree": {
       "type": "object",
       "properties": {

package/dist/agentic-config.d.ts

@@ -15,6 +15,19 @@ export type EnvFiles = {
     allow: string[];
     deny: string[];
 };
+/** Who merges a pull request the Ship script finds ready: the script under `auto`, the dev under `ask`. */
+export type PrMerge = "ask" | "auto";
+/** How closely a Review reads an unreviewed head: the agent reads it under `full`, no one under `off`. */
+export type PrReview = "full" | "off";
+/**
+ * How the Ship script ends a pull request: who merges it, how closely it is reviewed, and the slash
+ * command a `full` Review runs.
+ */
+export type PrConfig = {
+    merge: PrMerge;
+    review: PrReview;
+    reviewCommand: string;
+};
 export type Guardrails = {
     forcePush: ForcePush;
     commitOnProtected: CommitOnProtected;
@@ -38,16 +51,20 @@ export type GateChecks = {
     run: RunCheck[];
     [check: string]: unknown;
 };
-/** The Gate: its command, the steps run in order, the Checks run after them. */
+/** `gate.drift`: whether a Step may write the tree; `src/drift.ts` reads it. */
+export type DriftSetting = "fail" | "allow";
+/** The Gate: its command, the steps run in order, whether they may write the tree, the Checks run after them. */
 export type Gate = {
     command?: string;
     steps: string[];
+    drift: DriftSetting;
     checks: GateChecks;
 };
 /** `gate` as one layer writes it: every key optional, `checks` Check by Check. */
 export type GateLayer = {
     command?: string;
     steps?: string[];
+    drift?: DriftSetting;
     checks?: Partial<GateChecks>;
 };
 /** One layer as written in a file: every key optional, unknown top-level keys tolerated. */
@@ -66,6 +83,7 @@ export type AgenticConfig = {
         trailer?: string;
     };
     gate?: GateLayer;
+    pr?: Partial<PrConfig>;
     worktree?: {
         setup?: string[];
     };
@@ -85,6 +103,7 @@ export type ResolvedConfig = {
         trailer?: string;
     };
     gate: Gate;
+    pr: PrConfig;
     worktree: {
         setup: string[];
     };
@@ -121,9 +140,17 @@ export declare const STRICTNESS: {
     readonly forcePush: readonly ["deny", "ask", "lease"];
     readonly commitOnProtected: readonly ["deny", "allow"];
     readonly envFiles: readonly ["deny", "git"];
+    readonly merge: readonly ["ask", "auto"];
+    readonly review: readonly ["full", "off"];
 };
 /** What the guards run on while any layer is invalid. */
 export declare const STRICTEST_GUARDRAILS: Guardrails;
+/** What the Ship script runs on while any layer is invalid, and with nothing declared: it merges nothing itself. */
+export declare const STRICTEST_PR_MERGE: PrMerge;
+/** The Review depth while any layer is invalid, and with nothing declared: the agent reads every head. */
+export declare const STRICTEST_PR_REVIEW: PrReview;
+/** The command a `full` Review runs with nothing declared; it has no strictness order. */
+export declare const DEFAULT_REVIEW_COMMAND = "/code-review";
 /** What a repository gets with nothing declared. */
 export declare const DEFAULT_GUARDRAILS: Guardrails;
 /**

package/dist/agentic-config.js

@@ -15,7 +15,9 @@ export const COMMIT_CONVENTIONS = ["ticket-key", "conventional"];
 export const STRICTNESS = {
     forcePush: ["deny", "ask", "lease"],
     commitOnProtected: ["deny", "allow"],
-    envFiles: ["deny", "git"]
+    envFiles: ["deny", "git"],
+    merge: ["ask", "auto"],
+    review: ["full", "off"]
 };
 /** What the guards run on while any layer is invalid. */
 export const STRICTEST_GUARDRAILS = {
@@ -24,6 +26,13 @@ export const STRICTEST_GUARDRAILS = {
     envFiles: { policy: "deny", allow: [], deny: [] },
     protectedBranches: ["master", "main", "production"]
 };
+/** What the Ship script runs on while any layer is invalid, and with nothing declared: it merges nothing itself. */
+export const STRICTEST_PR_MERGE = "ask";
+/** The Review depth while any layer is invalid, and with nothing declared: the agent reads every head. */
+export const STRICTEST_PR_REVIEW = "full";
+const STRICTEST_PR = { merge: STRICTEST_PR_MERGE, review: STRICTEST_PR_REVIEW };
+/** The command a `full` Review runs with nothing declared; it has no strictness order. */
+export const DEFAULT_REVIEW_COMMAND = "/code-review";
 /** What a repository gets with nothing declared. */
 export const DEFAULT_GUARDRAILS = {
     forcePush: "lease",
@@ -169,9 +178,12 @@ function hasCheckScript(root) {
     const { scripts } = manifest;
     return typeof scripts === "object" && scripts !== null && "check" in scripts && typeof scripts.check === "string";
 }
-/** The Gate with nothing declared: `pnpm check` where the manifest has a `check` script, else no command. */
+/**
+ * The Gate with nothing declared: `pnpm check` where the manifest has a `check` script, else no command;
+ * no Step, no Check, and the watch for Drift on.
+ */
 function inferGate(root) {
-    const gate = { steps: [], checks: { run: [] } };
+    const gate = { steps: [], drift: "fail", checks: { run: [] } };
     if (hasCheckScript(root)) {
         gate.command = "pnpm check";
     }
@@ -190,6 +202,7 @@ export function inferConfig(root) {
         guardrails: cloneGuardrails(DEFAULT_GUARDRAILS),
         commit: { convention: "conventional" },
         gate: inferGate(root),
+        pr: { ...STRICTEST_PR, reviewCommand: DEFAULT_REVIEW_COMMAND },
         worktree: { setup: [] }
     };
 }
@@ -205,6 +218,7 @@ function applyLayer(base, layer) {
         },
         commit: { ...base.commit, ...layer.commit },
         gate: { ...base.gate, ...layer.gate, checks: { ...base.gate.checks, ...layer.gate?.checks } },
+        pr: { ...base.pr, ...layer.pr },
         worktree: { setup: layer.worktree?.setup ?? base.worktree.setup }
     };
 }
@@ -263,6 +277,18 @@ function loosenings(base, local) {
     }
     return problems;
 }
+/** Each local `pr` key less strict than the one it would override: `merge` auto over ask, `review` off over full. */
+function prLoosenings(base, local) {
+    const keys = ["merge", "review"];
+    return keys.flatMap((key) => {
+        const value = local?.[key];
+        if (value === undefined || rank(key, value) <= rank(key, base[key])) {
+            return [];
+        }
+        const message = `${show(value)} loosens ${show(base[key])}; the local file may tighten pr.${key}, never loosen it`;
+        return [{ file: LOCAL_FILE, path: `pr.${key}`, message }];
+    });
+}
 /** `commit.pattern` from the convention's preset when no layer set one; a set pattern wins. */
 function finalize(merged) {
     const pattern = merged.commit.pattern ?? COMMIT_PATTERNS[merged.commit.convention];
@@ -284,7 +310,10 @@ export function resolveConfig(root) {
         config = applyLayer(config, committed.value);
     }
     if (local.value !== undefined) {
-        const loosened = loosenings(config.guardrails, local.value.guardrails);
+        const loosened = [
+            ...loosenings(config.guardrails, local.value.guardrails),
+            ...prLoosenings(config.pr, local.value.pr)
+        ];
         if (loosened.length > 0) {
             problems.push(...loosened);
             localState = "invalid";
@@ -294,7 +323,8 @@ export function resolveConfig(root) {
         }
     }
     if (problems.length > 0) {
-        config = { ...config, guardrails: cloneGuardrails(STRICTEST_GUARDRAILS) };
+        // `reviewCommand` has no strictest value: it keeps what the valid layers name.
+        config = { ...config, guardrails: cloneGuardrails(STRICTEST_GUARDRAILS), pr: { ...config.pr, ...STRICTEST_PR } };
     }
     return {
         config: finalize(config),

package/dist/checks/agents-map.d.ts

@@ -1,7 +1,15 @@
 import { type Check } from "./check.ts";
 export type AgentsMapOptions = {
     file: string;
-    maxLines: number;
     maxBytes: number;
 };
+/** The rows of the Task Router in `text`, each its line and the paths it points at; none when it has no such table. */
+export declare function routes(text: string): {
+    line: number;
+    paths: string[];
+}[];
+/** The text of the map at `file`; throws `CannotRun` when it does not exist. */
+export declare function readMap(root: string, file: string): string;
 export declare const agentsMap: Check<AgentsMapOptions>;
+/** The agent map a resolved `gate.checks` points at: the `agents-map` Check's file, on or off. */
+export declare function mapFile(checks: Record<string, unknown>): string;

package/dist/checks/agents-map.js

@@ -1,17 +1,19 @@
 // `agents-map`: the agent map stays a map. Within its budget, naming the Gate command, routing to the
-// Primitives catalogue, every path its Task Router points at existing, and the skills directory, its
-// lock and its links in step.
-import { existsSync, globSync, lstatSync, readdirSync, readFileSync, realpathSync, statSync } from "node:fs";
-import { join } from "node:path";
+// Primitives catalogue, every path its Task Router points at existing, `CLAUDE.md` a link to it so
+// 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 { codeSpans, tableRows } from "../markdown.js";
-import { CannotRun } from "./check.js";
+import { CannotRun, optionsOf } from "./check.js";
 import { overBudget } from "./markdown-budget.js";
 import { catalogueFile } from "./primitives.js";
 const ROUTER = "Task Router";
 const AGENTS_SKILLS = ".agents/skills";
 const CLAUDE_SKILLS = ".claude/skills";
 const LOCK = "skills-lock.json";
+/** The file Claude Code reads at the repository root, in place of `AGENTS.md`. */
+const CLAUDE_MD = "CLAUDE.md";
 const REMEDIES = {
     missing: "write it, or point gate.checks.agents-map.file at the map",
     budget: `cut it, or move a topic into a doc a ${ROUTER} row points at`,
@@ -34,6 +36,14 @@ function exists(root, path) {
 function escape(text) {
     return text.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
 }
+/** The rows of the Task Router in `text`, each its line and the paths it points at; none when it has no such table. */
+export function routes(text) {
+    // The first column says when a row applies; the others say what to read.
+    return tableRows(text, ROUTER).map(({ cells, line }) => ({
+        line,
+        paths: codeSpans(cells.slice(1).join(" ")).filter(isPath)
+    }));
+}
 /** The budget, the Gate command, the row to the catalogue and every path the Task Router points at. */
 function judgeMap(root, { file, ...budget }, text) {
     const findings = overBudget(text, budget).map((message) => ({ file, message, remedy: REMEDIES.budget }));
@@ -45,17 +55,13 @@ function judgeMap(root, { file, ...budget }, text) {
         const message = `does not name the Gate command ${JSON.stringify(gate.command)}`;
         findings.push({ file, message, remedy: REMEDIES.command });
     }
-    // The first column says when a row applies; the others say what to read.
-    const routes = tableRows(text, ROUTER).map(({ cells, line }) => ({
-        line,
-        paths: codeSpans(cells.slice(1).join(" ")).filter(isPath)
-    }));
+    const rows = routes(text);
     const catalogue = catalogueFile(gate.checks);
-    if (existsSync(join(root, catalogue)) && !routes.some(({ paths }) => paths.includes(catalogue))) {
+    if (existsSync(join(root, catalogue)) && !rows.some(({ paths }) => paths.includes(catalogue))) {
         const message = `no ${ROUTER} row points at ${catalogue}`;
         findings.push({ file, message, remedy: REMEDIES.catalogue });
     }
-    for (const { line, paths } of routes) {
+    for (const { line, paths } of rows) {
         for (const missing of paths.filter((path) => !exists(root, path))) {
             const message = `the ${ROUTER} points at ${JSON.stringify(missing)}, which does not exist`;
             findings.push({ file, line, message, remedy: REMEDIES.route });
@@ -63,6 +69,31 @@ function judgeMap(root, { file, ...budget }, text) {
     }
     return findings;
 }
+/**
+ * `CLAUDE.md` a link to the map by its path from the root, so the link holds in every clone; nothing
+ * when the map is `CLAUDE.md` itself.
+ */
+function judgeLink(root, map) {
+    if (normalize(map) === CLAUDE_MD) {
+        return [];
+    }
+    const path = join(root, CLAUDE_MD);
+    const command = `ln -s ${map} ${CLAUDE_MD}`;
+    const stat = lstatSync(path, { throwIfNoEntry: false });
+    if (stat === undefined) {
+        return [{ file: CLAUDE_MD, message: "does not exist", remedy: `link it to the map: ${command}` }];
+    }
+    if (!stat.isSymbolicLink()) {
+        const message = `is a file of its own, not a link to ${map}`;
+        return [{ file: CLAUDE_MD, message, remedy: `move what it holds into ${map}, remove it, then ${command}` }];
+    }
+    const target = readlinkSync(path);
+    if (normalize(target) !== normalize(map)) {
+        const message = `links to ${JSON.stringify(target)}, not to ${map}`;
+        return [{ file: CLAUDE_MD, message, remedy: `remove it, then ${command}` }];
+    }
+    return [];
+}
 /** The names of the directories in `dir`, sorted; empty when there is no `dir`. */
 function directories(dir) {
     if (!existsSync(dir)) {
@@ -145,15 +176,27 @@ function linksTo(link, target) {
         return false;
     }
 }
-function run(root, options) {
-    const path = join(root, options.file);
+/** The text of the map at `file`; throws `CannotRun` when it does not exist. */
+export function readMap(root, file) {
+    const path = join(root, file);
     if (!existsSync(path)) {
-        throw new CannotRun({ file: options.file, message: "the map does not exist", remedy: REMEDIES.missing });
+        throw new CannotRun({ file, message: "the map does not exist", remedy: REMEDIES.missing });
     }
-    return [...judgeMap(root, options, readFileSync(path, "utf8")), ...judgeSkills(root)];
+    return readFileSync(path, "utf8");
+}
+function run(root, options) {
+    return [
+        ...judgeMap(root, options, readMap(root, options.file)),
+        ...judgeLink(root, options.file),
+        ...judgeSkills(root)
+    ];
 }
 export const agentsMap = {
     name: "agents-map",
-    defaults: { file: "AGENTS.md", maxLines: 150, maxBytes: 10240 },
+    defaults: { file: "AGENTS.md", maxBytes: 10240 },
     run
 };
+/** The agent map a resolved `gate.checks` points at: the `agents-map` Check's file, on or off. */
+export function mapFile(checks) {
+    return (optionsOf(agentsMap, checks["agents-map"]) ?? agentsMap.defaults).file;
+}

package/dist/checks/decision-records.d.ts

@@ -1,6 +1,11 @@
 import { type Check } from "./check.ts";
+/** The frontmatter fields beyond `status` a record can be held to, in the order they are judged. */
+declare const FIELDS: readonly ["date", "touches", "superseded-by", "amended-by"];
+export type DecisionField = (typeof FIELDS)[number];
 export type DecisionRecordsOptions = {
     dirs: string[];
     statuses: string[];
+    fields: DecisionField[];
 };
 export declare const decisionRecords: Check<DecisionRecordsOptions>;
+export {};