dw-sdlc 0.0.0-stage → 0.2.0

package/dist/checks/agents-map.js

@@ -0,0 +1,159 @@
+// `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";
+import { resolveConfig } from "../agentic-config.js";
+import { codeSpans, tableRows } from "../markdown.js";
+import { CannotRun } 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";
+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`,
+    command: "name it where the map lists the commands",
+    noCommand: "set gate.command in the agentic config, or give package.json a check script",
+    catalogue: "add a row that sends an agent to the catalogue",
+    route: "fix the path or drop it from the row",
+    unlocked: "add it through the skills CLI, or remove the directory",
+    unheld: "restore the skill, or drop it from the lock",
+    lock: "fix it, or write it again through the skills CLI",
+    stray: `remove it, or move the skill into ${AGENTS_SKILLS}`
+};
+/** A code span that names a path: no spaces, and a slash or a file extension; `*` makes it a glob. */
+function isPath(span) {
+    return /^[\w.*/-]+$/.test(span) && (span.includes("/") || /\.\w+$/.test(span));
+}
+function exists(root, path) {
+    return path.includes("*") ? globSync(path, { cwd: root }).length > 0 : existsSync(join(root, path));
+}
+function escape(text) {
+    return text.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+/** 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 }));
+    const { gate } = resolveConfig(root).config;
+    if (gate.command === undefined) {
+        findings.push({ message: "the Gate has no command for the map to name", remedy: REMEDIES.noCommand });
+    }
+    else if (!new RegExp(`(^|[^\\w-])${escape(gate.command)}($|[^\\w-])`, "m").test(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 catalogue = catalogueFile(gate.checks);
+    if (existsSync(join(root, catalogue)) && !routes.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 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 });
+        }
+    }
+    return findings;
+}
+/** The names of the directories in `dir`, sorted; empty when there is no `dir`. */
+function directories(dir) {
+    if (!existsSync(dir)) {
+        return [];
+    }
+    return readdirSync(dir)
+        .filter((name) => statSync(join(dir, name), { throwIfNoEntry: false })?.isDirectory() === true)
+        .toSorted();
+}
+/** The skills `skills-lock.json` pins, or why it cannot be read. */
+function lockedSkills(root) {
+    let lock;
+    try {
+        lock = JSON.parse(readFileSync(join(root, LOCK), "utf8"));
+    }
+    catch (error) {
+        return { problem: `not JSON: ${error instanceof Error ? error.message : String(error)}` };
+    }
+    if (typeof lock !== "object" || lock === null || !("skills" in lock)) {
+        return { problem: "it has no skills object" };
+    }
+    const { skills } = lock;
+    if (typeof skills !== "object" || skills === null || Array.isArray(skills)) {
+        return { problem: "it has no skills object" };
+    }
+    return Object.keys(skills).toSorted();
+}
+/**
+ * The skills directory, `.agents/skills` or else `.claude/skills`, against the lock where there is one,
+ * and `.agents/skills` against the links `.claude/skills` holds to it where there are both.
+ */
+function judgeSkills(root) {
+    const dir = existsSync(join(root, AGENTS_SKILLS)) ? AGENTS_SKILLS : CLAUDE_SKILLS;
+    const skills = directories(join(root, dir));
+    const findings = [];
+    if (existsSync(join(root, LOCK))) {
+        const locked = lockedSkills(root);
+        if ("problem" in locked) {
+            findings.push({ file: LOCK, message: `not a skills lock: ${locked.problem}`, remedy: REMEDIES.lock });
+        }
+        else {
+            for (const skill of skills.filter((name) => !locked.includes(name))) {
+                const message = `skill ${JSON.stringify(skill)} is not in ${LOCK}`;
+                findings.push({ file: `${dir}/${skill}`, message, remedy: REMEDIES.unlocked });
+            }
+            for (const skill of locked.filter((name) => !skills.includes(name))) {
+                const message = `locks skill ${JSON.stringify(skill)}, which ${dir} does not hold`;
+                findings.push({ file: LOCK, message, remedy: REMEDIES.unheld });
+            }
+        }
+    }
+    if (dir === AGENTS_SKILLS && existsSync(join(root, CLAUDE_SKILLS))) {
+        const entries = readdirSync(join(root, CLAUDE_SKILLS)).toSorted();
+        for (const skill of skills) {
+            const file = `${CLAUDE_SKILLS}/${skill}`;
+            const remedy = `link it to ../../${AGENTS_SKILLS}/${skill}`;
+            if (!entries.includes(skill)) {
+                findings.push({ file, message: `skill ${JSON.stringify(skill)} has no link here`, remedy });
+            }
+            else if (!linksTo(join(root, file), join(root, AGENTS_SKILLS, skill))) {
+                findings.push({ file, message: `is not a link to ${AGENTS_SKILLS}/${skill}`, remedy });
+            }
+        }
+        for (const entry of entries.filter((name) => !skills.includes(name))) {
+            const message = `${AGENTS_SKILLS} holds no skill ${JSON.stringify(entry)}`;
+            findings.push({ file: `${CLAUDE_SKILLS}/${entry}`, message, remedy: REMEDIES.stray });
+        }
+    }
+    return findings;
+}
+/** Whether `link` is a symbolic link that resolves to `target`. */
+function linksTo(link, target) {
+    if (!lstatSync(link).isSymbolicLink()) {
+        return false;
+    }
+    try {
+        return realpathSync(link) === realpathSync(target);
+    }
+    catch {
+        return false;
+    }
+}
+function run(root, options) {
+    const path = join(root, options.file);
+    if (!existsSync(path)) {
+        throw new CannotRun({ file: options.file, message: "the map does not exist", remedy: REMEDIES.missing });
+    }
+    return [...judgeMap(root, options, readFileSync(path, "utf8")), ...judgeSkills(root)];
+}
+export const agentsMap = {
+    name: "agents-map",
+    defaults: { file: "AGENTS.md", maxLines: 150, maxBytes: 10240 },
+    run
+};

package/dist/checks/check.d.ts

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

package/dist/checks/check.js

@@ -0,0 +1,21 @@
+// What every Check the package ships is: a name, the options `true` stands for, and a run over the
+// tree that answers with its failures. The Gate names the Check as each failure's rule.
+/** An input the Check needs is missing or unreadable, so the Gate cannot run: exit 2, not 1. */
+export class CannotRun extends Error {
+    finding;
+    constructor(finding) {
+        super(finding.message);
+        this.finding = finding;
+    }
+}
+/** The options `setting` turns the Check on with: the defaults under `true`, an object over them, else off. */
+export function optionsOf(check, setting) {
+    if (setting === true) {
+        return check.defaults;
+    }
+    if (typeof setting === "object" && setting !== null && !Array.isArray(setting)) {
+        // The schema has refused every key the Check does not take and every value of the wrong type.
+        return { ...check.defaults, ...setting };
+    }
+    return undefined;
+}

package/dist/checks/comment-budget.d.ts

@@ -0,0 +1,6 @@
+import type { Check } from "./check.ts";
+export type CommentBudgetOptions = {
+    maxProseLines: number;
+    roots: string[];
+};
+export declare const commentBudget: Check<CommentBudgetOptions>;

package/dist/checks/comment-budget.js

@@ -0,0 +1,141 @@
+// `comment-budget`: a comment says what the code cannot, in a few lines. A block, one `/* … */` or a run
+// of `//` lines alone on theirs, carries at most `maxProseLines` lines with a letter or a digit.
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { matching, treeFiles } from "./tree.js";
+const SOURCE = ["**/*.{ts,tsx,mts,cts,js,jsx,mjs,cjs}"];
+const REMEDY = "cut it to what the code cannot say, or move the reasoning into a doc and point at it";
+/** 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. */
+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 comments as blocks: a run of `//` lines alone on consecutive lines is one; a comment after code is none. */
+function blocksOf(comments) {
+    const blocks = [];
+    for (const comment of comments) {
+        const previous = blocks.at(-1);
+        if (comment.kind === "line" && previous?.kind === "line" && previous.end === comment.start - 1) {
+            previous.end = comment.end;
+            previous.text += `\n${comment.text}`;
+        }
+        else if (comment.kind !== "trailing") {
+            blocks.push({ ...comment });
+        }
+    }
+    return blocks;
+}
+/** The lines of a block that hold a letter or a digit once the comment markers around them are off. */
+function proseLines(block) {
+    return block
+        .replace(/^\/\*\*?/, "")
+        .replace(/\*\/$/, "")
+        .split("\n")
+        .map((line) => line
+        .trim()
+        .replace(/^\*\s?/, "")
+        .replace(/^\/\/\s?/, ""))
+        .filter((line) => /[\p{L}\p{N}]/u.test(line)).length;
+}
+function run(root, { maxProseLines, roots }) {
+    const findings = [];
+    for (const file of matching(root, treeFiles(root, roots), SOURCE)) {
+        for (const block of blocksOf(commentsOf(readFileSync(join(root, file), "utf8")))) {
+            const prose = proseLines(block.text);
+            if (prose > maxProseLines) {
+                const message = `a comment block of ${prose} prose lines, over the ${maxProseLines}-line budget`;
+                findings.push({ file, line: block.start, message, remedy: REMEDY });
+            }
+        }
+    }
+    return findings;
+}
+export const commentBudget = {
+    name: "comment-budget",
+    defaults: { maxProseLines: 3, roots: ["packages", "plugins", "scripts", "src"] },
+    run
+};

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

@@ -0,0 +1,6 @@
+import { type Check } from "./check.ts";
+export type DecisionRecordsOptions = {
+    dirs: string[];
+    statuses: string[];
+};
+export declare const decisionRecords: Check<DecisionRecordsOptions>;

package/dist/checks/decision-records.js

@@ -0,0 +1,105 @@
+// `decision-records`: the decisions directory stays a reliable index. Its records, the files named
+// `<number>-<slug>.md`, are numbered from 1 with no gap and no number taken twice, and each has a title
+// and a frontmatter status from the allowed set.
+import { readFileSync, statSync } from "node:fs";
+import { join } from "node:path";
+import { headings } from "../markdown.js";
+import { CannotRun } from "./check.js";
+import { treeFiles } from "./tree.js";
+/** A record's name in its directory: its number, a slug, `.md`, and no directory between. */
+const RECORD = /^(\d+)-[^/]+\.md$/;
+const REMEDIES = {
+    missing: "create the records directory, or point gate.checks.decision-records.dirs at it",
+    gap: "restore the missing records, or renumber the ones after the gap",
+    taken: "give each record a number of its own",
+    title: "start it with a level-1 heading that names the decision"
+};
+function isDirectory(path) {
+    return statSync(path, { throwIfNoEntry: false })?.isDirectory() === true;
+}
+/** The `status` of the frontmatter `text` opens with, its quotes dropped, and its 1-based line. */
+function statusOf(text) {
+    const lines = text.split("\n");
+    if (lines[0]?.trim() !== "---") {
+        return undefined;
+    }
+    for (let index = 1; index < lines.length && lines[index]?.trim() !== "---"; index++) {
+        const value = /^status:\s*(.*?)\s*$/.exec(lines[index] ?? "")?.[1]?.replace(/^(["'])(.*)\1$/, "$2");
+        if (value !== undefined && value !== "") {
+            return { value, line: index + 1 };
+        }
+    }
+    return undefined;
+}
+/** Each run of numbers from 1 to the highest that no record takes, as `0004` or `0004 to 0006`. */
+function gaps(taken, pad) {
+    const runs = [];
+    const highest = Math.max(0, ...taken);
+    let start;
+    for (let number = 1; number <= highest; number++) {
+        if (!taken.has(number)) {
+            start ??= number;
+        }
+        else if (start !== undefined) {
+            runs.push(start === number - 1 ? pad(start) : `${pad(start)} to ${pad(number - 1)}`);
+            start = undefined;
+        }
+    }
+    return runs;
+}
+/** What is wrong with the records of `dir`: the numbers they skip, then each record's number, title and status. */
+function judge(root, dir, statuses) {
+    const prefix = `${dir.replace(/\/+$/, "")}/`;
+    const records = treeFiles(root, [dir])
+        .map((file) => ({ file, name: file.slice(prefix.length) }))
+        .filter(({ name }) => RECORD.test(name))
+        .map(({ file, name }) => ({ file, digits: RECORD.exec(name)?.[1] ?? "" }));
+    const width = records[0]?.digits.length ?? 4;
+    const pad = (number) => String(number).padStart(width, "0");
+    const owners = new Map();
+    for (const { file, digits } of records) {
+        if (!owners.has(Number(digits))) {
+            owners.set(Number(digits), file);
+        }
+    }
+    const findings = gaps(new Set(owners.keys()), pad).map((gap) => ({
+        file: dir,
+        message: `no record is numbered ${gap}`,
+        remedy: REMEDIES.gap
+    }));
+    const allowed = `one of ${statuses.join(", ")}`;
+    for (const { file, digits } of records) {
+        const owner = owners.get(Number(digits));
+        if (owner !== file) {
+            findings.push({ file, message: `${digits} is taken by ${owner}`, remedy: REMEDIES.taken });
+        }
+        const text = readFileSync(join(root, file), "utf8");
+        if (!headings(text).some(({ level, text: title }) => level === 1 && title.trim() !== "")) {
+            findings.push({ file, message: "has no title", remedy: REMEDIES.title });
+        }
+        const status = statusOf(text);
+        if (status === undefined) {
+            findings.push({ file, message: "has no status", remedy: `give its frontmatter a status, ${allowed}` });
+        }
+        else if (!statuses.includes(status.value.split(/\s+/)[0] ?? "")) {
+            const message = `the status ${JSON.stringify(status.value)} is not allowed`;
+            findings.push({ file, line: status.line, message, remedy: `set it to ${allowed}` });
+        }
+    }
+    return findings;
+}
+function run(root, { dirs, statuses }) {
+    const present = dirs.filter((dir) => isDirectory(join(root, dir)));
+    if (present.length === 0) {
+        throw new CannotRun({ message: `none of ${dirs.join(", ")} exists`, remedy: REMEDIES.missing });
+    }
+    return present.flatMap((dir) => judge(root, dir, statuses));
+}
+export const decisionRecords = {
+    name: "decision-records",
+    defaults: {
+        dirs: ["docs/adr", "docs/decisions"],
+        statuses: ["proposed", "accepted", "active", "deprecated", "superseded"]
+    },
+    run
+};

package/dist/checks/file-size-ratchet.d.ts

@@ -0,0 +1,10 @@
+import { type Check } from "./check.ts";
+export type Group = {
+    name: string;
+    maxLines: number;
+    files: string[];
+};
+export type FileSizeRatchetOptions = {
+    groups: Group[];
+};
+export declare const fileSizeRatchet: Check<FileSizeRatchetOptions>;

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

@@ -0,0 +1,194 @@
+// `file-size-ratchet`: each file within the line limit of its group or, listed in the baseline, within
+// the count recorded there. A refresh only tightens the baseline: it lowers and drops, and adds no file.
+import { spawnSync } from "node:child_process";
+import { existsSync, mkdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
+import { dirname, join, matchesGlob } from "node:path";
+import { CannotRun } from "./check.js";
+import { lineCount } from "./markdown-budget.js";
+import { matching, treeFiles } from "./tree.js";
+const BASELINE = ".ai/file-size-ratchet.baseline.json";
+const REFRESH = "dw-sdlc gate --update-baseline";
+const REMEDIES = {
+    record: `record it with ${REFRESH}`,
+    shape: `make it an object of file paths and line counts, as ${REFRESH} writes it`,
+    twice: "keep one entry for it, the lower count",
+    stale: `run ${REFRESH}, which drops it`,
+    unreadable: "fix the failures it names"
+};
+/** A committed baseline gone from the tree: recording a new one would let every grown file back in. */
+const DELETED = {
+    file: BASELINE,
+    message: "the baseline is committed but gone from the tree",
+    remedy: `restore it with git restore ${BASELINE}`
+};
+function show(value) {
+    return JSON.stringify(value);
+}
+function plural(count, noun) {
+    return `${count} ${noun}${count === 1 ? "" : "s"}`;
+}
+function inBaseline(line) {
+    return line === undefined ? { file: BASELINE } : { file: BASELINE, line };
+}
+/** The first group with a glob that matches `path`. */
+function groupOf(path, groups) {
+    return groups.find(({ files }) => files.some((glob) => matchesGlob(path, glob)));
+}
+function measure(root, groups) {
+    const measured = new Map();
+    for (const path of matching(root, treeFiles(root), groups.flatMap(({ files }) => files))) {
+        const group = groupOf(path, groups);
+        if (group !== undefined && statSync(join(root, path)).isFile()) {
+            measured.set(path, { group, lines: lineCount(readFileSync(join(root, path), "utf8")) });
+        }
+    }
+    return measured;
+}
+/** The line of each `"<path>":` key in `text`; JSON keeps only the last of a key it reads twice. */
+function keyLines(text, path) {
+    const key = show(path).replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+    return Array.from(text.matchAll(new RegExp(`(?<!\\\\)${key}\\s*:`, "g")), ({ index }) => {
+        return text.slice(0, index).split("\n").length;
+    });
+}
+function readBaseline(root) {
+    const path = join(root, BASELINE);
+    if (!existsSync(path)) {
+        const committed = spawnSync("git", ["-C", root, "cat-file", "-e", `HEAD:${BASELINE}`]).status === 0;
+        return { state: "missing", committed };
+    }
+    const text = readFileSync(path, "utf8");
+    let parsed;
+    try {
+        parsed = JSON.parse(text);
+    }
+    catch (error) {
+        const message = `not JSON: ${error instanceof Error ? error.message : String(error)}`;
+        return { state: "invalid", findings: [{ file: BASELINE, message, remedy: REMEDIES.shape }] };
+    }
+    if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+        return { state: "invalid", findings: [{ file: BASELINE, message: "not an object", remedy: REMEDIES.shape }] };
+    }
+    const findings = [];
+    const entries = new Map();
+    for (const [file, count] of Object.entries(parsed)) {
+        const lines = keyLines(text, file);
+        if (lines.length > 1) {
+            const times = lines.length === 2 ? "twice" : `${lines.length} times`;
+            findings.push({ ...inBaseline(lines[1]), message: `lists ${show(file)} ${times}`, remedy: REMEDIES.twice });
+        }
+        if (typeof count === "number" && Number.isInteger(count) && count >= 1) {
+            entries.set(file, { count, line: lines[0] });
+        }
+        else {
+            const message = `${show(file)} is at ${show(count)}, not a line count`;
+            findings.push({ ...inBaseline(lines.at(-1)), message, remedy: REMEDIES.shape });
+        }
+    }
+    return findings.length > 0 ? { state: "invalid", findings } : { state: "valid", entries };
+}
+/** The entries that excuse nothing: a file no group holds, or a count within its group's limit. */
+function contradictions(entries, groups) {
+    const findings = [];
+    for (const [file, { count, line }] of entries) {
+        const group = groupOf(file, groups);
+        if (group === undefined) {
+            const message = `lists ${show(file)}, which no group holds`;
+            findings.push({ ...inBaseline(line), message, remedy: REMEDIES.stale });
+        }
+        else if (count <= group.maxLines) {
+            const message = `lists ${show(file)} at ${count} lines, within the ${group.maxLines}-line limit of the ${group.name} group`;
+            findings.push({ ...inBaseline(line), message, remedy: REMEDIES.stale });
+        }
+    }
+    return findings;
+}
+function run(root, { groups }) {
+    const read = readBaseline(root);
+    if (read.state === "missing") {
+        const missing = { file: BASELINE, message: "the baseline does not exist", remedy: REMEDIES.record };
+        throw new CannotRun(read.committed ? DELETED : missing);
+    }
+    if (read.state === "invalid") {
+        return read.findings;
+    }
+    const findings = contradictions(read.entries, groups);
+    for (const [file, { group, lines }] of measure(root, groups)) {
+        const recorded = read.entries.get(file)?.count;
+        if (recorded !== undefined && lines > recorded) {
+            const message = `${lines} lines, over the ${recorded} the baseline holds it to`;
+            findings.push({ file, message, remedy: `cut it back to ${recorded} lines or fewer` });
+        }
+        else if (recorded === undefined && lines > group.maxLines) {
+            const message = `${lines} lines, over the ${group.maxLines}-line limit of the ${group.name} group`;
+            findings.push({ file, message, remedy: `split it, or cut it to ${group.maxLines} lines` });
+        }
+    }
+    return findings;
+}
+function write(root, entries) {
+    const sorted = entries.toSorted(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0));
+    mkdirSync(dirname(join(root, BASELINE)), { recursive: true });
+    writeFileSync(join(root, BASELINE), `${JSON.stringify(Object.fromEntries(sorted), null, 2)}\n`);
+}
+/**
+ * Records every file over its limit where there is no baseline; else lowers each count that shrank
+ * and drops each entry that excuses nothing, adding none.
+ */
+function refresh(root, { groups }) {
+    const read = readBaseline(root);
+    if (read.state === "invalid") {
+        throw new CannotRun({
+            file: BASELINE,
+            message: "it is not a baseline the Ratchet can read",
+            remedy: REMEDIES.unreadable
+        });
+    }
+    if (read.state === "missing" && read.committed) {
+        throw new CannotRun(DELETED);
+    }
+    const measured = measure(root, groups);
+    if (read.state === "missing") {
+        const over = [...measured].filter(([, { group, lines }]) => lines > group.maxLines);
+        write(root, over.map(([file, { lines }]) => [file, lines]));
+        return `recorded — ${plural(over.length, "file")} over ${over.length === 1 ? "its" : "their"} limit`;
+    }
+    const kept = [];
+    let dropped = 0;
+    let lowered = 0;
+    for (const [file, { count }] of read.entries) {
+        const now = measured.get(file);
+        const tighter = now === undefined ? 0 : Math.min(now.lines, count);
+        if (now === undefined || tighter <= now.group.maxLines) {
+            dropped += 1;
+        }
+        else {
+            lowered += tighter < count ? 1 : 0;
+            kept.push([file, tighter]);
+        }
+    }
+    if (dropped === 0 && lowered === 0) {
+        return "unchanged";
+    }
+    write(root, kept);
+    const parts = [
+        ...(dropped > 0 ? [`${plural(dropped, "file")} dropped`] : []),
+        ...(lowered > 0 ? [`${plural(lowered, "count")} lowered`] : [])
+    ];
+    return `tightened — ${parts.join(", ")}`;
+}
+const TESTS = ["**/{test,tests,__tests__}/**", "**/*.{test,spec}.*"];
+const AGENT_DOCS = ["**/{AGENTS,CLAUDE,GLOSSARY}.md", "docs/agents/**/*.md"];
+const SOURCE = ["**/*.{ts,tsx,mts,cts,js,jsx,mjs,cjs,sh}"];
+export const fileSizeRatchet = {
+    name: "file-size-ratchet",
+    defaults: {
+        groups: [
+            { name: "tests", maxLines: 2000, files: TESTS },
+            { name: "agent-docs", maxLines: 120, files: AGENT_DOCS },
+            { name: "source", maxLines: 500, files: SOURCE }
+        ]
+    },
+    run,
+    baseline: { file: BASELINE, refresh }
+};