dotmd-cli 0.10.2 → 0.10.4

package/README.md

@@ -57,6 +57,7 @@ Any `.md` file with YAML frontmatter:
 
 ```markdown
 ---
+type: doc
 status: active
 updated: 2026-03-14
 module: auth
@@ -76,7 +77,31 @@ Design doc content here...
 - [ ] Add tests
 ```
 
-The only required field is `status`. Everything else is optional but unlocks more features.
+The only required field is `status`. Everything else is optional but unlocks more features. The `type` field (`plan`, `doc`, or `research`) enables type-specific statuses and smarter context briefings.
+
+## Document Types
+
+Every document can have a `type` field in its frontmatter. Types determine which statuses are valid and how the document appears in context briefings.
+
+| Type | Purpose | Valid Statuses |
+|------|---------|----------------|
+| `plan` | Execution plans | `in-session`, `active`, `planned`, `blocked`, `done`, `archived` |
+| `doc` | Design docs, specs, ADRs, RFCs | `draft`, `active`, `review`, `reference`, `deprecated`, `archived` |
+| `research` | Investigations, audits, analysis | `active`, `reference`, `archived` |
+
+Documents without a `type` field use the global `statuses.order` from config.
+
+Templates auto-set the type: `--template plan` sets `type: plan`, `--template adr` sets `type: doc`, `--template audit` sets `type: research`.
+
+Filter by type with `--type`:
+
+```bash
+dotmd query --type plan --status active   # active plans
+dotmd list --type doc                     # all docs
+dotmd export --type research              # export research only
+```
+
+Customize types and their statuses in config with the `types` key. See [`dotmd.config.example.mjs`](dotmd.config.example.mjs).
 
 ## Commands
 
@@ -117,6 +142,7 @@ dotmd completions <shell>    Output shell completion script (bash, zsh)
 --config <path>        Explicit config file path
 --dry-run, -n          Preview changes without writing anything
 --root <name>          Filter to a specific docs root
+--type <t1,t2>         Filter by document type (plan, doc, research)
 --verbose              Show resolved config details
 --help, -h             Show help (per-command with: dotmd <cmd> --help)
 --version, -v          Show version
@@ -133,7 +159,7 @@ dotmd query --status active --summarize             # AI summaries
 dotmd query --status active --summarize --summarize-limit 3
 ```
 
-Flags: `--status`, `--keyword`, `--module`, `--surface`, `--domain`, `--owner`, `--updated-since`, `--stale`, `--has-next-step`, `--has-blockers`, `--checklist-open`, `--sort`, `--limit`, `--all`, `--git`, `--json`, `--summarize`, `--summarize-limit`, `--model`.
+Flags: `--type`, `--status`, `--keyword`, `--module`, `--surface`, `--domain`, `--owner`, `--updated-since`, `--stale`, `--has-next-step`, `--has-blockers`, `--checklist-open`, `--sort`, `--limit`, `--all`, `--git`, `--json`, `--summarize`, `--summarize-limit`, `--model`.
 
 ### Scaffold with Templates
 
@@ -225,6 +251,7 @@ dotmd export --format html --output site # static HTML site
 dotmd export --format json > bundle.json # JSON bundle with bodies
 dotmd export docs/plan-a.md              # single doc + dependencies
 dotmd export --status active             # filtered export
+dotmd export --type plan                 # export only plans
 ```
 
 ### Notion Integration
@@ -359,6 +386,7 @@ export const lifecycle = {
   archiveStatuses: ['archived'],          // auto-move to archiveDir
   skipStaleFor: ['archived'],
   skipWarningsFor: ['archived'],
+  terminalStatuses: ['archived', 'deprecated', 'reference', 'done'],
 };
 
 export const taxonomy = {
@@ -378,7 +406,7 @@ export const index = {
 };
 ```
 
-All exports are optional. See [`dotmd.config.example.mjs`](dotmd.config.example.mjs) for the full reference.
+All exports are optional. Additional options: `types`, `context`, `display`, `presets`, `templates`, `excludeDirs`, `notion`. See [`dotmd.config.example.mjs`](dotmd.config.example.mjs) for the full reference.
 
 Config discovery walks up from cwd looking for `dotmd.config.mjs` or `.dotmd.config.mjs`.
 
@@ -424,6 +452,16 @@ export function onArchive(doc, { oldPath, newPath }) {
 
 Available: `onArchive`, `onStatusChange`, `onTouch`, `onNew`, `onRename`, `onLint`.
 
+### Transform Hooks
+
+```js
+// Add computed fields to every doc after parsing
+export function transformDoc(doc) {
+  doc.priority = doc.blockers?.length ? 'high' : 'normal';
+  return doc;
+}
+```
+
 ### AI Hooks
 
 ```js

package/bin/dotmd.mjs

@@ -238,6 +238,7 @@ Options:
   --template <name>    Use a template (default, plan, adr, rfc, audit, design)
   --status <s>         Set initial status (default: active)
   --title <t>          Override the document title
+  --root <name>        Create in a specific docs root
   --list-templates     Show available templates
 
 The filename is derived from <name> by slugifying it.
@@ -275,6 +276,7 @@ Options:
   --format <md|html|json>  Output format (default: md)
   --output <path>          Write to file/directory (default: stdout for md/json)
   --status <s1,s2>         Filter by status
+  --type <t1,t2>           Filter by type (plan, doc, research)
   --module <name>          Filter by module
   --root <name>            Filter by root
   --dry-run, -n            Preview without writing`,
@@ -335,7 +337,10 @@ Use --dry-run (-n) to preview changes without writing anything.`,
   init: `dotmd init — create starter config and docs directory
 
 Creates dotmd.config.mjs, docs/, and docs/docs.md in the current
-directory. Skips any files that already exist.`,
+directory. Skips any files that already exist.
+
+If docs/ already contains .md files, auto-detects statuses, surfaces,
+modules, and reference fields to pre-populate the config.`,
 };
 
 async function main() {
@@ -384,10 +389,17 @@ async function main() {
 
   const config = await resolveConfig(process.cwd(), explicitConfig);
 
+  // Watch is a pure proxy — pass raw args so the child process gets all flags
+  if (command === 'watch') { runWatch(args.slice(1), config); return; }
+
   // Strip global flags from restArgs so commands don't have to filter them
   const restArgs = [];
+  let rootArg = null;
+  let typeArg = null;
   for (let i = 1; i < args.length; i++) {
     if (args[i] === '--config') { i++; continue; }
+    if (args[i] === '--type' && args[i + 1]) { typeArg = args[++i]; continue; }
+    if (args[i] === '--root' && args[i + 1]) { rootArg = args[++i]; continue; }
     if (args[i] === '--dry-run' || args[i] === '-n' || args[i] === '--verbose') continue;
     restArgs.push(args[i]);
   }
@@ -416,19 +428,18 @@ async function main() {
     return;
   }
 
-  // Watch and diff (handle their own index building)
-  if (command === 'watch') { runWatch(restArgs, config); return; }
+  // Commands that handle their own index building
   if (command === 'diff') { runDiff(restArgs, config); return; }
   if (command === 'summary') { runSummary(restArgs, config); return; }
   if (command === 'deps') { runDeps(restArgs, config); return; }
-  if (command === 'export') { runExport(restArgs, config, { dryRun }); return; }
+  if (command === 'export') { runExport(restArgs, config, { dryRun, root: rootArg, type: typeArg }); return; }
   if (command === 'notion') { await runNotion(restArgs, config, { dryRun }); return; }
 
   // Lifecycle commands
   if (command === 'status') { await runStatus(restArgs, config, { dryRun }); return; }
   if (command === 'archive') { runArchive(restArgs, config, { dryRun }); return; }
   if (command === 'touch') { runTouch(restArgs, config, { dryRun }); return; }
-  if (command === 'new') { await runNew(restArgs, config, { dryRun }); return; }
+  if (command === 'new') { await runNew(restArgs, config, { dryRun, root: rootArg }); return; }
   if (command === 'lint') { runLint(restArgs, config, { dryRun }); return; }
   if (command === 'rename') { await runRename(restArgs, config, { dryRun }); return; }
   if (command === 'migrate') { runMigrate(restArgs, config, { dryRun }); return; }
@@ -437,27 +448,32 @@ async function main() {
 
   const index = buildIndex(config);
 
-  // Apply --root filter
-  const rootFilter = (() => { const i = args.indexOf('--root'); return i !== -1 && args[i + 1] ? args[i + 1] : null; })();
-  if (rootFilter) {
-    index.docs = index.docs.filter(d => d.root === rootFilter || d.root.endsWith('/' + rootFilter) || d.root.split('/').pop() === rootFilter);
-  }
+  // Apply --root and --type filters
+  const rootFilter = rootArg;
+  const typeFilter = typeArg;
 
-  // Apply --type filter
-  const typeFilter = (() => { const i = args.indexOf('--type'); return i !== -1 && args[i + 1] ? args[i + 1] : null; })();
-  if (typeFilter) {
-    const types = typeFilter.split(',').map(t => t.trim()).filter(Boolean);
-    index.docs = index.docs.filter(d => types.includes(d.type));
+  function applyIndexFilters(idx) {
+    if (rootFilter) {
+      idx.docs = idx.docs.filter(d => d.root === rootFilter || d.root.endsWith('/' + rootFilter) || d.root.split('/').pop() === rootFilter);
+    }
+    if (typeFilter) {
+      const types = typeFilter.split(',').map(t => t.trim()).filter(Boolean);
+      idx.docs = idx.docs.filter(d => types.includes(d.type));
+    }
+    if (rootFilter || typeFilter) {
+      idx.errors = idx.errors.filter(e => idx.docs.some(d => d.path === e.path));
+      idx.warnings = idx.warnings.filter(w => idx.docs.some(d => d.path === w.path));
+      idx.countsByStatus = {};
+      for (const doc of idx.docs) {
+        const s = doc.status ?? 'unknown';
+        idx.countsByStatus[s] = (idx.countsByStatus[s] ?? 0) + 1;
+      }
+    }
   }
 
+  applyIndexFilters(index);
+
   if (rootFilter || typeFilter) {
-    index.errors = index.errors.filter(e => index.docs.some(d => d.path === e.path));
-    index.warnings = index.warnings.filter(w => index.docs.some(d => d.path === w.path));
-    index.countsByStatus = {};
-    for (const doc of index.docs) {
-      const s = doc.status ?? 'unknown';
-      index.countsByStatus[s] = (index.countsByStatus[s] ?? 0) + 1;
-    }
   }
 
   if (verbose) {
@@ -500,6 +516,7 @@ async function main() {
       }
       // Show remaining issues
       const freshIndex = buildIndex(config);
+      applyIndexFilters(freshIndex);
       if (args.includes('--json')) {
         process.stdout.write(JSON.stringify({
           docsScanned: freshIndex.docs.length,
@@ -573,6 +590,10 @@ async function main() {
   if (command === 'focus') { runFocus(index, restArgs, config); return; }
   if (command === 'query') { runQuery(index, restArgs, config); return; }
   if (command === 'context') {
+    const summarize = args.includes('--summarize');
+    const modelIdx = args.indexOf('--model');
+    const model = modelIdx !== -1 && args[modelIdx + 1] ? args[modelIdx + 1] : undefined;
+
     if (args.includes('--json')) {
       const byStatus = {};
       for (const doc of index.docs) {
@@ -580,9 +601,36 @@ async function main() {
         if (!byStatus[s]) byStatus[s] = [];
         byStatus[s].push(doc);
       }
+      const byType = {};
+      for (const doc of index.docs) {
+        if (doc.type) {
+          if (!byType[doc.type]) byType[doc.type] = [];
+          byType[doc.type].push(doc);
+        }
+      }
+      if (summarize) {
+        const { summarizeDocBody } = await import('../src/ai.mjs');
+        const { extractFrontmatter } = await import('../src/frontmatter.mjs');
+        const { readFileSync } = await import('node:fs');
+        const limit = 5;
+        for (let i = 0; i < index.docs.length && i < limit; i++) {
+          try {
+            const absPath = path.resolve(config.repoRoot, index.docs[i].path);
+            const raw = readFileSync(absPath, 'utf8');
+            const { body } = extractFrontmatter(raw);
+            if (body?.trim()) {
+              const meta = { title: index.docs[i].title, status: index.docs[i].status, path: index.docs[i].path };
+              index.docs[i].aiSummary = config.hooks.summarizeDoc
+                ? config.hooks.summarizeDoc(body, meta)
+                : summarizeDocBody(body, meta, { model });
+            }
+          } catch { /* skip */ }
+        }
+      }
       const stale = index.docs.filter(d => d.isStale && !config.lifecycle.skipStaleFor.has(d.status));
       process.stdout.write(JSON.stringify({
         generatedAt: new Date().toISOString(),
+        docsByType: Object.keys(byType).length > 0 ? byType : undefined,
         docsByStatus: byStatus,
         countsByStatus: index.countsByStatus,
         stale: stale.map(d => ({ path: d.path, title: d.title, daysSinceUpdate: d.daysSinceUpdate })),
@@ -591,9 +639,6 @@ async function main() {
       }, null, 2) + '\n');
       return;
     }
-    const summarize = args.includes('--summarize');
-    const modelIdx = args.indexOf('--model');
-    const model = modelIdx !== -1 && args[modelIdx + 1] ? args[modelIdx + 1] : undefined;
     process.stdout.write(renderContext(index, config, { summarize, model }));
     return;
   }

package/dotmd.config.example.mjs

@@ -57,6 +57,7 @@ export const lifecycle = {
   archiveStatuses: ['archived'],      // auto-move to archiveDir on transition
   skipStaleFor: ['archived'],         // skip staleness checks
   skipWarningsFor: ['archived'],      // skip validation warnings (summary, etc.)
+  terminalStatuses: ['archived', 'deprecated', 'reference', 'done'],  // skip current_state/next_step warnings, exclude from stats scope
 };
 
 // Taxonomy validation — set fields to null to skip validation
@@ -107,7 +108,7 @@ export const presets = {
 // IMPORTANT: Use environment variables for tokens — never hardcode secrets in config files.
 // export const notion = {
 //   token: process.env.NOTION_TOKEN,
-//   databaseId: process.env.NOTION_DATABASE_ID,
+//   database: process.env.NOTION_DATABASE_ID,
 // };
 
 // ─── Function Hooks ──────────────────────────────────────────────────────────
@@ -123,20 +124,13 @@ export const presets = {
 //   return { errors: [], warnings };
 // }
 
-// Override the context briefing output.
-// export function renderContext(index, defaultRenderer) {
-//   return defaultRenderer(index);
-// }
-
-// Override the index file rendering.
-// export function renderIndex(index, defaultRenderer) {
-//   return defaultRenderer(index);
-// }
-
-// Override the status snapshot display format.
-// export function formatSnapshot(doc, defaultFormatter) {
-//   return defaultFormatter(doc);
-// }
+// Render hooks — override any renderer by wrapping the default.
+// export function renderContext(index, defaultRenderer) { return defaultRenderer(index); }
+// export function renderCompactList(index, defaultRenderer) { return defaultRenderer(index); }
+// export function renderCheck(index, defaultRenderer) { return defaultRenderer(index); }
+// export function renderStats(stats, defaultRenderer) { return defaultRenderer(stats); }
+// export function renderGraph(graph, defaultRenderer) { return defaultRenderer(graph); }
+// export function formatSnapshot(doc, defaultFormatter) { return defaultFormatter(doc); }
 
 // Post-parse doc transformation — add computed fields.
 // export function transformDoc(doc) {
@@ -147,3 +141,10 @@ export const presets = {
 // export function onArchive(doc, { oldPath, newPath }) {}
 // export function onStatusChange(doc, { oldStatus, newStatus, path }) {}
 // export function onTouch(doc, { path, date }) {}
+// export function onNew({ path, status, title, template }) {}
+// export function onRename({ oldPath, newPath, referencesUpdated }) {}
+// export function onLint({ path, fixes }) {}
+
+// AI hooks — override summarization (replaces local MLX model).
+// export function summarizeDoc(body, meta) { return 'Custom summary'; }
+// export function summarizeDiff(diffOutput, filePath) { return 'Custom diff summary'; }

package/package.json

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

package/src/completions.mjs

@@ -6,10 +6,10 @@ const COMMANDS = [
   'fix-refs', 'notion', 'export', 'summary', 'watch', 'diff', 'init', 'new', 'completions',
 ];
 
-const GLOBAL_FLAGS = ['--config', '--dry-run', '--verbose', '--root', '--help', '--version'];
+const GLOBAL_FLAGS = ['--config', '--dry-run', '--verbose', '--root', '--type', '--help', '--version'];
 
 const COMMAND_FLAGS = {
-  query: ['--status', '--keyword', '--module', '--surface', '--domain', '--owner',
+  query: ['--type', '--status', '--keyword', '--module', '--surface', '--domain', '--owner',
           '--updated-since', '--stale', '--has-next-step', '--has-blockers',
           '--checklist-open', '--sort', '--limit', '--all', '--git', '--json',
           '--summarize', '--summarize-limit', '--model'],
@@ -17,13 +17,13 @@ const COMMAND_FLAGS = {
   list: ['--verbose', '--json'],
   coverage: ['--json'],
   new: ['--status', '--title', '--template', '--list-templates', '--root'],
-  diff: ['--stat', '--since', '--summarize', '--model', '--max-tokens'],
+  diff: ['--stat', '--since', '--summarize', '--model'],
   check: ['--errors-only', '--fix', '--json'],
   stats: ['--json'],
   graph: ['--dot', '--json', '--status', '--module', '--surface'],
   deps: ['--json', '--depth'],
   notion: ['import', 'export', 'sync', '--force', '--dry-run'],
-  export: ['--format', '--output', '--status', '--module', '--root'],
+  export: ['--format', '--output', '--status', '--module', '--root', '--type'],
   focus: ['--json'],
   status: [],
   archive: [],

package/src/config.mjs

@@ -43,6 +43,7 @@ const DEFAULTS = {
     archiveStatuses: ['archived'],
     skipStaleFor: ['archived', 'reference'],
     skipWarningsFor: ['archived'],
+    terminalStatuses: ['archived', 'deprecated', 'reference', 'done'],
   },
 
   taxonomy: {
@@ -284,6 +285,7 @@ export async function resolveConfig(cwd, explicitConfigPath) {
   const archiveStatuses = new Set(lifecycle.archiveStatuses);
   const skipStaleFor = new Set(lifecycle.skipStaleFor);
   const skipWarningsFor = new Set(lifecycle.skipWarningsFor);
+  const terminalStatuses = new Set(lifecycle.terminalStatuses);
 
   // Warn if rootStatuses keys don't match any configured root
   for (const rootKey of Object.keys(rootStatusesRaw)) {
@@ -315,7 +317,7 @@ export async function resolveConfig(cwd, explicitConfigPath) {
     rootValidStatuses,
     staleDaysByStatus,
 
-    lifecycle: { archiveStatuses, skipStaleFor, skipWarningsFor },
+    lifecycle: { archiveStatuses, skipStaleFor, skipWarningsFor, terminalStatuses },
 
     validSurfaces,
     moduleRequiredStatuses,

package/src/export.mjs

@@ -11,7 +11,8 @@ export function runExport(argv, config, opts = {}) {
   let output = null;
   let statusFilter = null;
   let moduleFilter = null;
-  let rootFilter = null;
+  let rootFilter = opts.root ?? null;
+  let typeFilter = opts.type ?? null;
   const dryRun = opts.dryRun;
 
   for (let i = 0; i < argv.length; i++) {
@@ -20,6 +21,7 @@ export function runExport(argv, config, opts = {}) {
     if (argv[i] === '--status' && argv[i + 1]) { statusFilter = argv[++i]; continue; }
     if (argv[i] === '--module' && argv[i + 1]) { moduleFilter = argv[++i]; continue; }
     if (argv[i] === '--root' && argv[i + 1]) { rootFilter = argv[++i]; continue; }
+    if (argv[i] === '--type' && argv[i + 1]) { typeFilter = argv[++i]; continue; }
     if (argv[i] === '--config') { i++; continue; }
     if (argv[i].startsWith('-')) continue;
     positional.push(argv[i]);
@@ -54,6 +56,10 @@ export function runExport(argv, config, opts = {}) {
     if (rootFilter) {
       docs = docs.filter(d => d.root === rootFilter || d.root?.endsWith('/' + rootFilter) || d.root?.split('/').pop() === rootFilter);
     }
+    if (typeFilter) {
+      const types = typeFilter.split(',').map(t => t.trim()).filter(Boolean);
+      docs = docs.filter(d => types.includes(d.type));
+    }
   }
 
   if (docs.length === 0) {

package/src/index.mjs

@@ -131,6 +131,7 @@ export function parseDocFile(filePath, config) {
   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
   const refFields = {};
@@ -172,6 +173,7 @@ export function parseDocFile(filePath, config) {
     bodyLinks,
     refFields,
     checklistCompletionRate: computeChecklistCompletionRate(checklist),
+    hasCloseout,
     hasNextStep: Boolean(nextStep),
     hasBlockers: blockers.length > 0,
     daysSinceUpdate: computeDaysSinceUpdate(asString(parsedFrontmatter.updated) ?? null),

package/src/init.mjs

@@ -137,8 +137,7 @@ export function runInit(cwd) {
     process.stdout.write(`  ${green('create')}  docs/docs.md\n`);
   }
 
-  const today = new Date().toISOString().slice(0, 10);
   process.stdout.write(`\nReady. Create your first doc:\n`);
-  process.stdout.write(`  printf '---\\nstatus: active\\nupdated: ${today}\\n---\\n\\n# My Doc\\n' > docs/my-doc.md\n`);
+  process.stdout.write(`  dotmd new my-doc\n`);
   process.stdout.write(`  dotmd list\n\n`);
 }

package/src/new.mjs

@@ -27,7 +27,7 @@ const BUILTIN_TEMPLATES = {
   },
   audit: {
     description: 'Codebase audit or research investigation',
-    frontmatter: (s, d) => `type: research\nstatus: active\nupdated: ${d}\naudited: ${d}\naudit_level: pass1\nmodule:\nsource_of_truth: code\nsupports_plans:`,
+    frontmatter: (s, d) => `type: research\nstatus: ${s}\nupdated: ${d}\naudited: ${d}\naudit_level: pass1\nmodule:\nsource_of_truth: code\nsupports_plans:`,
     body: (t) => `\n# ${t}\n\n## Scope\n\n\n\n## Findings\n\n\n\n## Recommendations\n\n\n`,
   },
   design: {
@@ -45,7 +45,7 @@ export async function runNew(argv, config, opts = {}) {
   let status = 'active';
   let title = null;
   let templateName = null;
-  let rootName = null;
+  let rootName = opts.root ?? null;
   for (let i = 0; i < argv.length; i++) {
     if (argv[i] === '--status' && argv[i + 1]) { status = argv[++i]; continue; }
     if (argv[i] === '--title' && argv[i + 1]) { title = argv[++i]; continue; }

package/src/query.mjs

@@ -9,7 +9,16 @@ import { summarizeDocBody } from './ai.mjs';
 import { dim } from './color.mjs';
 
 export function runFocus(index, argv, config) {
-  const statusFilter = argv.find(a => !a.startsWith('-')) ?? 'active';
+  // Find first positional arg, skipping flag-value pairs like --root <name>
+  const FLAGS_WITH_VALUES = new Set(['--root']);
+  let statusFilter = 'active';
+  for (let i = 0; i < argv.length; i++) {
+    if (FLAGS_WITH_VALUES.has(argv[i])) { i++; continue; }
+    if (argv[i].startsWith('-')) continue;
+    statusFilter = argv[i];
+    break;
+  }
+
   const docs = index.docs.filter(doc => doc.status === statusFilter);
 
   if (argv.includes('--json')) {

package/src/render.mjs

@@ -324,9 +324,8 @@ export function renderCoverage(index, config) {
 }
 
 export function buildCoverage(index, config) {
-  const terminalStatuses = new Set(['archived', 'deprecated', 'reference', 'done']);
-  const scope = [...new Set(index.docs.map(d => d.status).filter(s => s && !terminalStatuses.has(s) && !config.lifecycle.skipWarningsFor.has(s)))];
-  const scoped = index.docs.filter(doc => doc.status && !terminalStatuses.has(doc.status) && !config.lifecycle.skipWarningsFor.has(doc.status));
+  const scope = [...new Set(index.docs.map(d => d.status).filter(s => s && !config.lifecycle.terminalStatuses.has(s) && !config.lifecycle.skipWarningsFor.has(s)))];
+  const scoped = index.docs.filter(doc => doc.status && !config.lifecycle.terminalStatuses.has(doc.status) && !config.lifecycle.skipWarningsFor.has(doc.status));
   const missingSurface = scoped.filter(doc => !doc.surface);
   const missingModule = scoped.filter(doc => !doc.module);
   const modulePlatform = scoped.filter(doc => doc.module === 'platform');

package/src/stats.mjs

@@ -8,7 +8,12 @@ function pct(n, total) {
 
 export function buildStats(index, config) {
   const docs = index.docs;
-  const scope = ['active', 'ready', 'planned', 'blocked'];
+  const scope = config.statusOrder.filter(s => !config.lifecycle.terminalStatuses.has(s) && !config.lifecycle.skipWarningsFor.has(s));
+  for (const typeSet of (config.typeStatuses?.values() ?? [])) {
+    for (const s of typeSet) {
+      if (!config.lifecycle.terminalStatuses.has(s) && !config.lifecycle.skipWarningsFor.has(s) && !scope.includes(s)) scope.push(s);
+    }
+  }
   const scoped = docs.filter(d => scope.includes(d.status));
   const nonArchived = docs.filter(d => !config.lifecycle.skipWarningsFor.has(d.status));
 

package/src/validate.mjs

@@ -80,8 +80,7 @@ export function validateDoc(doc, frontmatter, headingTitle, config) {
   }
 
   // Determine which statuses should have current_state and next_step
-  const terminalStatuses = new Set(['archived', 'deprecated', 'reference', 'done']);
-  const isWorkStatus = knownStatus && doc.status && !terminalStatuses.has(doc.status) && !config.lifecycle.skipWarningsFor.has(doc.status);
+  const isWorkStatus = knownStatus && doc.status && !config.lifecycle.terminalStatuses.has(doc.status) && !config.lifecycle.skipWarningsFor.has(doc.status);
 
   if (isWorkStatus && !asString(frontmatter.current_state)) {
     doc.warnings.push({ path: doc.path, level: 'warning', message: 'Missing `current_state`; index output is using a fallback or placeholder.' });
@@ -91,6 +90,11 @@ export function validateDoc(doc, frontmatter, headingTitle, config) {
     doc.warnings.push({ path: doc.path, level: 'warning', message: 'Missing `next_step`; command output will omit a clear immediate action.' });
   }
 
+  // Archived plans must have a ## Closeout section
+  if (config.lifecycle.archiveStatuses.has(doc.status) && doc.type === 'plan' && !doc.hasCloseout) {
+    doc.warnings.push({ path: doc.path, level: 'warning', message: 'Archived plan missing `## Closeout` section.' });
+  }
+
   // Validate reference fields resolve to existing files
   const docDir = path.dirname(path.join(config.repoRoot, doc.path));
   const allRefFields = [...(config.referenceFields.bidirectional || []), ...(config.referenceFields.unidirectional || [])];