dotmd-cli 0.83.0 → 0.85.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,60 @@ 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.
+
+## Flags
+
+A flag is something someone found that the person should know about when they
+come back: a plan that contradicts another, a decision open in one place and
+ruled in another, a citation that no longer says what it claims. Any session,
+person or check can add one, and no model is needed:
+
+```bash
+runlist flag add docs/plans/auth.md:42 "says tokens expire in 1h; the spec says 24h" --severity problem
+runlist flags                 # open flags, problems first, newest first
+runlist flag accept F3 --note "real, owner agrees"
+runlist flag reject F4        # not a problem; closed
+runlist flag resolve F3       # fixed
+runlist check --flag          # the check's errors become flags, attributed to it
+```
+
+Each flag keeps the text of the line it points at, so the list says when that
+line has moved or changed since. A repeat of an open flag on the same place is
+merged. The log is append-only, `.runlist/flags.jsonl` by default
+(`export const flags = { file }` moves it), and triage is recorded as events
+beside the flag, never over it. Every session start shows a count and the top
+open flags.
+
 ## 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, …]\`
@@ -1880,6 +1895,8 @@ async function main() {
   if (command === 'deps') { const { runDeps } = await import('../src/deps.mjs'); runDeps(restArgs, config); return; }
   if (command === 'unblocks') { const { runUnblocks } = await import('../src/deps.mjs'); runUnblocks(restArgs, config); return; }
   if (command === 'health') { const { runHealth } = await import('../src/health.mjs'); runHealth(restArgs, config); return; }
+  if (command === 'flags') { const { runFlags } = await import('../src/flags.mjs'); runFlags(restArgs, config); return; }
+  if (command === 'flag') { const { runFlag } = await import('../src/flags.mjs'); runFlag(restArgs, config); return; }
   if (command === 'glossary') { const { runGlossary } = await import('../src/glossary.mjs'); runGlossary(restArgs, config); return; }
   if (command === 'export') { const { runExport } = await import('../src/export.mjs'); runExport(restArgs, config, { dryRun, root: rootArg, type: typeArg }); return; }
 
@@ -1999,6 +2016,17 @@ async function main() {
       ? ['validate', 'transformDoc', 'formatSnapshot', 'renderCheck']
           .filter(name => typeof config.hooks?.[name] === 'function')
       : [];
+    // `--flag` puts each error on the flags list, attributed to this check, and
+    // resolves the check's earlier flags it no longer reports. Whole-repo runs
+    // only: a scoped run cannot tell a fixed error from one outside its scope.
+    const flagCheckErrors = async (checkIndex) => {
+      if (!args.includes('--flag') || dryRun) return;
+      if (checkTargets.length > 0) die('`--flag` runs on the whole repository; drop the path arguments.');
+      const { syncCheckFlags } = await import('../src/flags.mjs');
+      const findings = checkIndex.errors.filter(e => e.path).map(e => ({ file: e.path, text: e.message }));
+      const { added, resolved } = syncCheckFlags(config, 'runlist check', findings);
+      process.stderr.write(`flags: ${added} added, ${resolved} resolved\n`);
+    };
     const checkJson = (checkIndex) => {
       const builtInPassed = checkIndex.errors.length === 0;
       const complete = skippedCheckHooks.length === 0;
@@ -2053,6 +2081,7 @@ async function main() {
       applyIndexFilters(freshIndex);
       applyPathScopeToIndex(freshIndex, config, checkTargets);
       applyFloor(freshIndex);
+      await flagCheckErrors(freshIndex);
       if (args.includes('--json')) {
         process.stdout.write(JSON.stringify(checkJson(freshIndex), null, 2) + '\n');
       } else {
@@ -2065,6 +2094,7 @@ async function main() {
 
     applyPathScopeToIndex(index, config, checkTargets);
     applyFloor(index);
+    await flagCheckErrors(index);
 
     if (args.includes('--json')) {
       process.stdout.write(JSON.stringify(checkJson(index), null, 2) + '\n');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dotmd-cli",
-  "version": "0.83.0",
+  "version": "0.85.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/commands.mjs

@@ -78,6 +78,15 @@ const definitions = [
   command('summary', none, 'read', [form('<file>', { args: positionals(1, 1), options: [value('--model'), value('--max-tokens'), flag('--json')] })]),
   command('unblocks', none, 'read', [form('<file>', { args: positionals(1, 1), options: [flag('--json')] })]),
   command('health', none, 'read', [form('', { options: [flag('--json')] })]),
+  command('flags', none, 'read', [form('', { options: [flag('--all'), flag('--json')] })]),
+  command('flag', mutates('the flags log under the state directory'), 'mutate', [
+    form('add <file[:line]> <text...>', { subcommands: ['add'], args: positionals(2, Infinity), options: [value('--severity'), value('--by')] }),
+    form('accept <id>', { subcommands: ['accept'], args: positionals(1, 1), options: [value('--note'), value('--by')] }),
+    form('reject <id>', { subcommands: ['reject'], args: positionals(1, 1), options: [value('--note'), value('--by')] }),
+    form('resolve <id>', { subcommands: ['resolve'], args: positionals(1, 1), options: [value('--note'), value('--by')] }),
+    form('show <id>', { subcommands: ['show'], args: positionals(1, 1) }),
+    form('sync <check-name> [findings]', { subcommands: ['sync'], args: positionals(1, 2), dashPositionalsAfter: 1 }),
+  ]),
   command('glossary', none, 'read', [form('[term]', { args: positionals(0, 1), options: [flag('--list'), flag('--json')] })]),
   command('modules', none, 'read', [form('', { options: [value('--sort'), value('--limit'), flag('--all'), flag('--json')] })]),
   command('module', none, 'read', [form('<name>', { args: positionals(1, 1), options: [value('--sort'), flag('--json')] })]),
@@ -129,7 +138,7 @@ const definitions = [
   command('touch', mutates('managed source or managed source sweep'), 'mutate', [form('[file...]', { args: positionals(0, Infinity), options: [flag('--git')] })]),
   command('new', mutates('managed document destination; external body input unrestricted'), 'mutate', [form('[type] <name> [body...]', {
     args: positionals(0, Infinity),
-    options: [value('--status'), value('--title'), value('--runlist'), flag('--coordination'), flag('--roadmap'), flag('--lite', '--minimal'), flag('--audit', '--findings'), value('--body', '--message'), value('--root'), flag('--show-files'), flag('--list-templates', '--list-types')],
+    options: [value('--status'), value('--title'), value('--runlist'), flag('--coordination'), flag('--roadmap'), flag('--lite', '--minimal'), flag('--audit', '--findings'), value('--body', '--message'), value('--root'), flag('--show-files'), flag('--list-templates', '--list-types'), value('--question'), value('--answers'), value('--disposition')],
     dashPositionalsAfter: 1,
   })]),
   command('lint', mutates('managed source sweep with --fix; otherwise read-only'), 'mutate', [form('', { options: [flag('--fix')] })]),
@@ -151,7 +160,7 @@ const definitions = [
     form('migrate <type>', { subcommands: ['migrate'], args: positionals(1, 1), options: [flag('--yes', '-y'), flag('--json'), flag('--ignore-lifecycle-override')] }),
     form('', { options: [value('--type'), flag('--json')] }),
   ]),
-  command('check', mutates('managed fix sweeps and repo-generated index; otherwise validation'), 'mutate', [form('[paths...]', { args: positionals(0, Infinity), options: [flag('--fix'), flag('--errors-only'), flag('--no-collapse'), flag('--json'), flag('--verbose'), value('--min-docs')] })]),
+  command('check', mutates('managed fix sweeps and repo-generated index; otherwise validation'), 'mutate', [form('[paths...]', { args: positionals(0, Infinity), options: [flag('--fix'), flag('--errors-only'), flag('--no-collapse'), flag('--json'), flag('--verbose'), value('--min-docs'), flag('--flag')] })]),
   command('index', mutates('repo-generated index destination; --print is read-only'), 'mutate', [form('', { options: [flag('--print')] })]),
 
   command('self-check', none, 'internal', [form('', { options: [flag('--json')] })], { visibility: 'internal' }),

package/src/config.mjs

@@ -137,6 +137,10 @@ const DEFAULTS = {
   templates: {},
 
   glossary: null,
+  // `runlist new decision`: { section, prefix, register: { file, statusLine } }.
+  decisions: null,
+  // `runlist flag` / `runlist flags`: { file } moves the log from .runlist/flags.jsonl.
+  flags: 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 +421,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/flags.mjs

@@ -0,0 +1,299 @@
+import { appendFileSync, existsSync, mkdirSync, readFileSync } from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { withPathLocks } from './atomic-mutation.mjs';
+import { stateDir } from './naming.mjs';
+import { die, hostSessionSource, nowIso, toRepoPath } from './util.mjs';
+import { bold, dim, green, red, yellow } from './color.mjs';
+
+// Flags: what anyone found that the person should know when they come back —
+// a plan contradicting another, a decision open in one place and ruled in
+// another, a citation that no longer says what it claims. A session, a person
+// or a check adds one; no model is needed. A later pass may build context onto
+// an open flag, but the flag stands on what its author wrote.
+//
+// Storage is an append-only event log (`add`, `accept`, `reject`, `resolve`),
+// one JSON object per line, so nothing is overwritten and the triage record
+// survives as written. The current state of a flag is derived from its events.
+// Default path `.runlist/flags.jsonl`; `export const flags = { file }` moves it.
+
+export const SEVERITIES = ['problem', 'warn', 'info'];
+const TRIAGE = new Set(['accept', 'reject', 'resolve']);
+const QUOTE_MAX = 200;
+
+export function flagsFile(config) {
+  const configured = config.raw?.flags?.file;
+  return configured ? path.resolve(config.repoRoot, configured) : path.join(stateDir(config.repoRoot), 'flags.jsonl');
+}
+
+export function readFlagEvents(file) {
+  if (!existsSync(file)) return [];
+  const events = [];
+  for (const line of readFileSync(file, 'utf8').split('\n')) {
+    if (!line.trim()) continue;
+    try { events.push(JSON.parse(line)); } catch { /* a torn line is skipped, never fatal */ }
+  }
+  return events;
+}
+
+export function deriveFlags(events) {
+  const flags = new Map();
+  for (const e of events) {
+    if (e.event === 'add' && e.id && !flags.has(e.id)) {
+      flags.set(e.id, { ...e, state: 'open', triage: null, history: [] });
+      continue;
+    }
+    const flag = flags.get(e.id);
+    if (!flag || !TRIAGE.has(e.event)) continue;
+    flag.history.push({ event: e.event, at: e.at, by: e.by, note: e.note ?? null });
+    if (e.event === 'accept') flag.triage = 'accepted';
+    if (e.event === 'reject') { flag.triage = 'rejected'; flag.state = 'closed'; }
+    if (e.event === 'resolve') flag.state = 'resolved';
+  }
+  return [...flags.values()];
+}
+
+function nextId(flags) {
+  let max = 0;
+  for (const f of flags) max = Math.max(max, Number(String(f.id).replace(/^F/, '')) || 0);
+  return `F${max + 1}`;
+}
+
+// `--by check:<name>`, `--by model:<name>`, `--by person:<name>`; otherwise the
+// session the environment names, or the person at the keyboard.
+export function resolveAuthor(byArg, env = process.env) {
+  if (byArg) {
+    const m = byArg.match(/^(session|person|check|model):(.+)$/);
+    if (!m) die('--by is <kind>:<name>, where kind is session, person, check or model.');
+    return { kind: m[1], name: m[2].trim() };
+  }
+  const source = hostSessionSource(env);
+  if (source?.scope === 'session') return { kind: 'session', name: source.host, session: source.id };
+  return { kind: 'person', name: os.userInfo().username };
+}
+
+export function normalizeText(text) {
+  return text.replace(/\s+/g, ' ').trim().toLowerCase();
+}
+
+// `docs/plans/x.md:12` → file and line; the file must exist in the repo and
+// the line must be inside it. The line's text is kept, so a later read can say
+// whether the place still says what was flagged.
+export function resolvePlace(place, config) {
+  const m = place.match(/^(.*?)(?::(\d+))?$/);
+  const rel = m[1];
+  const line = m[2] ? Number(m[2]) : null;
+  const abs = path.resolve(config.repoRoot, rel);
+  if (!existsSync(abs)) die(`No such file: ${rel}`);
+  const repoPath = toRepoPath(abs, config.repoRoot);
+  if (repoPath.startsWith('..')) die(`${rel} is outside the repository.`);
+  let quote = null;
+  if (line !== null) {
+    const lines = readFileSync(abs, 'utf8').split('\n');
+    if (line < 1 || line > lines.length) die(`${repoPath} has ${lines.length} lines; there is no line ${line}.`);
+    quote = lines[line - 1].trim().slice(0, QUOTE_MAX);
+  }
+  return { file: repoPath, line, quote };
+}
+
+// Where the flagged text is now: unchanged, moved to another line, or gone.
+export function locateFlag(flag, config) {
+  if (flag.line == null) return { status: existsSync(path.resolve(config.repoRoot, flag.file)) ? 'here' : 'gone' };
+  let lines;
+  try { lines = readFileSync(path.resolve(config.repoRoot, flag.file), 'utf8').split('\n'); }
+  catch { return { status: 'gone' }; }
+  if ((lines[flag.line - 1] ?? '').trim().slice(0, QUOTE_MAX) === flag.quote) return { status: 'here', line: flag.line };
+  if (flag.quote) {
+    const at = lines.findIndex(l => l.trim().slice(0, QUOTE_MAX) === flag.quote);
+    if (at !== -1) return { status: 'moved', line: at + 1 };
+  }
+  return { status: 'changed' };
+}
+
+function withFlagsLock(config, fn) {
+  const file = flagsFile(config);
+  const dir = path.dirname(file);
+  if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+  return withPathLocks([file], { repoRoot: config.repoRoot }, () => fn(file));
+}
+
+function append(file, event) {
+  appendFileSync(file, `${JSON.stringify(event)}\n`, { flag: 'a' });
+}
+
+export function addFlag(config, { place, text, severity = 'warn', by = null }) {
+  if (!text || !text.trim()) die('A flag says what is wrong: runlist flag add <file[:line]> "<what is wrong>"');
+  if (!SEVERITIES.includes(severity)) die(`--severity is one of ${SEVERITIES.join(', ')}.`);
+  const where = resolvePlace(place, config);
+  const author = typeof by === 'object' && by ? by : resolveAuthor(by);
+  return withFlagsLock(config, file => {
+    const flags = deriveFlags(readFlagEvents(file));
+    const key = normalizeText(text);
+    const same = flags.find(f => f.state === 'open' && f.file === where.file && f.line === where.line && normalizeText(f.text) === key);
+    if (same) return { flag: same, added: false };
+    const event = { event: 'add', id: nextId(flags), at: nowIso(), ...where, text: text.trim(), severity, by: author };
+    append(file, event);
+    return { flag: { ...event, state: 'open', triage: null, history: [] }, added: true };
+  });
+}
+
+export function triageFlag(config, { id, event, note = null, by = null }) {
+  const author = typeof by === 'object' && by ? by : resolveAuthor(by);
+  return withFlagsLock(config, file => {
+    const flag = deriveFlags(readFlagEvents(file)).find(f => f.id === id);
+    if (!flag) die(`No flag ${id}.`);
+    if (flag.state !== 'open') die(`${id} is already ${flag.state === 'closed' ? 'rejected' : flag.state}.`);
+    append(file, { event, id, at: nowIso(), by: author, ...(note ? { note } : {}) });
+    return flag;
+  });
+}
+
+export function openFlags(config) {
+  const rank = f => SEVERITIES.indexOf(f.severity);
+  return deriveFlags(readFlagEvents(flagsFile(config)))
+    .filter(f => f.state === 'open')
+    .sort((a, b) => rank(a) - rank(b) || String(b.at).localeCompare(String(a.at)));
+}
+
+// A check's flags follow what the check reports: each error it reports is
+// flagged once, and a flag it raised earlier that it no longer reports is
+// resolved, so the list never holds a problem the check has stopped seeing.
+// A finding is matched to its open flag on file and text, not line: a check
+// reports the same problem at a new line after an edit above it, and that is
+// still one flag.
+export function syncCheckFlags(config, checkName, findings) {
+  const by = { kind: 'check', name: checkName };
+  const keyOf = f => `${f.file}\0${normalizeText(f.text)}`;
+  const current = new Set(findings.map(keyOf));
+  const open = new Set(openFlags(config).filter(f => f.by?.kind === 'check' && f.by?.name === checkName).map(keyOf));
+  let added = 0;
+  let resolved = 0;
+  for (const finding of findings) {
+    if (open.has(keyOf(finding))) continue;
+    if (!existsSync(path.resolve(config.repoRoot, finding.file))) continue;
+    const place = finding.line ? `${finding.file}:${finding.line}` : finding.file;
+    const severity = SEVERITIES.includes(finding.severity) ? finding.severity : 'problem';
+    try {
+      if (addFlag(config, { place, text: finding.text, severity, by }).added) { added++; open.add(keyOf(finding)); }
+    } catch { /* a line the file no longer has: the next run reports it again */ }
+  }
+  for (const flag of openFlags(config)) {
+    if (flag.by?.kind !== 'check' || flag.by?.name !== checkName) continue;
+    if (current.has(`${flag.file}\0${normalizeText(flag.text)}`)) continue;
+    triageFlag(config, { id: flag.id, event: 'resolve', note: `no longer reported by ${checkName}`, by });
+    resolved++;
+  }
+  return { added, resolved };
+}
+
+function authorLabel(by) {
+  if (!by) return 'unknown';
+  return by.kind === 'session' ? `${by.name} session ${String(by.session ?? '').slice(0, 8)}` : `${by.kind} ${by.name}`;
+}
+
+function placeLabel(flag, config) {
+  const where = locateFlag(flag, config);
+  const base = flag.line != null ? `${flag.file}:${flag.line}` : flag.file;
+  if (where.status === 'moved') return `${base} ${dim(`(now line ${where.line})`)}`;
+  if (where.status === 'changed') return `${base} ${yellow('(text there has changed)')}`;
+  if (where.status === 'gone') return `${base} ${yellow('(file gone)')}`;
+  return base;
+}
+
+const severityLabel = s => (s === 'problem' ? red(s) : s === 'warn' ? yellow(s) : dim(s));
+
+// One line for the session-start banner, or null when nothing is open.
+export function flagsHudLine(config, { top = 3 } = {}) {
+  let open;
+  try { open = openFlags(config); } catch { return null; }
+  if (open.length === 0) return null;
+  const problems = open.filter(f => f.severity === 'problem').length;
+  const items = open.slice(0, top).map(f => `${f.id} ${f.line != null ? `${f.file}:${f.line}` : f.file} ${f.text.slice(0, 80)}`).join('; ');
+  return `[runlist] ${open.length} open flag${open.length === 1 ? '' : 's'}${problems ? `, ${problems} problem${problems === 1 ? '' : 's'}` : ''}, for awareness: ${items}. List: \`runlist flags\`.`;
+}
+
+export function runFlags(argv, config) {
+  const json = argv.includes('--json');
+  const all = argv.includes('--all');
+  const events = readFlagEvents(flagsFile(config));
+  const flags = deriveFlags(events)
+    .filter(f => all || f.state === 'open')
+    .sort((a, b) => SEVERITIES.indexOf(a.severity) - SEVERITIES.indexOf(b.severity) || String(b.at).localeCompare(String(a.at)));
+  if (json) {
+    process.stdout.write(`${JSON.stringify(flags.map(f => ({ ...f, location: locateFlag(f, config) })), null, 2)}\n`);
+    return;
+  }
+  if (flags.length === 0) {
+    process.stdout.write(dim(all ? 'No flags.\n' : 'No open flags.\n'));
+    return;
+  }
+  for (const f of flags) {
+    const state = f.state === 'open' ? (f.triage === 'accepted' ? green('accepted') : '') : dim(f.state === 'closed' ? 'rejected' : f.state);
+    process.stdout.write(`${bold(f.id)} ${severityLabel(f.severity)} ${placeLabel(f, config)} ${state}\n`);
+    process.stdout.write(`  ${f.text}\n`);
+    process.stdout.write(dim(`  ${authorLabel(f.by)}, ${f.at}`) + '\n');
+  }
+}
+
+export function runFlag(argv, config) {
+  const [sub, ...rest] = argv;
+  const positional = [];
+  let severity;
+  let by = null;
+  let note = null;
+  for (let i = 0; i < rest.length; i++) {
+    const a = rest[i];
+    if (a === '--severity' && rest[i + 1]) { severity = rest[++i]; continue; }
+    if (a === '--by' && rest[i + 1]) { by = rest[++i]; continue; }
+    if (a === '--note' && rest[i + 1]) { note = rest[++i]; continue; }
+    if (a === '--config') { i++; continue; }
+    if (a.startsWith('-')) continue;
+    positional.push(a);
+  }
+  const usage = 'Usage: runlist flag add <file[:line]> "<what is wrong>" [--severity problem|warn|info]\n'
+    + '       runlist flag accept|reject|resolve <id> [--note "..."]\n'
+    + '       runlist flag show <id>\n'
+    + '       runlist flag sync <check-name> [@findings.json | -]';
+
+  if (sub === 'add') {
+    const [place, ...words] = positional;
+    if (!place) die(usage);
+    const { flag, added } = addFlag(config, { place, text: words.join(' '), severity, by });
+    process.stdout.write(added ? `${green('Flagged')} ${flag.id} ${placeLabel(flag, config)}\n` : `${dim('Already open as')} ${flag.id}\n`);
+    return;
+  }
+  if (TRIAGE.has(sub)) {
+    const [id] = positional;
+    if (!id) die(usage);
+    triageFlag(config, { id, event: sub, note, by });
+    process.stdout.write(`${green({ accept: 'Accepted', reject: 'Rejected', resolve: 'Resolved' }[sub])} ${id}\n`);
+    return;
+  }
+  if (sub === 'sync') {
+    // A check outside runlist hands over everything it reports now, as a JSON
+    // array of { file, line?, text, severity? }; the list follows it.
+    const [name, source] = positional;
+    if (!name) die('Usage: runlist flag sync <check-name> [@findings.json | -]   (JSON array of { file, line?, text, severity? })');
+    let raw;
+    try { raw = source && source !== '-' ? readFileSync(source.replace(/^@/, ''), 'utf8') : readFileSync(0, 'utf8'); }
+    catch (err) { die(`Could not read the findings: ${err.message}`); }
+    let findings;
+    try { findings = JSON.parse(raw); } catch { die('The findings are not valid JSON.'); }
+    if (!Array.isArray(findings) || findings.some(f => typeof f?.file !== 'string' || typeof f?.text !== 'string')) {
+      die('The findings are a JSON array of { file, line?, text, severity? }.');
+    }
+    const { added, resolved } = syncCheckFlags(config, name, findings);
+    process.stdout.write(`flags from ${name}: ${added} added, ${resolved} resolved\n`);
+    return;
+  }
+  if (sub === 'show') {
+    const flag = deriveFlags(readFlagEvents(flagsFile(config))).find(f => f.id === positional[0]);
+    if (!flag) die(`No flag ${positional[0] ?? ''}.`);
+    process.stdout.write(`${bold(flag.id)} ${severityLabel(flag.severity)} ${placeLabel(flag, config)}\n  ${flag.text}\n`);
+    if (flag.quote) process.stdout.write(dim(`  flagged line: ${flag.quote}`) + '\n');
+    process.stdout.write(dim(`  raised by ${authorLabel(flag.by)}, ${flag.at}`) + '\n');
+    for (const h of flag.history) process.stdout.write(dim(`  ${h.event} by ${authorLabel(h.by)}, ${h.at}${h.note ? `: ${h.note}` : ''}`) + '\n');
+    return;
+  }
+  die(usage);
+}

package/src/hud.mjs

@@ -1,3 +1,4 @@
+import { flagsHudLine, openFlags } from './flags.mjs';
 import { existsSync, readFileSync, readdirSync } from 'node:fs';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
@@ -263,6 +264,7 @@ export function buildHud(config) {
     fleet,
     recentRejections,
     misuseRecap,
+    flags: (() => { try { return openFlags(config).map(f => ({ id: f.id, severity: f.severity, file: f.file, line: f.line, text: f.text })); } catch { return []; } })(),
   };
 }
 
@@ -403,5 +405,10 @@ export function runHud(argv, config) {
     process.stdout.write(yellow(`[runlist] ${n} pending prompt${n === 1 ? '' : 's'} queued for this session — unless the user asks for something else, start by running \`runlist use\` to consume the oldest (${hud.prompts[0]}) and act on it. Peek first: \`runlist prompts show <file>\`; list: \`runlist prompts\`.`) + '\n');
   }
   if (hud.misuseRecap) process.stdout.write(yellow(`[runlist] ${hud.misuseRecap}`) + '\n');
+  // Open flags are the one piece of passive state printed here: the person
+  // asked that every session start knowing where things stand. It is worded
+  // as awareness, not an instruction, so no session treats it as its task.
+  const flagsLine = flagsHudLine(config);
+  if (flagsLine) process.stdout.write(yellow(flagsLine) + '\n');
   if (drift) process.stdout.write(yellow(drift) + '\n');
 }

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 });
 }