@plebeiantech/lat.md 0.12.3-fork.5 → 0.12.3-fork.7

package/dist/src/cli/check-coverage.d.ts

@@ -0,0 +1,2 @@
+import type { CheckError } from './check.js';
+export declare function checkCoverage(latticeDir: string, projectRoot?: string): Promise<CheckError[]>;

package/dist/src/cli/check-coverage.js

@@ -0,0 +1,71 @@
+import { readFile } from 'node:fs/promises';
+import { relative } from 'node:path';
+import { scanCodeRefs } from '../code-refs.js';
+import { listLatticeFiles } from '../lattice.js';
+import { indexNameFor } from './check-mode.js';
+import { toPosix } from '../walk.js';
+import { basename, dirname } from 'node:path';
+/**
+ * Fail a `lat.md/` tree that has documents and no `@lat:` ref pointing into it
+ * from anywhere in the codebase.
+ *
+ * `require-code-mention` was the only thing asking for refs, and it is opt-in
+ * frontmatter: an agent setting up a tree can simply not write it, and every
+ * check still passes. One did. Its reasons were both ordinary — it read a list
+ * of example comment markers as an exclusive language list and concluded its
+ * language was unsupported, and it was optimising for a green check rather
+ * than a correct one, so the option that could not fail was the one it took.
+ *
+ * A graph nothing points at cannot be reached from the code, which is the only
+ * reason it exists. So the floor is one ref, and the message says where to put
+ * the first one.
+ *
+ * Deliberately a floor and not a coverage ratio. Half this repository's own
+ * documents have no incoming ref and should not have one — a per-document rule
+ * would have to be either wrong here or watered down everywhere.
+ */
+/** Nothing to anchor: a tree of pure navigation, or a project with no code. */
+function isIndex(latticeDir, file) {
+    const holder = basename(dirname(file));
+    return (basename(file) ===
+        indexNameFor(holder === '' ? basename(latticeDir) : holder));
+}
+export async function checkCoverage(latticeDir, projectRoot = dirname(latticeDir)) {
+    const files = await listLatticeFiles(latticeDir);
+    const documents = files.filter((f) => !isIndex(latticeDir, f));
+    if (documents.length === 0)
+        return [];
+    const scan = await scanCodeRefs(projectRoot);
+    if (scan.files.length === 0)
+        return [];
+    if (scan.refs.length > 0)
+        return [];
+    const rootIndexPath = `${latticeDir}/${indexNameFor(basename(latticeDir))}`;
+    const rootIndexRel = toPosix(relative(process.cwd(), rootIndexPath));
+    // Quote the ref the reader should actually paste. A generic placeholder gets
+    // pasted verbatim and then fails `lat check code-refs`, which turns one
+    // error into two.
+    const stem = basename(latticeDir).replace(/\.md$/, '');
+    let anchor = `${stem}#Your Project`;
+    try {
+        const heading = (await readFile(rootIndexPath, 'utf-8')).match(/^#\s+(.+)$/m);
+        if (heading)
+            anchor = `${stem}#${heading[1].trim()}`;
+    }
+    catch {
+        // No root index, or unreadable — the placeholder still names the shape.
+    }
+    return [
+        {
+            file: rootIndexRel,
+            line: 1,
+            target: toPosix(relative(projectRoot, latticeDir)),
+            message: `${documents.length} document(s) here and no \`@lat:\` code ref anywhere in the project — nothing in the codebase can reach this graph.\n` +
+                '    Start at the application entrypoint (config/application.rb, src/index.ts, main.go, manage.py) and point it at the root index:\n' +
+                `        # @lat: [[${anchor}]]\n` +
+                '    Then add one ref per section that source code implements, at that code.\n' +
+                '    The marker is a comment syntax, not a language allowlist: `//` for C-family, `#` for Ruby, Python, shell, Elixir and the rest. The scan is textual and reads every non-markdown file.\n' +
+                '    An `@lat:` line is a machine directive, like a magic comment or a linter pragma. A project convention that minimises comments does not reach it.',
+        },
+    ];
+}

package/dist/src/cli/check-mode.d.ts

@@ -3,4 +3,10 @@ export declare const DIATAXIS_MODES: readonly ["tutorial", "how-to", "reference"
 export type DiataxisMode = (typeof DIATAXIS_MODES)[number];
 /** Directory below lat.md/ that holds each mode. */
 export declare const MODE_DIRS: Record<DiataxisMode, string>;
+/**
+ * The index file a directory is required to carry, e.g. `lat.md` for the root
+ * and `reference.md` for `reference/`. An index is navigation rather than
+ * content, so the `require-mode` gate below never asks one to declare a mode.
+ */
+export declare function indexNameFor(dirName: string): string;
 export declare function checkMode(latticeDir: string, projectRoot?: string): Promise<CheckError[]>;

package/dist/src/cli/check-mode.js

@@ -1,5 +1,5 @@
 import { readFile } from 'node:fs/promises';
-import { dirname, relative } from 'node:path';
+import { basename, dirname, join, relative } from 'node:path';
 import { listLatticeFiles, parseFrontmatter } from '../lattice.js';
 import { parse } from '../parser.js';
 import { quoteUntrusted } from '../untrusted.js';
@@ -181,9 +181,38 @@ function findImperativeHits(tree, content) {
     }
     return hits;
 }
+/**
+ * The index file a directory is required to carry, e.g. `lat.md` for the root
+ * and `reference.md` for `reference/`. An index is navigation rather than
+ * content, so the `require-mode` gate below never asks one to declare a mode.
+ */
+export function indexNameFor(dirName) {
+    return dirName.endsWith('.md') ? dirName : dirName + '.md';
+}
+/**
+ * Whether the root index turns the mode requirement on.
+ *
+ * Opt-in, and deliberately read from the tree rather than from a flag or an
+ * environment variable: the rule belongs to a documentation set, not to a
+ * machine or a CI job, and a tree that predates the rule has to keep passing.
+ * `lat init` stamps the flag into the root index it scaffolds, so a project
+ * set up after this exists is gated from its first commit while an older one
+ * is untouched until someone adds the line.
+ */
+async function requireModeEnabled(latticeDir) {
+    const indexPath = join(latticeDir, indexNameFor(basename(latticeDir)));
+    try {
+        const content = await readFile(indexPath, 'utf-8');
+        return parseFrontmatter(content).raw['require-mode'] === true;
+    }
+    catch {
+        return false;
+    }
+}
 export async function checkMode(latticeDir, projectRoot = dirname(latticeDir)) {
     const files = await listLatticeFiles(latticeDir);
     const errors = [];
+    const requireMode = await requireModeEnabled(latticeDir);
     for (const file of files) {
         const content = await readFile(file, 'utf-8');
         const relPath = relative(process.cwd(), file);
@@ -238,8 +267,21 @@ export async function checkMode(latticeDir, projectRoot = dirname(latticeDir)) {
             continue;
         }
         const mode = (declared ?? dirMode);
-        if (mode === undefined)
+        if (mode === undefined) {
+            const segments = relFromLattice.split('/');
+            const fileName = segments.pop();
+            const holder = segments.length === 0 ? basename(latticeDir) : segments.at(-1);
+            const isIndex = fileName === indexNameFor(holder);
+            if (requireMode && !isIndex) {
+                errors.push({
+                    file: relPath,
+                    line: 1,
+                    target,
+                    message: 'document declares no Diátaxis mode and is not in a mode directory — move it under lat.md/tutorials/, lat.md/how-to/, lat.md/reference/ or lat.md/explanation/, or declare one under its `lat:` frontmatter.\n    A document that would fail its mode is usually two documents: the lookup half belongs in reference/, the reasoning half in explanation/.\n    (The root index sets require-mode: true. Remove that line to turn this off.)',
+                });
+            }
             continue;
+        }
         const tree = parse(content);
         if (mode === 'how-to') {
             if (!orderedListPresent(tree)) {

package/dist/src/cli/check.js

@@ -6,6 +6,7 @@ import { scanCodeRefs } from '../code-refs.js';
 import { checkMode } from './check-mode.js';
 import { checkStatus } from './check-status.js';
 import { checkFrontmatter } from './check-frontmatter.js';
+import { checkCoverage } from './check-coverage.js';
 import { indexEntryNameFromDest } from './link-scheme.js';
 import { fencedLineMask } from './gen-index.js';
 import { SOURCE_EXTENSIONS, clearSymbolCache } from '../source-parser.js';
@@ -621,6 +622,7 @@ export async function checkAllCommand(ctx, opts = {}) {
     const modeErrors = await checkMode(ctx.latDir, ctx.projectRoot);
     const statusErrors = await checkStatus(ctx.latDir, ctx.projectRoot);
     const fmErrors = await checkFrontmatter(ctx.latDir, ctx.projectRoot);
+    const coverageErrors = await checkCoverage(ctx.latDir, ctx.projectRoot);
     const elapsed = Date.now() - startTime;
     const allErrors = [...md.errors, ...linkErrors, ...code.errors];
     const allFiles = { ...md.files };
@@ -658,12 +660,14 @@ export async function checkAllCommand(ctx, opts = {}) {
     lines.push(...formatCheckErrors(modeErrors, s));
     lines.push(...formatCheckErrors(statusErrors, s));
     lines.push(...formatCheckErrors(fmErrors, s));
+    lines.push(...formatCheckErrors(coverageErrors, s));
     const totalErrors = allErrors.length +
         indexErrors.length +
         sectionErrors.length +
         modeErrors.length +
         statusErrors.length +
-        fmErrors.length;
+        fmErrors.length +
+        coverageErrors.length;
     if (totalErrors > 0) {
         lines.push(formatErrorCount(totalErrors, s));
         return { output: lines.join('\n'), isError: true };

package/dist/src/cli/fork-instructions.d.ts

@@ -0,0 +1,19 @@
+export declare function readForkConventions(): string;
+/**
+ * Replace the fork block in `content`, or append one when absent.
+ *
+ * Returns null when the block is already byte-identical, so the caller can
+ * stay quiet rather than announce a write that did not happen.
+ */
+export declare function spliceForkBlock(content: string, body: string): string | null;
+/** Read the body currently fenced by the fork markers, or null if absent. */
+export declare function extractForkBlock(content: string): string | null;
+/**
+ * Write the fork's conventions into every instruction file and skill directory
+ * the selected agents produced.
+ *
+ * `fileHashes` is upstream's record, threaded through so `writeInitMeta`
+ * persists these entries alongside its own; a stored hash is what lets a later
+ * run tell "the user edited our block" from "the template moved on".
+ */
+export declare function writeForkInstructions(root: string, latDir: string, fileHashes: Record<string, string>, ask: (message: string) => Promise<boolean>): Promise<void>;

package/dist/src/cli/fork-instructions.js

@@ -0,0 +1,183 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { styleText } from 'node:util';
+import { contentHash, readFileHash } from '../init-version.js';
+import { findTemplatesDir } from './templates.js';
+/**
+ * The fork's own instruction channel into a consumer project.
+ *
+ * Upstream teaches a consumer's agent through `templates/AGENTS.md` and
+ * `templates/skill/SKILL.md`. Both are upstream files, and both are the ones
+ * upstream is most likely to rewrite, so every sentence this fork adds to them
+ * is a merge conflict bought on credit. The fork's Diátaxis block cost 13
+ * lines in one and 14 in the other before this module existed.
+ *
+ * Everything here writes into fork-owned paths instead. The entire upstream
+ * footprint is one import and one call in `initCmd`.
+ *
+ * Two shapes, because the destinations behave differently:
+ *
+ * - Always-loaded instruction files (`CLAUDE.md`, `AGENTS.md`,
+ *   `.github/copilot-instructions.md`) already carry upstream's
+ *   `%% lat:begin %%` block, so this appends a *second* block under its own
+ *   `%% lat-fork:begin %%` markers. Upstream's `appendTemplateSection` slices
+ *   between its own markers and leaves anything after them intact, so the two
+ *   blocks do not fight on re-run.
+ * - Skill directories get a separate `lat-md-conventions/SKILL.md`. Upstream
+ *   writes its `lat-md` skill with a whole-file hash comparison, so appending
+ *   to that file would make every later `lat init` report it as
+ *   user-modified and prompt.
+ */
+const FORK_BEGIN = '%% lat-fork:begin %%';
+const FORK_END = '%% lat-fork:end %%';
+/**
+ * Hash-map key for a fork block inside a file upstream also owns. Suffixed so
+ * it can never collide with upstream's entry for the same path — both live in
+ * one flat `file_hashes` record.
+ */
+function forkHashKey(relPath) {
+    return `${relPath}#lat-fork`;
+}
+/** Instruction files that use upstream's marker-append shape. */
+const BLOCK_TARGETS = [
+    'CLAUDE.md',
+    'AGENTS.md',
+    '.github/copilot-instructions.md',
+];
+/**
+ * Skill roots every agent integration installs into. Written to only when the
+ * directory already exists, which is what keeps this list from creating skill
+ * directories for agents the user did not select.
+ */
+const SKILL_ROOTS = [
+    '.claude/skills',
+    '.pi/skills',
+    '.agents/skills',
+    '.codex/skills',
+];
+const SKILL_NAME = 'lat-md-conventions';
+const SKILL_FRONTMATTER = `---
+name: ${SKILL_NAME}
+description: >-
+  Rules lat check enforces in this project: Diátaxis mode placement for every
+  lat.md/ document, mandatory @lat: code refs starting at the application
+  entrypoint, and test specs wired to their tests. Load alongside lat-md
+  whenever creating or editing files under lat.md/.
+---
+
+`;
+export function readForkConventions() {
+    return readFileSync(join(findTemplatesDir(), 'fork', 'conventions.md'), 'utf-8');
+}
+function wrapBlock(body) {
+    return `${FORK_BEGIN}\n${body}${body.endsWith('\n') ? '' : '\n'}${FORK_END}\n`;
+}
+/**
+ * Replace the fork block in `content`, or append one when absent.
+ *
+ * Returns null when the block is already byte-identical, so the caller can
+ * stay quiet rather than announce a write that did not happen.
+ */
+export function spliceForkBlock(content, body) {
+    const wrapped = wrapBlock(body);
+    const begin = content.indexOf(FORK_BEGIN);
+    const end = content.indexOf(FORK_END);
+    if (begin === -1 || end === -1 || end <= begin) {
+        let base = content;
+        if (base.length > 0 && !base.endsWith('\n'))
+            base += '\n';
+        return base + (base.length > 0 ? '\n' : '') + wrapped;
+    }
+    const endWithMarker = end + FORK_END.length;
+    const endWithNl = content[endWithMarker] === '\n' ? endWithMarker + 1 : endWithMarker;
+    const existing = content.slice(begin, endWithNl);
+    if (existing === wrapped)
+        return null;
+    return content.slice(0, begin) + wrapped + content.slice(endWithNl);
+}
+/** Read the body currently fenced by the fork markers, or null if absent. */
+export function extractForkBlock(content) {
+    const begin = content.indexOf(FORK_BEGIN);
+    const end = content.indexOf(FORK_END);
+    if (begin === -1 || end === -1 || end <= begin)
+        return null;
+    return content.slice(begin + FORK_BEGIN.length + 1, end);
+}
+/**
+ * Write the fork's conventions into every instruction file and skill directory
+ * the selected agents produced.
+ *
+ * `fileHashes` is upstream's record, threaded through so `writeInitMeta`
+ * persists these entries alongside its own; a stored hash is what lets a later
+ * run tell "the user edited our block" from "the template moved on".
+ */
+export async function writeForkInstructions(root, latDir, fileHashes, ask) {
+    const body = readForkConventions();
+    const bodyHash = contentHash(body);
+    const written = [];
+    for (const relPath of BLOCK_TARGETS) {
+        const absPath = join(root, relPath);
+        if (!existsSync(absPath))
+            continue;
+        const current = readFileSync(absPath, 'utf-8');
+        const existingBlock = extractForkBlock(current);
+        if (existingBlock !== null) {
+            const existingHash = contentHash(existingBlock);
+            if (existingHash === bodyHash) {
+                fileHashes[forkHashKey(relPath)] = bodyHash;
+                continue;
+            }
+            const storedHash = readFileHash(latDir, forkHashKey(relPath));
+            if (storedHash && existingHash !== storedHash) {
+                console.log(styleText('yellow', `  ${relPath}`) +
+                    ' lat-fork section has been modified.');
+                if (!(await ask('  Replace lat-fork section with latest template?'))) {
+                    console.log(styleText('dim', '  Kept existing section.'));
+                    continue;
+                }
+            }
+        }
+        const updated = spliceForkBlock(current, body);
+        if (updated === null) {
+            fileHashes[forkHashKey(relPath)] = bodyHash;
+            continue;
+        }
+        writeFileSync(absPath, updated);
+        fileHashes[forkHashKey(relPath)] = bodyHash;
+        written.push(relPath);
+    }
+    const skillBody = SKILL_FRONTMATTER + body;
+    const skillHash = contentHash(skillBody);
+    for (const skillRoot of SKILL_ROOTS) {
+        const rootAbs = join(root, skillRoot);
+        if (!existsSync(rootAbs))
+            continue;
+        const relPath = `${skillRoot}/${SKILL_NAME}/SKILL.md`;
+        const absPath = join(root, relPath);
+        if (existsSync(absPath)) {
+            const current = readFileSync(absPath, 'utf-8');
+            if (contentHash(current) === skillHash) {
+                fileHashes[relPath] = skillHash;
+                continue;
+            }
+            const storedHash = readFileHash(latDir, relPath);
+            if (storedHash && contentHash(current) !== storedHash) {
+                console.log(styleText('yellow', `  ${relPath}`) + ' has been modified.');
+                if (!(await ask('  Overwrite with latest lat template?'))) {
+                    console.log(styleText('dim', '  Kept existing file.'));
+                    continue;
+                }
+            }
+        }
+        mkdirSync(join(absPath, '..'), { recursive: true });
+        writeFileSync(absPath, skillBody);
+        fileHashes[relPath] = skillHash;
+        written.push(relPath);
+    }
+    if (written.length > 0) {
+        console.log('');
+        console.log(styleText('green', '  lat.md conventions') +
+            ' written to ' +
+            written.join(', '));
+    }
+}

package/dist/src/cli/fork-scaffold.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Turn the gate on in a root index, whatever frontmatter it already has.
+ *
+ * Bailing on any existing frontmatter — the first version of this — produced a
+ * silent no-op: a root index carrying `lat: tags: [...]` could never opt in,
+ * and `lat init` re-offered on every run because the flag it had just written
+ * was not there. Merging is what makes the offer terminate.
+ *
+ * Edited line by line rather than parsed and re-emitted, because re-emitting
+ * reformats the whole block and discards its comments. The one shape that
+ * cannot be edited safely — `lat:` carrying a flow mapping on its own line —
+ * is returned unchanged, and the caller falls back to printing the edit.
+ */
+export declare function stampRequireMode(content: string): string;
+/** Whether the gate is on, read straight from a root index's frontmatter. */
+export declare function requireModeSet(content: string): boolean;
+/**
+ * Append the four mode directories to the root index.
+ *
+ * Without this a fresh `lat init` leaves `lat check index` reporting four
+ * missing entries, which is a poor first impression of a tool whose whole
+ * pitch is that the check passes.
+ */
+export declare function listModeDirs(content: string): string;
+/**
+ * Scaffold the four mode directories and turn the gate on. Called only on the
+ * run that creates `lat.md/`, so an existing tree is never restructured
+ * underneath its owner.
+ */
+export declare function writeForkScaffold(latDir: string): void;
+/**
+ * Offer the gate to a tree `lat init` did not create.
+ *
+ * `writeForkScaffold` runs only on the branch that creates `lat.md/`, which
+ * left the flag unreachable for every project that already had one — that is,
+ * for every project that needs it. Restructuring someone's tree without asking
+ * is still wrong, so this asks.
+ *
+ * Silent when the flag is already set, when a previous run was told no, and
+ * when there is no TTY to ask — the non-interactive path prints the count and
+ * the manual edit instead, and records nothing, so a later interactive run
+ * still offers.
+ */
+export declare function offerRequireMode(latDir: string, interactive: boolean, ask: (message: string) => Promise<boolean>): Promise<void>;

package/dist/src/cli/fork-scaffold.js

@@ -0,0 +1,300 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { listLatticeFiles, parseFrontmatter } from '../lattice.js';
+import { basename, join, relative, sep } from 'node:path';
+import { styleText } from 'node:util';
+import { DIATAXIS_MODES, MODE_DIRS, indexNameFor } from './check-mode.js';
+/**
+ * Give a freshly created `lat.md/` the Diátaxis shape, and turn the gate on.
+ *
+ * Upstream's `templates/init/` holds two files and is copied wholesale, so a
+ * new tree is one flat root index. An agent asked to document a codebase then
+ * writes flat files beside it — which is not merely untidy: `checkMode` binds
+ * only inside the four mode directories, so flat placement puts every document
+ * out of reach of every shape rule. A bella-derms session did exactly that and
+ * confirmed afterwards that its largest document produced 64 errors the moment
+ * it was moved into `reference/`.
+ *
+ * Structure is the cheaper half of the fix. Four directories that already
+ * exist, each with a passing index, make placement the path of least
+ * resistance; `require-mode: true` in the root index makes flat placement an
+ * error rather than an option.
+ *
+ * Written from here rather than added to `templates/init/` because the flag
+ * has to land inside `lat.md/lat.md`, which upstream's template owns.
+ */
+/** One-line summary and body for each mode's index, keyed by directory. */
+const MODE_INDEX = {
+    tutorials: {
+        title: 'Tutorials',
+        lead: 'Guided first passes through this system, each ending somewhere the reader can see.',
+    },
+    'how-to': {
+        title: 'How-to',
+        lead: 'Recipes for tasks that recur, written for someone who already knows what they want.',
+    },
+    reference: {
+        title: 'Reference',
+        lead: 'Lookup facts about this system: fields, states, limits, names and defaults.',
+    },
+    explanation: {
+        title: 'Explanation',
+        lead: 'Why this system is shaped the way it is, and what the alternatives cost.',
+    },
+};
+/**
+ * A mode index has to satisfy its own mode. A tutorial index needs ordered
+ * steps and a stated outcome, a how-to index needs ordered steps, and a
+ * reference index must not carry a second paragraph — so each stub is written
+ * to the rule it will be checked against rather than to one house style.
+ */
+function indexBody(dir) {
+    const { title, lead } = MODE_INDEX[dir];
+    const header = `# ${title}\n\n${lead}\n`;
+    if (dir === 'tutorials') {
+        return (header +
+            '\nBy the end of any document here the reader will have run something and seen it work.\n' +
+            '\n1. Pick the tutorial closest to what you are trying to learn.\n' +
+            '2. Follow it top to bottom without skipping.\n' +
+            '3. Come back to `reference/` for the details it left out.\n');
+    }
+    if (dir === 'how-to') {
+        return (header +
+            '\n1. Find the recipe for the task in front of you.\n' +
+            '2. Follow its steps.\n' +
+            '3. If no recipe fits, write one here once the task is done.\n');
+    }
+    if (dir === 'reference') {
+        return header;
+    }
+    return (header +
+        '\nEach document here answers a "why", not a "how". The steps that follow ' +
+        'from a decision belong in `how-to/`, and the facts it fixes belong in ' +
+        '`reference/`.\n');
+}
+/**
+ * Turn the gate on in a root index, whatever frontmatter it already has.
+ *
+ * Bailing on any existing frontmatter — the first version of this — produced a
+ * silent no-op: a root index carrying `lat: tags: [...]` could never opt in,
+ * and `lat init` re-offered on every run because the flag it had just written
+ * was not there. Merging is what makes the offer terminate.
+ *
+ * Edited line by line rather than parsed and re-emitted, because re-emitting
+ * reformats the whole block and discards its comments. The one shape that
+ * cannot be edited safely — `lat:` carrying a flow mapping on its own line —
+ * is returned unchanged, and the caller falls back to printing the edit.
+ */
+export function stampRequireMode(content) {
+    const fence = content.match(/^---\n([\s\S]*?)\n---[ \t]*(\r?\n|$)/);
+    if (!fence) {
+        return `---\nlat:\n  require-mode: true\n---\n\n${content.replace(/^\n+/, '')}`;
+    }
+    const body = fence[1];
+    if (/^\s*require-mode\s*:/m.test(body))
+        return content;
+    const lines = body.split('\n');
+    const latAt = lines.findIndex((line) => /^lat\s*:/.test(line));
+    let merged;
+    if (latAt === -1) {
+        merged = [...lines, 'lat:', '  require-mode: true'];
+    }
+    else if (lines[latAt].replace(/^lat\s*:/, '').trim() !== '') {
+        // `lat: {mode: reference}` or `lat: &anchor` — a line-based insert would
+        // corrupt it, so say nothing and let the caller print the edit.
+        return content;
+    }
+    else {
+        // Siblings must share indentation, so take it from the existing first
+        // child rather than assuming two spaces.
+        const child = lines
+            .slice(latAt + 1)
+            .find((line) => line.trim() !== '' && /^\s/.test(line));
+        const indent = child ? (child.match(/^\s+/)?.[0] ?? '  ') : '  ';
+        merged = [
+            ...lines.slice(0, latAt + 1),
+            `${indent}require-mode: true`,
+            ...lines.slice(latAt + 1),
+        ];
+    }
+    const end = fence[0].length;
+    return `---\n${merged.join('\n')}\n---${fence[2] || '\n'}${content.slice(end)}`;
+}
+/** Whether the gate is on, read straight from a root index's frontmatter. */
+export function requireModeSet(content) {
+    return parseFrontmatter(content).raw['require-mode'] !== undefined;
+}
+/**
+ * Append the four mode directories to the root index.
+ *
+ * Without this a fresh `lat init` leaves `lat check index` reporting four
+ * missing entries, which is a poor first impression of a tool whose whole
+ * pitch is that the check passes.
+ */
+export function listModeDirs(content) {
+    const entries = DIATAXIS_MODES.map((mode) => {
+        const dir = MODE_DIRS[mode];
+        const { title, lead } = MODE_INDEX[dir];
+        return `- [${title}](${dir}/${dir}.md) — ${lead}`;
+    }).join('\n');
+    if (content.includes(`(${MODE_DIRS.reference}/`))
+        return content;
+    let base = content;
+    if (!base.endsWith('\n'))
+        base += '\n';
+    return `${base}\nEvery document belongs in exactly one of these.\n\n${entries}\n`;
+}
+/**
+ * Scaffold the four mode directories and turn the gate on. Called only on the
+ * run that creates `lat.md/`, so an existing tree is never restructured
+ * underneath its owner.
+ */
+export function writeForkScaffold(latDir) {
+    const created = [];
+    for (const mode of DIATAXIS_MODES) {
+        const dir = MODE_DIRS[mode];
+        const dirPath = join(latDir, dir);
+        const indexPath = join(dirPath, `${dir}.md`);
+        if (existsSync(indexPath))
+            continue;
+        mkdirSync(dirPath, { recursive: true });
+        writeFileSync(indexPath, indexBody(dir));
+        created.push(`${dir}/`);
+    }
+    const rootIndex = join(latDir, indexNameFor(basename(latDir)));
+    if (existsSync(rootIndex)) {
+        const current = readFileSync(rootIndex, 'utf-8');
+        const stamped = listModeDirs(stampRequireMode(current));
+        if (stamped !== current)
+            writeFileSync(rootIndex, stamped);
+    }
+    if (created.length > 0) {
+        console.log(styleText('green', 'Scaffolded Diátaxis modes') +
+            ' — ' +
+            created.join(' ') +
+            styleText('dim', ' (every document belongs in one of these)'));
+    }
+}
+// ── Adopting the gate in a tree that already exists ──────────────────
+/**
+ * Where a declined offer is remembered.
+ *
+ * Fork-owned rather than a field on upstream's `lat_init.json`, so recording
+ * it costs no edit to `src/init-version.ts`. `lat.md/.cache/` is already in
+ * the scaffolded `.gitignore`, so the marker stays out of the repository.
+ */
+function declinePath(latDir) {
+    return join(latDir, '.cache', 'lat_fork.json');
+}
+function declined(latDir) {
+    try {
+        const raw = JSON.parse(readFileSync(declinePath(latDir), 'utf-8'));
+        return (typeof raw === 'object' &&
+            raw !== null &&
+            raw['require_mode_declined'] === true);
+    }
+    catch {
+        return false;
+    }
+}
+function recordDecline(latDir) {
+    mkdirSync(join(latDir, '.cache'), { recursive: true });
+    writeFileSync(declinePath(latDir), JSON.stringify({ require_mode_declined: true }, null, 2) + '\n');
+}
+/** Documents the gate would reject today: not an index, no mode either way. */
+async function unmodedDocuments(latDir) {
+    const modeDirs = new Set(DIATAXIS_MODES.map((mode) => MODE_DIRS[mode]));
+    const files = await listLatticeFiles(latDir);
+    const offenders = [];
+    for (const file of files) {
+        const rel = relative(latDir, file).split(sep).join('/');
+        const segments = rel.split('/');
+        const fileName = segments.pop();
+        const holder = segments.length === 0 ? basename(latDir) : segments.at(-1);
+        if (fileName === indexNameFor(holder))
+            continue;
+        if (segments.length > 0 && modeDirs.has(segments[0]))
+            continue;
+        const declaredMode = parseFrontmatter(readFileSync(file, 'utf-8')).raw['mode'];
+        if (typeof declaredMode === 'string')
+            continue;
+        offenders.push(rel);
+    }
+    return offenders;
+}
+/**
+ * Offer the gate to a tree `lat init` did not create.
+ *
+ * `writeForkScaffold` runs only on the branch that creates `lat.md/`, which
+ * left the flag unreachable for every project that already had one — that is,
+ * for every project that needs it. Restructuring someone's tree without asking
+ * is still wrong, so this asks.
+ *
+ * Silent when the flag is already set, when a previous run was told no, and
+ * when there is no TTY to ask — the non-interactive path prints the count and
+ * the manual edit instead, and records nothing, so a later interactive run
+ * still offers.
+ */
+export async function offerRequireMode(latDir, interactive, ask) {
+    const rootIndex = join(latDir, indexNameFor(basename(latDir)));
+    if (!existsSync(rootIndex))
+        return;
+    if (requireModeSet(readFileSync(rootIndex, 'utf-8')))
+        return;
+    if (declined(latDir))
+        return;
+    const offenders = await unmodedDocuments(latDir);
+    console.log('');
+    console.log(styleText('bold', 'Diátaxis modes'));
+    console.log('  ' +
+        styleText('dim', 'Every document belongs in one of four modes. Without') +
+        ' require-mode ' +
+        styleText('dim', 'a document'));
+    console.log('  ' +
+        styleText('dim', 'placed outside a mode directory is checked against no shape rule at all.'));
+    if (offenders.length > 0) {
+        console.log('');
+        console.log(`  ${styleText('yellow', String(offenders.length))} document(s) would need a mode:`);
+        for (const name of offenders.slice(0, 5)) {
+            console.log('    ' + styleText('dim', name));
+        }
+        if (offenders.length > 5) {
+            console.log('    ' + styleText('dim', `... and ${offenders.length - 5} more`));
+        }
+    }
+    if (!interactive) {
+        console.log('');
+        console.log('  ' +
+            styleText('dim', 'To turn it on, add this to the top of') +
+            ` ${basename(latDir)}/${indexNameFor(basename(latDir))}:`);
+        console.log('');
+        for (const line of ['---', 'lat:', '  require-mode: true', '---']) {
+            console.log('    ' + styleText('cyan', line));
+        }
+        return;
+    }
+    console.log('');
+    if (!(await ask('  Turn require-mode on for this project?'))) {
+        recordDecline(latDir);
+        console.log('  ' +
+            styleText('dim', 'Skipped. Add') +
+            ' require-mode: true ' +
+            styleText('dim', 'to the root index whenever you want it.'));
+        return;
+    }
+    writeForkScaffold(latDir);
+    // The one frontmatter shape `stampRequireMode` refuses to edit. Saying so
+    // beats re-offering forever on a flag that never lands.
+    if (!requireModeSet(readFileSync(rootIndex, 'utf-8'))) {
+        console.log('  ' +
+            styleText('yellow', 'Could not edit the frontmatter safely.') +
+            styleText('dim', ' Add this under its `lat:` mapping by hand:'));
+        console.log('    ' + styleText('cyan', 'require-mode: true'));
+        return;
+    }
+    if (offenders.length > 0) {
+        console.log('  ' +
+            styleText('dim', 'Run') +
+            ' lat check ' +
+            styleText('dim', 'to see which documents need placing.'));
+    }
+}

package/dist/src/cli/init.js

@@ -15,6 +15,8 @@ import { INIT_VERSION, writeInitMeta, readInitVersion, readFileHash, contentHash
 import { getLocalVersion, fetchLatestVersion } from '../version.js';
 import { selectMenu } from './select-menu.js';
 import { checklistMenu } from './checklist-menu.js';
+import { writeForkInstructions } from './fork-instructions.js';
+import { offerRequireMode, writeForkScaffold } from './fork-scaffold.js';
 async function confirm(rl, message) {
     while (true) {
         let answer;
@@ -900,6 +902,7 @@ export async function initCmd(targetDir) {
             mkdirSync(latDir, { recursive: true });
             cpSync(templateDir, latDir, { recursive: true });
             console.log(styleText('green', 'Created lat.md/'));
+            writeForkScaffold(latDir);
         }
         // Step 2: Configure fresh/outdated setups, ask interactive users about an
         // available key, and offer to rebuild an index whose backend differs. This
@@ -954,6 +957,7 @@ export async function initCmd(targetDir) {
                 output: process.stdout,
             });
         }
+        await offerRequireMode(latDir, interactive, ask);
         if (!anySelected) {
             // Embedding setup is complete even when the user does not configure an
             // agent. Stamp the version so future non-interactive runs do not reapply
@@ -1004,6 +1008,7 @@ export async function initCmd(targetDir) {
             console.log(styleText('bold', 'Setting up Codex...'));
             await setupCodex(root, latDir, fileHashes, ask, commandStyle);
         }
+        await writeForkInstructions(root, latDir, fileHashes, ask);
         // Record init version and file hashes so `lat check` can detect stale setups
         writeInitMeta(latDir, fileHashes);
         console.log('');

package/dist/src/init-version.d.ts

@@ -3,7 +3,7 @@
  * requires users to re-run it (e.g. new hooks, generated files, MCP config, or
  * a configuration migration).
  */
-export declare const INIT_VERSION = 5;
+export declare const INIT_VERSION = 7;
 export declare function readInitVersion(latDir: string): number | null;
 export declare function readFileHash(latDir: string, relPath: string): string | null;
 export declare function contentHash(content: string): string;

package/dist/src/init-version.js

@@ -6,7 +6,7 @@ import { join } from 'node:path';
  * requires users to re-run it (e.g. new hooks, generated files, MCP config, or
  * a configuration migration).
  */
-export const INIT_VERSION = 5;
+export const INIT_VERSION = 7;
 function cachePath(latDir) {
     return join(latDir, '.cache', 'lat_init.json');
 }

package/dist/src/lattice.d.ts

@@ -38,7 +38,7 @@ export type MdLink = {
  * edit — the trap this list guards against is silent, so it must not depend on
  * whoever adds the next field remembering to register it twice.
  */
-export declare const LAT_FIELDS: readonly ["require-code-mention", "mode", "status", "reviewed-hash", "tags"];
+export declare const LAT_FIELDS: readonly ["require-code-mention", "mode", "require-mode", "status", "reviewed-hash", "tags"];
 /**
  * Something wrong with the frontmatter itself, carried out of the parser for a
  * caller to report. Both kinds fail OPEN if they stay quiet: a misplaced or

package/dist/src/lattice.js

@@ -15,6 +15,7 @@ import { visit } from 'unist-util-visit';
 export const LAT_FIELDS = [
     'require-code-mention',
     'mode',
+    'require-mode',
     'status',
     'reviewed-hash',
     'tags',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@plebeiantech/lat.md",
-  "version": "0.12.3-fork.5",
+  "version": "0.12.3-fork.7",
   "description": "A knowledge graph for your codebase, written in markdown",
   "type": "module",
   "license": "MIT",

package/templates/AGENTS.md

@@ -105,16 +105,3 @@ Details about this child topic.
 ```
 
 The second example is invalid because `Bad Section` has no leading paragraph. `lat check` validates this rule and reports errors for missing or overly long leading paragraphs.
-
-# Diátaxis modes
-
-Documents under `lat.md/tutorials/`, `lat.md/how-to/`, `lat.md/reference/`, and `lat.md/explanation/` are checked against their Diátaxis mode. Declare it explicitly with nested frontmatter, or rely on the directory:
-
-```markdown
----
-lat:
-  mode: reference
----
-```
-
-If a document is in one of the four mode directories, the declared mode must match that directory. Each mode enforces one shape rule: tutorials need an ordered list of steps and a stated outcome; how-to guides need an ordered list of steps; reference docs must not contain narrative prose (no second paragraph under a heading); explanations must not give imperative commands. Run `lat check mode` to validate.

package/templates/fork/conventions.md

@@ -0,0 +1,95 @@
+# lat.md conventions this project enforces
+
+`lat check` fails on every rule below. They are not style preferences. This
+block is generated and a later `lat init` replaces it — record project guidance
+in `lat.md/`, never here.
+
+## Every document goes in a Diátaxis mode directory
+
+A document belongs in exactly one of four subdirectories, and `lat check mode`
+enforces one shape rule for each:
+
+| Directory | Holds | Shape rule |
+| --- | --- | --- |
+| `lat.md/tutorials/` | a guided first pass for someone new | an ordered list of steps, and a stated outcome |
+| `lat.md/how-to/` | a recipe for a task that recurs | an ordered list of steps |
+| `lat.md/reference/` | lookup facts: fields, states, limits, names | no narrative prose — no second paragraph under a heading |
+| `lat.md/explanation/` | why the design is what it is | no imperative commands |
+
+Do not write documents at the top of `lat.md/`. The root index is the only file
+that belongs there. When it carries `require-mode: true`, a document with no
+declared mode and no mode directory is a `lat check` error.
+
+**A document that fails its mode is usually two documents.** A file that lists
+the states *and* argues for the design is mixed: the lookup half goes in
+`reference/`, the reasoning half in `explanation/`, and each links the other.
+Filing it under one mode and softening the prose until the check passes is the
+wrong repair. So is leaving it at the top level where no check can see it.
+
+Classify before writing, not after. If a `diataxis` skill is available, use it.
+
+## Every project has at least one `@lat:` code ref
+
+`lat check` fails a tree that has documents and no `@lat:` ref anywhere in the
+codebase. A graph nothing points at cannot be reached from the code, which is
+the only reason it exists.
+
+Start at the application entrypoint — `config/application.rb`, `src/index.ts`,
+`main.go`, `manage.py`, whatever a new reader opens first — and point it at the
+root index:
+
+```ruby
+# @lat: [[lat#Acme]]
+module Acme
+```
+
+Then one ref per section that source code actually implements, placed at that
+code. Never in a block at the top of a file.
+
+### An `@lat:` pointer is exempt from this project's comment conventions
+
+A repository that minimises, budgets, or forbids comments is right about prose
+comments and does not reach this one. An `@lat:` line is a machine directive,
+in the same class as `# frozen_string_literal:` or `// eslint-disable`. It
+carries no rationale, asserts nothing a reader could dispute, and cannot rot
+quietly — `lat check` fails the moment its target moves or disappears.
+
+Add the ref. Then, if the reasoning that would have been a comment is worth
+keeping, put it in a `lat.md/explanation/` section and let the pointer reach it.
+
+### The marker is a comment syntax, not a language allowlist
+
+`//` for C-family languages; `#` for Ruby, Python, shell, Elixir, YAML, Make,
+and everything else that comments with `#`. The scan is textual and walks every
+non-markdown file in the project, so every language works.
+
+Any list of example languages you find is a list of examples. Never conclude a
+language is unsupported because it is absent from one. `lat check` prints what
+it scanned:
+
+```
+Scanned 41 .md, 622 .rb, 118 .tsx in 1.2s
+```
+
+Read that line rather than guessing, and if you are still unsure, add one ref
+and run the check. It costs one command.
+
+(The tree-sitter grammars limit only `[[src/file.ts#symbol]]` wiki links, which
+resolve a symbol inside source. `@lat:` refs point the other way and have no
+such limit.)
+
+## Test specs are wired to their tests
+
+A document describing tests declares it in frontmatter:
+
+```markdown
+---
+lat:
+  require-code-mention: true
+---
+```
+
+Every leaf section then needs exactly one `@lat:` comment at the test that
+covers it, and every section needs at least one sentence saying what it
+verifies and why. `lat check` reports any spec section no test claims, and any
+ref pointing at no section.

package/templates/skill/SKILL.md

@@ -164,20 +164,7 @@ lat:
 ---
 ```
 
-Supported fields: `require-code-mention` for test spec enforcement, and `mode` for Diátaxis mode declaration.
-
-## Diátaxis modes
-
-Documents in `tutorials/`, `how-to/`, `reference/`, or `explanation/` under `lat.md/` are checked against their Diátaxis mode. Declare it with nested frontmatter:
-
-```yaml
----
-lat:
-  mode: reference
----
-```
-
-If the document is in one of the four mode directories, the declared mode must match that directory. Each mode enforces one shape rule: tutorials need an ordered list of steps and a stated outcome; how-to guides need an ordered list of steps; reference docs must not contain narrative prose (no second paragraph under a heading); explanations must not give imperative commands. `lat check mode` validates this.
+Currently the only supported field is `require-code-mention` for test spec enforcement.
 
 ## Validation