@jterrazz/typescript 9.1.1 → 9.2.1

package/README.md

@@ -11,14 +11,15 @@ npm install @jterrazz/typescript --save-dev
 ## The CLI
 
 ```bash
-npx typescript build       # Build application (ESM + types)
-npx typescript bundle      # Bundle library (ESM + CJS + types)
-npx typescript start       # Run the built application
-npx typescript dev         # Build, run, and rebuild on changes
-npx typescript docs        # Compile the committed docs/reference tree from source
-npx typescript check       # Type-check, lint, format-check, and unused-code in parallel
-npx typescript fix         # Auto-fix lint and formatting issues
-npx typescript clean       # Remove .artifacts/ (dist/ stays — it is the product)
+npx typescript build           # Build application (ESM + types)
+npx typescript bundle          # Bundle library (ESM + CJS + types)
+npx typescript start           # Run the built application
+npx typescript dev             # Build, run, and rebuild on changes
+npx typescript docs            # Compile the committed docs/reference tree from source
+npx typescript docs-layout .   # Check a repository's docs/ against the manual spine
+npx typescript check           # Type-check, lint, format-check, and unused-code in parallel
+npx typescript fix             # Auto-fix lint and formatting issues
+npx typescript clean           # Remove .artifacts/ (dist/ stays — it is the product)
 ```
 
 ## How it works
@@ -40,12 +41,15 @@ Fully compiled — no JavaScript in the hot path:
 
 The full corpus lives in [`docs/`](docs/):
 
-- [Getting started](docs/01-getting-started.md) — install and configure a project.
-- [Building](docs/02-building.md) — `build`, `bundle`, `start`, `dev`.
-- [Quality checks](docs/03-quality-checks.md) — `check` / `fix` and their passes.
-- [Lint presets](docs/04-lint-presets.md) — oxlint presets, `compose`, architecture, knip.
-- [Docs pipeline](docs/05-docs-pipeline.md) — the `typescript docs` compiler.
-- [Repo structure](docs/06-repo-structure.md) — pointer to the shared doctrine; what's TypeScript-specific here.
+- [Architecture](docs/01-architecture.md) — the four layers and what each one holds.
+- [Developing](docs/02-developing.md) — install and configure a project.
+- [Testing](docs/03-testing.md) — how this toolchain proves itself.
+- [Operating](docs/04-operating.md) — what publishes it, and which number moves.
+- [Building](docs/05-building.md) — `build`, `bundle`, `start`, `dev`.
+- [Quality checks](docs/06-quality-checks.md) — `check` / `fix` and their passes.
+- [Lint presets](docs/07-lint-presets.md) — oxlint presets, `compose`, architecture, knip.
+- [Docs pipeline](docs/08-docs-pipeline.md) — the `typescript docs` compiler.
+- [Repo structure](docs/09-repo-structure.md) — pointer to the shared doctrine; what's TypeScript-specific here.
 
 For agents: read the chapters and the generated [`docs/reference/`](docs/reference/) tree straight from the repo, plus the [`skills/jterrazz-typescript`](skills/jterrazz-typescript/SKILL.md) Claude Code skill (the toolchain). The repo-structure doctrine itself is a Claude Code skill too — `jterrazz-repo-structure`, shipped from [`jterrazz-studio`](https://github.com/jterrazz/jterrazz-studio).
 

package/bin/commands/check.sh

@@ -314,6 +314,21 @@ run_checks() {
         gitignore_pid=$!
     fi
 
+    # Docs (layout): the manual's shape — the map, the spine, the numbering, the
+    # three subfolders, the decision mold. Its unit is the REPOSITORY, not the
+    # package: a manual answers for the whole tree, and only its root carries the
+    # AGENTS.md that routes into it. So the pass asks its question exactly where a
+    # repository is — `.git` here, a file in a worktree and a directory in a clone.
+    # Nothing else gates it: a repository with NO docs/ is the population the rule
+    # exists for, and it fails on `docs-absent`. Check-only, like every read-only
+    # gate — there is no rewrite that can author a chapter.
+    local docs_layout_pid=""
+    local docs_layout_status=0
+    if [ "$FIX_MODE" = false ] && [ -e ".git" ]; then
+        node "$PACKAGE_ROOT/lib/check-docs.js" > "$tmp_dir/docs-layout.log" 2>&1 &
+        docs_layout_pid=$!
+    fi
+
     # Conventions checker: only in check mode, once per specs root the workspace
     # owns, gated by the package that OWNS that root — a member may depend on
     # @jterrazz/test while the root does not, and the reverse.
@@ -359,6 +374,7 @@ run_checks() {
     wait $format_pid; local format_status=$?
     [ -n "$knip_pid" ] && { wait $knip_pid; knip_status=$?; }
     [ -n "$gitignore_pid" ] && { wait $gitignore_pid; gitignore_status=$?; }
+    [ -n "$docs_layout_pid" ] && { wait $docs_layout_pid; docs_layout_status=$?; }
 
     # One pass, N runs: the pass fails if any run failed, and only the logs of
     # the runs that FAILED are printed — a green member stays silent.
@@ -447,6 +463,16 @@ run_checks() {
             fi
         fi
 
+        if [ -n "$docs_layout_pid" ]; then
+            printf "\n${CYAN_BG}${BRIGHT_WHITE} RUN ${NC} Docs (layout)\n\n"
+            if [ $docs_layout_status -ne 0 ]; then
+                [ -s "$tmp_dir/docs-layout.log" ] && cat "$tmp_dir/docs-layout.log"
+                printf "${RED}✗ Failed with exit code %d${NC}\n" $docs_layout_status
+            else
+                printf "${GREEN}✓ Passed${NC}\n"
+            fi
+        fi
+
         if [ ${#docs_pids[@]} -gt 0 ]; then
             printf "\n${CYAN_BG}${BRIGHT_WHITE} RUN ${NC} Docs (sync)\n\n"
             if [ $docs_status -ne 0 ]; then
@@ -467,7 +493,7 @@ run_checks() {
         printf "\n${CYAN_BG}${BRIGHT_WHITE} END ${NC} Finalizing quality checks\n\n"
     fi
 
-    if [ $type_status -eq 0 ] && [ $lint_status -eq 0 ] && [ $format_status -eq 0 ] && [ $knip_status -eq 0 ] && [ $gitignore_status -eq 0 ] && [ $checker_status -eq 0 ] && [ $docs_status -eq 0 ]; then
+    if [ $type_status -eq 0 ] && [ $lint_status -eq 0 ] && [ $format_status -eq 0 ] && [ $knip_status -eq 0 ] && [ $gitignore_status -eq 0 ] && [ $checker_status -eq 0 ] && [ $docs_layout_status -eq 0 ] && [ $docs_status -eq 0 ]; then
         printf "${GREEN}✓ All checks passed${NC}\n"
         exit 0
     else

package/bin/typescript.sh

@@ -160,6 +160,14 @@ case "$COMMAND" in
         fi
         ;;
 
+    docs-layout)
+        # The manual's shape, on its own — the same gate `check` runs as its
+        # Docs (layout) pass, reachable by a repository that has no npm project
+        # to hang it on (a Go, Rust or Ansible tree wiring it into `make lint`
+        # through npx). It takes the repository root and needs nothing installed.
+        exec node "$PACKAGE_ROOT/lib/check-docs.js" "${1:-$PROJECT_ROOT}"
+        ;;
+
     check|fix)
         exec bash "$SCRIPT_DIR/commands/check.sh" "$COMMAND" "$@"
         ;;
@@ -168,14 +176,15 @@ case "$COMMAND" in
         printf "${CYAN_BG}${BRIGHT_WHITE} TYPESCRIPT ${NC} TypeScript toolchain\n\n"
         printf "Usage: typescript <command>\n\n"
         printf "Commands:\n"
-        printf "  build     Build application (ESM + types)\n"
-        printf "  bundle    Bundle library (ESM + CJS + types)\n"
-        printf "  start     Run the built application\n"
-        printf "  dev       Build, run, and rebuild on changes\n"
-        printf "  docs      Generate the committed docs/reference tree; --check verifies sync\n"
-        printf "  check     Check types, lint, formatting, and unused code\n"
-        printf "  fix       Auto-fix lint and formatting issues\n"
-        printf "  clean     Remove .artifacts/ — dist/ stays, it is the build's product\n\n"
+        printf "  build        Build application (ESM + types)\n"
+        printf "  bundle       Bundle library (ESM + CJS + types)\n"
+        printf "  start        Run the built application\n"
+        printf "  dev          Build, run, and rebuild on changes\n"
+        printf "  docs         Generate the committed docs/reference tree; --check verifies sync\n"
+        printf "  docs-layout  Check a repository's docs/ against the manual spine\n"
+        printf "  check        Check types, lint, formatting, and unused code\n"
+        printf "  fix          Auto-fix lint and formatting issues\n"
+        printf "  clean        Remove .artifacts/ — dist/ stays, it is the build's product\n\n"
         printf "Examples:\n"
         printf "  typescript build\n"
         printf "  typescript bundle\n"
@@ -183,6 +192,7 @@ case "$COMMAND" in
         printf "  typescript dev\n"
         printf "  typescript docs\n"
         printf "  typescript docs --check\n"
+        printf "  typescript docs-layout .\n"
         printf "  typescript check\n"
         printf "  typescript fix\n"
         printf "  typescript clean\n"

package/lib/check-docs.js

@@ -0,0 +1,150 @@
+#!/usr/bin/env node
+
+/**
+ * The shape of a repository's manual, read off the filesystem and judged by
+ * `@jterrazz/typescript/docs`.
+ *
+ * Every repository carries the same `docs/`: a map, the fixed spine —
+ * architecture, developing, testing, and operating when the repository ships
+ * something that runs — and its own chapters numbered contiguously after it.
+ * This file is the READER: it builds the plain tree the rule engine takes
+ * (`src/docs.js`) and prints what comes back. Every sentence, every rule id and
+ * the journal-word roster live in the engine, so a second reader — terra,
+ * sweeping clones it never installed — judges by the same copy.
+ *
+ * Usage: node check-docs.js [root]
+ *
+ * One line per violation, `<rule>  <path>  <message>`. Exit code: 0 when the
+ * repository holds the shape, 1 otherwise.
+ *
+ * The unit is the REPOSITORY, not the package: a manual answers for the whole
+ * tree, and only the root carries the `AGENTS.md` that routes into it. The one
+ * place the workspace shows through is the `04-operating.md` presence test,
+ * whose Dockerfile and `.infrastructure/` clauses are read at the root AND at
+ * every workspace member's root — a monorepo deploys from a member as readily
+ * as from its root (ADR-007, the toolchain's unit is the workspace package).
+ * The publishable clause stays on the ROOT manifest: a private root that holds
+ * a publishable member is a question for its owner, not a verdict for a gate.
+ */
+
+import { existsSync, readdirSync, readFileSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import { argv, exit, stdout } from 'node:process';
+
+import { auditDocs, HEAD_LINES } from '../src/docs.js';
+import { workspaceMembers } from './workspace-members.js';
+
+/** Every markdown link target of a page, in the order the page carries them. */
+const LINK = /!?\[[^\]]*]\(\s*(?<target>[^\s)]+)/g;
+
+/** Where a repository declares a deployment it owns. */
+const INFRASTRUCTURE = '.infrastructure';
+
+/**
+ * Every path under `docs/`, repository-relative, directories carrying a
+ * trailing slash. `docs/` itself is the first entry when it exists — its
+ * absence is the whole verdict.
+ */
+function listDocs(root) {
+    const paths = [];
+
+    /** One directory, depth-first, sorted — a listing a machine can diff. */
+    function walk(relativePath) {
+        paths.push(`${relativePath}/`);
+
+        const entries = readdirSync(join(root, relativePath), { withFileTypes: true });
+        for (const entry of entries.sort((a, b) => (a.name < b.name ? -1 : 1))) {
+            const child = `${relativePath}/${entry.name}`;
+            if (entry.isDirectory()) {
+                walk(child);
+            } else {
+                paths.push(child);
+            }
+        }
+    }
+
+    if (existsSync(join(root, 'docs'))) {
+        walk('docs');
+    }
+
+    return paths;
+}
+
+/** A file's text, or null when it is not there — an unreadable file is an absent one. */
+function read(path) {
+    try {
+        return readFileSync(path, 'utf8');
+    } catch {
+        return null;
+    }
+}
+
+/** The head and the links of every markdown page of the tree. */
+function readPages(root, files) {
+    const heads = {};
+    const links = {};
+
+    for (const path of files) {
+        if (!path.endsWith('.md')) {
+            continue;
+        }
+
+        const text = read(join(root, path)) ?? '';
+        heads[path] = text.split('\n').slice(0, HEAD_LINES);
+        links[path] = [...text.matchAll(LINK)].map((match) => match.groups.target);
+    }
+
+    return { heads, links };
+}
+
+/** A `Dockerfile`, or one of its variants, in a directory. */
+function hasDockerfile(dir) {
+    try {
+        return readdirSync(dir).some(
+            (name) => name === 'Dockerfile' || name.startsWith('Dockerfile.'),
+        );
+    } catch {
+        return false;
+    }
+}
+
+/** A manifest that npm would publish — one that never says it is private. */
+function isPublishable(dir) {
+    const manifest = read(join(dir, 'package.json'));
+    if (manifest === null) {
+        return false;
+    }
+
+    try {
+        return JSON.parse(manifest).private !== true;
+    } catch {
+        return false;
+    }
+}
+
+/** The three facts `04-operating.md` is asked for, read at the root and its members. */
+function readShips(root) {
+    const roots = [root, ...workspaceMembers(root).map((member) => join(root, member))];
+
+    return {
+        dockerfile: roots.some((dir) => hasDockerfile(dir)),
+        infrastructure: roots.some((dir) => existsSync(join(dir, INFRASTRUCTURE))),
+        publishable: isPublishable(root),
+    };
+}
+
+const root = resolve(argv.slice(2).find((argument) => !argument.startsWith('--')) ?? '.');
+const files = listDocs(root);
+
+const violations = auditDocs({
+    agents: read(join(root, 'AGENTS.md')),
+    files,
+    ...readPages(root, files),
+    ships: readShips(root),
+});
+
+for (const violation of violations) {
+    stdout.write(`${violation.rule}  ${violation.path}  ${violation.message}\n`);
+}
+
+exit(violations.length > 0 ? 1 : 0);

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@jterrazz/typescript",
-    "version": "9.1.1",
+    "version": "9.2.1",
     "author": "Jean-Baptiste Terrazzoni <contact@jterrazz.com>",
     "repository": {
         "type": "git",
@@ -23,6 +23,10 @@
             "types": "./src/index.d.ts",
             "default": "./src/index.js"
         },
+        "./docs": {
+            "types": "./src/docs.d.ts",
+            "default": "./src/docs.js"
+        },
         "./oxfmt": {
             "types": "./src/oxfmt.d.ts",
             "default": "./src/oxfmt.js"

package/src/docs.d.ts

@@ -0,0 +1,42 @@
+/** The `docs/` tree of one repository, as a rule engine needs to see it. */
+export interface DocsTree {
+    /** The root `AGENTS.md`, its whole text, or `null` when the repository has none. */
+    readonly agents: null | string;
+    /**
+     * Every path under `docs/`, repository-relative, sorted, directories carrying
+     * a trailing slash — `docs/` itself included, whose absence IS `docs-absent`.
+     */
+    readonly files: readonly string[];
+    /**
+     * The opening lines of each file a rule reads — a decision record's head, a
+     * reference page's generation stamp. The reader supplies the first
+     * `HEAD_LINES` of every markdown file under `docs/`; no rule looks further
+     * down a page, so a `**Status:**` below that line is a status the manual
+     * does not declare.
+     */
+    readonly heads: Readonly<Record<string, readonly string[]>>;
+    /** Every markdown link target of each file under `docs/`, in the order the page carries them. */
+    readonly links: Readonly<Record<string, readonly string[]>>;
+    /** The three facts the `04-operating.md` presence test is derived from. */
+    readonly ships: {
+        /** A `Dockerfile` at the repository root or at a workspace member's. */
+        readonly dockerfile: boolean;
+        /** An `.infrastructure/` directory at either. */
+        readonly infrastructure: boolean;
+        /** A `package.json` at either that is not `"private": true`. */
+        readonly publishable: boolean;
+    };
+}
+
+/** One broken rule, naming the path it is about and the sentence the gate prints. */
+export interface DocsViolation {
+    readonly message: string;
+    readonly path: string;
+    readonly rule: string;
+}
+
+/** How many opening lines of a file a rule may read. */
+export declare const HEAD_LINES: number;
+
+/** What breaks the shape of `docs/`, in rule order. An empty array is a compliant manual. */
+export declare function auditDocs(tree: DocsTree): readonly DocsViolation[];

package/src/docs.js

@@ -0,0 +1,446 @@
+/**
+ * The shape of a repository's `docs/`, judged as a pure function.
+ *
+ * Every repository carries the same manual: a map at `docs/README.md`, a fixed
+ * spine — architecture, developing, testing, and operating when the repository
+ * ships something that runs — and its own chapters numbered contiguously after
+ * it. `auditDocs` takes a plain description of that tree and returns what
+ * breaks the shape. Nothing here reads the filesystem, so the same rules judge
+ * a project running `typescript check` and a clone nobody installed anything
+ * into.
+ *
+ * This module is the single executable copy of the rule ids AND of the sentence
+ * each one prints. A page names the ids and what each refuses; it never spells
+ * a message, so the two cannot drift.
+ */
+
+/** How many opening lines of a file a rule may read — the reader supplies them. */
+export const HEAD_LINES = 20;
+
+/** The four reserved numbers, in order: position 01 through 04. */
+const SPINE = ['01-architecture.md', '02-developing.md', '03-testing.md', '04-operating.md'];
+
+/** The three the spine REQUIRES; 04 is required only by the presence test. */
+const REQUIRED_SPINE = SPINE.slice(0, 3);
+
+/** The only subfolders `docs/` may hold. */
+const SUBFOLDERS = new Set(['_assets/', 'decisions/', 'reference/']);
+
+/**
+ * The closed roster of journal words. A chapter names a SUBJECT the repository
+ * has, never the state of a piece of work: the record of a decision is an ADR,
+ * and the history is git's. This is the roster's one copy — no page keeps a
+ * second one.
+ */
+const JOURNAL_WORDS = new Set([
+    'draft',
+    'exploration',
+    'legacy',
+    'misc',
+    'notes',
+    'old',
+    'proposal',
+    'review',
+    'todo',
+    'wip',
+]);
+
+/** The closed status vocabulary of a decision record. */
+const STATUSES = new Set(['Proposed', 'Accepted', 'Deprecated']);
+
+/**
+ * The fourth status carries the record that replaced it, as a link a reader
+ * can follow — a citation is a place a human can look, not just a number.
+ */
+const SUPERSEDED = /^Superseded by \[ADR-\d{3}\]\([^)]+\)$/;
+
+/** The same status named but not linked — the successor exists, the citation does not. */
+const BARE_SUPERSEDED = /^Superseded by ADR-\d{3}$/;
+
+/** What a chapter's file name must be: two digits, lowercase words, single hyphens. */
+const CHAPTER_NAME = /^\d{2}-[a-z\d]+(?:-[a-z\d]+)*\.md$/;
+
+/** What a decision record's file name must be: three digits, then the same words. */
+const DECISION_NAME = /^\d{3}-[a-z\d]+(?:-[a-z\d]+)*\.md$/;
+
+/** A decision record's first heading, carrying the number the file claims. */
+const DECISION_HEADING = /^# ADR-(?<number>\d{3}): \S/;
+
+/** The `**Status:**` line of a decision record, wherever it sits in the head. */
+const DECISION_STATUS = /^\*\*Status:\*\*\s*(?<status>.+?)\s*$/;
+
+/** The marker every file under `reference/` carries — it is generated, never authored. */
+const GENERATED = 'GENERATED';
+
+/** A link with a scheme (`https:`, `mailto:`) cites; it never reaches into a tree. */
+const SCHEME = /^[a-z][\d+.a-z-]*:/i;
+
+/** What each of the three presence facts means, in the sentence `04` is asked for. */
+const SHIPPING_REASONS = [
+    ['dockerfile', 'an image (a Dockerfile)'],
+    ['infrastructure', 'a deployment (.infrastructure/)'],
+    ['publishable', 'a published package (package.json is not private)'],
+];
+
+/** Directly under `docs/` — a file, or a directory with its trailing slash. */
+function directChildren(files) {
+    return files.filter((path) => /^docs\/[^/]+\/?$/.test(path));
+}
+
+/** Everything under a folder of `docs/`, named relative to that folder. */
+function under(files, folder) {
+    const prefix = `docs/${folder}`;
+
+    return files
+        .filter((path) => path.startsWith(prefix) && !path.endsWith('/'))
+        .map((path) => ({ name: path.slice(prefix.length), path }));
+}
+
+/** A number as a chapter writes it — two digits, more only when it has to. */
+function padded(value) {
+    return String(value).padStart(2, '0');
+}
+
+/** The link target itself, without the anchor a reader lands on. */
+function targetPath(link) {
+    return link.split('#')[0].replace(/^\.\//, '');
+}
+
+/** A link that names a chapter of the same folder — `03-testing.md`, no slash. */
+function isChapterLink(target) {
+    return /^\d/.test(target) && !target.includes('/');
+}
+
+/**
+ * A link resolved against the page carrying it, `..` folded. A result that
+ * still opens on `..` climbed above the repository root: it reaches into
+ * another tree.
+ */
+function resolveLink(from, link) {
+    const stack = [];
+
+    for (const segment of [...from.split('/').slice(0, -1), ...link.split('/')]) {
+        if (segment === '' || segment === '.') {
+            continue;
+        }
+        if (segment !== '..') {
+            stack.push(segment);
+        } else if (stack.length === 0 || stack.at(-1) === '..') {
+            stack.push('..');
+        } else {
+            stack.pop();
+        }
+    }
+
+    return stack.join('/');
+}
+
+/** The map's verdicts: it exists, it is bijective with the chapters, it routes nowhere else. */
+function auditMap(report, { chapters, files, links }) {
+    if (!files.includes('docs/README.md')) {
+        report(
+            'docs-map-missing',
+            'docs/README.md',
+            'docs/README.md is missing — the map is the one file an outside corpus points at',
+        );
+
+        return;
+    }
+
+    const rows = [...new Set(links.map((link) => targetPath(link)).filter(isChapterLink))];
+
+    for (const row of rows) {
+        if (!chapters.some((chapter) => chapter.name === row)) {
+            report(
+                'docs-map-drift',
+                'docs/README.md',
+                `docs/README.md and the chapters disagree: ${row} has no file`,
+            );
+        }
+    }
+    for (const chapter of chapters) {
+        if (!rows.includes(chapter.name)) {
+            report(
+                'docs-map-drift',
+                'docs/README.md',
+                `docs/README.md and the chapters disagree: ${chapter.name} has no row`,
+            );
+        }
+    }
+
+    for (const link of links) {
+        const target = targetPath(link);
+        const routes =
+            target === '' ||
+            isChapterLink(target) ||
+            target.startsWith('decisions/') ||
+            target.startsWith('reference/');
+
+        if (!routes) {
+            report(
+                'docs-map-foreign-link',
+                'docs/README.md',
+                `docs/README.md links ${link}: the map routes to its own chapters and nothing else`,
+            );
+        }
+    }
+}
+
+/** The chapters: their names, their numbering, the four reserved positions, their subjects. */
+function auditChapters(report, { chapters, ships }) {
+    for (const chapter of chapters) {
+        if (!CHAPTER_NAME.test(chapter.name)) {
+            report(
+                'docs-chapter-name',
+                chapter.path,
+                `${chapter.path} is not NN-kebab.md — two digits, lowercase words, single hyphens`,
+            );
+        }
+    }
+
+    const numbers = chapters.map((chapter) => chapter.number).sort((a, b) => a - b);
+    const hasOperating = numbers.includes(4);
+    // 04 is the one number the spine never requires (`docs-operating-missing`
+    // Asks for it on its own terms), so a run missing it is still contiguous —
+    // Every number from 05 on shifts down one slot to close the gap.
+    const expected = (index) => (!hasOperating && index + 1 >= 4 ? index + 2 : index + 1);
+    const contiguous = numbers.every((number, index) => number === expected(index));
+    if (numbers.length > 0 && !contiguous) {
+        report(
+            'docs-chapter-numbering',
+            'docs/',
+            `chapter numbers run ${numbers.map(padded).join(', ')}: they are contiguous from 01, one file per number, except that 04 may be absent`,
+        );
+    }
+
+    for (const chapter of chapters) {
+        const reserved = SPINE[chapter.number - 1];
+        if (reserved !== undefined && chapter.name !== reserved) {
+            report(
+                'docs-spine-name',
+                chapter.path,
+                `${chapter.path} takes number ${padded(chapter.number)}, which is reserved for ${reserved}`,
+            );
+        }
+    }
+
+    for (const name of REQUIRED_SPINE) {
+        if (!chapters.some((chapter) => chapter.name === name)) {
+            report(
+                'docs-spine-missing',
+                `docs/${name}`,
+                `${name} is missing — the spine is architecture, developing, testing`,
+            );
+        }
+    }
+
+    const operating = SPINE[3];
+    const reason = SHIPPING_REASONS.find(([fact]) => ships?.[fact])?.[1];
+    if (reason !== undefined && !chapters.some((chapter) => chapter.name === operating)) {
+        report(
+            'docs-operating-missing',
+            `docs/${operating}`,
+            `${operating} is missing — this repository ships ${reason}`,
+        );
+    }
+
+    for (const chapter of chapters) {
+        const word = chapter.name.split(/[.-]/).find((segment) => JOURNAL_WORDS.has(segment));
+        if (word !== undefined) {
+            report(
+                'docs-journal-chapter',
+                chapter.path,
+                `${chapter.path} names a journal, not a subject — ${word}; the record is an ADR, the history is git's`,
+            );
+        }
+    }
+}
+
+/** What sits directly under `docs/` and is neither the map, a chapter, nor one of the three folders. */
+function auditFolder(report, { children }) {
+    for (const path of children) {
+        const name = path.slice('docs/'.length);
+
+        if (name.endsWith('/')) {
+            if (!SUBFOLDERS.has(name)) {
+                report(
+                    'docs-foreign-folder',
+                    path,
+                    `${path} is not one of decisions/, reference/, _assets/`,
+                );
+            }
+        } else if (name !== 'README.md' && !/^\d/.test(name)) {
+            report(
+                'docs-loose-file',
+                path,
+                `${path} is neither the map nor a chapter — number it, or move it under _assets/`,
+            );
+        }
+    }
+}
+
+/** One decision record: the name it takes, the heading it opens on, the status it declares. */
+function auditRecord(report, record, heads) {
+    const number = record.name.slice(0, 3);
+    const head = heads[record.path] ?? [];
+    const opening = head[0] ?? '';
+
+    if (DECISION_HEADING.exec(opening)?.groups?.number !== number) {
+        report(
+            'docs-decision-heading',
+            record.path,
+            `${record.path} opens on ${opening === '' ? 'an empty line' : opening}: the mold is "# ADR-${number}: Title"`,
+        );
+    }
+
+    const status = head.map((line) => DECISION_STATUS.exec(line)?.groups?.status).find(Boolean);
+    if (status === undefined || !(STATUSES.has(status) || SUPERSEDED.test(status))) {
+        const message =
+            status !== undefined && BARE_SUPERSEDED.test(status)
+                ? `${record.path}: **Status:** names a successor but no link — write Superseded by [ADR-NNN](file.md)`
+                : `${record.path}: **Status:** is none of Proposed, Accepted, Superseded by [ADR-NNN](file.md), Deprecated`;
+        report('docs-decision-status', record.path, message);
+    }
+}
+
+/** The `decisions/` folder: its records, its numbering, its mold, and the index it never keeps. */
+function auditDecisions(report, { files, heads }) {
+    if (!files.includes('docs/decisions/')) {
+        return;
+    }
+
+    const entries = under(files, 'decisions/');
+
+    for (const entry of entries) {
+        if (entry.name !== '_template.md' && entry.name !== 'README.md') {
+            if (!DECISION_NAME.test(entry.name)) {
+                report('docs-decision-name', entry.path, `${entry.path} is not NNN-kebab.md`);
+            }
+        }
+    }
+
+    const records = entries.filter((entry) => /^\d{3}-/.test(entry.name));
+    for (const record of records) {
+        auditRecord(report, record, heads);
+    }
+
+    const claimed = new Map();
+    for (const record of records) {
+        const number = record.name.slice(0, 3);
+        const first = claimed.get(number);
+
+        if (first === undefined) {
+            claimed.set(number, record.name);
+        } else {
+            report(
+                'docs-decision-number',
+                'docs/decisions/',
+                `ADR-${number} is claimed by ${first} and ${record.name}`,
+            );
+        }
+    }
+
+    if (files.includes('docs/decisions/README.md')) {
+        report(
+            'docs-decision-index',
+            'docs/decisions/README.md',
+            'docs/decisions/README.md is an index — an index is a copy; the queue is derived (terra <brand> decisions)',
+        );
+    }
+
+    if (!files.includes('docs/decisions/_template.md')) {
+        report(
+            'docs-template-missing',
+            'docs/decisions/_template.md',
+            'docs/decisions/_template.md is missing — the mold sits where the record is written',
+        );
+    }
+}
+
+/** Every page under `reference/` says so on its first line: it is a projection. */
+function auditReference(report, { files, heads }) {
+    for (const entry of under(files, 'reference/')) {
+        if (!entry.name.endsWith('.md')) {
+            continue;
+        }
+        if (!(heads[entry.path]?.[0] ?? '').includes(GENERATED)) {
+            report(
+                'docs-reference-unstamped',
+                entry.path,
+                `${entry.path} carries no ${GENERATED} marker — reference/ is a projection, never authored`,
+            );
+        }
+    }
+}
+
+/** No page of the manual reaches into a tree the repository does not own. */
+function auditLinks(report, { files, links }) {
+    for (const path of files) {
+        for (const link of links[path] ?? []) {
+            if (link.startsWith('#') || SCHEME.test(link)) {
+                continue;
+            }
+            if (link.startsWith('/') || resolveLink(path, link).startsWith('..')) {
+                report(
+                    'docs-cross-repo-link',
+                    path,
+                    `${path} links ${link}: another repository's tree is not a place this manual may reach`,
+                );
+            }
+        }
+    }
+}
+
+/**
+ * What breaks the shape of `docs/`, in rule order, each violation naming the
+ * path it is about. An empty array is a compliant manual.
+ *
+ * A repository with no `docs/` gets exactly one violation: every other rule
+ * would restate the same absence, and one sentence is the whole answer.
+ */
+export function auditDocs(tree) {
+    const files = tree.files ?? [];
+
+    if (!files.includes('docs/')) {
+        return [
+            {
+                message:
+                    'docs/ is missing — every repository carries its own manual, starting at docs/README.md',
+                path: 'docs/',
+                rule: 'docs-absent',
+            },
+        ];
+    }
+
+    const violations = [];
+    const report = (rule, path, message) => violations.push({ message, path, rule });
+
+    const children = directChildren(files);
+    const chapters = children
+        .filter((path) => !path.endsWith('/') && /^\d/.test(path.slice('docs/'.length)))
+        .map((path) => ({
+            name: path.slice('docs/'.length),
+            number: Number.parseInt(path.slice('docs/'.length), 10),
+            path,
+        }));
+    const heads = tree.heads ?? {};
+    const links = tree.links ?? {};
+
+    auditMap(report, { chapters, files, links: links['docs/README.md'] ?? [] });
+    auditChapters(report, { chapters, ships: tree.ships });
+    auditFolder(report, { children });
+    auditDecisions(report, { files, heads });
+    auditReference(report, { files, heads });
+
+    if (tree.agents === null || !(tree.agents ?? '').includes('docs/README.md')) {
+        report(
+            'docs-agents-route',
+            'AGENTS.md',
+            'AGENTS.md does not route to docs/README.md — the brief is a map, not a manual',
+        );
+    }
+
+    auditLinks(report, { files, links });
+
+    return violations;
+}

package/src/docs.test.ts

@@ -0,0 +1,524 @@
+import { expect, test } from 'vitest';
+
+import { auditDocs } from './docs.js';
+
+/**
+ * The manual every repository carries, in its smallest compliant form: a map,
+ * the three required spine chapters, and a brief that routes into it. Each test
+ * breaks exactly one thing and reads the rule that names it.
+ */
+function manual(overrides: Record<string, unknown> = {}) {
+    return {
+        agents: '# Agent brief\n\nThe corpus is docs/README.md.\n',
+        files: [
+            'docs/',
+            'docs/01-architecture.md',
+            'docs/02-developing.md',
+            'docs/03-testing.md',
+            'docs/README.md',
+        ],
+        heads: {},
+        links: {
+            'docs/README.md': ['01-architecture.md', '02-developing.md', '03-testing.md'],
+        },
+        ships: { dockerfile: false, infrastructure: false, publishable: false },
+        ...overrides,
+    };
+}
+
+/** The rule ids a tree breaks, in the order the engine reports them. */
+function rules(tree: ReturnType<typeof manual>) {
+    return auditDocs(tree as never).map((violation) => violation.rule);
+}
+
+/** The sentence one rule printed about a tree. */
+function sentence(tree: ReturnType<typeof manual>, rule: string) {
+    return auditDocs(tree as never).find((violation) => violation.rule === rule)?.message;
+}
+
+test('passes the smallest compliant manual', () => {
+    // Given - a map, the three spine chapters, a brief that routes into them
+    // Then - nothing to say
+    expect(auditDocs(manual() as never)).toEqual([]);
+});
+
+test('names a repository that carries no manual at all, and says nothing else', () => {
+    // Given - a repository with no docs/ directory
+    const tree = manual({ agents: null, files: [] });
+
+    // Then - one sentence, not a cascade of every rule the absence breaks
+    expect(rules(tree)).toEqual(['docs-absent']);
+    expect(sentence(tree, 'docs-absent')).toBe(
+        'docs/ is missing — every repository carries its own manual, starting at docs/README.md',
+    );
+});
+
+test('names a docs/ with no map', () => {
+    // Given - chapters with no README.md to route into them
+    const tree = manual({
+        files: ['docs/', 'docs/01-architecture.md', 'docs/02-developing.md', 'docs/03-testing.md'],
+        links: {},
+    });
+
+    // Then - the map is the one file an outside corpus points at
+    expect(rules(tree)).toEqual(['docs-map-missing']);
+    expect(sentence(tree, 'docs-map-missing')).toBe(
+        'docs/README.md is missing — the map is the one file an outside corpus points at',
+    );
+});
+
+test('names a map that routes to a chapter nobody wrote', () => {
+    // Given - a row for a fourth chapter that does not exist
+    const tree = manual({
+        links: {
+            'docs/README.md': [
+                '01-architecture.md',
+                '02-developing.md',
+                '03-testing.md',
+                '05-presets.md',
+            ],
+        },
+    });
+
+    // Then - the drift is named from the map's side
+    expect(sentence(tree, 'docs-map-drift')).toBe(
+        'docs/README.md and the chapters disagree: 05-presets.md has no file',
+    );
+});
+
+test('names a chapter the map forgot', () => {
+    // Given - a fourth chapter with no row
+    const tree = manual({
+        files: [...manual().files, 'docs/04-operating.md'],
+    });
+
+    // Then - the drift is named from the chapter's side
+    expect(sentence(tree, 'docs-map-drift')).toBe(
+        'docs/README.md and the chapters disagree: 04-operating.md has no row',
+    );
+});
+
+test('names a map link that leaves the manual', () => {
+    // Given - a map routing to the repository's own README
+    const tree = manual({
+        links: { 'docs/README.md': [...manual().links['docs/README.md'], '../README.md'] },
+    });
+
+    // Then - the map routes to chapters, decisions/ and reference/, and nothing else
+    expect(sentence(tree, 'docs-map-foreign-link')).toBe(
+        'docs/README.md links ../README.md: the map routes to its own chapters and nothing else',
+    );
+});
+
+test('lets the map route to decisions/ and reference/', () => {
+    // Given - the two folders a map may point at
+    const tree = manual({
+        links: {
+            'docs/README.md': [
+                ...manual().links['docs/README.md'],
+                'decisions/',
+                'reference/index.md',
+            ],
+        },
+    });
+
+    // Then - neither is foreign
+    expect(rules(tree)).toEqual([]);
+});
+
+test('names a chapter that is not NN-kebab.md', () => {
+    // Given - a fourth chapter with one digit and an upper-case word
+    const tree = manual({
+        files: [...manual().files, 'docs/4-Lint_presets.md'],
+        links: { 'docs/README.md': [...manual().links['docs/README.md'], '4-Lint_presets.md'] },
+    });
+
+    // Then - the mold is named, and the number it took is still judged
+    expect(sentence(tree, 'docs-chapter-name')).toBe(
+        'docs/4-Lint_presets.md is not NN-kebab.md — two digits, lowercase words, single hyphens',
+    );
+});
+
+test('names chapter numbers that skip, and numbers claimed twice', () => {
+    // Given - two chapters numbered 05 and none numbered 04
+    const tree = manual({
+        files: [...manual().files, 'docs/05-building.md', 'docs/05-presets.md'],
+        links: {
+            'docs/README.md': [
+                ...manual().links['docs/README.md'],
+                '05-building.md',
+                '05-presets.md',
+            ],
+        },
+    });
+
+    // Then - one sentence about the whole run
+    expect(sentence(tree, 'docs-chapter-numbering')).toBe(
+        'chapter numbers run 01, 02, 03, 05, 05: they are contiguous from 01, one file per number, except that 04 may be absent',
+    );
+});
+
+test('names a chapter sitting on a reserved number', () => {
+    // Given - a getting-started chapter taking position 01
+    const tree = manual({
+        files: ['docs/', 'docs/01-getting-started.md', 'docs/README.md'],
+        links: { 'docs/README.md': ['01-getting-started.md'] },
+    });
+
+    // Then - the position names its owner
+    expect(sentence(tree, 'docs-spine-name')).toBe(
+        'docs/01-getting-started.md takes number 01, which is reserved for 01-architecture.md',
+    );
+});
+
+test('names each missing spine chapter', () => {
+    // Given - a manual holding architecture alone
+    const tree = manual({
+        files: ['docs/', 'docs/01-architecture.md', 'docs/README.md'],
+        links: { 'docs/README.md': ['01-architecture.md'] },
+    });
+
+    // Then - developing and testing are each asked for
+    expect(rules(tree)).toEqual(['docs-spine-missing', 'docs-spine-missing']);
+    expect(sentence(tree, 'docs-spine-missing')).toBe(
+        '02-developing.md is missing — the spine is architecture, developing, testing',
+    );
+});
+
+test('asks for 04-operating.md from a repository that ships an image', () => {
+    // Given - a Dockerfile at the root or at a workspace member's root
+    const tree = manual({ ships: { dockerfile: true, infrastructure: false, publishable: false } });
+
+    // Then - the reason it is asked for is named
+    expect(sentence(tree, 'docs-operating-missing')).toBe(
+        '04-operating.md is missing — this repository ships an image (a Dockerfile)',
+    );
+});
+
+test('asks for 04-operating.md from a published package', () => {
+    // Given - a manifest that never says it is private
+    const tree = manual({ ships: { dockerfile: false, infrastructure: false, publishable: true } });
+
+    // Then - the third clause of the presence test speaks
+    expect(sentence(tree, 'docs-operating-missing')).toBe(
+        '04-operating.md is missing — this repository ships a published package (package.json is not private)',
+    );
+});
+
+test('never asks for 04-operating.md from a repository that ships nothing', () => {
+    // Given - no image, no infrastructure, a private manifest
+    // Then - the lint only ever requires; it never forbids a 04 either
+    expect(rules(manual())).toEqual([]);
+});
+
+test('lets 05 follow 03 directly when the repository ships nothing', () => {
+    // Given - 01-03 then 05, no 04 chapter, nothing that would ask for one
+    const tree = manual({
+        files: [...manual().files, 'docs/05-building.md'],
+        links: { 'docs/README.md': [...manual().links['docs/README.md'], '05-building.md'] },
+    });
+
+    // Then - 04 is the one gap the numbering excuses
+    expect(rules(tree)).toEqual([]);
+});
+
+test('still asks for 04-operating.md from that same shape once it ships', () => {
+    // Given - the same 01-03 + 05 shape, but an image this time
+    const tree = manual({
+        files: [...manual().files, 'docs/05-building.md'],
+        links: { 'docs/README.md': [...manual().links['docs/README.md'], '05-building.md'] },
+        ships: { dockerfile: true, infrastructure: false, publishable: false },
+    });
+
+    // Then - the numbering stays clean; only the presence test speaks
+    expect(rules(tree)).toEqual(['docs-operating-missing']);
+});
+
+test('refuses a gap at 05 even though 04 may be absent', () => {
+    // Given - 01-03 then 06, skipping past the one number the spine excuses
+    const tree = manual({
+        files: [...manual().files, 'docs/06-quality-checks.md'],
+        links: { 'docs/README.md': [...manual().links['docs/README.md'], '06-quality-checks.md'] },
+    });
+
+    // Then - only 04 is excused; 05 still has to be there
+    expect(rules(tree)).toEqual(['docs-chapter-numbering']);
+});
+
+test('names a chapter that is a journal, not a subject', () => {
+    // Given - a fourth chapter recording a design exploration
+    const tree = manual({
+        files: [...manual().files, 'docs/04-design-exploration.md'],
+        links: {
+            'docs/README.md': [...manual().links['docs/README.md'], '04-design-exploration.md'],
+        },
+    });
+
+    // Then - the word is named, and so is where that content belongs
+    expect(sentence(tree, 'docs-journal-chapter')).toBe(
+        "docs/04-design-exploration.md names a journal, not a subject — exploration; the record is an ADR, the history is git's",
+    );
+});
+
+test('names a subfolder that is none of the three', () => {
+    // Given - a folder of dated QA passes under docs/
+    const tree = manual({ files: [...manual().files, 'docs/qa/', 'docs/qa/2026-01.md'] });
+
+    // Then - the three are named
+    expect(sentence(tree, 'docs-foreign-folder')).toBe(
+        'docs/qa/ is not one of decisions/, reference/, _assets/',
+    );
+});
+
+test('names a file under docs/ that is neither the map nor a chapter', () => {
+    // Given - an unnumbered page dropped beside the chapters
+    const tree = manual({ files: [...manual().files, 'docs/automations.md'] });
+
+    // Then - number it, or move it out of the chapter space
+    expect(sentence(tree, 'docs-loose-file')).toBe(
+        'docs/automations.md is neither the map nor a chapter — number it, or move it under _assets/',
+    );
+});
+
+/** A decisions/ folder holding one well-formed record — the ground the decision rules judge. */
+function withDecisions(overrides: Record<string, unknown> = {}) {
+    return manual({
+        files: [
+            ...manual().files,
+            'docs/decisions/',
+            'docs/decisions/001-the-first-call.md',
+            'docs/decisions/_template.md',
+        ],
+        heads: {
+            'docs/decisions/001-the-first-call.md': [
+                '# ADR-001: The first call',
+                '',
+                '**Status:** Accepted',
+            ],
+        },
+        ...overrides,
+    });
+}
+
+test('passes a well-formed decisions folder', () => {
+    // Given - one record on the mold, beside the mold itself
+    // Then - nothing to say
+    expect(rules(withDecisions())).toEqual([]);
+});
+
+test('names a decision file that is not NNN-kebab.md', () => {
+    // Given - a record named without its number
+    const tree = withDecisions({
+        files: [...withDecisions().files, 'docs/decisions/the-second-call.md'],
+    });
+
+    // Then - the mold of the name is stated
+    expect(sentence(tree, 'docs-decision-name')).toBe(
+        'docs/decisions/the-second-call.md is not NNN-kebab.md',
+    );
+});
+
+test('names a decision opening on the wrong heading', () => {
+    // Given - a record whose title forgets the ADR number
+    const tree = withDecisions({
+        heads: {
+            'docs/decisions/001-the-first-call.md': [
+                '# The first call',
+                '',
+                '**Status:** Accepted',
+            ],
+        },
+    });
+
+    // Then - the line it opens on, and the mold it owes
+    expect(sentence(tree, 'docs-decision-heading')).toBe(
+        'docs/decisions/001-the-first-call.md opens on # The first call: the mold is "# ADR-001: Title"',
+    );
+});
+
+test('names a decision whose heading claims another number', () => {
+    // Given - a record numbered 001 titled ADR-002
+    const tree = withDecisions({
+        heads: {
+            'docs/decisions/001-the-first-call.md': [
+                '# ADR-002: The first call',
+                '',
+                '**Status:** Accepted',
+            ],
+        },
+    });
+
+    // Then - the same rule catches the disagreement
+    expect(rules(tree)).toEqual(['docs-decision-heading']);
+});
+
+test('names a decision outside the status vocabulary', () => {
+    // Given - a record declaring a status nobody defined
+    const tree = withDecisions({
+        heads: {
+            'docs/decisions/001-the-first-call.md': [
+                '# ADR-001: The first call',
+                '',
+                '**Status:** Draft',
+            ],
+        },
+    });
+
+    // Then - the four the vocabulary holds
+    expect(sentence(tree, 'docs-decision-status')).toBe(
+        'docs/decisions/001-the-first-call.md: **Status:** is none of Proposed, Accepted, Superseded by [ADR-NNN](file.md), Deprecated',
+    );
+});
+
+test('accepts a superseded status that links the record replacing it', () => {
+    // Given - the one status carrying an argument, written as a citation
+    const tree = withDecisions({
+        heads: {
+            'docs/decisions/001-the-first-call.md': [
+                '# ADR-001: The first call',
+                '',
+                '**Status:** Superseded by [ADR-014](014-the-later-call.md)',
+            ],
+        },
+    });
+
+    // Then - nothing to say
+    expect(rules(tree)).toEqual([]);
+});
+
+test('refuses a superseded status with no link naming the successor', () => {
+    // Given - the bare form: a successor is named, but not as a place to look
+    const tree = withDecisions({
+        heads: {
+            'docs/decisions/001-the-first-call.md': [
+                '# ADR-001: The first call',
+                '',
+                '**Status:** Superseded by ADR-014',
+            ],
+        },
+    });
+
+    // Then - the missing link is the whole complaint
+    expect(sentence(tree, 'docs-decision-status')).toBe(
+        'docs/decisions/001-the-first-call.md: **Status:** names a successor but no link — write Superseded by [ADR-NNN](file.md)',
+    );
+});
+
+test('names a number two records claim', () => {
+    // Given - two records numbered 001
+    const tree = withDecisions({
+        files: [...withDecisions().files, 'docs/decisions/001-the-same-call.md'],
+        heads: {
+            ...withDecisions().heads,
+            'docs/decisions/001-the-same-call.md': [
+                '# ADR-001: The same call',
+                '',
+                '**Status:** Proposed',
+            ],
+        },
+    });
+
+    // Then - both claimants are named
+    expect(sentence(tree, 'docs-decision-number')).toBe(
+        'ADR-001 is claimed by 001-the-first-call.md and 001-the-same-call.md',
+    );
+});
+
+test('names a hand-written decisions index', () => {
+    // Given - a README.md listing the records
+    const tree = withDecisions({ files: [...withDecisions().files, 'docs/decisions/README.md'] });
+
+    // Then - an index is a copy, and the queue is derived
+    expect(sentence(tree, 'docs-decision-index')).toBe(
+        'docs/decisions/README.md is an index — an index is a copy; the queue is derived (terra <brand> decisions)',
+    );
+});
+
+test('names a decisions folder with no mold', () => {
+    // Given - records with no _template.md beside them
+    const tree = withDecisions({
+        files: withDecisions().files.filter((path) => path !== 'docs/decisions/_template.md'),
+    });
+
+    // Then - the mold sits where the record is written
+    expect(sentence(tree, 'docs-template-missing')).toBe(
+        'docs/decisions/_template.md is missing — the mold sits where the record is written',
+    );
+});
+
+test('names a reference page carrying no generation marker', () => {
+    // Given - a hand-authored page inside the projection
+    const tree = manual({
+        files: [...manual().files, 'docs/reference/', 'docs/reference/index.md'],
+        heads: { 'docs/reference/index.md': ['# API'] },
+    });
+
+    // Then - reference/ is a projection, never authored
+    expect(sentence(tree, 'docs-reference-unstamped')).toBe(
+        'docs/reference/index.md carries no GENERATED marker — reference/ is a projection, never authored',
+    );
+});
+
+test('passes a stamped reference page', () => {
+    // Given - the marker the docs compiler writes on its first line
+    const tree = manual({
+        files: [...manual().files, 'docs/reference/', 'docs/reference/index.md'],
+        heads: {
+            'docs/reference/index.md': ['<!-- GENERATED by `typescript docs` — DO NOT EDIT -->'],
+        },
+    });
+
+    // Then - nothing to say
+    expect(rules(tree)).toEqual([]);
+});
+
+test('names a repository whose brief does not route to the manual', () => {
+    // Given - no AGENTS.md at the root
+    const tree = manual({ agents: null });
+
+    // Then - the brief is a map, not a manual
+    expect(sentence(tree, 'docs-agents-route')).toBe(
+        'AGENTS.md does not route to docs/README.md — the brief is a map, not a manual',
+    );
+});
+
+test('names a brief that exists but routes elsewhere', () => {
+    // Given - a brief restating the corpus instead of pointing at it
+    const tree = manual({ agents: '# Agent brief\n\nEverything you need is right here.\n' });
+
+    // Then - the same rule
+    expect(rules(tree)).toEqual(['docs-agents-route']);
+});
+
+test('names a chapter reaching into another repository', () => {
+    // Given - a chapter linking a sibling clone's page
+    const tree = manual({
+        links: {
+            ...manual().links,
+            'docs/01-architecture.md': ['../../package-test/docs/README.md'],
+        },
+    });
+
+    // Then - another repository's tree is not a place this manual may reach
+    expect(sentence(tree, 'docs-cross-repo-link')).toBe(
+        "docs/01-architecture.md links ../../package-test/docs/README.md: another repository's tree is not a place this manual may reach",
+    );
+});
+
+test('lets a chapter cite a sibling repository by url, and reach its own root', () => {
+    // Given - a forge link, an anchor, and a link back up to the repository's README
+    const tree = manual({
+        links: {
+            ...manual().links,
+            'docs/01-architecture.md': [
+                'https://github.com/jterrazz/jterrazz-studio/blob/main/docs/08-repo-structure.md',
+                '#the-spine',
+                '../README.md',
+                '02-developing.md',
+            ],
+        },
+    });
+
+    // Then - a citation is not a reach, and the repository's own tree is fair game
+    expect(rules(tree)).toEqual([]);
+});