honestdocs 0.0.0-stage → 0.1.1

package/src/docs.mjs

@@ -0,0 +1,139 @@
+// The document set: finding the files, reading them, and deriving the fields nobody
+// should type.
+//
+// One rule runs through all of it: a field a person has to remember to update is a field
+// that will be wrong. So `progress`, `files`, `superseded-by` and `updated` are derived —
+// from the checklist in the body, from git, from the other document's `supersedes` — and
+// overwritten on every `index`. Only `title`, `status`, `supersedes` and `related` are
+// written by hand, because only a person knows them.
+
+import { existsSync, readdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
+import { basename, dirname, join, relative } from "node:path";
+import { parse, stringify } from "./frontmatter.mjs";
+import { filesForAllDocs, isShallow, lastChangeDates, toplevel, uncommittedFiles } from "./git.mjs";
+
+/** Files in the documents folder that are about the system, not documents in it. */
+const NOT_DOCUMENTS = new Set(["INDEX.md", "README.md"]);
+const SKIP_DIRS = new Set([".git", "node_modules", "assets"]);
+
+const idOf = (file) => basename(file, ".md");
+export const today = () => new Date().toISOString().slice(0, 10);
+
+export function slugify(s) {
+  return String(s).toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "").slice(0, 60);
+}
+
+/** Every document file, sorted, as absolute paths. */
+function listFiles(config) {
+  const out = [];
+  const skip = config.templatesDir;
+  const walk = (dir) => {
+    for (const entry of readdirSync(dir)) {
+      if (SKIP_DIRS.has(entry)) continue;
+      const p = join(dir, entry);
+      if (statSync(p).isDirectory()) {
+        if (p !== skip) walk(p);
+      } else if (entry.endsWith(".md") && !(dir === config.docsDir && NOT_DOCUMENTS.has(entry))) out.push(p);
+    }
+  };
+  if (existsSync(config.docsDir)) walk(config.docsDir);
+  return out.sort();
+}
+
+const relPath = (config, file) => relative(config.docsDir, file).split("\\").join("/");
+
+/** The area a file sits in, from its folder; null at the top level. */
+export function folderArea(config, file) {
+  const dir = dirname(relPath(config, file));
+  return dir === "." ? null : dir.split("/")[0];
+}
+
+/** Read every document: `{ file, rel, id, meta, body }`, meta `{}` when missing (`hasMeta` false). */
+export function loadDocs(config) {
+  return listFiles(config).map((file) => {
+    const { meta, body } = parse(readFileSync(file, "utf8"));
+    return { file, rel: relPath(config, file), id: idOf(file), meta: meta ?? {}, hasMeta: !!meta, body };
+  });
+}
+
+export function writeDoc(doc) {
+  writeFileSync(doc.file, stringify(doc.meta) + doc.body);
+}
+
+export function findDoc(docs, id) {
+  return docs.find((d) => d.id === id) ?? null;
+}
+
+/** `done/total` over `- [x]` and `- [ ]` in the body; "" when there is no checklist. */
+export function checklistProgress(body) {
+  const done = (body.match(/^\s*[-*] \[[xX]\]/gm) ?? []).length;
+  const open = (body.match(/^\s*[-*] \[ \]/gm) ?? []).length;
+  return done + open === 0 ? "" : `${done}/${done + open}`;
+}
+
+/** The unticked checklist lines, for `brief`. */
+export function openItems(body) {
+  return [...body.matchAll(/^\s*[-*] \[ \]\s*(.+)$/gm)].map((m) => m[1].trim());
+}
+
+/**
+ * What git can tell about the set. `available` is false outside a repository and in a
+ * shallow clone, where every derived value would be wrong — better to derive nothing and
+ * say so than to write a wrong answer into a hundred files.
+ */
+export function gitFacts(config) {
+  const docsTop = toplevel(config.docsDir);
+  const shallow = !!docsTop && (isShallow(config.docsDir) || config.codeRepos.some((r) => toplevel(r) && isShallow(r)));
+  if (!docsTop || shallow) {
+    return { available: false, reason: docsTop ? "shallow clone" : "not a git repository", dates: {}, files: {}, dirty: new Set() };
+  }
+  return {
+    available: true,
+    dates: lastChangeDates(config.docsDir),
+    files: filesForAllDocs(config),
+    dirty: uncommittedFiles(config.docsDir),
+  };
+}
+
+/**
+ * Compute the derived fields for every document, in memory. Returns the documents whose
+ * frontmatter changed, each with `before` and the new `meta`. Nothing is written here —
+ * `index` writes, `check` only compares.
+ */
+export function derive(config, docs, facts = gitFacts(config)) {
+  const replacedBy = new Map();
+  for (const d of docs) for (const t of asList(d.meta.supersedes)) replacedBy.set(t, d.id);
+
+  const changed = [];
+  for (const d of docs) {
+    if (!d.hasMeta || !d.meta.id) continue;
+    const before = JSON.stringify(d.meta);
+    const meta = { ...d.meta };
+
+    const progress = checklistProgress(d.body);
+    if (progress || meta.progress) meta.progress = progress;
+
+    if (facts.available) {
+      const files = facts.files[d.id] ?? [];
+      if (files.length || asList(meta.files).length) meta.files = files;
+      const last = facts.dirty.has(d.rel) ? today() : facts.dates[d.rel];
+      if (last) meta.updated = last;
+    }
+
+    const by = replacedBy.get(d.id);
+    if (by) {
+      meta["superseded-by"] = by;
+      // A replaced document that still says it is in force is the single most expensive
+      // thing in a docs folder: someone builds from it.
+      if (meta.status !== "superseded" && meta.status !== "abandoned" && meta.status !== "retired") meta.status = "superseded";
+    } else if (asList(meta["superseded-by"]).length) {
+      // Nothing replaces it any more — the newer document dropped its `supersedes`.
+      meta["superseded-by"] = "";
+    }
+
+    if (JSON.stringify(meta) !== before) changed.push({ doc: d, before: JSON.parse(before), meta });
+  }
+  return changed;
+}
+
+export const asList = (v) => (Array.isArray(v) ? v : v ? [v] : []);

package/src/frontmatter.mjs

@@ -0,0 +1,90 @@
+// Frontmatter: a deliberately small YAML subset — `key: scalar` and `key: [a, b]`,
+// nothing nested.
+//
+// Documents are read and rewritten by these scripts far more often than a full YAML
+// parser would earn its keep, and a strict, flat shape is what lets `check` say something
+// precise. Anything a real YAML parser would read differently is quoted on the way out.
+
+const FM = /^?---\r?\n([\s\S]*?)\r?\n---[ \t]*(?:\r?\n|$)/;
+
+const unquote = (v) => {
+  if (v.length >= 2 && v.startsWith('"') && v.endsWith('"')) {
+    try {
+      return JSON.parse(v);
+    } catch {
+      return v.slice(1, -1);
+    }
+  }
+  if (v.length >= 2 && v.startsWith("'") && v.endsWith("'")) return v.slice(1, -1).replace(/''/g, "'");
+  return v;
+};
+
+/** Split `[a, "b, c", d]` into items, honouring quotes. */
+function splitList(inner) {
+  const items = [];
+  let cur = "";
+  let quote = null;
+  for (const ch of inner) {
+    if (quote) {
+      cur += ch;
+      if (ch === quote) quote = null;
+    } else if (ch === '"' || ch === "'") {
+      cur += ch;
+      quote = ch;
+    } else if (ch === ",") {
+      items.push(cur);
+      cur = "";
+    } else cur += ch;
+  }
+  items.push(cur);
+  return items.map((s) => unquote(s.trim())).filter((s) => s !== "");
+}
+
+/** `{ meta, body }`; `meta` is null when the file has no frontmatter block at all. */
+export function parse(raw) {
+  const m = FM.exec(raw);
+  if (!m) return { meta: null, body: raw.replace(/^/, "") };
+  const meta = {};
+  for (const line of m[1].split(/\r?\n/)) {
+    const kv = /^([A-Za-z][\w-]*):[ \t]*(.*)$/.exec(line);
+    if (!kv) continue;
+    const [, key, rest] = kv;
+    const v = rest.trim();
+    if (v === "") meta[key] = "";
+    else if (v.startsWith("[") && v.endsWith("]")) meta[key] = splitList(v.slice(1, -1));
+    else if (v === "true" || v === "false") meta[key] = v === "true";
+    else meta[key] = unquote(v);
+  }
+  return { meta, body: raw.slice(m[0].length) };
+}
+
+const KEY_ORDER = [
+  "id", "title", "area", "type", "status", "legacy",
+  "created", "updated", "completed", "progress",
+  "supersedes", "superseded-by", "related", "files",
+];
+
+// A plain scalar that a YAML parser would read as something else — structure, a comment,
+// a number, a boolean — or that carries leading/trailing space, gets quoted.
+const NEEDS_QUOTES = /^[\s[\]{}>|*&!%@`#'",?:-]|[\s:]$|: | #|^(true|false|yes|no|null|~)$|^[\d.+-]+$/i;
+
+const scalar = (v) => {
+  const s = String(v);
+  return NEEDS_QUOTES.test(s) && !/^\d{4}-\d{2}-\d{2}$/.test(s) ? JSON.stringify(s) : s;
+};
+const listItem = (v) => {
+  const s = String(v);
+  return /[,[\]"']|^\s|\s$/.test(s) ? JSON.stringify(s) : s;
+};
+
+export function stringify(meta) {
+  const keys = [...KEY_ORDER.filter((k) => k in meta), ...Object.keys(meta).filter((k) => !KEY_ORDER.includes(k))];
+  const lines = keys.map((k) => {
+    const v = meta[k];
+    if (Array.isArray(v)) return `${k}: [${v.map(listItem).join(", ")}]`;
+    if (v === undefined || v === null || v === "") return `${k}:`;
+    if (typeof v === "boolean" || typeof v === "number") return `${k}: ${v}`;
+    return `${k}: ${scalar(v)}`;
+  });
+  return `---\n${lines.join("\n")}\n---\n`;
+}

package/src/git.mjs

@@ -0,0 +1,181 @@
+// Everything honestdocs asks git. Each question is one `git log` over the whole history,
+// parsed here, rather than one call per document — a project with a few hundred
+// documents should not mean a few hundred processes.
+
+import { execFileSync } from "node:child_process";
+import { realpathSync } from "node:fs";
+import { basename, join, relative } from "node:path";
+
+const RS = "\x1e"; // starts a commit
+const GS = "\x1d"; // ends its message
+
+/** Run git; "" when it fails (not a repository, git missing). */
+export function git(args, cwd) {
+  try {
+    return execFileSync("git", ["-c", "core.quotepath=off", ...args], {
+      cwd,
+      encoding: "utf8",
+      maxBuffer: 512 * 1024 * 1024,
+      stdio: ["ignore", "pipe", "ignore"],
+    });
+  } catch {
+    return "";
+  }
+}
+
+/**
+ * The canonical form of a path. Windows can spell one folder two ways — a short 8.3 name
+ * such as `RUNNER~1` from the environment, the long name from git — and `path.relative`
+ * between the two spellings walks out of the folder instead of into it.
+ */
+export function real(p) {
+  try {
+    return realpathSync.native(p);
+  } catch {
+    return p;
+  }
+}
+
+export const toplevel = (dir) => {
+  const top = git(["rev-parse", "--show-toplevel"], dir).trim();
+  return top ? real(top) : null;
+};
+
+/** A shallow clone (CI's default) has no history to derive anything from. */
+export const isShallow = (dir) => git(["rev-parse", "--is-shallow-repository"], dir).trim() === "true";
+
+/**
+ * The date each file under `dir` last changed in content, as `{ "area/x.md": "YYYY-MM-DD" }`
+ * with paths relative to `dir`.
+ *
+ * A pure rename is not an edit: moving a folder of documents must not stamp all of them
+ * with the date of the move, which would erase their history in one commit. So history is
+ * read newest first, and a rename links the older path to the newer one — the edits made
+ * under the old name still count for the file as it is called now. A file whose only
+ * commit is a rename gets that commit's date.
+ */
+export function lastChangeDates(dir) {
+  const out = git(["log", `--format=${RS}%ad`, "--date=short", "--name-status", "-M", "--relative", "--", "."], dir);
+  const dates = {};
+  const seen = {};
+  const current = new Map(); // a path as it was then → the path it is called now
+  const now = (p) => current.get(p) ?? p;
+  for (const chunk of out.split(RS)) {
+    const [dateLine, ...entries] = chunk.split(/\r?\n/);
+    const date = dateLine.trim();
+    for (const entry of entries) {
+      if (!entry) continue;
+      const [status, a, b] = entry.split("\t");
+      if (status.startsWith("R") || status.startsWith("C")) {
+        const target = now(b);
+        seen[target] ??= date;
+        if (status !== "R100" && status !== "C100") dates[target] ??= date;
+        if (status.startsWith("R")) current.set(a, target);
+      } else if (a) {
+        const target = now(a);
+        seen[target] ??= date;
+        if (status !== "D") dates[target] ??= date;
+      }
+    }
+  }
+  for (const [p, d] of Object.entries(seen)) dates[p] ??= d;
+  return dates;
+}
+
+/**
+ * Files under `dir` with changes git has not committed yet, relative to `dir`. Their
+ * `updated` is today: the edit is happening now, and it will be committed with today's
+ * date far more often than not.
+ */
+export function uncommittedFiles(dir) {
+  const top = toplevel(dir);
+  if (!top) return new Set();
+  const out = git(["status", "--porcelain=v1", "-z", "--untracked-files=all", "--", "."], dir);
+  const set = new Set();
+  const entries = out.split("\0");
+  for (let i = 0; i < entries.length; i++) {
+    const e = entries[i];
+    if (e.length < 4) continue;
+    // A rename is followed by its old path as a separate entry; skip that one.
+    if (e[0] === "R" || e[0] === "C") i++;
+    const rel = relative(real(dir), join(top, e.slice(3))).split("\\").join("/");
+    if (!rel.startsWith("..")) set.add(rel);
+  }
+  return set;
+}
+
+/**
+ * Which files the commits naming each document touched: `{ id: [file, …] }`, newest
+ * commit first.
+ *
+ * A commit names a document with a trailer line — `Doc: 2026-11-02-token-rotation` — and
+ * may name several, on several lines or comma-separated. The match is on the whole id:
+ * `Doc: 2026-11-02-auth` must not count as a commit for `2026-11-02-auth-tokens`.
+ *
+ * Paths are given as they are named now: a file renamed after the commit is listed under
+ * its new name. That is also what lets `exclude` — the documents folder, when it lives in
+ * the same repository as the code — still recognise documents committed before the folder
+ * was moved.
+ */
+function filesByTrailer(repo, trailer, { exclude = null, prefix = "" } = {}) {
+  const out = git(["log", "-i", "-E", `--grep=^${trailer}:`, `--format=${RS}%B${GS}`, "--name-only"], repo);
+  if (!out) return {};
+  const now = renamesToNow(repo);
+  const line = new RegExp(`^${trailer}:[ \\t]*(.+)$`, "gim");
+  const result = {};
+  for (const chunk of out.split(RS)) {
+    const end = chunk.indexOf(GS);
+    if (end < 0) continue;
+    const message = chunk.slice(0, end);
+    const files = chunk.slice(end + 1).split(/\r?\n/).map((s) => now(s.trim())).filter(Boolean)
+      .filter((f) => !exclude || !(f === exclude || f.startsWith(exclude + "/")));
+    if (!files.length) continue;
+    const ids = new Set();
+    for (const m of message.matchAll(line)) {
+      for (const id of m[1].split(",")) if (id.trim()) ids.add(id.trim());
+    }
+    for (const id of ids) {
+      const set = (result[id] ??= new Set());
+      for (const f of files) set.add(prefix + f);
+    }
+  }
+  return Object.fromEntries(Object.entries(result).map(([k, v]) => [k, [...v]]));
+}
+
+/**
+ * A function from a path as some commit named it to the path it has today, following
+ * every rename in the history, newest first.
+ */
+function renamesToNow(repo) {
+  const out = git(["log", "-M", "--diff-filter=R", "--name-status", "--format="], repo);
+  const map = new Map();
+  const now = (p) => map.get(p) ?? p;
+  for (const entry of out.split(/\r?\n/)) {
+    const [status, from, to] = entry.split("\t");
+    if (status?.startsWith("R") && from && to) map.set(from, now(to));
+  }
+  return now;
+}
+
+/**
+ * The trailer-derived files across every configured code repository. With more than one
+ * repository, each path is prefixed with its repository's folder name so `app/x.ts` in
+ * one is not confused with `app/x.ts` in another.
+ */
+export function filesForAllDocs(config) {
+  const merged = {};
+  const multi = config.codeRepos.length > 1;
+  for (const repoDir of config.codeRepos) {
+    const top = toplevel(repoDir);
+    if (!top) continue;
+    const rel = relative(top, real(config.docsDir)).split("\\").join("/");
+    const exclude = rel && !rel.startsWith("..") ? rel : null;
+    const prefix = multi ? basename(top) + "/" : "";
+    const found = filesByTrailer(top, config.trailer, { exclude, prefix });
+    for (const [id, files] of Object.entries(found)) {
+      const set = new Set([...(merged[id] ?? []), ...files]);
+      merged[id] = [...set];
+    }
+  }
+  return merged;
+}

package/src/render.mjs

@@ -0,0 +1,84 @@
+// INDEX.md: two views of the same set — newest first, for "what has been happening",
+// and by area, for "where is the document about X". Generated, never maintained.
+//
+// The output carries no generation timestamp, on purpose: the same documents must give
+// byte-identical output, so `check` can tell a stale index from a fresh one.
+
+import { LIFECYCLES } from "./config.mjs";
+
+export const MARK = {
+  draft: "✏️",
+  planned: "📋",
+  "in-progress": "🔧",
+  done: "✅",
+  current: "📘",
+  superseded: "🗑️",
+  retired: "📦",
+  abandoned: "⛔",
+};
+
+const esc = (s) => String(s ?? "").replace(/\|/g, "\\|").replace(/\r?\n/g, " ");
+const link = (d) => `[${esc(d.meta.title || d.id)}](${encodeURI(d.rel)})`;
+const byUpdated = (a, b) =>
+  String(b.meta.updated ?? "").localeCompare(String(a.meta.updated ?? "")) || a.id.localeCompare(b.id);
+const byCreated = (a, b) =>
+  String(b.meta.created ?? "").localeCompare(String(a.meta.created ?? "")) || a.id.localeCompare(b.id);
+
+export function renderIndex(config, docs) {
+  const legend = new Map();
+  for (const lifecycle of Object.values(LIFECYCLES)) {
+    for (const [status, text] of Object.entries(lifecycle)) if (!legend.has(status)) legend.set(status, text);
+  }
+
+  const lines = [
+    `# ${config.title}`,
+    "",
+    "> Generated by `honestdocs index`. Do not edit — change the document's own frontmatter",
+    "> and run it again.",
+    ">",
+    "> **The code is the truth.** A document records what was decided at the time. Where the",
+    "> two disagree, believe the code, then come back and correct the document's `status`.",
+    "",
+    `${docs.length} document${docs.length === 1 ? "" : "s"}`,
+    "",
+    "| | Status | Meaning |",
+    "|---|---|---|",
+    ...Object.keys(MARK).map((s) => `| ${MARK[s]} | ${s} | ${esc(legend.get(s))} |`),
+    "",
+  ];
+
+  const recent = [...docs].sort(byUpdated).slice(0, config.recent);
+  if (recent.length) {
+    lines.push("## Recently changed", "", "| Updated | | Document | Area |", "|---|---|---|---|");
+    for (const d of recent) {
+      lines.push(`| ${esc(d.meta.updated)} | ${MARK[d.meta.status] ?? ""} | ${link(d)} | ${esc(d.meta.area)} |`);
+    }
+    lines.push("");
+  }
+
+  const areaNames = Object.keys(config.areas);
+  const present = [...new Set(docs.map((d) => d.meta.area).filter(Boolean))].sort(
+    (a, b) => (areaNames.indexOf(a) + 1 || 1e9) - (areaNames.indexOf(b) + 1 || 1e9) || a.localeCompare(b),
+  );
+  if (present.length) lines.push("## By area", "");
+  for (const area of present) {
+    lines.push(`### ${area}`, "");
+    if (config.areas[area]) lines.push(`_${esc(config.areas[area])}_`, "");
+    lines.push("| | Document | Type | Progress | Updated |", "|---|---|---|---|---|");
+    for (const d of docs.filter((x) => x.meta.area === area).sort(byCreated)) {
+      lines.push(
+        `| ${MARK[d.meta.status] ?? ""} | ${link(d)} | ${esc(d.meta.type)} | ${esc(d.meta.progress)} | ${esc(d.meta.updated)} |`,
+      );
+    }
+    lines.push("");
+  }
+
+  const loose = docs.filter((d) => !d.meta.area);
+  if (loose.length) {
+    lines.push("## Not filed yet", "", "| Document |", "|---|");
+    for (const d of loose.sort((a, b) => a.id.localeCompare(b.id))) lines.push(`| ${link(d)} |`);
+    lines.push("");
+  }
+
+  return lines.join("\n");
+}

package/src/rules.mjs

@@ -0,0 +1,52 @@
+// Numbered rules inside `rule` documents.
+//
+// A rule is a list item that opens with its id in bold:
+//
+//   - **R3** Every route checks the item it names, not just the caller.
+//     Test: `tests/routes/item-scope.test.ts`
+//
+// The id is letters then digits (R3, M12, SEC4). Lines indented under the item belong to
+// it; a `Test:` or `Tests:` line names, in backticks, the files that prove it. A rule that
+// can be a test should be one, and `check` fails when a named test does not exist — so
+// "the test for this rule" cannot quietly become a file that was deleted last spring.
+
+const RULE = /^(\s*)[-*]\s+\*\*([A-Z][A-Z0-9]*?\d+)\*\*[.:]?\s*(.*)$/;
+const TEST = /^\s*Tests?:\s*(.+)$/i;
+const FENCE = /^\s*(```|~~~)/;
+
+export function parseRules(body) {
+  const rules = [];
+  let cur = null;
+  let inFence = false;
+  const lines = body.split(/\r?\n/);
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    if (FENCE.test(line)) {
+      inFence = !inFence;
+      cur = null;
+      continue;
+    }
+    if (inFence) continue;
+    const m = RULE.exec(line);
+    if (m) {
+      cur = { id: m[2], text: m[3].trim(), tests: [], line: i + 1, indent: m[1].length };
+      const inline = /^(.*?)\s+Tests?:\s*(`.+)$/i.exec(cur.text);
+      if (inline) {
+        cur.text = inline[1];
+        for (const p of inline[2].matchAll(/`([^`]+)`/g)) cur.tests.push(p[1].trim());
+      }
+      rules.push(cur);
+      continue;
+    }
+    if (!cur) continue;
+    const indent = /^(\s*)/.exec(line)[1].length;
+    if (line.trim() === "" || indent <= cur.indent) {
+      cur = null;
+      continue;
+    }
+    const t = TEST.exec(line);
+    if (t) for (const p of t[1].matchAll(/`([^`]+)`/g)) cur.tests.push(p[1].trim());
+    else cur.text += " " + line.trim();
+  }
+  return rules;
+}

package/src/templates.mjs

@@ -0,0 +1,26 @@
+// Body templates for new documents. A project can override any of them by putting
+// `<type>.md` in the folder its config names under `templates`; the rest fall back to the
+// ones shipped here.
+
+import { existsSync, readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const PACKAGE_ROOT = join(dirname(fileURLToPath(import.meta.url)), "..");
+const BUILT_IN = join(PACKAGE_ROOT, "templates");
+
+export function templateFor(config, type) {
+  for (const dir of [config.templatesDir, BUILT_IN]) {
+    if (!dir) continue;
+    const file = join(dir, `${type}.md`);
+    if (existsSync(file)) return readFileSync(file, "utf8").replace(/\r\n/g, "\n");
+  }
+  return "# {{title}}\n\n## Log\n";
+}
+
+export function fill(template, values) {
+  return template.replace(/\{\{\s*(\w+)\s*\}\}/g, (m, k) => (k in values ? String(values[k]) : m));
+}
+
+/** A file shipped with the package (guides, the agents snippet, the skill). */
+export const packageFile = (...parts) => readFileSync(join(PACKAGE_ROOT, ...parts), "utf8").replace(/\r\n/g, "\n");

package/templates/decision.md

@@ -0,0 +1,17 @@
+# {{title}}
+
+## Context
+
+_The forces at play: what is true, what is constrained, what is being asked for._
+
+## Decision
+
+_The choice, stated so it can be followed: "We will …"._
+
+## Alternatives considered
+
+_Each option that lost, and the reason it lost._
+
+## Consequences
+
+_Both the good ones and the ones we are choosing to live with._

package/templates/design.md

@@ -0,0 +1,28 @@
+# {{title}}
+
+## Context
+
+_What is the situation, and why now?_
+
+## Goals / Non-goals
+
+## Design
+
+## Alternatives considered
+
+_What else was on the table, and the reason it lost. This is the section that stops the
+same argument being had again in three months — by a person or by an AI that proposes the
+rejected option as if it were new._
+
+## Checklist
+
+- [ ] first step
+
+## Verification
+
+_How someone tells this actually works: a command, a test, a thing to look at._
+
+## Log
+
+_Dated notes as the work goes. Also the hand-over: what a new session — yours or someone
+else's — needs to know to pick this up._

package/templates/plan.md

@@ -0,0 +1,31 @@
+# {{title}}
+
+## Context
+
+_What is the situation, and why now?_
+
+## Goals / Non-goals
+
+## Decision
+
+_The approach, in a paragraph. Details belong in the checklist and the log._
+
+## Alternatives considered
+
+_What else was on the table, and the reason it lost._
+
+## Checklist
+
+_Ticked boxes drive `progress`. A box nobody can tick — dropped, deferred — gets a line in
+the Log saying what happened to it._
+
+- [ ] first step
+
+## Verification
+
+_How someone tells this actually works: a command, a test, a thing to look at._
+
+## Log
+
+_Dated notes as the work goes. Also the hand-over: what a new session needs to know to
+pick this up._

package/templates/postmortem.md

@@ -0,0 +1,21 @@
+# {{title}}
+
+## Timeline
+
+_Times, in order, from the first sign to the all-clear._
+
+## Impact
+
+_Who was affected, and how badly. Be specific; "it broke" teaches nobody anything._
+
+## Root cause
+
+_With the evidence that proves it — not the first plausible story._
+
+## What we changed
+
+## What we deliberately did not change, and why
+
+## Checklist
+
+- [ ] follow-up

package/templates/reference.md

@@ -0,0 +1,8 @@
+# {{title}}
+
+_Background that should stay true. When it goes out of date, fix it here, in place —
+never write a second document that contradicts this one._
+
+## Log
+
+_Dated one-liners: what changed in this document and why._