dw-sdlc 0.7.0 → 0.10.0

package/README.md

@@ -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
 {
@@ -43,23 +48,29 @@ its `roots` to `maxProseLines` lines of prose, 3 by default.
 `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 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
+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. The local layer may tighten it and never loosen it, and `--merge` acts
-as `auto` for one call. A pull request the `gh` account did not open is always the dev's to merge.
+dev under `ask`, the default. `pr.review` says how closely a head no one has reviewed is read: the
+agent reviews it under `full`, one `sdlc-reviewer` subagent of the plugin does under `light`, and no
+one does under `off`. Under `auto`, the default, the script routes the depth from the changes:
+lockfiles alone `off`; a workflow file, more than 100 changed lines outside lockfiles, or a change
+too large to size `full`; the rest `light`. The local layer may tighten either and never loosen it;
+`--merge` acts as `auto` and `--review full|light|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" } }
+{ "pr": { "merge": "auto", "review": "full" } }
 ```
 
-`pr ship` answers `review` 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.
+`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
 

package/config/agentic.config.schema.json

@@ -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",
@@ -358,12 +387,42 @@
       "additionalProperties": false
     },
     "pr": {
-      "description": "How the Ship script, `dw-sdlc pr ship`, ends a pull request. The local override may tighten it and never loosen it.",
+      "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 runs the command `pr.reviewCommand` names over the changes. `light`: one `sdlc-reviewer` subagent reads the diff at medium effort. `off`: the script posts the `dw-sdlc/review` success itself and no one reads them. `auto`: built-in rules route the depth from the changes the Review would read: lockfiles alone `off`; a file under `.github/workflows/`, more than 100 changed lines outside lockfiles, or a change the script cannot size, more files than GitHub's compare lists or a file outside lockfiles with no patch, `full`; the rest `light`. Default `auto`; an invalid layer runs `full`. Strictest first: full, auto, light, off.",
+          "enum": ["full", "auto", "light", "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
+    },
+    "worker": {
+      "description": "How a Worker's Claude Code session starts: the command, the model and the effort. No strictness order, as with `pr.reviewCommand`: any layer sets any key freely.",
+      "type": "object",
+      "properties": {
+        "command": {
+          "description": "The command a Worker starts with: the words that start its Claude Code session, before the flags of its own, such as `--model` and `--effort`. Default `claude`. It belongs to one machine, so it sits in the local layer, where `dw-sdlc setup` writes `cswap run -- --dangerously-skip-permissions` when `cswap` is on PATH.",
+          "type": "string",
+          "minLength": 1
+        },
+        "model": {
+          "description": "The model a Worker runs on, as Claude Code's `--model` takes it. Default `sonnet`.",
+          "type": "string",
+          "minLength": 1
+        },
+        "effort": {
+          "description": "The effort a Worker runs at, one of Claude Code's effort levels. Default `high`.",
+          "enum": ["low", "medium", "high", "xhigh", "max"]
         }
       },
       "additionalProperties": false

package/dist/agentic-config.d.ts

@@ -17,6 +17,33 @@ export type EnvFiles = {
 };
 /** 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 command `pr.reviewCommand` names under `full`,
+ * one `sdlc-reviewer` subagent under `light`, no one under `off`.
+ */
+export type ReviewDepth = "full" | "light" | "off";
+/** The Review depths, strictest first: what the dev's `--review` names. */
+export declare const REVIEW_DEPTHS: readonly ["full", "light", "off"];
+/** `pr.review`: a Review depth, or `auto`, which routes one from the changes by built-in rules. */
+export type PrReview = ReviewDepth | "auto";
+/**
+ * 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;
+};
+/** Claude Code's effort levels, lowest first: what `worker.effort` takes. */
+declare const WORKER_EFFORTS: readonly ["low", "medium", "high", "xhigh", "max"];
+export type WorkerEffort = (typeof WORKER_EFFORTS)[number];
+/** How a Worker's Claude Code session starts: the words that start it, its model and its effort. */
+export type WorkerConfig = {
+    command: string;
+    model: string;
+    effort: WorkerEffort;
+};
 export type Guardrails = {
     forcePush: ForcePush;
     commitOnProtected: CommitOnProtected;
@@ -40,16 +67,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. */
@@ -68,9 +99,8 @@ export type AgenticConfig = {
         trailer?: string;
     };
     gate?: GateLayer;
-    pr?: {
-        merge?: PrMerge;
-    };
+    pr?: Partial<PrConfig>;
+    worker?: Partial<WorkerConfig>;
     worktree?: {
         setup?: string[];
     };
@@ -90,9 +120,8 @@ export type ResolvedConfig = {
         trailer?: string;
     };
     gate: Gate;
-    pr: {
-        merge: PrMerge;
-    };
+    pr: PrConfig;
+    worker: WorkerConfig;
     worktree: {
         setup: string[];
     };
@@ -130,11 +159,16 @@ export declare const STRICTNESS: {
     readonly commitOnProtected: readonly ["deny", "allow"];
     readonly envFiles: readonly ["deny", "git"];
     readonly merge: readonly ["ask", "auto"];
+    readonly review: readonly ["full", "auto", "light", "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: the agent reads every head in full. */
+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

@@ -11,12 +11,17 @@ export const LOCAL_FILE = ".ai/agentic.config.local.json";
 export const SCHEMA_FILE = "config/agentic.config.schema.json";
 export const SCHEMA_PATH = join(import.meta.dirname, "..", SCHEMA_FILE);
 export const COMMIT_CONVENTIONS = ["ticket-key", "conventional"];
+/** The Review depths, strictest first: what the dev's `--review` names. */
+export const REVIEW_DEPTHS = ["full", "light", "off"];
+/** Claude Code's effort levels, lowest first: what `worker.effort` takes. */
+const WORKER_EFFORTS = ["low", "medium", "high", "xhigh", "max"];
 /** Strictest value first; the local override may only move towards the front. */
 export const STRICTNESS = {
     forcePush: ["deny", "ask", "lease"],
     commitOnProtected: ["deny", "allow"],
     envFiles: ["deny", "git"],
-    merge: ["ask", "auto"]
+    merge: ["ask", "auto"],
+    review: ["full", "auto", "light", "off"]
 };
 /** What the guards run on while any layer is invalid. */
 export const STRICTEST_GUARDRAILS = {
@@ -27,6 +32,15 @@ export const STRICTEST_GUARDRAILS = {
 };
 /** 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: the agent reads every head in full. */
+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: the merge the dev's, the depth routed from the changes. */
+const DEFAULT_PR = { merge: STRICTEST_PR_MERGE, review: "auto", reviewCommand: DEFAULT_REVIEW_COMMAND };
+/** What a Worker starts with when no layer says otherwise; no key has a strictness order. */
+const DEFAULT_WORKER = { command: "claude", model: "sonnet", effort: "high" };
 /** What a repository gets with nothing declared. */
 export const DEFAULT_GUARDRAILS = {
     forcePush: "lease",
@@ -172,9 +186,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";
     }
@@ -193,7 +210,8 @@ export function inferConfig(root) {
         guardrails: cloneGuardrails(DEFAULT_GUARDRAILS),
         commit: { convention: "conventional" },
         gate: inferGate(root),
-        pr: { merge: STRICTEST_PR_MERGE },
+        pr: { ...DEFAULT_PR },
+        worker: { ...DEFAULT_WORKER },
         worktree: { setup: [] }
     };
 }
@@ -210,6 +228,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 },
+        worker: { ...base.worker, ...layer.worker },
         worktree: { setup: layer.worktree?.setup ?? base.worktree.setup }
     };
 }
@@ -268,13 +287,17 @@ function loosenings(base, local) {
     }
     return problems;
 }
-/** A local `pr.merge` less strict than the one it would override: `auto` over `ask`. */
+/** Each local `pr` key less strict than the one it would override: `merge` auto over ask, `review` off over light over auto over full. */
 function prLoosenings(base, local) {
-    if (local === undefined || rank("merge", local) <= rank("merge", base)) {
-        return [];
-    }
-    const message = `${show(local)} loosens ${show(base)}; the local file may tighten pr.merge, never loosen it`;
-    return [{ file: LOCAL_FILE, path: "pr.merge", message }];
+    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) {
@@ -299,7 +322,7 @@ export function resolveConfig(root) {
     if (local.value !== undefined) {
         const loosened = [
             ...loosenings(config.guardrails, local.value.guardrails),
-            ...prLoosenings(config.pr.merge, local.value.pr?.merge)
+            ...prLoosenings(config.pr, local.value.pr)
         ];
         if (loosened.length > 0) {
             problems.push(...loosened);
@@ -310,7 +333,8 @@ export function resolveConfig(root) {
         }
     }
     if (problems.length > 0) {
-        config = { ...config, guardrails: cloneGuardrails(STRICTEST_GUARDRAILS), pr: { merge: STRICTEST_PR_MERGE } };
+        // `reviewCommand` and `worker` have no strictest value: they keep 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 {};