dw-sdlc 0.16.1 → 0.18.0

package/dist/checks/comments.js

@@ -0,0 +1,255 @@
+// The comments of a source file: every comment in JavaScript, TypeScript or shell `text` with its lines,
+// its text and whether it stands alone on its line, never one inside a string, a template literal, a
+// regular expression, an expansion or a heredoc. `comment-budget` and `disable-directives` read them.
+/** The characters after which a `/` opens a regular expression, not a division. */
+const BEFORE_REGEX = new Set("(,=:[!&|?{};+-*%<>~^");
+const KEYWORD_BEFORE_REGEX = /(^|[^\w$])(return|typeof|instanceof|in|of|new|delete|void|throw|case|do|else|yield|await)$/;
+/** Where the regular expression whose `/` is at `start` ends, or undefined when the line ends first. */
+function regexEnd(text, start) {
+    let inClass = false;
+    for (let index = start + 1; index < text.length; index += 1) {
+        const char = text[index];
+        if (char === "\\") {
+            index += 1;
+        }
+        else if (char === "\n") {
+            return undefined;
+        }
+        else if (char === "[" || char === "]") {
+            inClass = char === "[";
+        }
+        else if (char === "/" && !inClass) {
+            return index + 1;
+        }
+    }
+    return undefined;
+}
+/** Whether the `/` at `index` opens a regular expression: the code before it ends where a value starts. */
+function opensRegex(text, index) {
+    const before = text.slice(0, index).trimEnd();
+    const last = before.at(-1);
+    return last === undefined || BEFORE_REGEX.has(last) || KEYWORD_BEFORE_REGEX.test(before);
+}
+/** Every comment in JavaScript or TypeScript `text`, skipping strings, template literals and regular expressions. */
+export function commentsOf(text) {
+    const comments = [];
+    // The open quotes, and a `{` for each brace opened inside a template literal's `${…}`.
+    const stack = [];
+    let line = 1;
+    let index = 0;
+    while (index < text.length) {
+        const char = text[index];
+        const next = text[index + 1];
+        const top = stack.at(-1);
+        if (top === "'" || top === '"' || top === "`") {
+            if (char === "\\") {
+                line += next === "\n" ? 1 : 0;
+                index += 2;
+                continue;
+            }
+            if (top === "`" && char === "$" && next === "{") {
+                stack.push("{");
+                index += 2;
+                continue;
+            }
+            if (char === top) {
+                stack.pop();
+            }
+            line += char === "\n" ? 1 : 0;
+            index += 1;
+            continue;
+        }
+        if (char === "'" || char === '"' || char === "`" || (char === "{" && top === "{")) {
+            stack.push(char);
+        }
+        else if (char === "}" && top === "{") {
+            stack.pop();
+        }
+        else if (char === "/" && next === "/") {
+            const stop = text.indexOf("\n", index) === -1 ? text.length : text.indexOf("\n", index);
+            const alone = text.slice(text.lastIndexOf("\n", index - 1) + 1, index).trim() === "";
+            comments.push({ kind: alone ? "line" : "trailing", start: line, end: line, text: text.slice(index, stop) });
+            index = stop;
+            continue;
+        }
+        else if (char === "/" && next === "*") {
+            const close = text.indexOf("*/", index + 2);
+            const body = text.slice(index, close === -1 ? text.length : close + 2);
+            const start = line;
+            line += body.split("\n").length - 1;
+            comments.push({ kind: "block", start, end: line, text: body });
+            index += body.length;
+            continue;
+        }
+        else if (char === "/" && opensRegex(text, index)) {
+            index = regexEnd(text, index) ?? index + 1;
+            continue;
+        }
+        line += char === "\n" ? 1 : 0;
+        index += 1;
+    }
+    return comments;
+}
+/** The characters that end a shell word, so a `#` after one opens a comment. */
+const WORD_BREAK = new Set(" \t\n;&|()<>");
+/** Where the line that holds `index` ends: at its newline, or at the end of `text`. */
+export function lineEnd(text, index) {
+    const newline = text.indexOf("\n", index);
+    return newline === -1 ? text.length : newline;
+}
+/** Where a span that `closer` ends, read from `start`, stops, past the closer; `\` escapes a character when `escapes`. */
+export function spanEnd(text, start, closer, escapes) {
+    for (let index = start; index < text.length; index += 1) {
+        if (escapes && text.charAt(index) === "\\") {
+            index += 1;
+        }
+        else if (text.charAt(index) === closer) {
+            return index + 1;
+        }
+    }
+    return text.length;
+}
+/** The heredoc whose `<<` is at `start`, its delimiter's quotes off, and where the delimiter's word ends. */
+export function heredocAt(text, start) {
+    const strip = text.charAt(start + 2) === "-";
+    let index = start + (strip ? 3 : 2);
+    while (text.charAt(index) === " " || text.charAt(index) === "\t") {
+        index += 1;
+    }
+    let end = index;
+    while (end < text.length && !WORD_BREAK.has(text.charAt(end))) {
+        const char = text.charAt(end);
+        end = char === "'" || char === '"' ? spanEnd(text, end + 1, char, false) : end + (char === "\\" ? 2 : 1);
+    }
+    return { delimiter: text.slice(index, end).replace(/["'\\]/g, ""), strip, end };
+}
+/** Where the heredoc body that starts at `start` ends: past the line that is its delimiter. */
+export function heredocEnd(text, start, { delimiter, strip }) {
+    for (let index = start; index < text.length;) {
+        const end = lineEnd(text, index);
+        const line = text.slice(index, end);
+        index = end + 1;
+        if ((strip ? line.replace(/^\t+/, "") : line) === delimiter) {
+            return index;
+        }
+    }
+    return text.length;
+}
+/** The character that opens a nesting inside each frame and the one that closes it; a double quote has none. */
+const NESTING = {
+    code: ["(", ")"],
+    arithmetic: ["(", ")"],
+    expansion: ["{", "}"],
+    double: []
+};
+/**
+ * Every `#` comment in shell `text`: a `#` that starts a word of code, never one in a quote, an
+ * expansion, an arithmetic `((…))` or a heredoc body, nor the shebang on line 1.
+ */
+export function shellCommentsOf(text) {
+    const comments = [];
+    const newlines = [...text.matchAll(/\n/g)].map((match) => match.index);
+    const outer = [];
+    let frame = { kind: "code", depth: 0 };
+    const heredocs = [];
+    let wordStart = true;
+    let index = text.startsWith("#!") ? lineEnd(text, 0) : 0;
+    const open = (kind, length) => {
+        outer.push(frame);
+        frame = { kind, depth: 0 };
+        index += length;
+        wordStart = true;
+    };
+    const close = (length) => {
+        frame = outer.pop() ?? frame;
+        index += length;
+        wordStart = false;
+    };
+    const skipTo = (end) => {
+        index = end;
+        wordStart = false;
+    };
+    while (index < text.length) {
+        const char = text.charAt(index);
+        const next = text.charAt(index + 1);
+        const { kind } = frame;
+        const [opener, closer] = NESTING[kind];
+        if (char === "\\" && next === "\n") {
+            index += 2;
+        }
+        else if (char === "\\") {
+            skipTo(index + 2);
+        }
+        else if (kind === "double" && char === '"') {
+            close(1);
+        }
+        else if (char === "$" && text.startsWith("((", index + 1)) {
+            open("arithmetic", 3);
+        }
+        else if (char === "$" && next === "(") {
+            open("code", 2);
+        }
+        else if (char === "$" && next === "{") {
+            open("expansion", 2);
+        }
+        else if (char === "`") {
+            skipTo(spanEnd(text, index + 1, "`", true));
+        }
+        else if (kind === "double") {
+            index += 1;
+        }
+        else if (char === "$" && next === "'") {
+            skipTo(spanEnd(text, index + 2, "'", true));
+        }
+        else if (char === "'") {
+            skipTo(spanEnd(text, index + 1, "'", false));
+        }
+        else if (char === '"') {
+            open("double", 1);
+        }
+        else if (kind === "code" && char === "#" && wordStart) {
+            const end = lineEnd(text, index);
+            const line = newlines.filter((newline) => newline < index).length + 1;
+            const alone = text.slice(text.lastIndexOf("\n", index - 1) + 1, index).trim() === "";
+            comments.push({ kind: alone ? "line" : "trailing", start: line, end: line, text: text.slice(index, end) });
+            index = end;
+        }
+        else if (kind === "code" && char === "\n") {
+            index += 1;
+            for (const heredoc of heredocs.splice(0)) {
+                index = heredocEnd(text, index, heredoc);
+            }
+            wordStart = true;
+        }
+        else if (kind === "code" && text.startsWith("<<<", index)) {
+            index += 3;
+            wordStart = true;
+        }
+        else if (kind === "code" && text.startsWith("<<", index)) {
+            const { end, ...heredoc } = heredocAt(text, index);
+            heredocs.push(heredoc);
+            skipTo(end);
+        }
+        else if (kind === "code" && text.startsWith("((", index)) {
+            open("arithmetic", 2);
+        }
+        else if (char === opener) {
+            frame.depth += 1;
+            index += 1;
+            wordStart = true;
+        }
+        else if (char === closer && frame.depth > 0) {
+            frame.depth -= 1;
+            index += 1;
+            wordStart = true;
+        }
+        else if (char === closer && outer.length > 0) {
+            close(kind === "arithmetic" && next === ")" ? 2 : 1);
+        }
+        else {
+            wordStart = WORD_BREAK.has(char);
+            index += 1;
+        }
+    }
+    return comments;
+}

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/disable-directives.d.ts

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

package/dist/checks/disable-directives.js

@@ -0,0 +1,91 @@
+// `disable-directives`: a lint rule or a type check switched off says why. A Disable directive in a comment
+// fails unless a reason follows `--` on its line, follows an `@ts-` directive or is a comment above it.
+// The language of a file picks the comments read and the directives looked for.
+import { readFileSync } from "node:fs";
+import { basename, extname, join } from "node:path";
+import { commentsOf } from "./comments.js";
+import { hashCommentsOf } from "./hash-comments.js";
+import { matching, treeFiles } from "./tree.js";
+const REMEDY = "add one after `--` on its line, or in a comment on the line above";
+const SCRIPT_EXTENSIONS = [".ts", ".tsx", ".mts", ".cts", ".js", ".jsx", ".mjs", ".cjs"];
+const RUBY_EXTENSIONS = [".rb", ".rake", ".gemspec", ".ru"];
+const RUBY_NAMES = ["Rakefile", "Gemfile"];
+const PYTHON_EXTENSIONS = [".py", ".pyi"];
+function languageOf(file) {
+    const extension = extname(file);
+    if (SCRIPT_EXTENSIONS.includes(extension)) {
+        return "script";
+    }
+    if (RUBY_EXTENSIONS.includes(extension) || RUBY_NAMES.includes(basename(file))) {
+        return "ruby";
+    }
+    return PYTHON_EXTENSIONS.includes(extension) ? "python" : undefined;
+}
+/**
+ * The pattern that finds a directive at the start of a comment's line, its name in group 1. A Python
+ * `noqa` may follow other words of its comment, after a `#` of its own: `# type: ignore  # noqa`.
+ */
+const DIRECTIVES = {
+    script: /^((?:oxlint|eslint)-disable(?:-next-line|-line)?|@ts-expect-error|@ts-ignore)(?![\w-])/,
+    ruby: /^(rubocop:disable)(?![\w-])/,
+    python: /(?:^|#\s*)(noqa)(?![\w-])/i
+};
+/** The reason `--` gives: text after it, set off from what comes before by space. */
+const DASH_REASON = /(?:^|\s)--+\s*\S/;
+/** A comment's lines, each as text starting after its markers and indent, with the line it sits on. */
+function linesOf({ start, text }, language) {
+    return text.split("\n").map((raw, offset) => {
+        const body = language === "script" ? raw.replace(/^\s*(?:\/\/+|\/\*+|\*+(?!\/))?\s*/, "") : raw.replace(/^\s*#+\s*/, "");
+        return { line: start + offset, text: body.replace(/\s*\*\/\s*$/, "").trimEnd() };
+    });
+}
+/** Whether `rest`, the text of a directive's line after its name, gives a reason. */
+function givesReason(directive, rest) {
+    if (directive.startsWith("@ts-")) {
+        return /[^\s-]/.test(rest.replace(/^\s*:/, ""));
+    }
+    return DASH_REASON.test(rest);
+}
+/** The directive that starts a line of a comment, and the text after it, or undefined. */
+function directiveIn(text, language) {
+    const match = DIRECTIVES[language].exec(text);
+    return match === null ? undefined : { directive: match[1] ?? "", rest: text.slice(match.index + match[0].length) };
+}
+function run(root, { files, exempt }) {
+    const findings = [];
+    for (const file of matching(root, treeFiles(root), files, exempt)) {
+        const language = languageOf(file);
+        if (language === undefined) {
+            continue;
+        }
+        const text = readFileSync(join(root, file), "utf8");
+        const comments = language === "script" ? commentsOf(text) : hashCommentsOf(text, language);
+        const found = comments.flatMap((comment) => linesOf(comment, language).flatMap(({ line, text: body }) => {
+            const directive = directiveIn(body, language);
+            return directive === undefined ? [] : [{ line, ...directive }];
+        }));
+        const directiveLines = new Set(found.map(({ line }) => line));
+        // The line above a directive gives a reason when a comment alone on its line ends on it and no directive does.
+        const commentEnds = new Set(comments.filter(({ kind }) => kind !== "trailing").map(({ end }) => end));
+        for (const { line, directive, rest } of found) {
+            const above = commentEnds.has(line - 1) && !directiveLines.has(line - 1);
+            if (!givesReason(directive, rest) && !above) {
+                findings.push({ file, line, directive, message: `${directive} gives no reason`, remedy: REMEDY });
+            }
+        }
+    }
+    return findings;
+}
+export const disableDirectives = {
+    name: "disable-directives",
+    defaults: {
+        files: [
+            "**/*.{ts,tsx,mts,cts,js,jsx,mjs,cjs}",
+            "**/*.{rb,rake,gemspec,ru}",
+            "**/{Rakefile,Gemfile}",
+            "**/*.{py,pyi}"
+        ],
+        exempt: ["references/**", "**/vendor/**", "**/node_modules/**"]
+    },
+    run
+};

package/dist/checks/hash-comments.d.ts

@@ -0,0 +1,4 @@
+import type { Comment } from "./comments.ts";
+export type HashLanguage = "ruby" | "python";
+/** Every `#` comment in Ruby or Python `text`, skipping strings, Ruby heredocs, `=begin` blocks and Python triple quotes. */
+export declare function hashCommentsOf(text: string, language: HashLanguage): Comment[];

package/dist/checks/hash-comments.js

@@ -0,0 +1,121 @@
+// The `#` comments of a Ruby or Python file: every `#` that is not inside a string, as the comments of
+// `comments.ts` are, so a directive in a string literal or a heredoc is none.
+const HEREDOC = /^<<([~-]?)(["'`]?)([A-Za-z_]\w*)\2/;
+/** The heredoc that opens at `index`, or undefined: a bare `<<NAME` counts only in capitals, as `list <<NAME` is an append. */
+function heredocAt(text, index) {
+    const match = HEREDOC.exec(text.slice(index, index + 80));
+    if (match === null || (match[1] === "" && !/^[A-Z_]/.test(match[3] ?? ""))) {
+        return undefined;
+    }
+    return { terminator: match[3] ?? "", indented: match[1] !== "", length: match[0].length };
+}
+/** Where a heredoc body that starts at `start` ends: past the line that is its terminator. */
+function heredocEnd(text, start, { terminator, indented }) {
+    for (let index = start; index < text.length;) {
+        const stop = text.indexOf("\n", index);
+        const end = stop === -1 ? text.length : stop;
+        const line = text.slice(index, end);
+        index = end + 1;
+        if ((indented ? line.trim() : line) === terminator) {
+            return Math.min(index, text.length);
+        }
+    }
+    return text.length;
+}
+/** Where the block that runs from `index` to the next line that starts with `until` ends; the end of `text` if none. */
+function blockEnd(text, index, until) {
+    const stop = text.indexOf(`\n${until}`, index);
+    if (stop === -1) {
+        return text.length;
+    }
+    const end = text.indexOf("\n", stop + 1);
+    return end === -1 ? text.length : end;
+}
+/** Every `#` comment in Ruby or Python `text`, skipping strings, Ruby heredocs, `=begin` blocks and Python triple quotes. */
+export function hashCommentsOf(text, language) {
+    const comments = [];
+    // The open quotes, a triple quote as its three characters, and a `{` for each brace opened in a Ruby `#{…}`.
+    const stack = [];
+    const heredocs = [];
+    let line = 1;
+    let index = 0;
+    const skipTo = (end) => {
+        line += text.slice(index, end).split("\n").length - 1;
+        index = end;
+    };
+    if (language === "ruby" && text.startsWith("=begin")) {
+        skipTo(blockEnd(text, 0, "=end"));
+    }
+    while (index < text.length) {
+        const char = text.charAt(index);
+        const next = text.charAt(index + 1);
+        const top = stack.at(-1);
+        if (top !== undefined && top !== "{") {
+            if (char === "\\") {
+                skipTo(Math.min(index + 2, text.length));
+            }
+            else if (language === "ruby" && char === "#" && next === "{" && top !== "'") {
+                stack.push("{");
+                index += 2;
+            }
+            else if (text.startsWith(top, index)) {
+                stack.pop();
+                index += top.length;
+            }
+            else {
+                line += char === "\n" ? 1 : 0;
+                index += 1;
+            }
+        }
+        else if (char === "'" || char === '"' || (language === "ruby" && char === "`")) {
+            const triple = language === "python" && text.startsWith(char.repeat(3), index);
+            stack.push(triple ? char.repeat(3) : char);
+            index += triple ? 3 : 1;
+        }
+        else if (char === "{" && top === "{") {
+            stack.push("{");
+            index += 1;
+        }
+        else if (char === "}" && top === "{") {
+            stack.pop();
+            index += 1;
+        }
+        else if (char === "#" && language === "ruby" && next === "{") {
+            index += 1;
+        }
+        else if (char === "#") {
+            const stop = text.indexOf("\n", index);
+            const end = stop === -1 ? text.length : stop;
+            const alone = text.slice(text.lastIndexOf("\n", index - 1) + 1, index).trim() === "";
+            comments.push({ kind: alone ? "line" : "trailing", start: line, end: line, text: text.slice(index, end) });
+            index = end;
+        }
+        else if (char === "\n") {
+            line += 1;
+            index += 1;
+            for (const heredoc of heredocs.splice(0)) {
+                skipTo(heredocEnd(text, index, heredoc));
+            }
+            if (language === "ruby" && text.startsWith("=begin", index)) {
+                skipTo(blockEnd(text, index, "=end"));
+            }
+            else if (language === "ruby" && text.startsWith("__END__", index)) {
+                skipTo(text.length);
+            }
+        }
+        else if (language === "ruby" && char === "<" && next === "<") {
+            const heredoc = heredocAt(text, index);
+            if (heredoc === undefined) {
+                index += 2;
+            }
+            else {
+                heredocs.push(heredoc);
+                index += heredoc.length;
+            }
+        }
+        else {
+            index += 1;
+        }
+    }
+    return comments;
+}

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

@@ -4,11 +4,13 @@ import { agentsMap } from "./agents-map.js";
 import { optionsOf } from "./check.js";
 import { commentBudget } from "./comment-budget.js";
 import { decisionRecords } from "./decision-records.js";
+import { disableDirectives } from "./disable-directives.js";
 import { fileSizeRatchet } from "./file-size-ratchet.js";
 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 {
@@ -23,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;
         }
     };
@@ -36,7 +42,9 @@ const SHIPPED = [
     ship(temporalLanguage),
     ship(decisionRecords),
     ship(fileSizeRatchet),
-    ship(commentBudget)
+    ship(commentBudget),
+    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>;