dw-sdlc 0.5.0 → 0.6.0

package/config/references.schema.json

@@ -1,56 +1,70 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "$id": "https://raw.githubusercontent.com/dominikwozniak/dw-sdlc/main/plugins/references/config/references.schema.json",
+  "$id": "https://raw.githubusercontent.com/dominikwozniak/dw-sdlc/main/packages/dw-sdlc/config/references.schema.json",
   "title": "references",
-  "description": "The `references` key of `.ai/agentic.config.json`: the repositories an agent reads to see how a problem was solved before, each brought to its ref under `references/<dir>` by the Sync. Only the committed file is read; the local layer adds no References. Every `dir` is unique in the list, which this schema cannot say and the Sync refuses. A key the Sync refuses syncs nothing.",
-  "type": "array",
-  "items": {
-    "type": "object",
-    "properties": {
-      "dir": {
-        "description": "The one directory under `references/` the clone lives in: letters, digits, `_`, `.` and `-`, not starting with `.` or `-`.",
-        "type": "string",
-        "pattern": "^[A-Za-z0-9_][A-Za-z0-9_.-]*$"
-      },
-      "repository": {
-        "description": "A URL `git` can fetch. A `https://github.com/` one fetches with the GitHub CLI's credentials. No whitespace, and no leading `-`, which `git` would read as an option.",
-        "type": "string",
-        "pattern": "^[^\\s-]\\S*$"
-      },
-      "ref": {
-        "description": "A branch, whose head the clone moves to, or a tag. `{name}` in it stands for the exact version the root `package.json` pins for package `name`, read through the default catalog of `pnpm-workspace.yaml` when the pin says `catalog:` or `catalog:default`. No whitespace, and no leading `-`.",
-        "type": "string",
-        "pattern": "^[^\\s-]\\S*$"
-      },
-      "only": {
-        "description": "Paths the sparse checkout holds beside the repository's top-level files, relative to the clone and inside it; a directory ends in `/`. Absent, the whole tree is checked out. Present, it names at least one path, and a path the ref's tree lacks fails the Reference.",
-        "type": "array",
-        "minItems": 1,
-        "items": {
-          "type": "string",
-          "pattern": "^(?!/)(?!(?:.*/)?\\.\\.(?:/|$)).+$"
-        }
-      },
-      "skip": {
-        "description": "Paths the sparse checkout leaves out, relative to the clone and inside it. Empty or absent, nothing is left out. With `only`, each lies inside one of its paths, which this schema cannot say and the Sync refuses.",
-        "type": "array",
-        "items": {
-          "type": "string",
-          "pattern": "^(?!/)(?!(?:.*/)?\\.\\.(?:/|$)).+$"
-        }
-      },
-      "what": {
-        "description": "What the Reference is.",
-        "type": "string",
-        "minLength": 1
-      },
-      "when": {
-        "description": "When an agent reaches for it.",
-        "type": "string",
-        "minLength": 1
-      }
+  "description": "`.ai/references.json`: the repositories an agent reads to see how a problem was solved before, each brought to its ref under `references/<dir>` by the Sync. Only the committed file is read. A `references` key in `.ai/agentic.config.json` is refused: `dw-sdlc references setup` moves it here. A file the Sync refuses syncs nothing.",
+  "type": "object",
+  "properties": {
+    "$schema": {
+      "type": "string"
+    },
+    "version": {
+      "const": 1
     },
-    "required": ["dir", "repository", "ref", "what", "when"],
-    "additionalProperties": false
-  }
+    "references": {
+      "description": "The References, in the order the Router lists them. Every `dir` is unique in the list, which this schema cannot say and the Sync refuses.",
+      "type": "array",
+      "items": {
+        "type": "object",
+        "properties": {
+          "dir": {
+            "description": "The one directory under `references/` the clone lives in: letters, digits, `_`, `.` and `-`, not starting with `.` or `-`.",
+            "type": "string",
+            "pattern": "^[A-Za-z0-9_][A-Za-z0-9_.-]*$"
+          },
+          "repository": {
+            "description": "A URL `git` can fetch. A `https://github.com/` one fetches with the GitHub CLI's credentials. No whitespace, and no leading `-`, which `git` would read as an option.",
+            "type": "string",
+            "pattern": "^[^\\s-]\\S*$"
+          },
+          "ref": {
+            "description": "A branch, whose head the clone moves to, or a tag. `{name}` in it stands for the exact version the root `package.json` pins for package `name`, read through the default catalog of `pnpm-workspace.yaml` when the pin says `catalog:` or `catalog:default`. No whitespace, and no leading `-`.",
+            "type": "string",
+            "pattern": "^[^\\s-]\\S*$"
+          },
+          "only": {
+            "description": "Paths the sparse checkout holds beside the repository's top-level files, relative to the clone and inside it; a directory ends in `/`. Absent, the whole tree is checked out. Present, it names at least one path, and a path the ref's tree lacks fails the Reference.",
+            "type": "array",
+            "minItems": 1,
+            "items": {
+              "type": "string",
+              "pattern": "^(?!/)(?!(?:.*/)?\\.\\.(?:/|$)).+$"
+            }
+          },
+          "skip": {
+            "description": "Paths the sparse checkout leaves out, relative to the clone and inside it. Empty or absent, nothing is left out. With `only`, each lies inside one of its paths, which this schema cannot say and the Sync refuses.",
+            "type": "array",
+            "items": {
+              "type": "string",
+              "pattern": "^(?!/)(?!(?:.*/)?\\.\\.(?:/|$)).+$"
+            }
+          },
+          "what": {
+            "description": "What the Reference is.",
+            "type": "string",
+            "minLength": 1
+          },
+          "when": {
+            "description": "When an agent reaches for it.",
+            "type": "string",
+            "minLength": 1
+          }
+        },
+        "required": ["dir", "repository", "ref", "what", "when"],
+        "additionalProperties": false
+      }
+    }
+  },
+  "required": ["version", "references"],
+  "additionalProperties": false
 }

package/dist/commands/doctor.js

@@ -100,6 +100,7 @@ function checkPlugin(probe, claude) {
         };
     }
     const version = typeof entry.version === "string" ? entry.version : "?";
+    const installPath = typeof entry.installPath === "string" ? entry.installPath : "?";
     if (entry.enabled !== true) {
         return {
             name: "plugin",
@@ -110,7 +111,7 @@ function checkPlugin(probe, claude) {
     return {
         name: "plugin",
         level: "PASS",
-        detail: `${version} enabled; ${pluginOrigin(probe, claude, String(entry.installPath ?? ""))}`
+        detail: `${version} enabled; ${pluginOrigin(probe, claude, installPath)}`
     };
 }
 /** The `version` of the package.json in `dir`, or undefined when there is none. */

package/dist/commands/references-setup.js

@@ -1,12 +1,12 @@
-// `dw-sdlc references setup` sets a repository up to declare References: the five files its USAGE names,
-// each written only when it would change. Existing content stays: a list gains the entries it lacks at
-// its end, nothing is removed or reordered, and a file the step cannot read as it expects is refused.
+// `dw-sdlc references setup` sets a repository up to declare References: the files its USAGE names,
+// each written only when it would change. A list gains the entries it lacks at its end; the one removal
+// is a `references` key moving out of the agentic config. A file it cannot read as expected is refused.
 import { spawnSync } from "node:child_process";
 import { existsSync, lstatSync, mkdirSync, readFileSync, symlinkSync, writeFileSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { parseArgs } from "node:util";
-import { appendKey, parseObject, render } from "../json-text.js";
-import { CONFIG, readReferences } from "../references-key.js";
+import { parseObject, removeKey, render } from "../json-text.js";
+import { CONFIG, REFERENCES_FILE, leftoverKey, leftoverProblem, parseReferences, readFile } from "../references-key.js";
 import { renderBlock, withBlock } from "../router-block.js";
 const ROUTER = "references/AGENTS.md";
 /** A symlink to the Router, so Claude Code loads it. */
@@ -14,6 +14,8 @@ const ROUTER_LINK = "references/CLAUDE.md";
 const SETTINGS = ".claude/settings.json";
 const IGNORE = ".gitignore";
 const TEMPLATE = join(import.meta.dirname, "..", "..", "templates", "router.md");
+/** Where a file the setup creates points `$schema`: the schema the pinned package installs. */
+const SCHEMA = "../node_modules/dw-sdlc/config/references.schema.json";
 /** A clone's own agent files at any depth; Claude Code matches the globs against absolute paths. */
 const EXCLUDES = [
     "**/references/*/CLAUDE.md",
@@ -33,12 +35,13 @@ const USAGE = `Usage: dw-sdlc references setup [--root <dir>] [--dry-run | --che
 
 Sets the repository at --root, or the one the current directory sits in, up to declare References:
 the Router in ${ROUTER} with its CLAUDE.md symlink and, between its two markers, the table of each
-Reference's dir and when from the references key, claudeMdExcludes in ${SETTINGS} for the clones'
-own agent files, the ${IGNORE} lines that keep every clone out of git but the Router, and an empty
-references key in ${CONFIG}. Every file is written only when it would change, and the text around
-the Router's table never; --dry-run reports without writing, and --check does the same and exits 1
-when a file would change. Prints one line per file. Exit 1 when a file is refused, 2 on a bad
-argument.`;
+Reference's dir and when from ${REFERENCES_FILE}, claudeMdExcludes in ${SETTINGS} for the clones' own agent
+files, the ${IGNORE} lines that keep every clone out of git but the Router, and ${REFERENCES_FILE} itself
+with no References when it is missing. A references key in ${CONFIG} moves into a missing ${REFERENCES_FILE}
+and leaves the config; with the file there too, both stay and the step is refused. Every file is
+written only when it would change, and the text around the Router's table never; --dry-run reports
+without writing, and --check does the same and exits 1 when a file would change. Prints one line
+per file. Exit 1 when a file is refused, 2 on a bad argument.`;
 function messageOf(error) {
     return error instanceof Error ? error.message : String(error);
 }
@@ -116,16 +119,43 @@ function withIgnoreLines(current) {
     const gap = head !== "" && !ignored ? "\n" : "";
     return { text: `${head}${gap}${missing.join("\n")}\n` };
 }
-/** The config with an empty `references` key when it has none, inserted so its own layout stays. */
-function withEmptyKey(current) {
-    if (current === undefined) {
-        return { text: render({ references: [] }) };
+/** The text of a References file the setup creates, declaring `references`. */
+function fileOf(references) {
+    return render({ $schema: SCHEMA, version: 1, references });
+}
+/**
+ * Where the References come from: a `references` key left in the config moves into a missing file,
+ * and a repository with neither gets the file with no References; the file and the key both there
+ * are refused, and so is a key the parser refuses.
+ */
+function source(root) {
+    const key = leftoverKey(root);
+    const path = join(root, REFERENCES_FILE);
+    if (key === undefined) {
+        const reading = readFile(root);
+        if ("problem" in reading) {
+            // The problem is the file's own, and the Router's line names it; the file stays as it is.
+            return { problem: reading.problem, file: { text: readFileSync(path, "utf8") } };
+        }
+        return {
+            references: reading.references,
+            file: { text: existsSync(path) ? readFileSync(path, "utf8") : fileOf([]) }
+        };
     }
-    const config = parseObject(current);
-    if (config === undefined) {
-        return { refusal: "is not a JSON object; fix it by hand first" };
+    if (existsSync(path)) {
+        return { problem: leftoverProblem(true) };
+    }
+    const parsed = parseReferences(key);
+    if ("problem" in parsed) {
+        return { problem: `${CONFIG}: ${parsed.problem.path}: ${parsed.problem.message}; fix it by hand first` };
     }
-    return { text: Object.hasOwn(config, "references") ? current : appendKey(current, "references", []) };
+    return {
+        references: parsed.references,
+        file: { text: fileOf(key) },
+        config: (current) => current === undefined || parseObject(current) === undefined
+            ? { refusal: "is not a JSON object; fix it by hand first" }
+            : { text: removeKey(current, "references") }
+    };
 }
 /** The repository `dir` sits in, or `dir` itself outside one. */
 function toplevel(dir) {
@@ -135,12 +165,12 @@ function toplevel(dir) {
 function setup(root, dryRun) {
     const writer = new Writer(root, dryRun);
     const template = readFileSync(TEMPLATE, "utf8");
-    const reading = readReferences(root);
+    const from = source(root);
     writer.put(ROUTER, (current) => {
-        if ("problem" in reading) {
-            return { refusal: `${reading.problem}; the table comes from the key, so fix it first` };
+        if ("problem" in from) {
+            return { refusal: `${from.problem}; the table comes from ${REFERENCES_FILE}, so fix it first` };
         }
-        const next = withBlock(current ?? template, renderBlock(reading.references ?? []));
+        const next = withBlock(current ?? template, renderBlock(from.references ?? []));
         return "problem" in next ? { refusal: next.problem } : next;
     });
     writer.create(ROUTER_LINK, (path) => {
@@ -148,7 +178,10 @@ function setup(root, dryRun) {
     });
     writer.put(SETTINGS, withExcludes);
     writer.put(IGNORE, withIgnoreLines);
-    writer.put(CONFIG, withEmptyKey);
+    writer.put(REFERENCES_FILE, () => ("problem" in from ? (from.file ?? { refusal: from.problem }) : from.file));
+    if (!("problem" in from) && from.config !== undefined) {
+        writer.put(CONFIG, from.config);
+    }
     return writer.steps;
 }
 export function run(argv) {

package/dist/commands/references-sync.js

@@ -1,4 +1,4 @@
-// `dw-sdlc references sync`, the Sync: every Reference the committed config declares brought to its ref
+// `dw-sdlc references sync`, the Sync: every Reference `.ai/references.json` declares brought to its ref
 // under references/<dir>, each clone shallow, blobless, detached and sparse where its entry says. An
 // entry that fails fails alone, and a repository that declares no References gets no output at all.
 import { spawnSync } from "node:child_process";
@@ -7,7 +7,7 @@ import { extname, join } from "node:path";
 import { setTimeout as sleep } from "node:timers/promises";
 import { parseArgs } from "node:util";
 import { readPins, resolveRef } from "../pins.js";
-import { CONFIG, readReferences } from "../references-key.js";
+import { REFERENCES_FILE, readReferences } from "../references-key.js";
 import { renderBlock, withBlock } from "../router-block.js";
 const CLONES = "references";
 const ROUTER = "references/AGENTS.md";
@@ -22,7 +22,7 @@ export const summary = "bring every declared Reference to its ref under referenc
 const USAGE = `Usage: dw-sdlc references sync [dir...]
   or:  pnpm references:sync [dir...], in a checkout of dw-sdlc
 
-Brings every Reference the references key of ${CONFIG} declares to its ref under ${CLONES}/<dir>, or
+Brings every Reference ${REFERENCES_FILE} declares to its ref under ${CLONES}/<dir>, or
 only the given dirs: a missing one cloned shallow, an existing one moved to its branch's head or its
 tag, holding the top-level files and the paths its only names when it has one, without the paths
 its skip names. Prints one line per Reference. Exit 1 when any Reference fails, 2 on a bad key,
@@ -304,7 +304,7 @@ export async function run(argv) {
     const references = reading.references ?? [];
     const unknown = cli.dirs.filter((dir) => !references.some((reference) => reference.dir === dir));
     if (unknown.length > 0) {
-        fail(`not in the references of ${CONFIG}: ${unknown.join(", ")}`);
+        fail(`not in ${REFERENCES_FILE}: ${unknown.join(", ")}`);
     }
     if (reading.references === undefined) {
         return 0;
@@ -335,7 +335,7 @@ export async function run(argv) {
             .map((entry) => `${CLONES}/${entry.name}`)
         : [];
     if (stray.length > 0) {
-        console.log(`Not listed in ${CONFIG}, left alone: ${stray.join(", ")}`);
+        console.log(`Not listed in ${REFERENCES_FILE}, left alone: ${stray.join(", ")}`);
     }
     return failed ? 1 : 0;
 }

package/dist/json-text.d.ts

@@ -5,3 +5,8 @@ export declare function parseObject(text: string): JsonObject | undefined;
 export declare function render(value: unknown): string;
 /** `text`, a JSON object, with `key` set to `value` after its last key, two spaces in. */
 export declare function appendKey(text: string, key: string, value: unknown): string;
+/**
+ * `text`, a JSON object, without its top-level `key`, every copy of it when the key repeats; the
+ * members around it keep their layout.
+ */
+export declare function removeKey(text: string, key: string): string;

package/dist/json-text.js

@@ -1,5 +1,5 @@
 // The text of a JSON object file as the setup commands read and write it: parsed only when it holds an
-// object, rendered two spaces in, and a key appended so a hand-formatted file keeps its layout.
+// object, rendered two spaces in, and a key appended or removed so a hand-formatted file keeps its layout.
 export function isObject(value) {
     return typeof value === "object" && value !== null && !Array.isArray(value);
 }
@@ -24,3 +24,76 @@ export function appendKey(text, key, value) {
     const rendered = JSON.stringify(value, null, 2).replaceAll("\n", "\n  ");
     return `${body}${comma}\n  ${JSON.stringify(key)}: ${rendered}\n${text.slice(close)}`;
 }
+/** The index just past the JSON string that opens at `start`, or the text's end when it never closes. */
+function stringEnd(text, start) {
+    let index = start + 1;
+    while (index < text.length && text[index] !== '"') {
+        index += text[index] === "\\" ? 2 : 1;
+    }
+    return Math.min(index + 1, text.length);
+}
+/** The start and end of the top-level member `key` in `text`, a JSON object, from its name to its value's end. */
+function memberSpan(text, key) {
+    let depth = 0;
+    let expectKey = false;
+    let start;
+    // Just past the last character that is not whitespace: where the member's value ends once a `,` or `}` follows.
+    let lastValue = 0;
+    for (let index = 0; index < text.length;) {
+        const char = text.charAt(index);
+        if (char === '"') {
+            const end = stringEnd(text, index);
+            if (depth === 1 && expectKey) {
+                expectKey = false;
+                if (start === undefined && JSON.parse(text.slice(index, end)) === key) {
+                    start = index;
+                }
+            }
+            lastValue = end;
+            index = end;
+            continue;
+        }
+        if (char === "{" || char === "[") {
+            depth += 1;
+            expectKey = char === "{" && depth === 1;
+        }
+        else if (char === "}" || char === "]") {
+            depth -= 1;
+            if (depth === 0 && start !== undefined) {
+                return { start, end: lastValue };
+            }
+        }
+        else if (char === "," && depth === 1) {
+            if (start !== undefined) {
+                return { start, end: lastValue };
+            }
+            expectKey = true;
+        }
+        if (!/\s/.test(char)) {
+            lastValue = index + 1;
+        }
+        index += 1;
+    }
+    return undefined;
+}
+/**
+ * `text`, a JSON object, without its top-level `key`, every copy of it when the key repeats; the
+ * members around it keep their layout.
+ */
+export function removeKey(text, key) {
+    const span = memberSpan(text, key);
+    if (span === undefined) {
+        return text;
+    }
+    return removeKey(withoutSpan(text, span), key);
+}
+/** `text` without the member at `span` and the comma that joins it to its neighbour. */
+function withoutSpan(text, span) {
+    const after = text.slice(span.end).match(/^\s*,\s*/);
+    if (after !== null) {
+        return text.slice(0, span.start) + text.slice(span.end + after[0].length);
+    }
+    const before = text.slice(0, span.start).match(/,?\s*$/);
+    const cut = span.start - (before?.[0].length ?? 0);
+    return text.slice(0, cut) + text.slice(span.end);
+}

package/dist/references-key.d.ts

@@ -1,4 +1,6 @@
-/** The committed config, the only file the key is read from. */
+/** The committed file the References are read from; no local layer adds to it. */
+export declare const REFERENCES_FILE = ".ai/references.json";
+/** The committed agentic config: a `references` key in it is refused, so the file stays the one list. */
 export declare const CONFIG = ".ai/agentic.config.json";
 export type Reference = {
     dir: string;
@@ -20,12 +22,29 @@ export declare function parseReferences(value: unknown): {
 } | {
     problem: KeyProblem;
 };
+/** The References the file's parsed `value` declares, or the first problem in it; `""` names its root. */
+export declare function parseFile(value: unknown): {
+    references: Reference[];
+} | {
+    problem: KeyProblem;
+};
+/** The `references` key the agentic config at `root` still holds, `undefined` without one or the config. */
+export declare function leftoverKey(root: string): unknown;
+/** Why a `references` key left in the config stops a read, by whether the file is there beside it. */
+export declare function leftoverProblem(fileExists: boolean): string;
 /**
- * The References the committed config at `root` declares, `undefined` without the file or the key,
- * or the problem that stops the read: the file is not a JSON object, or the key fails the parser.
+ * The References the file at `root` declares, `undefined` without the file, or the problem that stops
+ * the read: a `references` key left in the agentic config, a file that is not JSON, or one the parser
+ * refuses. A config that is not JSON is the guards' to report, not the read's.
  */
 export declare function readReferences(root: string): {
     references: Reference[] | undefined;
 } | {
     problem: string;
 };
+/** The References the file at `root` declares, `undefined` without it, the agentic config unread. */
+export declare function readFile(root: string): {
+    references: Reference[] | undefined;
+} | {
+    problem: string;
+};

package/dist/references-key.js

@@ -1,10 +1,13 @@
-// The strict parser of the `references` key, the authority at runtime, and the reader of the committed
-// config that holds it. `config/references.schema.json` documents the same contract, and
-// `test/references-key.test.ts` runs one case list through both. The first problem stops the parse.
+// The strict parser of `.ai/references.json`, the authority at runtime, and its reader. The file's
+// `references` key holds the entries. `config/references.schema.json` documents the same contract,
+// and `test/references-key.test.ts` runs one case list through both. The first problem stops the parse.
 import { existsSync, readFileSync } from "node:fs";
 import { join } from "node:path";
-/** The committed config, the only file the key is read from. */
+/** The committed file the References are read from; no local layer adds to it. */
+export const REFERENCES_FILE = ".ai/references.json";
+/** The committed agentic config: a `references` key in it is refused, so the file stays the one list. */
 export const CONFIG = ".ai/agentic.config.json";
+const FILE_FIELDS = ["$schema", "version", "references"];
 const FIELDS = ["dir", "repository", "ref", "only", "skip", "what", "when"];
 const REQUIRED = ["dir", "repository", "ref", "what", "when"];
 const DIR_NAME = /^[A-Za-z0-9_][A-Za-z0-9_.-]*$/;
@@ -119,31 +122,78 @@ export function parseReferences(value) {
         throw error;
     }
 }
-/**
- * The References the committed config at `root` declares, `undefined` without the file or the key,
- * or the problem that stops the read: the file is not a JSON object, or the key fails the parser.
- */
-export function readReferences(root) {
-    const path = join(root, CONFIG);
+/** The References the file's parsed `value` declares, or the first problem in it; `""` names its root. */
+export function parseFile(value) {
+    if (!isObject(value)) {
+        return { problem: { path: "", message: `must be an object, not ${kind(value)}` } };
+    }
+    const unknown = Object.keys(value).find((field) => !FILE_FIELDS.includes(field));
+    if (unknown !== undefined) {
+        return { problem: { path: "", message: `unknown key ${JSON.stringify(unknown)}` } };
+    }
+    const missing = ["version", "references"].find((field) => !Object.hasOwn(value, field));
+    if (missing !== undefined) {
+        return { problem: { path: "", message: `missing key ${JSON.stringify(missing)}` } };
+    }
+    if (value.$schema !== undefined && typeof value.$schema !== "string") {
+        return { problem: { path: "$schema", message: `must be a string, not ${kind(value.$schema)}` } };
+    }
+    if (value.version !== 1) {
+        return { problem: { path: "version", message: `must be 1, not ${JSON.stringify(value.version)}` } };
+    }
+    return parseReferences(value.references);
+}
+/** The JSON object at `path`, `undefined` without the file, or why it is not one. */
+function readObject(path, name) {
     if (!existsSync(path)) {
-        return { references: undefined };
+        return { value: undefined };
     }
-    let config;
+    let value;
     try {
-        config = JSON.parse(readFileSync(path, "utf8"));
+        value = JSON.parse(readFileSync(path, "utf8"));
     }
     catch (error) {
-        return { problem: `${CONFIG}: not JSON: ${error instanceof Error ? error.message : String(error)}` };
+        return { problem: `${name}: not JSON: ${error instanceof Error ? error.message : String(error)}` };
+    }
+    return isObject(value) ? { value } : { problem: `${name}: not a JSON object` };
+}
+/** The `references` key the agentic config at `root` still holds, `undefined` without one or the config. */
+export function leftoverKey(root) {
+    const read = readObject(join(root, CONFIG), CONFIG);
+    return "value" in read && read.value !== undefined && Object.hasOwn(read.value, "references")
+        ? read.value.references
+        : undefined;
+}
+/** Why a `references` key left in the config stops a read, by whether the file is there beside it. */
+export function leftoverProblem(fileExists) {
+    return fileExists
+        ? `${CONFIG} has a references key beside ${REFERENCES_FILE}; merge it into the file and remove the key by hand`
+        : `${CONFIG}: the references key belongs in ${REFERENCES_FILE}; move it there with \`dw-sdlc references setup\``;
+}
+/**
+ * The References the file at `root` declares, `undefined` without the file, or the problem that stops
+ * the read: a `references` key left in the agentic config, a file that is not JSON, or one the parser
+ * refuses. A config that is not JSON is the guards' to report, not the read's.
+ */
+export function readReferences(root) {
+    if (leftoverKey(root) !== undefined) {
+        return { problem: leftoverProblem(existsSync(join(root, REFERENCES_FILE))) };
     }
-    if (!isObject(config)) {
-        return { problem: `${CONFIG}: not a JSON object` };
+    return readFile(root);
+}
+/** The References the file at `root` declares, `undefined` without it, the agentic config unread. */
+export function readFile(root) {
+    const read = readObject(join(root, REFERENCES_FILE), REFERENCES_FILE);
+    if ("problem" in read) {
+        return read;
     }
-    if (!Object.hasOwn(config, "references")) {
+    if (read.value === undefined) {
         return { references: undefined };
     }
-    const parsed = parseReferences(config.references);
+    const parsed = parseFile(read.value);
     if ("problem" in parsed) {
-        return { problem: `${CONFIG}: ${parsed.problem.path}: ${parsed.problem.message}` };
+        const where = parsed.problem.path === "" ? "" : `${parsed.problem.path}: `;
+        return { problem: `${REFERENCES_FILE}: ${where}${parsed.problem.message}` };
     }
     return { references: parsed.references };
 }

package/dist/router-block.d.ts

@@ -1,5 +1,5 @@
 import type { Reference } from "./references-key.ts";
-/** The block the key gives: one row per Reference in the key's order, or one line when it has none. */
+/** The block the file gives: one row per Reference in the file's order, or one line when it has none. */
 export declare function renderBlock(references: Reference[]): string;
 /**
  * The Router's text with `block` in place of the one between its markers: as it is when the two say

package/dist/router-block.js

@@ -1,12 +1,12 @@
-// The Router's block: a table of each Reference's `dir` and `when`, written from the `references` key
+// The Router's block: a table of each Reference's `dir` and `when`, written from `.ai/references.json`
 // between two markers. The setup writes it and the Sync checks it; the rest of the Router is the
-// author's. A block is in step when its rows say what the key says, not its bytes, which a formatter pads.
-const START = "<!-- references:start — written from .ai/agentic.config.json by the setup; edit the key -->";
+// author's. A block is in step when its rows say what the file says, not its bytes, which a formatter pads.
+const START = "<!-- references:start — written from .ai/references.json by the setup; edit the file -->";
 const END = "<!-- references:end -->";
 const START_LINE = /^<!-- references:start\b.*-->\s*$/;
 const END_LINE = /^<!-- references:end -->\s*$/;
 const NONE = "No Reference is declared yet: `/sdlc-references-add <repository>` adds one.";
-/** The block the key gives: one row per Reference in the key's order, or one line when it has none. */
+/** The block the file gives: one row per Reference in the file's order, or one line when it has none. */
 export function renderBlock(references) {
     const body = references.length === 0
         ? [NONE]

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dw-sdlc",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "description": "The Gate and the agentic config of a repository: the dw-sdlc bin with the Gate, the setup, the doctor, the config check, and the Sync and setup of References; the resolver of the config's layers, its JSON Schema and the validator that reads it.",
   "license": "MIT",
   "repository": {

package/templates/router.md

@@ -9,11 +9,11 @@ file routes reference material only.
 
 ## The list
 
-The table below is written from the `references` key of `.ai/agentic.config.json` by the setup, so
-edit the key, never the table; the key also holds `what` each Reference is, its repository, its ref
-and the paths its clone skips. Before you research, open the clones whose `when` matches the task.
+The table below is written from `.ai/references.json` by the setup, so edit the file, never the
+table; the file also holds `what` each Reference is, its repository, its ref and the paths its clone
+skips. Before you research, open the clones whose `when` matches the task.
 
-<!-- references:start — written from .ai/agentic.config.json by the setup; edit the key -->
+<!-- references:start — written from .ai/references.json by the setup; edit the file -->
 
 No Reference is declared yet: `/sdlc-references-add <repository>` adds one.
 <!-- references:end -->