@baldurpan/create-ai-workflow 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Baldur Páll Hólmgeirsson
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,165 @@
+# `@baldurpan/create-ai-workflow`
+
+**Overlays a planning workflow onto an existing repository.** It is not a scaffolder — despite the
+`create-` name, it expects a repo you already have, and it refuses to run where `context/` exists.
+
+```bash
+npx @baldurpan/create-ai-workflow      # or: npm create @baldurpan/ai-workflow
+```
+
+You get a backlog, plan documents with phase ledgers, two verification gates, and seven commands that
+move work between them. Your coding agent runs the commands; you read and hand-edit the files.
+
+---
+
+## The three tiers
+
+```
+/roadmap "idea"  ──▶  pending                  Tier 1 — the backlog
+                        │                      context/roadmap.md, notes in context/drafts/
+                  /feature-plan [--activate]    writes context/plans/<NAME>-PLAN.md, then STOPS
+                        ▼
+                  a plan exists                Tier 2 — one plan, with a phase status ledger
+                        │
+                  /feature-implement           activates, then runs phases: code → verify → review
+                        ▼
+                  /feature-close               ──▶ context/archive/ + a context/history.md row
+```
+
+Every boundary is crossed by an explicit command, never as a side-effect. Every command finds its own
+starting point — nothing has to be looked up first.
+
+## The commands
+
+| Command | Does |
+|---|---|
+| `/roadmap` | prints the backlog, or appends one `pending` entry — capturing any material you supply as a draft |
+| `/feature-plan` | turns an entry into a plan document and **stops**. Planning is not activation |
+| `/feature-implement` | activates a planned feature and runs **one phase**, through both gates |
+| `/feature-status` | read-only. Reconciles the ledger against the repo, then names **exactly one** next action |
+| `/feature-close` | retires a feature: a `history.md` row, a `git mv` into `archive/`, and a reviewed reference sweep |
+| `/orchestrate` | one ad-hoc, commit-sized change through the same gates — no entry, no ledger |
+| `/onboard` | fills in your own stubs, running each verification command before writing it down |
+
+## What makes it different
+
+**No document states its own status.** There is no `**Status:**` header anywhere. Whether a feature is
+being worked is a marker in `roadmap.md`; whether it *has* a plan is whether its `Doc` field points into
+`plans/`; where a phase stands is the plan's own ledger. Those facts are orthogonal, so none of them can go
+stale against another.
+
+**Nothing is cached, parsed, or generated.** An agent reads the hand-written ledger every time, so editing
+a row by hand changes the answer immediately. There is no build step in the loop and no generated
+"current state" file to disagree with its source.
+
+**One file names a command.** `context/verify.md` holds this project's real lint, typecheck, build and
+test commands. No skill, agent prompt or role file carries a copy — a hardcoded stack rots the moment the
+project changes shape, and a second copy rots faster. `/onboard` **runs each candidate and writes only the
+ones that exit 0.**
+
+**A finding outlives the session that found it.** A reviewer `FAIL` or a capped gate is written to
+`context/findings.md` *before* the loopback, so it survives the conversation ending. An open `P0`/`P1`
+blocks its phase from being marked `done` and blocks `/feature-close`.
+
+## What gets installed
+
+```
+context/
+  README.md  workflow.md  plan-template.md  plan-template.notes.md  roles/  standards/     tool-owned
+  stack.md  verify.md  executors.md  roadmap.md  history.md  findings.md                   yours
+  drafts/  plans/  archive/                                                                yours
+  .state/manifest.json
+.claude/skills/<seven>/SKILL.md   .claude/agents/*.agent.md                                tool-owned
+.agents/skills/<seven>/SKILL.md   the same seven bodies, for hosts that read that tree       tool-owned
+AGENTS.md   a delimited block, merged into whatever is already there
+CLAUDE.md   a single @AGENTS.md line, and only when the file does not exist
+```
+
+Nothing is committed. Review the diff yourself.
+
+### The ownership boundary is a data structure, not a rule
+
+`context/.state/manifest.json` lists every tool-owned file with its hash. `update` walks that manifest —
+and a project-owned file is not in it, so **no code path reaches it.** Anything else you add under
+`context/` (`decisions.md`, `glossary.md`, `ops-notes.md`) survives by the same property, with no feature
+required to protect it.
+
+```bash
+npx @baldurpan/create-ai-workflow update --dry-run   # print the plan, change nothing
+npx @baldurpan/create-ai-workflow update             # conflicts stop it; nothing is written
+npx @baldurpan/create-ai-workflow update --force     # back up edited files (.bak) and take ours
+```
+
+| On disk | `update` does |
+|---|---|
+| matches the manifest | replaces silently |
+| differs | reports a conflict; `--force` backs up and replaces |
+| missing | restores |
+| not in the manifest | nothing — it cannot reach it |
+
+## Standards
+
+`context/standards/` ships a vendored default, and `context/standards/README.md` holds a
+conditional-loading table that agents actually traverse — the skills say "consult the conditional loading
+table", and that is how standards get loaded per task.
+
+**A wrong set is not inert**, because it is loaded unprompted on every task. Swap it:
+
+```bash
+npx @baldurpan/create-ai-workflow standards add <git-url>
+```
+
+That command **refuses to install a tree the skills cannot navigate**: the source's README must carry a
+usable conditional-loading table, or you are offered a generated one (`--generate-index`). Whatever lands
+is project-owned from that point — it drops out of the manifest, so `update` never clobbers it. Editing
+the bundled tree in place has the same effect.
+
+## `check`
+
+```bash
+npx @baldurpan/create-ai-workflow check
+```
+
+Reports structural breakage: an illegal status word, a `Depends on` naming a phase that does not exist or
+a cycle, two entries marked `active`, a second phase table, a `**Status:**` header, a plan no entry points
+at, a dead `Doc` or history link, a closed finding still in the file.
+
+It **never writes** — there is no `--fix`, because the moment it can repair a ledger, a program's edit
+competes with a hand edit. Nothing depends on it: no skill calls it and no git hook installs it. **Delete
+it and every workflow answer is unchanged.** It reads `roadmap.md`, `plans/`, `history.md` and
+`findings.md` — never `archive/`, because validating retired records against current rules is how
+validators earn a reputation for crying wolf. Every message quotes the rule it enforces, so a false
+positive points at the document that is out of step.
+
+## Scope
+
+**Both skill trees ship.** Claude Code reads `.claude/skills/`; Codex reads `.agents/skills/` and never
+looks at the other one. They get the same seven bodies — the only difference is one frontmatter line,
+`disable-model-invocation: true`, which is Claude Code's key and means nothing elsewhere. The bodies are
+written runtime-neutral, with no runtime primitive named in any of them, and a test enforces it.
+
+Duplication is the cost, and it is contained by construction rather than by discipline: one canonical
+source lives in the package, both trees are written at install, both are hashed in the manifest, and
+neither is ever hand-edited. Editing one is a conflict, not a divergence.
+
+`AGENTS.md` is the content home, so Cursor, Copilot and Gemini CLI get the command block for free without
+a tree of their own. An install made before the second tree existed gains it on the next `update`, listed
+as `add` in the plan.
+
+**No host's review command is named anywhere in the package.** Which coder or reviewer serves Gate 2 is a
+per-machine fact that hosts change underneath you, so `/onboard` asks and writes the chosen invocation into
+`context/executors.md`. What ships is the contract — a review happens, blocking findings carry a `P0`–`P3`
+severity, a `FAIL` writes a finding before the loopback — not the command.
+
+Requires Node 20.10 or newer. One `context/` per repository.
+
+## Licence
+
+The tool is MIT.
+
+`context/standards/` is vendored from
+[`baldurpan/ai-engineering-standards`](https://github.com/baldurpan/ai-engineering-standards) at the ref
+recorded in `context/standards/.source`. **That repository carries no licence file**, so the terms under
+which the vendored content may be redistributed are unsettled — it is bundled here on the author's own
+authority and nothing more. If you are installing this into a repository where that matters, run
+`standards add <git-url>` and point it at a tree whose terms you know.

package/dist/agents-block.js

@@ -0,0 +1,70 @@
+/**
+ * The AGENTS.md block. The tool never owns that file — it owns a delimited region inside it, and
+ * everything outside the markers is the user's.
+ */
+export const START_MARKER = '<!-- ai-workflow:start -->';
+export const END_MARKER = '<!-- ai-workflow:end -->';
+function allIndexesOf(haystack, needle) {
+    const out = [];
+    for (let i = haystack.indexOf(needle); i !== -1; i = haystack.indexOf(needle, i + needle.length)) {
+        out.push(i);
+    }
+    return out;
+}
+export function inspect(text) {
+    if (text === null)
+        return { kind: 'no-file' };
+    const starts = allIndexesOf(text, START_MARKER);
+    const ends = allIndexesOf(text, END_MARKER);
+    if (starts.length === 0 && ends.length === 0)
+        return { kind: 'no-markers' };
+    if (starts.length > 1 || ends.length > 1) {
+        return { kind: 'duplicate', count: Math.max(starts.length, ends.length) };
+    }
+    if (starts.length === 1 && ends.length === 0) {
+        return { kind: 'malformed', reason: 'an opening marker with no closing marker' };
+    }
+    if (starts.length === 0 && ends.length === 1) {
+        return { kind: 'malformed', reason: 'a closing marker with no opening marker' };
+    }
+    const start = starts[0];
+    const end = ends[0];
+    if (end < start) {
+        return { kind: 'malformed', reason: 'the closing marker appears before the opening marker' };
+    }
+    const body = text.slice(start + START_MARKER.length, end).trim();
+    return { kind: 'present', body, start, end: end + END_MARKER.length };
+}
+/** The full block, markers included, as it is written into a file. */
+export function render(body) {
+    return `${START_MARKER}\n${body.trim()}\n${END_MARKER}`;
+}
+export class BlockConflictError extends Error {
+}
+/**
+ * The file text after writing `body` into it. Refuses on `duplicate` and `malformed` — those are the two
+ * states where guessing which region to replace could destroy the user's own content.
+ */
+export function apply(text, body) {
+    const state = inspect(text);
+    const block = render(body);
+    switch (state.kind) {
+        case 'no-file':
+            return `# AGENTS.md\n\nThe agent-neutral entry point for this repository.\n\n${block}\n`;
+        case 'no-markers': {
+            const existing = text.replace(/\s+$/, '');
+            return `${existing}\n\n${block}\n`;
+        }
+        case 'present': {
+            const before = text.slice(0, state.start);
+            const after = text.slice(state.end);
+            return `${before}${block}${after}`;
+        }
+        case 'duplicate':
+            throw new BlockConflictError(`AGENTS.md contains ${state.count} ai-workflow blocks. Delete the extra one, then re-run — ` +
+                'replacing one of two would be a coin flip.');
+        case 'malformed':
+            throw new BlockConflictError(`AGENTS.md has ${state.reason}. Fix the markers by hand, then re-run — re-appending blindly ` +
+                'would leave two partial blocks.');
+    }
+}

package/dist/bin.js

@@ -0,0 +1,14 @@
+#!/usr/bin/env node
+import { main } from "./cli.js";
+import { fail, UserError } from "./log.js";
+main(process.argv.slice(2))
+    .then((code) => {
+    process.exitCode = code;
+})
+    .catch((error) => {
+    if (error instanceof UserError)
+        fail(error.message);
+    else
+        fail(error.stack ?? String(error));
+    process.exitCode = 1;
+});

package/dist/check/markdown.js

@@ -0,0 +1,47 @@
+/**
+ * Blank out HTML comments, preserving line count so reported line numbers stay true. The stubs ship their
+ * example entries commented out, so a parser that reads them would find a phantom roadmap entry on a fresh
+ * install.
+ */
+export function stripComments(text) {
+    return text.replace(/<!--[\s\S]*?-->/g, (match) => match.replace(/[^\n]/g, ' '));
+}
+function splitCells(line) {
+    return line
+        .trim()
+        .replace(/^\|/, '')
+        .replace(/\|$/, '')
+        .split('|')
+        .map((cell) => cell.trim());
+}
+const SEPARATOR = /^\s*\|?\s*:?-{2,}:?\s*(\|\s*:?-{2,}:?\s*)*\|?\s*$/;
+/** Every GitHub-flavoured pipe table in the text. */
+export function parseTables(text) {
+    const lines = text.split('\n');
+    const tables = [];
+    for (let i = 0; i < lines.length - 1; i += 1) {
+        const header = lines[i];
+        const separator = lines[i + 1];
+        if (!header.trim().startsWith('|') || !SEPARATOR.test(separator))
+            continue;
+        const table = { line: i + 1, header: splitCells(header), rows: [] };
+        let j = i + 2;
+        for (; j < lines.length; j += 1) {
+            const row = lines[j];
+            if (!row.trim().startsWith('|'))
+                break;
+            table.rows.push({ line: j + 1, cells: splitCells(row) });
+        }
+        tables.push(table);
+        i = j - 1;
+    }
+    return tables;
+}
+/** The link targets in a line of markdown, in order. */
+export function linkTargets(line) {
+    const out = [];
+    const pattern = /\]\(([^)\s]+)/g;
+    for (let m = pattern.exec(line); m !== null; m = pattern.exec(line))
+        out.push(m[1]);
+    return out;
+}

package/dist/check/parse.js

@@ -0,0 +1,113 @@
+import { linkTargets, parseTables, stripComments } from "./markdown.js";
+export const PHASE_STATUSES = ['not started', 'in progress', 'blocked', 'done'];
+export const FEATURE_MARKERS = ['pending', 'active'];
+export function parseRoadmap(text) {
+    const lines = stripComments(text).split('\n');
+    const entries = [];
+    let current = null;
+    for (let i = 0; i < lines.length; i += 1) {
+        const line = lines[i];
+        const heading = /^###\s+(.*\S)\s*$/.exec(line);
+        if (heading) {
+            current = null;
+            const text = heading[1];
+            const marker = /`([^`]+)`\s*$/.exec(text);
+            if (!marker)
+                continue;
+            const name = text
+                .slice(0, marker.index)
+                .replace(/[\s—–-]+$/, '')
+                .trim();
+            if (!name)
+                continue;
+            current = { name, marker: marker[1].trim(), line: i + 1, doc: null, docLine: null };
+            entries.push(current);
+            continue;
+        }
+        if (/^##\s/.test(line))
+            current = null;
+        if (!current || current.doc !== null)
+            continue;
+        if (/^\s*[-*]\s*\*\*Doc:?\*\*/i.test(line)) {
+            current.docLine = i + 1;
+            current.doc = linkTargets(line)[0] ?? null;
+        }
+    }
+    return entries;
+}
+const isPhaseTable = (table) => {
+    const lower = table.header.map((c) => c.toLowerCase());
+    return lower.includes('phase') && lower.includes('status');
+};
+/** Every table in a plan that looks like a phase ledger. More than one is itself a finding. */
+export function parseLedgers(text) {
+    return parseTables(stripComments(text))
+        .filter(isPhaseTable)
+        .map((table) => {
+        const index = (name) => table.header.findIndex((c) => c.toLowerCase() === name);
+        const numberAt = index('#');
+        const phaseAt = index('phase');
+        const statusAt = index('status');
+        const dependsAt = index('depends on');
+        const rows = table.rows.map((row) => {
+            const raw = dependsAt === -1 ? '' : (row.cells[dependsAt] ?? '');
+            const numberCell = numberAt === -1 ? '' : (row.cells[numberAt] ?? '');
+            const parsedNumber = Number.parseInt(numberCell.trim(), 10);
+            return {
+                line: row.line,
+                number: Number.isNaN(parsedNumber) ? null : parsedNumber,
+                name: phaseAt === -1 ? '' : (row.cells[phaseAt] ?? ''),
+                status: (statusAt === -1 ? '' : (row.cells[statusAt] ?? '')).replace(/`/g, '').trim(),
+                dependsRaw: raw,
+                dependsOn: parseDepends(raw),
+            };
+        });
+        return { table, columns: table.header, rows };
+    });
+}
+function parseDepends(raw) {
+    const cleaned = raw.replace(/[`*]/g, '').trim().toLowerCase();
+    if (cleaned === '' || cleaned === '—' || cleaned === '–' || cleaned === '-' || cleaned === 'none') {
+        return [];
+    }
+    return cleaned
+        .split(/[,\s]+/)
+        .map((part) => Number.parseInt(part.replace(/[^0-9]/g, ''), 10))
+        .filter((n) => !Number.isNaN(n));
+}
+export function parseFindings(text) {
+    const lines = stripComments(text).split('\n');
+    let section = null;
+    const out = [];
+    for (let i = 0; i < lines.length; i += 1) {
+        const line = lines[i];
+        const h2 = /^##\s+(\S+)/.exec(line);
+        if (h2) {
+            const name = h2[1].toLowerCase();
+            section = name === 'open' ? 'Open' : name === 'closed' ? 'Closed' : null;
+            continue;
+        }
+        const h3 = /^###\s+(F-\d+)\b(.*)$/.exec(line);
+        if (h3)
+            out.push({ id: h3[1], line: i + 1, section, heading: h3[2].trim() });
+    }
+    return out;
+}
+export function parseHistory(text) {
+    const table = parseTables(stripComments(text)).find((t) => t.header.map((c) => c.toLowerCase()).includes('feature'));
+    if (!table)
+        return [];
+    const featureAt = table.header.findIndex((c) => c.toLowerCase() === 'feature');
+    return table.rows.map((row) => ({
+        line: row.line,
+        feature: (featureAt === -1 ? '' : (row.cells[featureAt] ?? '')).trim(),
+        documents: row.cells.flatMap((cell) => linkTargets(cell)),
+    }));
+}
+/** Lines carrying a `**Status:**` header — the one thing no document under `context/` may state. */
+export function statusHeaderLines(text) {
+    return stripComments(text)
+        .split('\n')
+        .map((line, i) => (/^\s*\*\*Status:?\*\*/i.test(line) ? i + 1 : 0))
+        .filter((n) => n > 0);
+}

package/dist/check/rules.js

@@ -0,0 +1,245 @@
+import { readFileSync } from 'node:fs';
+import path from 'node:path';
+import { exists, walk } from "../paths.js";
+import { PHASE_STATUSES, parseFindings, parseHistory, parseLedgers, parseRoadmap, statusHeaderLines, } from "./parse.js";
+/** Used only when `context/plan-template.md` is missing — the template is the source of truth. */
+const FALLBACK_COLUMNS = ['#', 'Phase', 'Status', 'Depends on', 'Note'];
+const RULES = {
+    columns: 'context/plan-template.notes.md — "the ledger\'s column set is fixed — `check` compares every plan\'s ledger against the template\'s"',
+    status: 'context/workflow.md — "Phase | the plan\'s ledger, Status column | `not started`, `in progress`, `blocked`, `done`"',
+    depends: 'context/workflow.md — "take the lowest-numbered phase that is not `done` and whose `Depends on` entries are all `done`"',
+    active: 'context/workflow.md — "At most one roadmap entry is `active`."',
+    statusHeader: 'context/README.md — "No document states its own status. There is no `**Status:**` header anywhere under `context/`."',
+    oneTable: 'context/plan-template.md §6.1 — "Exactly one table in this document has these columns. Do not add a second phase table"',
+    orphanPlan: 'context/workflow.md — "whether a feature has a plan | whether its **Doc** field points into `plans/`"',
+    deadLink: 'context/workflow.md — "Each entry\'s **Doc** field points at its document" · "a link into `context/archive/`"',
+    closedFinding: 'context/findings.md — "Closed findings leave this file … This file must not grow for the life of the project."',
+};
+function read(root, rel) {
+    const full = path.join(root, rel);
+    return exists(full) ? readFileSync(full, 'utf8') : null;
+}
+export function expectedColumns(root) {
+    const template = read(root, 'context/plan-template.md');
+    const ledger = template ? parseLedgers(template)[0] : undefined;
+    return ledger ? ledger.columns : FALLBACK_COLUMNS;
+}
+/**
+ * Reads `roadmap.md`, `plans/`, `history.md` and `findings.md` — never `archive/`. A retired plan encodes
+ * whatever format was current when it was written, and validating historical records against current rules
+ * is the false-positive machine that makes validators get ignored.
+ */
+export function runChecks(root) {
+    const problems = [];
+    const columns = expectedColumns(root);
+    const roadmapText = read(root, 'context/roadmap.md');
+    const roadmap = roadmapText ? parseRoadmap(roadmapText) : [];
+    if (roadmapText === null) {
+        problems.push({
+            level: 'error',
+            file: 'context/roadmap.md',
+            message: 'missing — the Tier-1 backlog is where every feature status lives',
+            rule: RULES.active,
+        });
+    }
+    // More than one entry marked `active`.
+    const active = roadmap.filter((entry) => entry.marker === 'active');
+    if (active.length > 1) {
+        for (const entry of active) {
+            problems.push({
+                level: 'error',
+                file: 'context/roadmap.md',
+                line: entry.line,
+                message: `"${entry.name}" is marked \`active\`, and so ${active.length === 2 ? 'is' : 'are'} ${active
+                    .filter((e) => e !== entry)
+                    .map((e) => `"${e.name}"`)
+                    .join(', ')}`,
+                rule: RULES.active,
+            });
+        }
+    }
+    // A `Doc` field pointing at a missing file. Targets are relative to `context/`.
+    for (const entry of roadmap) {
+        if (!entry.doc || /^[a-z]+:/i.test(entry.doc))
+            continue;
+        const target = path.join(root, 'context', decodeURI(entry.doc));
+        if (!exists(target)) {
+            problems.push({
+                level: 'error',
+                file: 'context/roadmap.md',
+                line: entry.docLine ?? entry.line,
+                message: `"${entry.name}" points its **Doc** at \`${entry.doc}\`, which does not exist`,
+                rule: RULES.deadLink,
+            });
+        }
+    }
+    // A `history.md` link pointing at a missing file.
+    const historyText = read(root, 'context/history.md');
+    for (const row of historyText ? parseHistory(historyText) : []) {
+        for (const target of row.documents) {
+            if (/^[a-z]+:/i.test(target))
+                continue;
+            if (!exists(path.join(root, 'context', decodeURI(target)))) {
+                problems.push({
+                    level: 'error',
+                    file: 'context/history.md',
+                    line: row.line,
+                    message: `the row for "${row.feature}" links \`${target}\`, which does not exist`,
+                    rule: RULES.deadLink,
+                });
+            }
+        }
+    }
+    // A closed finding still sitting in findings.md.
+    const findingsText = read(root, 'context/findings.md');
+    for (const finding of findingsText ? parseFindings(findingsText) : []) {
+        if (finding.section === 'Closed') {
+            problems.push({
+                level: 'note',
+                file: 'context/findings.md',
+                line: finding.line,
+                message: `${finding.id} is closed and still in the file — it belongs in the retiring plan's log`,
+                rule: RULES.closedFinding,
+            });
+        }
+    }
+    // `**Status:**` headers, in the files this command reads.
+    const scanned = [
+        'context/roadmap.md',
+        'context/history.md',
+        'context/findings.md',
+        ...planPaths(root),
+    ];
+    for (const rel of scanned) {
+        const text = read(root, rel);
+        if (text === null)
+            continue;
+        for (const line of statusHeaderLines(text)) {
+            problems.push({
+                level: 'error',
+                file: rel,
+                line,
+                message: 'a `**Status:**` header — a document that states its own status is a copy that goes stale',
+                rule: RULES.statusHeader,
+            });
+        }
+    }
+    // Every plan under plans/.
+    const pointedAt = new Set(roadmap
+        .filter((entry) => entry.doc?.startsWith('plans/'))
+        .map((entry) => path.posix.normalize(entry.doc)));
+    for (const rel of planPaths(root)) {
+        const text = read(root, rel);
+        const relFromContext = rel.slice('context/'.length);
+        if (!pointedAt.has(relFromContext)) {
+            problems.push({
+                level: 'error',
+                file: rel,
+                message: 'no roadmap entry points at this plan — nothing can reach it, and nothing retires it',
+                rule: RULES.orphanPlan,
+            });
+        }
+        const ledgers = parseLedgers(text);
+        if (ledgers.length === 0) {
+            problems.push({
+                level: 'error',
+                file: rel,
+                message: 'no phase ledger — a document in `plans/` is one that has an executable ledger',
+                rule: RULES.columns,
+            });
+            continue;
+        }
+        if (ledgers.length > 1) {
+            for (const ledger of ledgers.slice(1)) {
+                problems.push({
+                    level: 'error',
+                    file: rel,
+                    line: ledger.table.line,
+                    message: `a second phase table (the first is at line ${ledgers[0].table.line}) — a differently-shaped one nearby is a decoy that gets read by mistake`,
+                    rule: RULES.oneTable,
+                });
+            }
+        }
+        const ledger = ledgers[0];
+        if (ledger.columns.join(' | ') !== columns.join(' | ')) {
+            problems.push({
+                level: 'error',
+                file: rel,
+                line: ledger.table.line,
+                message: `ledger columns are \`${ledger.columns.join(' | ')}\`; the template's are \`${columns.join(' | ')}\``,
+                rule: RULES.columns,
+            });
+        }
+        for (const row of ledger.rows) {
+            if (!PHASE_STATUSES.includes(row.status)) {
+                problems.push({
+                    level: 'error',
+                    file: rel,
+                    line: row.line,
+                    message: `phase ${row.number ?? '?'} has status \`${row.status}\`; it must be one of ${PHASE_STATUSES.map((s) => `\`${s}\``).join(', ')}`,
+                    rule: RULES.status,
+                });
+            }
+        }
+        problems.push(...dependencyProblems(rel, ledger));
+    }
+    return problems;
+}
+function planPaths(root) {
+    const dir = path.join(root, 'context', 'plans');
+    if (!exists(dir))
+        return [];
+    return walk(dir)
+        .filter((rel) => rel.endsWith('.md'))
+        .map((rel) => path.posix.join('context/plans', rel.split(path.sep).join('/')));
+}
+function dependencyProblems(file, ledger) {
+    const problems = [];
+    const numbers = new Set(ledger.rows.map((row) => row.number).filter((n) => n !== null));
+    for (const row of ledger.rows) {
+        for (const dependency of row.dependsOn) {
+            if (!numbers.has(dependency)) {
+                problems.push({
+                    level: 'error',
+                    file,
+                    line: row.line,
+                    message: `phase ${row.number ?? '?'} depends on phase ${dependency}, which is not in the ledger`,
+                    rule: RULES.depends,
+                });
+            }
+        }
+    }
+    const edges = new Map();
+    for (const row of ledger.rows) {
+        if (row.number !== null)
+            edges.set(row.number, row.dependsOn.filter((d) => numbers.has(d)));
+    }
+    const state = new Map();
+    const reported = new Set();
+    const visit = (node, stack) => {
+        if (state.get(node) === 'done')
+            return;
+        if (state.get(node) === 'visiting') {
+            const cycle = [...stack.slice(stack.indexOf(node)), node];
+            const key = [...cycle].sort((a, b) => a - b).join(',');
+            if (!reported.has(key)) {
+                reported.add(key);
+                problems.push({
+                    level: 'error',
+                    file,
+                    line: ledger.rows.find((row) => row.number === node)?.line,
+                    message: `the \`Depends on\` column forms a cycle: ${cycle.join(' → ')}`,
+                    rule: RULES.depends,
+                });
+            }
+            return;
+        }
+        state.set(node, 'visiting');
+        for (const next of edges.get(node) ?? [])
+            visit(next, [...stack, node]);
+        state.set(node, 'done');
+    };
+    for (const node of edges.keys())
+        visit(node, []);
+    return problems;
+}