dw-sdlc 0.17.0 → 0.19.0

package/README.md

@@ -1,9 +1,10 @@
 # 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, 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.
+The bin and the config behind the [dw-sdlc](https://github.com/dominikwozniak/dw-sdlc) Claude Code plugins.
+`.ai/agentic.config.json` declares how a repository 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, the file's JSON Schema and the resolver of its layers. The Gate
+and the Ship script work in any repository, with or without the plugins.
 
 ## Install
 
@@ -13,17 +14,17 @@ Node 24 or later.
 pnpm add -D dw-sdlc
 ```
 
+Every release goes to npm from GitHub Actions by trusted publishing, and every version after 0.17.0
+carries provenance too. Trust evidence never drops from one version to the next, so a repository on
+pnpm's `trustPolicy: no-downgrade` takes each release. Dependabot offers one after the seven days of
+`minimumReleaseAge`; a repository that cannot wait names `dw-sdlc` in `minimumReleaseAgeExclude` under
+its own rule for exclusions.
+
 ## The Gate
 
-`dw-sdlc gate` runs the Steps under `gate.steps` in order from the repository root, then every Check
-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.
+`dw-sdlc gate` proves a change. It runs the Steps under `gate.steps`, the repository's own commands, in
+order from the repository root, stopping at the first that fails. Then it runs every Check under
+`gate.checks`, a named rule the package ships, none stopping the next.
 
 ```json
 {
@@ -35,76 +36,113 @@ lines, exit codes and document.
 }
 ```
 
-A Step is a command string, or `{ "command": "…", "hint": "…" }`; a `gate.checks.run` entry takes a
-`hint` beside `name` and `command`. When the Step or script fails, the Gate prints `hint: <text>` under
-its failure line, and `--json` carries `hint` on every Step and Check, `null` where there is none.
-
 ```json
 { "scripts": { "check": "dw-sdlc gate" } }
 ```
 
-Under `gate.checks`, a Check the package ships is `true` for its defaults or an object of its options.
-`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.
-`disable-directives` fails every Disable directive in a comment that gives no reason: `oxlint-disable*`,
-`eslint-disable*`, `@ts-expect-error`, `@ts-ignore`, `rubocop:disable` and `noqa`. A reason follows `--`
-on the directive's line, follows an `@ts-` directive, or is a comment on the line above.
+It prints one line per Step and per Check, and the last 50 lines of a command that fails. A Step that
+creates, changes or deletes a file git tracks or would track fails as Drift, unless `gate.drift` is
+`"allow"`. A Step written as `{ "command": "…", "hint": "…" }` prints `hint: <text>` under its failure
+line; a `gate.checks.run` entry takes a `hint` beside `name` and `command`.
+
+| flag                | does                                                                              |
+| ------------------- | --------------------------------------------------------------------------------- |
+| `--json`            | prints the result as one document; each Step and Check carries `tail` and `hint`  |
+| `--verbose`         | streams every command's output instead of the tail                                |
+| `--cache`           | skips the run when the tree and the Gate match the last green run in the checkout |
+| `--update-baseline` | after a green run, tightens the baseline of each Ratchet                          |
+
+| exit | means                                                                              |
+| ---- | ---------------------------------------------------------------------------------- |
+| 0    | everything passes                                                                  |
+| 1    | a Step or a Check fails, or a Step drifts                                          |
+| 2    | the Gate cannot run: an invalid config layer, a command not found, a missing input |
+
+`dw-sdlc check <name>` runs one Check alone, with the same lines, exit codes and document.
+
+### Checks
+
+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             |
+
+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).
 
 ## 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 GitHub reports `BEHIND`, 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`, 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.
+`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. It performs its own Actions:
+it updates a branch GitHub reports `BEHIND`, marks the head reviewed at Review depth `off`, marks a draft
+ready once nothing else holds it back, and squash merges when the merge is its own. It never deletes a
+branch. `--dry-run` performs nothing.
+
+| exit | whose turn         |
+| ---- | ------------------ |
+| 0    | done               |
+| 10   | the agent's: act   |
+| 20   | nobody's yet: wait |
+| 30   | the dev's: park    |
+| 2    | it cannot run      |
+
+| key                | sets                                                                                           |
+| ------------------ | ---------------------------------------------------------------------------------------------- |
+| `pr.merge`         | who merges: the script under `auto`, the dev under `ask`, the default                          |
+| `pr.review`        | the Review depth of an unreviewed head: `full`, `light`, `off`, or `auto` from the change size |
+| `pr.reviewCommand` | the slash command a `full` Review runs, `/code-review` by default                              |
 
 ```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. A Review
-that leaves a Finding open posts it with `--findings`, in state failure, "read, findings open": the
-read mark. After the next push, `details.since` names the last head a Review read, clean or marked,
-so the Review after a fix reads the fix alone. `pr reviewed` 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.
+The local layer may tighten `pr.merge` and `pr.review`, never loosen them. `--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. `light` spawns the `sdlc-reviewer` subagent of the
+[`sdlc` plugin](https://github.com/dominikwozniak/dw-sdlc/blob/main/plugins/sdlc/README.md#the-light-review).
 
-Three Reviews with no success between them end the loop: `pr ship` answers `park review-limit`
-instead of `review`, whose command, `dw-sdlc pr reviewed <n> -R <owner/name> --head <sha> --accept`,
-is the dev's. `--accept` posts the success described "accepted by the dev, findings open"; with
-`--findings` it exits 2. The limit is a constant, not a config key, and `--review <depth>` on a call
-buys one more Review past it.
+`dw-sdlc pr reviewed <n> --head <sha>` pins a Review to the head it read, as the commit status
+`dw-sdlc/review`: clean, Findings open with `--findings`, or accepted by the dev with `--accept`. The
+routing rules, the read mark and the limit of three unclean Reviews are in
+[How the Ship script merges a pull request](https://github.com/dominikwozniak/dw-sdlc/blob/main/docs/overview.md#how-the-ship-script-merges-a-pull-request).
 
 ## Commands
 
-| command            | what it does                                                                               |
-| ------------------ | ------------------------------------------------------------------------------------------ |
-| `gate`             | the Steps of `gate.steps` in order, then every Check under `gate.checks`                   |
-| `check <name>`     | one Check of the Gate by its name, without the Steps and the other Checks                  |
-| `primitives`       | the Primitives that own each path, with their summaries and documents                      |
-| `setup`            | this machine's local config layer, the git excludes and the permission rules               |
-| `doctor`           | one PASS / WARN / FAIL line per machine check the guardrails rely on                       |
-| `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 Review pinned to the head it read, as a commit status: clean, Findings open, or accepted |
-| `recap`            | the facts a Recap rests on and whether the session can be closed                           |
-
-`dw-sdlc <command> --help` gives each one's options.
+| command            | what it does                                                                                      |
+| ------------------ | ------------------------------------------------------------------------------------------------- |
+| `gate`             | the Gate: the Steps of `gate.steps` in order, then every Check under `gate.checks`                |
+| `check <name>`     | one Check of the Gate by its name, without the Steps and the other Checks                         |
+| `primitives`       | the Primitives that own each path, or that a change removes, adds or extends                      |
+| `setup`            | the Gate adopted where asked, this machine's local config layer, git excludes and permissions     |
+| `doctor`           | one PASS / WARN / FAIL line per machine check the `sdlc` plugin relies on                         |
+| `config`           | the resolved agentic config, or one file validated against the schema                             |
+| `references sync`  | every declared Reference, a repository cloned for reading, 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 Review pinned to the head it read, as a commit status                                           |
+| `recap`            | the facts a Recap rests on, whether the session can be closed and what could come next            |
+| `sweep`            | Landed branches and clean worktrees removed, and what it keeps named                              |
+| `worker start`     | a Worker started on a Brief in a herdr terminal                                                   |
+| `worker ls`        | the Workers this Lead started and their states                                                    |
+| `worker report`    | a Recap delivered to the Lead, retried while it is blocked                                        |
+| `lead start`       | the next session started as a Lead in a herdr terminal of its own                                 |
+
+`dw-sdlc --help` lists them, and `dw-sdlc <command> --help` gives each one's options and exit codes. A
+Primitive is one unit a repository exposes to an agent, a module, a hook, a script, a config key or a
+skill, listed in `.ai/primitives.json`. A Recap, a Brief, a Worker and a Lead belong to the
+[`sdlc-sessions` plugin](https://github.com/dominikwozniak/dw-sdlc/blob/main/plugins/sdlc-sessions/README.md).
 
 ## The resolver
 
@@ -115,8 +153,8 @@ const { config, problems } = resolveConfig(process.cwd())
 ```
 
 `resolveConfig` merges the committed `.ai/agentic.config.json`, the machine's
-`.ai/agentic.config.local.json` and what it infers from the repository. `problems` names each layer
-that fails the schema; an invalid layer is dropped whole.
+`.ai/agentic.config.local.json` and what it infers from the repository. `problems` names each layer that
+fails the schema; an invalid layer is dropped whole, and the guards then run the strictest set.
 
 ## License
 

package/config/agentic.config.schema.json

@@ -1,8 +1,8 @@
 {
   "$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",
+  "$id": "https://raw.githubusercontent.com/dominikwozniak/dw-sdlc/main/packages/dw-sdlc/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` 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.",
+  "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`, `pr.merge` and `pr.review` 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": {
@@ -428,6 +428,22 @@
                 }
               },
               "additionalProperties": false
+            },
+            "skill-sections": {
+              "description": "Every README section a skill copies matches its source. A part is the section of the README under the heading with GitHub's anchor `<anchor>`, up to the next heading of its level or above, copied whole between `<!-- README.md#<anchor> -->` and `<!-- /README.md#<anchor> -->`, each on its own line, with a blank line inside each. The README is the `README.md` of the directory that holds the `skills` directory the file is in, or of the file's own directory outside one. A part fails when it differs from its section, when the README has no heading with its anchor, and when no Primitive in the catalogue `primitives` reads names `<README>#<anchor>` among its docs; a marker without its pair fails too. A marker inside code is none, and a code fence that never closes above a marker fails, since it hides that marker. `dw-sdlc check skill-sections --write` writes each part from its section. A repository with no part passes without reading the catalogue; one with a part and no valid catalogue cannot run.",
+              "type": ["boolean", "object"],
+              "properties": {
+                "files": {
+                  "description": "Globs of the skill files, against the files git tracks or would track; `*` and `**` skip a name that starts with a dot. Default `**/skills/**/*.md`.",
+                  "type": "array",
+                  "items": {
+                    "type": "string",
+                    "minLength": 1
+                  },
+                  "uniqueItems": true
+                }
+              },
+              "additionalProperties": false
             }
           },
           "additionalProperties": false

package/dist/catalogue.d.ts

@@ -27,6 +27,10 @@ export type CatalogueRead = {
     catalogue: Catalogue;
     text: string;
 };
+/** The catalogue `text` holds, or why it is not one. */
+export declare function parseCatalogue(text: string): Exclude<CatalogueRead, {
+    state: "missing";
+}>;
 /** The catalogue at `file` under `root`, or why there is none to read. */
 export declare function readCatalogue(root: string, file: string): CatalogueRead;
 /**

package/dist/catalogue.js

@@ -34,13 +34,8 @@ const SCHEMA = {
     },
     additionalProperties: false
 };
-/** The catalogue at `file` under `root`, or why there is none to read. */
-export function readCatalogue(root, file) {
-    const path = join(root, file);
-    if (!existsSync(path)) {
-        return { state: "missing" };
-    }
-    const text = readFileSync(path, "utf8");
+/** The catalogue `text` holds, or why it is not one. */
+export function parseCatalogue(text) {
     let parsed;
     try {
         parsed = JSON.parse(text);
@@ -55,6 +50,11 @@ export function readCatalogue(root, file) {
     // The schema above is the runtime twin of `Catalogue`: a document it accepts has this shape.
     return { state: "valid", catalogue: parsed, text };
 }
+/** The catalogue at `file` under `root`, or why there is none to read. */
+export function readCatalogue(root, file) {
+    const path = join(root, file);
+    return existsSync(path) ? parseCatalogue(readFileSync(path, "utf8")) : { state: "missing" };
+}
 /**
  * How near the `code` entry `entry`, a file or a directory, names `path`: the length of the entry when
  * it is the path or a directory above it, -1 when it is neither.

package/dist/checks/check.d.ts

@@ -22,6 +22,8 @@ export type Check<Options extends object> = {
     run: (root: string, options: Options) => 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;
 };
 /** 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/decision-records.d.ts

@@ -7,5 +7,20 @@ export type DecisionRecordsOptions = {
     statuses: string[];
     fields: DecisionField[];
 };
+/** The first words of a status that say a record once governed and no longer does. */
+export declare const OUT_OF_FORCE: Set<string>;
+/**
+ * The `status` of the frontmatter `text` opens with, its quotes dropped, and its 1-based line. It keeps a
+ * reader apart from `frontmatter`, which a status never goes through: a ` #` is part of it.
+ */
+export declare function statusOf(text: string): {
+    value: string;
+    line: number;
+} | undefined;
+/**
+ * The status of the decision record `path` names, whole, or "" when it has none; undefined when `path` is
+ * no record of `dirs` or is not on disk. A record is a file `<number>-<slug>.md` directly under a directory.
+ */
+export declare function recordStatus(root: string, dirs: string[], path: string): string | undefined;
 export declare const decisionRecords: Check<DecisionRecordsOptions>;
 export {};

package/dist/checks/decision-records.js

@@ -12,6 +12,8 @@ const FIELDS = ["date", "touches", "superseded-by", "amended-by"];
 const RECORD = /^(\d+)-[^/]+\.md$/;
 /** The first words of a status that put a record in force, so it governs the paths under its `touches`. */
 const IN_FORCE = new Set(["accepted", "active"]);
+/** The first words of a status that say a record once governed and no longer does. */
+export const OUT_OF_FORCE = new Set(["deprecated", "superseded"]);
 /** A character that makes a path under `touches` a glob. */
 const GLOB = /[*?[\]{}]/;
 const REMEDIES = {
@@ -37,7 +39,7 @@ function isDirectory(path) {
  * The `status` of the frontmatter `text` opens with, its quotes dropped, and its 1-based line. It keeps a
  * reader apart from `frontmatter`, which a status never goes through: a ` #` is part of it.
  */
-function statusOf(text) {
+export function statusOf(text) {
     const lines = text.split("\n");
     if (lines[0]?.trim() !== "---") {
         return undefined;
@@ -55,6 +57,18 @@ function isDay(value) {
     const date = new Date(`${value}T00:00:00Z`);
     return /^\d{4}-\d{2}-\d{2}$/.test(value) && !Number.isNaN(date.getTime()) && date.toISOString().startsWith(value);
 }
+/**
+ * The status of the decision record `path` names, whole, or "" when it has none; undefined when `path` is
+ * no record of `dirs` or is not on disk. A record is a file `<number>-<slug>.md` directly under a directory.
+ */
+export function recordStatus(root, dirs, path) {
+    const inDirs = dirs.some((dir) => {
+        const prefix = `${dir.replace(/\/+$/, "")}/`;
+        return path.startsWith(prefix) && RECORD.test(path.slice(prefix.length));
+    });
+    const file = join(root, path);
+    return inDirs && existsSync(file) ? (statusOf(readFileSync(file, "utf8"))?.value ?? "") : undefined;
+}
 function judgeDate({ file, keys }) {
     const date = keys.get("date");
     if (date === undefined || date.value === "") {

package/dist/checks/index.d.ts

@@ -7,6 +7,7 @@ export type EnabledCheck = {
         file: string;
         refresh: (root: string) => string;
     };
+    write?: (root: string) => string;
 };
 /** The name of every Check the package ships, in the order the Gate runs them. */
 export declare const CHECK_NAMES: readonly string[];

package/dist/checks/index.js

@@ -10,6 +10,7 @@ import { markdownBudget } from "./markdown-budget.js";
 import { markdownRefs } from "./markdown-refs.js";
 import { primitives } from "./primitives.js";
 import { routedDocs } from "./routed-docs.js";
+import { skillSections } from "./skill-sections.js";
 import { temporalLanguage } from "./temporal-language.js";
 function ship(check) {
     return {
@@ -24,6 +25,10 @@ function ship(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);
+            }
             return enabled;
         }
     };
@@ -38,7 +43,8 @@ const SHIPPED = [
     ship(decisionRecords),
     ship(fileSizeRatchet),
     ship(commentBudget),
-    ship(disableDirectives)
+    ship(disableDirectives),
+    ship(skillSections)
 ];
 /** The name of every Check the package ships, in the order the Gate runs them. */
 export const CHECK_NAMES = SHIPPED.map(({ name }) => name);

package/dist/checks/primitives.js

@@ -1,11 +1,12 @@
-// `primitives`: the catalogue says what is true of the tree. Unique ids, a known group, a one-line
-// summary, every code and docs path on disk with its anchor resolving, and every file under the roots
-// named by a Primitive.
+// `primitives`: the catalogue says what is true of the tree. Unique ids that start with their group, a
+// one-line summary, real code and docs paths, no decision record out of force, every file named.
 import { existsSync } from "node:fs";
 import { join } from "node:path";
+import { resolveConfig } from "../agentic-config.js";
 import { CATALOGUE_FILE, primitivesNaming, readCatalogue } from "../catalogue.js";
 import { anchorsOf } from "../markdown.js";
 import { CannotRun, optionsOf } from "./check.js";
+import { decisionRecords, OUT_OF_FORCE, recordStatus } from "./decision-records.js";
 import { treeFiles } from "./tree.js";
 const MAX_SUMMARY = 120;
 /** A file a test runs, never shipped: under a test directory, or named as a test. */
@@ -14,6 +15,8 @@ const REMEDIES = {
     missing: "create it, or point gate.checks.primitives.file at the catalogue",
     shape: "give it the catalogue's shape: version 1, groups of id and name, primitives of id, name, group, summary, code and docs",
     duplicate: "give each Primitive an id of its own",
+    prefix: "start the id with its group and a . or a -, or move the Primitive into the group its id starts with",
+    record: "name the record that replaces it, or drop the entry",
     group: "add the group to groups, or move the Primitive into one listed there",
     summary: `keep the summary to one line of ${MAX_SUMMARY} characters or fewer`,
     path: "fix the path or drop it",
@@ -30,10 +33,13 @@ function lineOf(text, id, nth) {
     return match?.index === undefined ? undefined : text.slice(0, start + match.index).split("\n").length;
 }
 /** What is wrong with one Primitive, declared at `at`: its group, its summary, each code and docs entry. */
-function judge(root, catalogue, primitive, at, cache) {
+function judge(root, catalogue, primitive, at, cache, records) {
     const { id, group, summary, code, docs } = primitive;
     const findings = [];
     const fail = (message, remedy) => findings.push({ ...at, message, remedy });
+    if (!id.startsWith(`${group}.`) && !id.startsWith(`${group}-`)) {
+        fail(`the id ${show(id)} does not start with its group ${show(group)} and a "." or a "-"`, REMEDIES.prefix);
+    }
     if (!catalogue.groups.some((known) => known.id === group)) {
         fail(`${show(id)} is in group ${show(group)}, which groups does not list`, REMEDIES.group);
     }
@@ -55,6 +61,10 @@ function judge(root, catalogue, primitive, at, cache) {
         else if (anchor !== undefined && !anchorsOf(root, path, cache).has(anchor)) {
             fail(`${show(id)} names the doc ${show(entry)}, which has no heading with that anchor`, REMEDIES.anchor);
         }
+        const status = recordStatus(root, records, path);
+        if (status !== undefined && OUT_OF_FORCE.has(status.split(/\s+/)[0] ?? "")) {
+            fail(`${show(id)} names the decision record ${show(entry)}, whose status ${show(status)} is no longer in force`, REMEDIES.record);
+        }
     }
     return findings;
 }
@@ -67,6 +77,7 @@ function run(root, { file, roots }) {
         return read.problems.map((message) => ({ file, message, remedy: REMEDIES.shape }));
     }
     const { catalogue, text } = read;
+    const records = (optionsOf(decisionRecords, resolveConfig(root).config.gate.checks["decision-records"]) ?? decisionRecords.defaults).dirs;
     const findings = [];
     const seen = new Map();
     const cache = new Map();
@@ -82,7 +93,7 @@ function run(root, { file, roots }) {
                 remedy: REMEDIES.duplicate
             });
         }
-        findings.push(...judge(root, catalogue, primitive, at, cache));
+        findings.push(...judge(root, catalogue, primitive, at, cache, records));
     }
     for (const path of treeFiles(root, roots)) {
         if (!TEST_FILE.test(path) && primitivesNaming(catalogue, path).length === 0) {

package/dist/checks/skill-sections.d.ts

@@ -0,0 +1,5 @@
+import { type Check } from "./check.ts";
+export type SkillSectionsOptions = {
+    files: string[];
+};
+export declare const skillSections: Check<SkillSectionsOptions>;