dotmd-cli 0.82.0 → 0.84.0

package/README.md

@@ -213,6 +213,9 @@ runlist new plan platform-work --coordination
 runlist runlists
 ```
 
+`runlist new hub platform-work` makes the same coordination hub; add
+`--runlist a,b,c` or `--roadmap` for the other two shapes.
+
 For progress across several runlists, create a roadmap:
 
 ```bash
@@ -225,6 +228,37 @@ Roadmaps roll up progress recursively and choose the first startable plan across
 their child runlists. Runlists and roadmaps are held out of actionable plan
 counts so dashboards do not double-count their children.
 
+## Decisions
+
+A decision is an entry in its plan, not a document of its own. Write the record
+(the situation, what exists today, what each answer leaves in place) to a file
+and add it:
+
+```bash
+runlist new decision auth-revamp --question "Which token store?" @record.md
+```
+
+It takes the next id (`D1`, `D2`, …) that no decision item in that plan uses,
+lands at the end of the plan's top-level decisions section (created before
+`## Version History` when there is none) with a `Disposition: OPEN.` line, and
+refuses an empty record. `--disposition held` parks it instead.
+
+A corpus that indexes its decisions in one register numbers them in one
+sequence. Name the register, and the id follows the highest the register or the
+plan uses, and the register gets the entry's row in the same locked write:
+
+```js
+export const decisions = {
+  section: 'Decisions',
+  prefix: 'D',
+  register: { file: 'docs/plans/register.md', statusLine: 'waiting on you:' },
+};
+```
+
+The register block is the fenced block whose first line carries `statusLine`.
+The row is the question plus `--answers` (what each answer leaves in place),
+which is required when a register is configured.
+
 ## Safety Model
 
 - Mutation commands support `--dry-run` / `-n`.

package/bin/dotmd.mjs

@@ -1001,6 +1001,21 @@ Examples:
   EOF
   runlist new prompt cleanup-tomorrow "look at remaining lint warnings"
 
+Hubs and decisions:
+  runlist new hub <slug>                     # coordination hub (a plan)
+  runlist new hub <slug> --runlist a,b,c     # sprint hub plus child plans
+  runlist new hub <slug> --roadmap           # roadmap hub
+  runlist new decision <plan> --question "<question>" [--answers "<…>"] @record.md
+                       Adds the next numbered entry to the plan's top-level
+                       decisions section with a \`Disposition: OPEN.\` line (or
+                       \`--disposition held\`) and the record, which is required;
+                       a plan with no such section gets \`## Decisions\`. With a
+                       register in config, the id is numbered across the corpus
+                       and the register gets its row, question plus --answers
+                       (required then), in the same locked write. Config:
+                       \`export const decisions = { section, prefix,
+                       register: { file, statusLine } }\`.
+
 Scaffolding runlists (plans only):
   --runlist <a,b,c>    Create a sprint runlist hub plus one child plan per slug.
                        The hub carries \`runlist: [<hub>-01-a.md, <hub>-02-b.md, …]\`
@@ -1752,12 +1767,18 @@ async function main() {
     process.stderr.write(`Repo root: ${config.repoRoot}\n`);
   }
 
+  // A printed list shows status, title, age and next step, none of which the
+  // validating passes produce, so it reads the index the way `prompts` and
+  // `hud` do. `--json` emits each document's warnings and errors, so it still
+  // pays for the full pass.
+  const listIndexOptions = listArgs => (listArgs.includes('--json') ? {} : { fast: true });
+
   // Preset aliases (user config can override built-in commands below)
   if ((command === 'stale' || command === 'actionable') && !config.configuredPresetNames.has(command)) {
     const { buildIndex } = await import('../src/index.mjs');
     const { runQuery } = await import('../src/query.mjs');
     const { statusMetadataFor } = await import('../src/status-metadata.mjs');
-    const index = buildIndex(config);
+    const index = buildIndex(config, listIndexOptions(restArgs));
     applyIndexFilters(index);
     const docs = index.docs.filter(doc => {
       const metadata = statusMetadataFor(config, doc.type, doc.status);
@@ -1774,7 +1795,7 @@ async function main() {
   if (config.presets[command]) {
     const { buildIndex } = await import('../src/index.mjs');
     const { runQuery } = await import('../src/query.mjs');
-    const index = buildIndex(config);
+    const index = buildIndex(config, listIndexOptions([...config.presets[command], ...restArgs]));
     applyIndexFilters(index);
     runQuery(index, [...config.presets[command], ...restArgs], config, { preset: command, type: typeArg, root: rootArg });
     return;
@@ -1787,7 +1808,7 @@ async function main() {
   if (command === 'plans') {
     const { buildIndex } = await import('../src/index.mjs');
     const { runQuery } = await import('../src/query.mjs');
-    const index = buildIndex(config);
+    const index = buildIndex(config, listIndexOptions(restArgs));
     applyIndexFilters(index);
     const sub = restArgs[0];
     let defaults;
@@ -1807,7 +1828,7 @@ async function main() {
   if (command === 'runlists') {
     const { buildIndex } = await import('../src/index.mjs');
     const { runRunlists } = await import('../src/query.mjs');
-    const index = buildIndex(config);
+    const index = buildIndex(config, listIndexOptions(restArgs));
     applyIndexFilters(index);
     runRunlists(index, restArgs, config);
     return;
@@ -1818,7 +1839,7 @@ async function main() {
   if (command === 'roadmaps') {
     const { buildIndex } = await import('../src/index.mjs');
     const { runRoadmaps } = await import('../src/roadmap.mjs');
-    const index = buildIndex(config);
+    const index = buildIndex(config, listIndexOptions(restArgs));
     applyIndexFilters(index);
     runRoadmaps(index, restArgs, config);
     return;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dotmd-cli",
-  "version": "0.82.0",
+  "version": "0.84.0",
   "description": "CLI for managing markdown documents with YAML frontmatter — index, query, validate, graph, export, lifecycle, and AI summaries.",
   "type": "module",
   "license": "MIT",

package/src/config.mjs

@@ -137,6 +137,8 @@ const DEFAULTS = {
   templates: {},
 
   glossary: null,
+  // `runlist new decision`: { section, prefix, register: { file, statusLine } }.
+  decisions: null,
 
   // Opt-in JSONL command journal at .dotmd/journal.jsonl. Default off — agents
   // and users who want usage observability flip this on (or set RUNLIST_JOURNAL=1).
@@ -417,6 +419,14 @@ function validateConfig(userConfig, config, validStatuses, indexPath) {
     }
   }
 
+  if (userConfig.decisions != null) {
+    const d = userConfig.decisions;
+    if (typeof d !== 'object' || Array.isArray(d)) warnings.push('Config: decisions must be an object.');
+    else if (d.register != null && (typeof d.register?.file !== 'string' || typeof d.register?.statusLine !== 'string')) {
+      warnings.push('Config: decisions.register needs a file and a statusLine.');
+    }
+  }
+
   // Unknown top-level user config keys
   for (const key of Object.keys(userConfig)) {
     if (!VALID_CONFIG_KEYS.has(key)) {

package/src/decision.mjs

@@ -0,0 +1,220 @@
+import { readFileSync } from 'node:fs';
+import path from 'node:path';
+import { mutateFileSet } from './atomic-mutation.mjs';
+import { authorizeManagedSource } from './managed-path.mjs';
+import { walkSections } from './section.mjs';
+import { die, nowIso, resolveDocPath, toRepoPath } from './util.mjs';
+import { green, dim } from './color.mjs';
+
+// `runlist new decision <plan> --question "…" @record.md`
+//
+// A decision is not a document of its own: it is an entry in the owning plan's
+// decisions section, carrying an id, a disposition and a written record. This
+// adds one, numbered after the highest id of its prefix the plan (and the
+// register, when there is one) already uses, at the end of the plan's top-level
+// decisions section, creating `## Decisions` when the plan has none. A
+// decisions heading nested inside a workstream is that workstream's record and
+// is left alone.
+//
+// Config (`runlist.config.mjs`), all optional:
+//   export const decisions = {
+//     section: 'Decisions',   // the heading the entry lands under
+//     prefix: 'D',            // what a new id is written under
+//     register: { file: 'docs/plans/register.md', statusLine: 'waiting on you:' },
+//   };
+// With a register, ids are one sequence across the corpus: the next id is
+// numbered after the highest the register or the plan uses, and the register
+// gets the entry's index row in the same locked write as the plan. Without
+// one, ids are plan-local.
+
+const DISPOSITIONS = new Set(['open', 'held']);
+const DECISION_HEADING = /\bdecisions?\b/i;
+
+function splitDoc(raw) {
+  if (!raw.startsWith('---\n')) return null;
+  const end = raw.indexOf('\n---\n', 4);
+  if (end === -1) return null;
+  return { frontmatter: raw.slice(4, end), body: raw.slice(end + 5) };
+}
+
+function stripFences(text) {
+  return text.replace(/^(`{3,}|~{3,})[^\n]*\n[\s\S]*?^\1[^\n]*$/gm, '');
+}
+
+const escapeRe = text => text.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+
+// Ids are read where a decision item starts (a heading, a list or bold lead,
+// a table row or a register row), never from prose, where the same shape is
+// as likely to be a job code or a citation of another plan's decision.
+function highestId(text, prefix) {
+  const re = new RegExp(`^\\s*(?:#{1,6}\\s+|[-*]\\s+(?:\\[[ xX]\\]\\s+)?|\\|\\s*)?\\**${escapeRe(prefix)}(\\d{1,4})\\b`);
+  let max = 0;
+  for (const line of text.split('\n')) {
+    const m = line.match(re);
+    if (m) max = Math.max(max, Number(m[1]));
+  }
+  return max;
+}
+
+export function nextDecisionId(body, prefix, register = null) {
+  let max = highestId(stripFences(body), prefix);
+  if (register) {
+    const rows = register.rows.map(row => row.match(new RegExp(`^${escapeRe(prefix)}(\\d{1,4})\\b`))?.[1]);
+    for (const n of rows) if (n) max = Math.max(max, Number(n));
+  }
+  return `${prefix}${max + 1}`;
+}
+
+// The register block: a fence whose first line carries the configured status
+// line. Returns its rows and where the closing fence sits, or null.
+export function findRegister(text, statusLine) {
+  const lines = text.split('\n');
+  const wanted = statusLine.trim().toLowerCase();
+  for (let i = 0; i < lines.length; i++) {
+    const open = lines[i].match(/^(`{3,}|~{3,})/);
+    if (!open) continue;
+    let close = i + 1;
+    while (close < lines.length && !lines[close].startsWith(open[1])) close++;
+    if (close >= lines.length) return null;
+    const first = (lines[i + 1] ?? '').trim().toLowerCase();
+    if (first.includes(wanted)) {
+      return { closeLine: close, rows: lines.slice(i + 2, close).filter(line => line.trim()) };
+    }
+    i = close;
+  }
+  return null;
+}
+
+export function insertRegisterRow(text, register, row) {
+  const lines = text.split('\n');
+  let at = register.closeLine;
+  while (at > 0 && lines[at - 1].trim() === '') at--;
+  lines.splice(at, 0, row);
+  return lines.join('\n');
+}
+
+// Returns the new body and where the entry went. Pure, for tests.
+export function insertDecision(body, { id, question, disposition, record, section: heading = 'Decisions' }) {
+  const lines = body.split('\n');
+  const sections = walkSections(body);
+  const named = s => s.heading.replace(/[^\w\s]+$/, '').trim().toLowerCase() === heading.toLowerCase();
+  const section = sections.find(s => s.level === 2 && named(s))
+    ?? sections.find(s => s.level === 2 && DECISION_HEADING.test(s.heading));
+  const level = section ? Math.min(section.level + 1, 6) : 3;
+  const entry = [
+    `${'#'.repeat(level)} ${id}  ${question.trim()}`,
+    '',
+    `Disposition: ${disposition.toUpperCase()}.`,
+    '',
+    record.trim(),
+  ];
+
+  if (section) {
+    // After the section's last non-blank line, subsections included.
+    let at = section.lineEnd;
+    while (at > section.lineStart && lines[at - 1].trim() === '') at--;
+    const tail = at < lines.length && lines[at].trim() !== '' ? [''] : [];
+    lines.splice(at, 0, '', ...entry, ...tail);
+    return { body: lines.join('\n'), placement: `under \`${section.heading}\``, heading: section.heading };
+  }
+
+  const block = [`## ${heading}`, '', ...entry];
+  const before = sections.find(s => s.level === 2 && /^(version history|closeout)\b/i.test(s.heading));
+  if (before) {
+    lines.splice(before.lineStart - 1, 0, ...block, '');
+    return { body: lines.join('\n'), placement: `in a new \`## ${heading}\` before \`${before.heading}\``, heading };
+  }
+  const trimmed = body.replace(/\n+$/, '');
+  return { body: `${trimmed}\n\n${block.join('\n')}\n`, placement: `in a new \`## ${heading}\` at the end`, heading };
+}
+
+export function runNewDecision({ planArg, question, disposition, record, answers = null }, config, { dryRun = false } = {}) {
+  const usage = 'Usage: runlist new decision <plan> --question "<the question>" @record.md';
+  if (!planArg) die(`${usage}\nThe plan is the file whose decisions section gets the entry.`);
+  if (!question || !question.trim()) die(`--question is required.\n${usage}`);
+  if (/\n/.test(question)) die('--question is one line; the record carries the rest.');
+  if (!record || !record.trim()) {
+    die('A decision needs its record: the situation, what exists today, and what each answer leaves in place.\n'
+      + `Write it to a file and pass @path, pipe it in, or pass --body "...".\n${usage}`);
+  }
+  disposition = (disposition ?? 'open').toLowerCase();
+  if (!DISPOSITIONS.has(disposition)) {
+    die(`--disposition must be open or held; a ruled or closed decision is edited in place, not added.`);
+  }
+
+  const resolved = resolveDocPath(planArg, config)
+    ?? (planArg.endsWith('.md') ? null : resolveDocPath(`${planArg}.md`, config))
+    ?? (planArg.includes('/') ? null : resolveDocPath(path.join('plans', `${planArg}.md`), config));
+  if (!resolved) die(`No such plan: ${planArg}`);
+  const planPath = authorizeManagedSource(resolved, config, { kind: 'Decision target' }).path;
+  const planRepoPath = toRepoPath(planPath, config.repoRoot);
+
+  const settings = config.raw?.decisions ?? {};
+  const prefix = settings.prefix ?? 'D';
+  const section = settings.section ?? 'Decisions';
+  let registerPath = null;
+  if (settings.register?.file) {
+    if (!settings.register.statusLine) die('decisions.register needs a statusLine: the first line of the register block.');
+    const registerResolved = resolveDocPath(settings.register.file, config);
+    if (!registerResolved) die(`The decisions register in config does not exist: ${settings.register.file}`);
+    registerPath = authorizeManagedSource(registerResolved, config, { kind: 'Decision register' }).path;
+  }
+  const sameFile = registerPath === planPath;
+  if (registerPath && (!answers || !answers.trim())) {
+    die('--answers is required with a register: the row says what each answer leaves in place and what it costs.\n'
+      + `${usage} --answers "Yes: … No: …"`);
+  }
+
+  const today = nowIso();
+  const planRaw = readFileSync(planPath, 'utf8');
+  const registerRaw = registerPath && !sameFile ? readFileSync(registerPath, 'utf8') : null;
+
+  const planDoc = splitDoc(planRaw.replace(/\r\n/g, '\n'));
+  if (!planDoc) die(`${planRepoPath} has no frontmatter block; runlist only adds decisions to managed documents.`);
+  const registerText = sameFile ? planDoc.body : registerRaw?.replace(/\r\n/g, '\n');
+  const register = registerPath ? findRegister(registerText, settings.register.statusLine) : null;
+  if (registerPath && !register) {
+    die(`${toRepoPath(registerPath, config.repoRoot)} has no block whose first line carries "${settings.register.statusLine}".`);
+  }
+
+  const id = nextDecisionId(planDoc.body, prefix, register);
+  const inserted = insertDecision(planDoc.body, { id, question, disposition, record, section });
+  let planBody = inserted.body;
+  let row = null;
+  if (register && sameFile) {
+    row = registerRow({ id, disposition, today, question, answers, heading: inserted.heading, link: path.basename(planPath) });
+    planBody = insertRegisterRow(planBody, findRegister(planBody, settings.register.statusLine), row);
+  }
+  const bump = fm => (/^updated:/m.test(fm) ? fm.replace(/^updated:.*$/m, `updated: ${today}`) : fm);
+  const planOut = `---\n${bump(planDoc.frontmatter)}\n---\n${planBody}`;
+
+  const updates = [{ path: planPath, expectedContent: planRaw, content: planOut }];
+  if (register && !sameFile) {
+    const link = path.relative(path.dirname(registerPath), planPath).split(path.sep).join('/');
+    row = registerRow({ id, disposition, today, question, answers, heading: inserted.heading, link });
+    const registerOut = insertRegisterRow(registerText, register, row);
+    const registerDoc = splitDoc(registerOut);
+    updates.push({
+      path: registerPath,
+      expectedContent: registerRaw,
+      content: registerDoc ? `---\n${bump(registerDoc.frontmatter)}\n---\n${registerDoc.body}` : registerOut,
+    });
+  }
+
+  const registerRepoPath = registerPath ? toRepoPath(registerPath, config.repoRoot) : null;
+  if (dryRun) {
+    process.stdout.write(`[dry-run] Would add ${id} to ${planRepoPath} ${inserted.placement}\n`);
+    if (row) process.stdout.write(`[dry-run] Would add its row to the register in ${registerRepoPath}:\n  ${row}\n`);
+    return { id, row };
+  }
+
+  mutateFileSet({ updates }, { repoRoot: config.repoRoot });
+  process.stdout.write(`${green('Added')} ${id} to ${planRepoPath} ${dim(inserted.placement)}\n`);
+  if (row) process.stdout.write(`${green('Added')} its row to the register in ${registerRepoPath}\n`);
+  return { id, row };
+}
+
+function registerRow({ id, disposition, today, question, answers, heading, link }) {
+  const text = `${question.trim()} ${answers.trim()}`;
+  return `${id} ${disposition.toUpperCase()} ${today.slice(0, 10)}: ${text} Record: [${link} § ${heading} ${id}](${link}).`;
+}

package/src/extractors.mjs

@@ -42,7 +42,8 @@ export function extractNextStep(body) {
 }
 
 export function extractBodyLinks(body) {
-  if (!body) return [];
+  // Every inline link contains `](`, and masking never creates one.
+  if (!body || !body.includes('](')) return [];
   // Strip fenced code blocks, then MASK inline code rather than delete it.
   // Deleting it ate the commonest link idiom in a plan hub: [`plan.md`](plan.md)
   // has its link TEXT as a code span, so removing the span left `[](plan.md)`,

package/src/index.mjs

@@ -4,6 +4,7 @@ import { extractFrontmatter, parseSimpleFrontmatter } from './frontmatter.mjs';
 import { extractFirstHeading, extractSummary, extractStatusSnapshot, extractNextStep, extractChecklistCounts, extractBodyLinks } from './extractors.mjs';
 import { asString, normalizeStringList, normalizeBlockers, mergeUniqueStrings, toRepoPath, warn, die, resolveDocPath, suggestCandidates } from './util.mjs';
 import { findLexicalDocsRoot } from './managed-path.mjs';
+import { openParseCache, fileStamp, stampSize } from './parse-cache.mjs';
 import { validateDoc, validatePlanShape, validateDocShape, checkBidirectionalReferences, checkGitStaleness, checkRunlistBackPointers, checkCoordinationHubExecutionMode, checkRoadmapHubExecutionMode, computeDaysSinceUpdate, computeIsStale, computeChecklistCompletionRate, enrichRefErrorSuggestions } from './validate.mjs';
 import { checkIndex } from './index-file.mjs';
 import { checkClaudeCommands } from './claude-commands.mjs';
@@ -30,7 +31,9 @@ export function buildIndex(config, opts = {}) {
   const invokeHooks = opts.invokeHooks ?? !config._execution?.suppressSideEffects;
   const gitStaleness = opts.gitStaleness ?? config._execution?.gitStaleness ?? true;
   const skipWarningOnlyChecks = fast || errorsOnly;
-  const docs = collectDocFiles(config).map(f => parseDocFile(f, config, { fast }));
+  const cache = openParseCache(config);
+  const docs = collectDocFiles(config).map(f => parseDocFile(f, config, { fast, cache }));
+  if (cache && !config._execution?.suppressSideEffects) cache.save();
   if (!fast) {
     // Per-file validation (validateDoc) ran during parse without sibling
     // visibility. Now that the full index is materialized, enrich
@@ -271,16 +274,45 @@ function walkMarkdownFiles(directory, files, excludedDirs, skipPaths, seen = new
   }
 }
 
-export function parseDocFile(filePath, config, opts = {}) {
-  const { fast = false } = opts;
-  const relativePath = toRepoPath(filePath, config.repoRoot);
-  const raw = readFileSync(filePath, 'utf8');
-  const { frontmatter, body } = extractFrontmatter(raw);
+// Everything parseDocFile takes from the file's text alone, with no config and
+// no clock, which is what the parse cache may keep.
+function extractDocText(frontmatter, body) {
   const fmWarnings = [];
   const parsedFrontmatter = parseSimpleFrontmatter(frontmatter, fmWarnings);
-  const headingTitle = extractFirstHeading(body);
+  return {
+    parsedFrontmatter,
+    fmWarnings: fmWarnings.map(w => ({ message: w.message })),
+    headingTitle: extractFirstHeading(body),
+    bodySummary: extractSummary(body),
+    bodyStatusSnapshot: extractStatusSnapshot(body),
+    bodyNextStep: extractNextStep(body),
+    checklist: extractChecklistCounts(body),
+    bodyLinks: extractBodyLinks(body),
+    hasCloseout: /^##\s+Closeout/m.test(body),
+  };
+}
+
+export function parseDocFile(filePath, config, opts = {}) {
+  const { fast = false, cache = null } = opts;
+  const relativePath = toRepoPath(filePath, config.repoRoot);
+  const stamp = cache ? fileStamp(filePath) : null;
+  let text = stamp ? cache.get(relativePath, stamp) : null;
+  // Validation reads the body itself, so only a fast build can skip the read.
+  let body = null;
+  if (!text || !fast) {
+    const raw = readFileSync(filePath, 'utf8');
+    const extracted = extractFrontmatter(raw);
+    body = extracted.body;
+    // A file rewritten between the stat and the read no longer matches its stamp.
+    if (text && Buffer.byteLength(raw) !== stampSize(stamp)) text = null;
+    if (!text) {
+      text = extractDocText(extracted.frontmatter, body);
+      if (stamp) cache.set(relativePath, stamp, text);
+    }
+  }
+  const { parsedFrontmatter, fmWarnings, headingTitle, checklist, bodyLinks, hasCloseout } = text;
   const title = asString(parsedFrontmatter.title) ?? headingTitle ?? path.basename(filePath, '.md');
-  const summary = asString(parsedFrontmatter.summary) ?? extractSummary(body) ?? null;
+  const summary = asString(parsedFrontmatter.summary) ?? text.bodySummary ?? null;
   // For terminal-status docs (archived / reference / deprecated by default),
   // skip the body-scrape and the "No current_state set" fallback when the user
   // didn't set `current_state:` in frontmatter explicitly. Body text on a
@@ -305,7 +337,7 @@ export function parseDocFile(filePath, config, opts = {}) {
   } else if (isTerminalDoc) {
     currentState = null;
   } else {
-    const scraped = extractStatusSnapshot(body);
+    const scraped = text.bodyStatusSnapshot;
     if (scraped) {
       currentState = scraped;
       currentStateOrigin = 'body';
@@ -313,7 +345,7 @@ export function parseDocFile(filePath, config, opts = {}) {
       currentState = 'No current_state set';
     }
   }
-  const nextStep = asString(parsedFrontmatter.next_step) ?? extractNextStep(body) ?? null;
+  const nextStep = asString(parsedFrontmatter.next_step) ?? text.bodyNextStep ?? null;
   // `blocked_by` is accepted as an alias for `blockers` since 0.39.3 — agents
   // filing tickets naturally reach for the JIRA/Linear name. If both are set,
   // they're merged (de-duped via normalizeBlockers → mergeUniqueStrings).
@@ -328,9 +360,6 @@ export function parseDocFile(filePath, config, opts = {}) {
   const domain = asString(parsedFrontmatter.domain) ?? null;
   const audience = asString(parsedFrontmatter.audience) ?? null;
   const executionMode = asString(parsedFrontmatter.execution_mode) ?? null;
-  const checklist = extractChecklistCounts(body);
-  const bodyLinks = extractBodyLinks(body);
-  const hasCloseout = /^##\s+Closeout/m.test(body);
 
   // Dynamic reference field extraction. A leading `>` on a value (e.g.
   // `"> docs/audit-beyond-platform.md"`) marks that single ref as one-way —

package/src/markdown-code-spans.mjs

@@ -1,7 +1,5 @@
-function maskRange(value, start, end) {
-  return value.slice(0, start)
-    + value.slice(start, end).replace(/[^\n]/g, 'x')
-    + value.slice(end);
+function mask(text) {
+  return text.includes('\n') ? text.replace(/[^\n]/g, 'x') : 'x'.repeat(text.length);
 }
 
 // Markdown code spans close only on a backtick run of the same length as their
@@ -11,13 +9,19 @@ function maskRange(value, start, end) {
 // rewriter survive: after an unmatched opener, nothing is treated as prose
 // until a compatible closer appears.
 export function maskInlineCodeLine(line, state = { run: null }) {
-  const ranges = [];
+  if (!line.includes('`')) return state.run === null ? line : mask(line);
+
   const runs = [...line.matchAll(/`+/g)];
+  const findCloser = (from, length) => {
+    for (let i = from; i < runs.length; i++) if (runs[i][0].length === length) return i;
+    return -1;
+  };
+  const ranges = [];
   let index = 0;
 
   if (state.run !== null) {
-    const closingIndex = runs.findIndex(candidate => candidate[0].length === state.run);
-    if (closingIndex === -1) return maskRange(line, 0, line.length);
+    const closingIndex = findCloser(0, state.run);
+    if (closingIndex === -1) return mask(line);
     const closing = runs[closingIndex];
     ranges.push([0, closing.index + closing[0].length]);
     index = closingIndex + 1;
@@ -26,8 +30,7 @@ export function maskInlineCodeLine(line, state = { run: null }) {
 
   for (; index < runs.length; index++) {
     const opening = runs[index];
-    const closingIndex = runs.findIndex((candidate, candidateIndex) =>
-      candidateIndex > index && candidate[0].length === opening[0].length);
+    const closingIndex = findCloser(index + 1, opening[0].length);
     if (closingIndex === -1) {
       ranges.push([opening.index, line.length]);
       state.run = opening[0].length;
@@ -38,7 +41,15 @@ export function maskInlineCodeLine(line, state = { run: null }) {
     index = closingIndex;
   }
 
-  return ranges.reduceRight((masked, [start, end]) => maskRange(masked, start, end), line);
+  // Ranges are ascending and disjoint, so one left-to-right pass builds the
+  // result instead of re-copying the whole line once per span.
+  let out = '';
+  let cursor = 0;
+  for (const [start, end] of ranges) {
+    out += line.slice(cursor, start) + mask(line.slice(start, end));
+    cursor = end;
+  }
+  return out + line.slice(cursor);
 }
 
 export function maskInlineCodeSpans(value) {

package/src/new.mjs

@@ -2,6 +2,7 @@ import { spawnSync } from 'node:child_process';
 import { existsSync, readFileSync, mkdirSync, fstatSync } from 'node:fs';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
+import { runNewDecision } from './decision.mjs';
 import { toRepoPath, die, warn, nowIso, emitFilesFooter } from './util.mjs';
 import { green, dim, bold } from './color.mjs';
 import { isInteractive, promptText } from './prompt.mjs';
@@ -652,9 +653,14 @@ next_step:
 export async function runNew(argv, config, opts = {}) {
   const { dryRun } = opts;
 
+  if (argv.find(a => !a.startsWith('-')) === 'decision') return runNewDecisionArgs(argv, config, opts);
+
   const knownTypes = new Set(Object.keys(BUILTIN_TEMPLATES));
   // Also include any custom templates from config
   for (const k of Object.keys(config.raw?.templates ?? {})) knownTypes.add(k);
+  // `hub` is a plan with a hub body; `decision` is handled above.
+  knownTypes.add('hub');
+  knownTypes.add('decision');
 
   const hasNameForBody = args => {
     if (args.length >= 2 && knownTypes.has(args[0])) return true;
@@ -713,11 +719,27 @@ export async function runNew(argv, config, opts = {}) {
     name = positional[1];
     if (positional.length > 2) bodyArg = positional.slice(2).join(' ');
   } else {
+    // `new <name> <inline body>` is a doc with the type left out, but a single
+    // bare word in the body slot is almost always a mistyped type and a slug
+    // (`new decison foo`), which used to create `<type-name>.md` with the slug
+    // as its whole body.
+    const [first, second] = positional;
+    if (positional.length === 2 && !/[/\\]|\.md$/.test(first) && /^[A-Za-z][\w.-]*$/.test(second)) {
+      die(`Unknown type \`${first}\`. Types: ${[...knownTypes].join(', ')}.\n`
+        + `For a doc named ${first} with "${second}" as its body, run: runlist new doc ${first} "${second}"`);
+    }
     typeName = 'doc';
     name = positional[0];
     if (positional.length > 1) bodyArg = positional.slice(1).join(' ');
   }
 
+  // A hub is a plan with a hub body. Coordination is the default shape, being
+  // the one a hub without children or tiers has.
+  if (typeName === 'hub') {
+    typeName = 'plan';
+    if (runlistArg === null && !roadmap) coordination = true;
+  }
+
   if (!name) {
     if (isInteractive()) {
       name = await promptText(`${typeName} name: `);
@@ -1145,6 +1167,8 @@ export function newHelpForRepo(config) {
     if (statuses.length) rows.push(`  ${''.padEnd(width)}   statuses: ${statuses.join(', ')}`);
   }
   const roots = (config.docsRoots ?? [config.docsRoot]).map(r => path.basename(r));
+  rows.push(`  ${'hub'.padEnd(width)} → a plan with a hub body (coordination unless --runlist or --roadmap)`);
+  rows.push(`  ${'decision'.padEnd(width)} → an entry in an existing plan's decisions section`);
   return `This repo:
 ${rows.join('\n')}
   roots (for --root): ${roots.join(', ')}`;
@@ -1206,4 +1230,29 @@ function listTemplates(config) {
     if (desc) process.stdout.write(`  ${dim(desc)}\n`);
     process.stdout.write('\n');
   }
+  process.stdout.write(`  hub\n  ${dim('A plan with a hub body: coordination by default, --runlist or --roadmap for the others.')}\n\n`);
+  process.stdout.write(`  decision\n  ${dim('An entry in an existing plan\'s decisions section: runlist new decision <plan> --question "…" @record.md')}\n\n`);
+}
+
+function runNewDecisionArgs(argv, config, opts) {
+  const positional = [];
+  let question = null;
+  let disposition = null;
+  let answers = null;
+  let bodyFlag = null;
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === '--question' && argv[i + 1] !== undefined) { question = argv[++i]; continue; }
+    if (a === '--disposition' && argv[i + 1] !== undefined) { disposition = argv[++i]; continue; }
+    if (a === '--answers' && argv[i + 1] !== undefined) { answers = argv[++i]; continue; }
+    if ((a === '--body' || a === '--message') && argv[i + 1] !== undefined) { bodyFlag = argv[++i]; continue; }
+    if (a === '--config' || a === '--root') { i++; continue; }
+    if (!a.startsWith('-') || a === '-') positional.push(a);
+  }
+  const [, planArg, ...rest] = positional;
+  let record = null;
+  if (bodyFlag !== null) record = readBodyInput(bodyFlag);
+  else if (rest.length) record = readBodyInput(rest.join(' '));
+  else record = readPipedBodyInput();
+  return runNewDecision({ planArg, question, disposition, record, answers }, config, { dryRun: opts.dryRun });
 }

package/src/parse-cache.mjs

@@ -0,0 +1,99 @@
+import { existsSync, readFileSync, statSync, writeFileSync, unlinkSync } from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { commitRename } from './durable-rename.mjs';
+import { readEnv, stateDir } from './naming.mjs';
+
+// What every build of the index used to redo from scratch: read each document
+// and pull its frontmatter, links, checklist and summary out of the body. None
+// of that depends on the config or the clock, so it is kept per file under the
+// state directory and reused while the file's size, times and inode are
+// unchanged. Everything that does depend on them (terminal statuses, staleness,
+// reference fields, validation) is still computed on every run.
+//
+// One line per document, `path \t stamp \t json`, so a hit parses only its own
+// line and hands back fresh objects: nothing a caller does to a document can
+// leak into what is saved. The cache is an optimisation and never an input:
+// a missing, unreadable or foreign-version file is treated as empty, a failed
+// write is dropped, and `RUNLIST_NO_PARSE_CACHE=1` turns it off.
+
+const SCHEMA = 1;
+const FILE_NAME = 'parse-cache';
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const VERSION = (() => {
+  try { return JSON.parse(readFileSync(path.join(__dirname, '..', 'package.json'), 'utf8')).version; }
+  catch { return 'unknown'; }
+})();
+const HEADER = JSON.stringify({ schema: SCHEMA, version: VERSION });
+
+export function fileStamp(filePath) {
+  try {
+    const s = statSync(filePath, { bigint: true });
+    return `${s.size}:${s.mtimeNs}:${s.ctimeNs}:${s.ino}`;
+  } catch {
+    return null;
+  }
+}
+
+export function stampSize(stamp) {
+  return Number(stamp.slice(0, stamp.indexOf(':')));
+}
+
+export function openParseCache(config) {
+  if (readEnv('NO_PARSE_CACHE') === '1') return null;
+  const dir = stateDir(config.repoRoot);
+  // The state directory is created, and ignored by git, by `init` and the
+  // commands that own it; a repo without one gets no cache rather than a new
+  // untracked folder from a read-only command.
+  if (!existsSync(dir)) return null;
+  const cachePath = path.join(dir, FILE_NAME);
+  const lines = new Map();
+  try {
+    const text = readFileSync(cachePath, 'utf8');
+    const rows = text.split('\n');
+    if (rows[0] === HEADER) {
+      for (let i = 1; i < rows.length; i++) {
+        const row = rows[i];
+        const a = row.indexOf('\t');
+        const b = row.indexOf('\t', a + 1);
+        if (a < 0 || b < 0) continue;
+        lines.set(row.slice(0, a), { stamp: row.slice(a + 1, b), row });
+      }
+    }
+  } catch { /* no cache yet */ }
+
+  const seen = new Set();
+  let dirty = false;
+
+  return {
+    get(key, stamp) {
+      seen.add(key);
+      const entry = lines.get(key);
+      if (!entry || entry.stamp !== stamp) return null;
+      try { return JSON.parse(entry.row.slice(entry.row.indexOf('\t', entry.row.indexOf('\t') + 1) + 1)); }
+      catch { return null; }
+    },
+    set(key, stamp, value) {
+      seen.add(key);
+      if (/[\t\n]/.test(key)) return;
+      lines.set(key, { stamp, row: `${key}\t${stamp}\t${JSON.stringify(value)}` });
+      dirty = true;
+    },
+    save({ complete = true } = {}) {
+      if (complete) {
+        for (const key of lines.keys()) {
+          if (!seen.has(key)) { lines.delete(key); dirty = true; }
+        }
+      }
+      if (!dirty) return;
+      const temp = `${cachePath}.${process.pid}.${Date.now()}.tmp`;
+      try {
+        writeFileSync(temp, [HEADER, ...[...lines.values()].map(entry => entry.row)].join('\n'), 'utf8');
+        commitRename(temp, cachePath);
+        dirty = false;
+      } catch {
+        try { unlinkSync(temp); } catch { /* already gone */ }
+      }
+    },
+  };
+}

package/src/pickup.mjs

@@ -1,5 +1,5 @@
 import { createHash, randomUUID } from 'node:crypto';
-import { existsSync, mkdirSync, readFileSync, readdirSync, realpathSync, statSync } from 'node:fs';
+import { existsSync, lstatSync, mkdirSync, readFileSync, readdirSync, realpathSync, statSync } from 'node:fs';
 import path from 'node:path';
 import { authorizeManagedSource, authorizeRepoGeneratedPath } from './managed-path.mjs';
 import os from 'node:os';
@@ -233,7 +233,48 @@ function validateBinding(record, identity, config) {
   return record;
 }
 
+// Working out a plan's canonical identity lists every directory on its path,
+// three times over, and listing plans asks it of every plan in the repo. A
+// record can only belong to a plan whose file name it carries, so the names in
+// the ownership folder rule most plans out first. The summary is rebuilt
+// whenever the folder changes, and any record it cannot read turns the check
+// off, so the full identity check still decides every case it could get wrong.
+let ownershipNamesCache = null;
+
+function ownershipNames(config) {
+  const dir = ownershipRoot(config);
+  let stamp;
+  try { stamp = `${dir}\0${statSync(dir, { bigint: true }).mtimeNs}`; }
+  catch { return new Set(); }
+  if (ownershipNamesCache?.stamp === stamp) return ownershipNamesCache.names;
+  let names = new Set();
+  try {
+    for (const entry of readdirSync(dir)) {
+      if (!entry.endsWith('.json')) continue;
+      const record = parseOwnership(readFileSync(path.join(dir, entry), 'utf8'), entry);
+      if (record.corrupt) { names = null; break; }
+      names.add(path.basename(record.canonicalPath).toLowerCase());
+      names.add(path.basename(record.plan).toLowerCase());
+    }
+  } catch { names = null; }
+  ownershipNamesCache = { stamp, names };
+  return names;
+}
+
+function mayHaveOwnershipRecord(absolutePath, config) {
+  const names = ownershipNames(config);
+  if (names === null || names.has(path.basename(absolutePath).toLowerCase())) return true;
+  try {
+    if (lstatSync(absolutePath).isSymbolicLink()) return true;
+    // A record whose fields were rewritten still sits at its identity's file
+    // name, and has to be found to be reported corrupt.
+    const guess = createHash('sha256').update(realpathSync(absolutePath)).digest('hex');
+    return existsSync(path.join(ownershipRoot(config), `${guess}.json`));
+  } catch { return true; }
+}
+
 export function readPlanOwnership(repoPath, config) {
+  if (!mayHaveOwnershipRecord(path.resolve(config.repoRoot, repoPath), config)) return null;
   let identity;
   try { identity = canonicalPlanIdentity(path.resolve(config.repoRoot, repoPath), config); }
   catch { return null; }