dw-sdlc 0.0.0-stage → 0.1.0

package/dist/agentic-config.js

@@ -0,0 +1,307 @@
+// Reads what a repository declares for an agent: `.ai/agentic.config.json` (committed), then
+// `.ai/agentic.config.local.json` (one machine) over it, then what the repository itself implies. The
+// local file may tighten `guardrails` and never loosen it; any invalid layer is dropped whole and the
+// guards fall back to the strictest defaults until it is fixed. The guardrails plugin's `hooks/config.jq`
+// is the same merge for the guards; this file is the reference, and the plugin's tests run both.
+import { spawnSync } from "node:child_process";
+import { existsSync, readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { validate } from "./json-schema.js";
+export const COMMITTED_FILE = ".ai/agentic.config.json";
+export const LOCAL_FILE = ".ai/agentic.config.local.json";
+/** The schema's path inside this package. */
+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"];
+/** 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"]
+};
+/** What the guards run on while any layer is invalid. */
+export const STRICTEST_GUARDRAILS = {
+    forcePush: "deny",
+    commitOnProtected: "deny",
+    envFiles: { policy: "deny", allow: [], deny: [] },
+    protectedBranches: ["master", "main", "production"]
+};
+/** What a repository gets with nothing declared. */
+export const DEFAULT_GUARDRAILS = {
+    forcePush: "lease",
+    commitOnProtected: "allow",
+    envFiles: { policy: "git", allow: ["**/.env.example", "**/.env.sample", "**/.env.template"], deny: [] },
+    protectedBranches: ["master", "main", "production"]
+};
+function cloneGuardrails(source) {
+    return {
+        forcePush: source.forcePush,
+        commitOnProtected: source.commitOnProtected,
+        envFiles: { policy: source.envFiles.policy, allow: [...source.envFiles.allow], deny: [...source.envFiles.deny] },
+        protectedBranches: [...source.protectedBranches]
+    };
+}
+/**
+ * Whether an `envFiles` glob selects the file at `relativePath` (to the repository root, or the
+ * basename outside one). `*` and `?` as in a shell pattern, `*` crossing `/`; a leading `**` and a
+ * slash mean at any depth. The same rule `hooks/block-env-access.sh` applies with `[[ == ]]`.
+ */
+export function matchesEnvGlob(glob, relativePath) {
+    const anyDepth = glob.startsWith("**/");
+    const pattern = anyDepth ? glob.slice(3) : glob;
+    const source = pattern
+        .split("")
+        .map((char) => {
+        if (char === "*") {
+            return ".*";
+        }
+        if (char === "?") {
+            return ".";
+        }
+        return char.replace(/[.+^${}()|[\]\\]/g, "\\$&");
+    })
+        .join("");
+    return new RegExp(`^${anyDepth ? "(.*/)?" : ""}${source}$`).test(relativePath);
+}
+// The preset each convention names. `ticket-key` is a ticket key ahead of a short type list;
+// `conventional` is Conventional Commits. Both are POSIX ERE, because `grep -E` runs them.
+export const COMMIT_PATTERNS = {
+    "ticket-key": "^\\[[A-Z]+-[0-9]+\\] (feat|fix|refactor|docs|chore|test|perf|ci|revert): .+",
+    conventional: "^(build|chore|ci|docs|feat|fix|perf|refactor|revert|style|test)(\\([^)]+\\))?!?: .+"
+};
+const NODE_LOCKFILES = [
+    ["pnpm-lock.yaml", "pnpm"],
+    ["package-lock.json", "npm"],
+    ["yarn.lock", "yarn"],
+    ["bun.lock", "bun"],
+    ["bun.lockb", "bun"]
+];
+function messageOf(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+function show(value) {
+    return JSON.stringify(value);
+}
+let schema;
+function loadSchema() {
+    schema ??= JSON.parse(readFileSync(SCHEMA_PATH, "utf8"));
+    return schema;
+}
+/**
+ * The schema's public `$id`: what a written config points its `$schema` at. Stable across plugin
+ * installs, where `SCHEMA_PATH` moves with every version.
+ */
+export function schemaId() {
+    const loaded = loadSchema();
+    if (typeof loaded === "object" && loaded !== null && "$id" in loaded && typeof loaded.$id === "string") {
+        return loaded.$id;
+    }
+    throw new Error(`${SCHEMA_PATH} declares no string $id`);
+}
+/** Parses and validates one document; `file` names it in every problem. */
+export function validateDocument(file, text) {
+    let parsed;
+    try {
+        parsed = JSON.parse(text);
+    }
+    catch (error) {
+        return { problems: [{ file, path: "", message: `not JSON: ${messageOf(error)}` }] };
+    }
+    const problems = validate(loadSchema(), parsed).map(({ path, message }) => ({ file, path, message }));
+    if (problems.length > 0) {
+        return { problems };
+    }
+    // The schema is the runtime twin of `AgenticConfig`: a document it accepts has this shape.
+    return { value: parsed };
+}
+/** `file` from the first of `checkouts` that has it. */
+function readLayer(checkouts, file) {
+    const source = checkouts.find((checkout) => existsSync(join(checkout, file)));
+    if (source === undefined) {
+        return { state: "absent", problems: [] };
+    }
+    const result = validateDocument(file, readFileSync(join(source, file), "utf8"));
+    if ("problems" in result) {
+        return { state: "invalid", problems: result.problems, source };
+    }
+    return { state: "valid", value: result.value, problems: [], source };
+}
+/** The top level of the repository holding `dir`, or undefined outside one. */
+export function findRepository(dir) {
+    const toplevel = spawnSync("git", ["-C", dir, "rev-parse", "--show-toplevel"], { encoding: "utf8" });
+    return toplevel.status === 0 ? toplevel.stdout.trim() : undefined;
+}
+/** The top level of the repository holding `dir`, or `dir` itself outside one. */
+export function repositoryRoot(dir) {
+    return findRepository(dir) ?? dir;
+}
+/**
+ * The main checkout of the linked worktree at `root`, or undefined for a main checkout or outside a
+ * repository: a linked worktree's git dir differs from the common one, which sits in the main checkout.
+ */
+export function mainCheckout(root) {
+    const args = ["-C", root, "rev-parse", "--path-format=absolute", "--git-dir", "--git-common-dir"];
+    const result = spawnSync("git", args, { encoding: "utf8" });
+    if (result.status !== 0) {
+        return undefined;
+    }
+    const [gitDir, commonDir] = result.stdout.trim().split("\n");
+    return gitDir === undefined || commonDir === undefined || gitDir === commonDir ? undefined : dirname(commonDir);
+}
+function inferPackageManagers(root) {
+    const managers = {};
+    const lockfile = NODE_LOCKFILES.find(([file]) => existsSync(join(root, file)));
+    if (lockfile !== undefined) {
+        managers.node = lockfile[1];
+    }
+    return managers;
+}
+/** Whether `package.json` at `root` declares a `check` script; a missing or unreadable manifest has none. */
+function hasCheckScript(root) {
+    let manifest;
+    try {
+        manifest = JSON.parse(readFileSync(join(root, "package.json"), "utf8"));
+    }
+    catch {
+        return false;
+    }
+    if (typeof manifest !== "object" || manifest === null || !("scripts" in manifest)) {
+        return false;
+    }
+    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. */
+function inferGate(root) {
+    const gate = { steps: [], checks: { run: [] } };
+    if (hasCheckScript(root)) {
+        gate.command = "pnpm check";
+    }
+    return gate;
+}
+/**
+ * The bottom layer: the package manager the lockfile implies, the Gate command the manifest's `check`
+ * script implies, plus the defaults every key falls back to. `commit.pattern` is left to
+ * `resolveConfig`, which fills it from the convention when no layer sets one.
+ */
+export function inferConfig(root) {
+    return {
+        version: 1,
+        baseBranch: "auto",
+        packageManagers: inferPackageManagers(root),
+        guardrails: cloneGuardrails(DEFAULT_GUARDRAILS),
+        commit: { convention: "conventional" },
+        gate: inferGate(root),
+        worktree: { setup: [] }
+    };
+}
+function applyLayer(base, layer) {
+    return {
+        version: 1,
+        baseBranch: layer.baseBranch ?? base.baseBranch,
+        packageManagers: { ...base.packageManagers, ...layer.packageManagers },
+        guardrails: {
+            ...base.guardrails,
+            ...layer.guardrails,
+            envFiles: { ...base.guardrails.envFiles, ...layer.guardrails?.envFiles }
+        },
+        commit: { ...base.commit, ...layer.commit },
+        gate: { ...base.gate, ...layer.gate, checks: { ...base.gate.checks, ...layer.gate?.checks } },
+        worktree: { setup: layer.worktree?.setup ?? base.worktree.setup }
+    };
+}
+function rank(key, value) {
+    const order = STRICTNESS[key];
+    return order.indexOf(value);
+}
+const LOOSENS = "the local file may tighten guardrails, never loosen them";
+/**
+ * Every guardrail the local layer sets less strictly than what it would override: a lower-ranked
+ * `forcePush`, `commitOnProtected` or `envFiles.policy`, an added `envFiles.allow` entry, a dropped
+ * `envFiles.deny` entry, a dropped protected branch.
+ */
+function loosenings(base, local) {
+    if (local === undefined) {
+        return [];
+    }
+    const problems = [];
+    if (local.forcePush !== undefined && rank("forcePush", local.forcePush) > rank("forcePush", base.forcePush)) {
+        const message = `${show(local.forcePush)} loosens ${show(base.forcePush)}; ${LOOSENS}`;
+        problems.push({ file: LOCAL_FILE, path: "guardrails.forcePush", message });
+    }
+    if (local.commitOnProtected !== undefined &&
+        rank("commitOnProtected", local.commitOnProtected) > rank("commitOnProtected", base.commitOnProtected)) {
+        const message = `${show(local.commitOnProtected)} loosens ${show(base.commitOnProtected)}; ${LOOSENS}`;
+        problems.push({ file: LOCAL_FILE, path: "guardrails.commitOnProtected", message });
+    }
+    const policy = local.envFiles?.policy;
+    if (policy !== undefined && rank("envFiles", policy) > rank("envFiles", base.envFiles.policy)) {
+        const message = `${show(policy)} loosens ${show(base.envFiles.policy)}; ${LOOSENS}`;
+        problems.push({ file: LOCAL_FILE, path: "guardrails.envFiles.policy", message });
+    }
+    if (local.envFiles?.allow !== undefined) {
+        const known = new Set(base.envFiles.allow);
+        const added = local.envFiles.allow.filter((glob) => !known.has(glob));
+        if (added.length > 0) {
+            const message = `adds ${added.map(show).join(", ")}; the local file may drop allowed env files, never add them`;
+            problems.push({ file: LOCAL_FILE, path: "guardrails.envFiles.allow", message });
+        }
+    }
+    if (local.envFiles?.deny !== undefined) {
+        const kept = new Set(local.envFiles.deny);
+        const dropped = base.envFiles.deny.filter((glob) => !kept.has(glob));
+        if (dropped.length > 0) {
+            const message = `drops ${dropped.map(show).join(", ")}; the local file may add denied env files, never drop them`;
+            problems.push({ file: LOCAL_FILE, path: "guardrails.envFiles.deny", message });
+        }
+    }
+    if (local.protectedBranches !== undefined) {
+        const kept = new Set(local.protectedBranches);
+        const dropped = base.protectedBranches.filter((branch) => !kept.has(branch));
+        if (dropped.length > 0) {
+            const message = `drops ${dropped.map(show).join(", ")}; the local file may add protected branches, never remove them`;
+            problems.push({ file: LOCAL_FILE, path: "guardrails.protectedBranches", message });
+        }
+    }
+    return problems;
+}
+/** `commit.pattern` from the convention's preset when no layer set one; a set pattern wins. */
+function finalize(merged) {
+    const pattern = merged.commit.pattern ?? COMMIT_PATTERNS[merged.commit.convention];
+    return { ...merged, commit: { ...merged.commit, pattern } };
+}
+/**
+ * Local over committed over inferred, for the repository at `root`. A linked worktree reads a layer it
+ * lacks from its main checkout, where a repository that keeps `.ai/` out of git has the only copy.
+ */
+export function resolveConfig(root) {
+    const shared = mainCheckout(root);
+    const checkouts = shared === undefined ? [root] : [root, shared];
+    const committed = readLayer(checkouts, COMMITTED_FILE);
+    const local = readLayer(checkouts, LOCAL_FILE);
+    const problems = [...committed.problems, ...local.problems];
+    let localState = local.state;
+    let config = inferConfig(root);
+    if (committed.value !== undefined) {
+        config = applyLayer(config, committed.value);
+    }
+    if (local.value !== undefined) {
+        const loosened = loosenings(config.guardrails, local.value.guardrails);
+        if (loosened.length > 0) {
+            problems.push(...loosened);
+            localState = "invalid";
+        }
+        else {
+            config = applyLayer(config, local.value);
+        }
+    }
+    if (problems.length > 0) {
+        config = { ...config, guardrails: cloneGuardrails(STRICTEST_GUARDRAILS) };
+    }
+    return {
+        config: finalize(config),
+        problems,
+        layers: { committed: committed.state, local: localState },
+        sources: { committed: committed.source, local: local.source }
+    };
+}

package/dist/catalogue.d.ts

@@ -0,0 +1,36 @@
+export type Group = {
+    id: string;
+    name: string;
+};
+export type Primitive = {
+    id: string;
+    name: string;
+    group: string;
+    summary: string;
+    code: string[];
+    docs: string[];
+};
+export type Catalogue = {
+    version: 1;
+    groups: Group[];
+    primitives: Primitive[];
+};
+/** Where a repository keeps its catalogue unless its config says otherwise. */
+export declare const CATALOGUE_FILE = ".ai/primitives.json";
+export type CatalogueRead = {
+    state: "missing";
+} | {
+    state: "invalid";
+    problems: string[];
+} | {
+    state: "valid";
+    catalogue: Catalogue;
+    text: string;
+};
+/** The catalogue at `file` under `root`, or why there is none to read. */
+export declare function readCatalogue(root: string, file: string): CatalogueRead;
+/**
+ * The Primitives whose `code` names `path`, relative to the repository root: of those, the ones whose
+ * entry is nearest the path, so a file wins over the directory holding it. Empty when none names it.
+ */
+export declare function primitivesNaming(catalogue: Catalogue, path: string): Primitive[];

package/dist/catalogue.js

@@ -0,0 +1,74 @@
+// The Primitives catalogue: what a repository exposes to an agent, where the code of each lives and
+// which documents explain it. Read and held to its shape here; the `primitives` Check judges what it
+// says and `dw-sdlc primitives --paths` answers from it.
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { validate } from "./json-schema.js";
+/** Where a repository keeps its catalogue unless its config says otherwise. */
+export const CATALOGUE_FILE = ".ai/primitives.json";
+const STRINGS = { type: "array", items: { type: "string", minLength: 1 }, minItems: 1 };
+const NAMED = { type: "string", minLength: 1 };
+const SCHEMA = {
+    type: "object",
+    required: ["version", "groups", "primitives"],
+    properties: {
+        version: { const: 1 },
+        groups: {
+            type: "array",
+            items: {
+                type: "object",
+                required: ["id", "name"],
+                properties: { id: NAMED, name: NAMED },
+                additionalProperties: false
+            }
+        },
+        primitives: {
+            type: "array",
+            items: {
+                type: "object",
+                required: ["id", "name", "group", "summary", "code", "docs"],
+                properties: { id: NAMED, name: NAMED, group: NAMED, summary: NAMED, code: STRINGS, docs: STRINGS },
+                additionalProperties: false
+            }
+        }
+    },
+    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");
+    let parsed;
+    try {
+        parsed = JSON.parse(text);
+    }
+    catch (error) {
+        return { state: "invalid", problems: [`not JSON: ${error instanceof Error ? error.message : String(error)}`] };
+    }
+    const problems = validate(SCHEMA, parsed).map(({ path: at, message }) => (at === "" ? message : `${at}: ${message}`));
+    if (problems.length > 0) {
+        return { state: "invalid", problems };
+    }
+    // The schema above is the runtime twin of `Catalogue`: a document it accepts has this shape.
+    return { state: "valid", catalogue: parsed, text };
+}
+/**
+ * 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.
+ */
+function covers(entry, path) {
+    const prefix = entry.replace(/\/+$/, "");
+    return path === prefix || path.startsWith(`${prefix}/`) ? prefix.length : -1;
+}
+/**
+ * The Primitives whose `code` names `path`, relative to the repository root: of those, the ones whose
+ * entry is nearest the path, so a file wins over the directory holding it. Empty when none names it.
+ */
+export function primitivesNaming(catalogue, path) {
+    const nearest = catalogue.primitives.map((primitive) => Math.max(-1, ...primitive.code.map((entry) => covers(entry, path))));
+    const best = Math.max(-1, ...nearest);
+    return best === -1 ? [] : catalogue.primitives.filter((_, index) => nearest[index] === best);
+}

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

@@ -0,0 +1,7 @@
+import { type Check } from "./check.ts";
+export type AgentsMapOptions = {
+    file: string;
+    maxLines: number;
+    maxBytes: number;
+};
+export declare const agentsMap: Check<AgentsMapOptions>;

package/dist/checks/agents-map.js

@@ -0,0 +1,166 @@
+// `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 { 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, maxLines, maxBytes }, text) {
+    const findings = [];
+    const lines = text.endsWith("\n") ? text.split("\n").length - 1 : text.split("\n").length;
+    if (lines > maxLines) {
+        findings.push({ file, message: `${lines} lines, over the ${maxLines}-line budget`, remedy: REMEDIES.budget });
+    }
+    const bytes = Buffer.byteLength(text);
+    if (bytes > maxBytes) {
+        findings.push({ file, message: `${bytes} bytes, over the ${maxBytes}-byte budget`, 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,17 @@
+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);
+}
+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[];
+};
+/** 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/index.d.ts

@@ -0,0 +1,8 @@
+import { type Finding } from "./check.ts";
+/** A Check turned on by its setting, ready to judge a tree. */
+export type EnabledCheck = {
+    name: string;
+    run: (root: string) => Finding[];
+};
+/** Every shipped Check a resolved `gate.checks` turns on with `true` or its options. */
+export declare function enabledChecks(checks: Record<string, unknown>): EnabledCheck[];

package/dist/checks/index.js

@@ -0,0 +1,19 @@
+// The Checks the package ships, in the order the Gate runs them. A new Check is a module beside this
+// file, one row below and one key under `gate.checks` in the schema, listed in the same order.
+import { agentsMap } from "./agents-map.js";
+import { optionsOf } from "./check.js";
+import { primitives } from "./primitives.js";
+function ship(check) {
+    return {
+        name: check.name,
+        enable: (setting) => {
+            const options = optionsOf(check, setting);
+            return options === undefined ? undefined : { name: check.name, run: (root) => check.run(root, options) };
+        }
+    };
+}
+const SHIPPED = [ship(primitives), ship(agentsMap)];
+/** Every shipped Check a resolved `gate.checks` turns on with `true` or its options. */
+export function enabledChecks(checks) {
+    return SHIPPED.flatMap(({ name, enable }) => enable(checks[name]) ?? []);
+}

package/dist/checks/primitives.d.ts

@@ -0,0 +1,8 @@
+import { type Check } from "./check.ts";
+export type PrimitivesOptions = {
+    file: string;
+    roots: string[];
+};
+export declare const primitives: Check<PrimitivesOptions>;
+/** The catalogue a resolved `gate.checks` points at: the `primitives` Check's file, on or off. */
+export declare function catalogueFile(checks: Record<string, unknown>): string;