dotmd-cli 0.9.6 → 0.10.2

package/bin/dotmd.mjs

@@ -75,6 +75,7 @@ Setup:
 Global Options:
   --config <path>        Explicit config file path
   --root <name>          Filter to a specific docs root
+  --type <t1,t2>         Filter by document type (plan, doc, research)
   --dry-run, -n          Preview changes without writing anything
   --verbose              Show config details and doc count
   --help, -h             Show help (per-command: dotmd <cmd> --help)
@@ -99,6 +100,7 @@ Add to your shell config:
   query: `dotmd query — filtered document search
 
 Filters:
+  --type <t1,t2>         Filter by type (plan, doc, research)
   --status <s1,s2>       Filter by status (comma-separated)
   --keyword <term>       Search title, summary, state, path
   --module <name>        Filter by module
@@ -439,6 +441,16 @@ async function main() {
   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 --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));
+  }
+
+  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 = {};

package/dotmd.config.example.mjs

@@ -13,7 +13,27 @@ export const archiveDir = 'archived';
 // Directories to skip when scanning
 export const excludeDirs = ['evidence'];
 
-// Status workflow — order determines display grouping
+// Document types — each type has its own status vocabulary and context layout
+// Defaults: plan, doc, research. Override to customize statuses per type.
+// export const types = {
+//   plan: {
+//     statuses: ['in-session', 'active', 'planned', 'blocked', 'done', 'archived'],
+//     context: { expanded: ['in-session', 'active'], listed: ['planned', 'blocked'], counted: ['done', 'archived'] },
+//     staleDays: { 'in-session': 1, active: 14, planned: 30, blocked: 30 },
+//   },
+//   doc: {
+//     statuses: ['draft', 'active', 'review', 'reference', 'deprecated', 'archived'],
+//     context: { expanded: ['active'], listed: ['draft', 'review'], counted: ['reference', 'deprecated', 'archived'] },
+//     staleDays: { draft: 30, active: 14, review: 14 },
+//   },
+//   research: {
+//     statuses: ['active', 'reference', 'archived'],
+//     context: { expanded: ['active'], listed: [], counted: ['reference', 'archived'] },
+//     staleDays: { active: 30 },
+//   },
+// };
+
+// Status workflow — fallback for docs without a type field. Order determines display grouping.
 export const statuses = {
   order: ['active', 'ready', 'planned', 'research', 'blocked', 'reference', 'archived'],
   // Additional statuses valid only in specific roots (merged with order)

package/package.json

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

package/src/config.mjs

@@ -10,6 +10,24 @@ const DEFAULTS = {
   archiveDir: 'archived',
   excludeDirs: [],
 
+  types: {
+    plan: {
+      statuses: ['in-session', 'active', 'planned', 'blocked', 'done', 'archived'],
+      context: { expanded: ['in-session', 'active'], listed: ['planned', 'blocked'], counted: ['done', 'archived'] },
+      staleDays: { 'in-session': 1, active: 14, planned: 30, blocked: 30 },
+    },
+    doc: {
+      statuses: ['draft', 'active', 'review', 'reference', 'deprecated', 'archived'],
+      context: { expanded: ['active'], listed: ['draft', 'review'], counted: ['reference', 'deprecated', 'archived'] },
+      staleDays: { draft: 30, active: 14, review: 14 },
+    },
+    research: {
+      statuses: ['active', 'reference', 'archived'],
+      context: { expanded: ['active'], listed: [], counted: ['reference', 'archived'] },
+      staleDays: { active: 30 },
+    },
+  },
+
   statuses: {
     order: ['active', 'ready', 'planned', 'research', 'blocked', 'reference', 'archived'],
     staleDays: {
@@ -209,12 +227,34 @@ export async function resolveConfig(cwd, explicitConfigPath) {
     }
   }
 
+  // Resolve document types
+  const typesConfig = config.types ?? {};
+  const validTypes = new Set(Object.keys(typesConfig));
+  const typeStatuses = new Map();
+  const typeContextConfig = new Map();
+  for (const [typeName, typeDef] of Object.entries(typesConfig)) {
+    typeStatuses.set(typeName, new Set(typeDef.statuses ?? []));
+    if (typeDef.context) typeContextConfig.set(typeName, typeDef.context);
+  }
+
   const statusOrder = config.statuses.order;
   const validStatuses = new Set(statusOrder);
+  // Merge all type-specific statuses into the global valid set
+  for (const typeSet of typeStatuses.values()) {
+    for (const s of typeSet) validStatuses.add(s);
+  }
   const staleDaysByStatus = {};
   for (const status of statusOrder) {
     staleDaysByStatus[status] = config.statuses.staleDays?.[status] ?? null;
   }
+  // Merge type-specific staleDays
+  for (const typeDef of Object.values(typesConfig)) {
+    if (typeDef.staleDays) {
+      for (const [status, days] of Object.entries(typeDef.staleDays)) {
+        if (!(status in staleDaysByStatus)) staleDaysByStatus[status] = days;
+      }
+    }
+  }
 
   // Per-root additional statuses (merged with global validStatuses)
   const rootStatusesRaw = config.statuses.rootStatuses ?? {};
@@ -269,6 +309,9 @@ export async function resolveConfig(cwd, explicitConfigPath) {
 
     statusOrder,
     validStatuses,
+    validTypes,
+    typeStatuses,
+    typeContextConfig,
     rootValidStatuses,
     staleDaysByStatus,
 

package/src/index.mjs

@@ -143,9 +143,12 @@ export function parseDocFile(filePath, config) {
   const docRoot = roots.find(r => filePath.startsWith(r)) ?? config.docsRoot;
   const rootLabel = path.relative(config.repoRoot, docRoot).split(path.sep).join('/');
 
+  const docType = asString(parsedFrontmatter.type) ?? null;
+
   const doc = {
     path: relativePath,
     root: rootLabel,
+    type: docType,
     status: asString(parsedFrontmatter.status) ?? null,
     owner: asString(parsedFrontmatter.owner) ?? null,
     surface,

package/src/lifecycle.mjs

@@ -19,28 +19,42 @@ export async function runStatus(argv, config, opts = {}) {
   let newStatus = argv[1];
 
   if (!input) { die('Usage: dotmd status <file> <new-status>'); }
+
+  const filePath = resolveDocPath(input, config);
+  if (!filePath) { die(`File not found: ${input}\nSearched: ${toRepoPath(config.repoRoot, config.repoRoot) || '.'}, ${toRepoPath(config.docsRoot, config.repoRoot)}`); }
+
+  // Determine type-specific or root-specific valid statuses
+  const raw = readFileSync(filePath, 'utf8');
+  const { frontmatter: fmRaw } = extractFrontmatter(raw);
+  const parsedFm = parseSimpleFrontmatter(fmRaw);
+  const docType = asString(parsedFm.type) ?? null;
+  const fileRoot = findFileRoot(filePath, config);
+  const rootLabel = path.relative(config.repoRoot, fileRoot).split(path.sep).join('/');
+
+  // Build effective valid status set: type > root > global
+  let effectiveValid;
+  let effectiveOrder;
+  if (docType && config.typeStatuses?.has(docType)) {
+    effectiveValid = config.typeStatuses.get(docType);
+    effectiveOrder = [...effectiveValid];
+  } else {
+    const rootSet = config.rootValidStatuses?.get(rootLabel);
+    effectiveValid = rootSet ?? config.validStatuses;
+    effectiveOrder = config.statusOrder;
+  }
+
   if (!newStatus) {
     if (isInteractive()) {
-      newStatus = await promptChoice('Which status?', config.statusOrder);
+      newStatus = await promptChoice('Which status?', effectiveOrder);
       if (!newStatus) die('No status selected.');
     } else {
       die('Usage: dotmd status <file> <new-status>');
     }
   }
-  const filePath = resolveDocPath(input, config);
-  if (!filePath) { die(`File not found: ${input}\nSearched: ${toRepoPath(config.repoRoot, config.repoRoot) || '.'}, ${toRepoPath(config.docsRoot, config.repoRoot)}`); }
 
-  // Validate status against root-specific vocabulary
-  const fileRoot = findFileRoot(filePath, config);
-  const rootLabel = path.relative(config.repoRoot, fileRoot).split(path.sep).join('/');
-  const rootSet = config.rootValidStatuses?.get(rootLabel);
-  const effectiveValid = rootSet ?? config.validStatuses;
   if (!effectiveValid.has(newStatus)) { die(`Invalid status: ${newStatus}\nValid: ${[...effectiveValid].join(', ')}`); }
 
-  const raw = readFileSync(filePath, 'utf8');
-  const { frontmatter } = extractFrontmatter(raw);
-  const parsed = parseSimpleFrontmatter(frontmatter);
-  const oldStatus = asString(parsed.status);
+  const oldStatus = asString(parsedFm.status);
 
   if (oldStatus === newStatus) {
     process.stdout.write(`${toRepoPath(filePath, config.repoRoot)}: already ${newStatus}, no changes made.\n`);

package/src/lint.mjs

@@ -1,4 +1,5 @@
 import { readFileSync, writeFileSync } from 'node:fs';
+import path from 'node:path';
 import { extractFrontmatter, parseSimpleFrontmatter, replaceFrontmatter } from './frontmatter.mjs';
 import { asString, toRepoPath, escapeRegex, warn } from './util.mjs';
 import { buildIndex, collectDocFiles } from './index.mjs';
@@ -29,6 +30,16 @@ export function runLint(argv, config, opts = {}) {
     const repoPath = toRepoPath(filePath, config.repoRoot);
     const fixes = [];
 
+    // Missing type (fixable — infer from root: plans → 'plan', else 'doc')
+    if (!asString(parsed.type)) {
+      const roots = config.docsRoots || [config.docsRoot];
+      const docRoot = roots.find(r => filePath.startsWith(r)) ?? config.docsRoot;
+      const rootLabel = path.relative(config.repoRoot, docRoot).split(path.sep).join('/');
+      // If the root label contains 'plan' (e.g. 'docs/plans'), default to plan type
+      const inferredType = rootLabel.includes('plan') ? 'plan' : 'doc';
+      fixes.push({ field: 'type', oldValue: null, newValue: inferredType, type: 'add' });
+    }
+
     // Missing status (fixable via AI inference)
     if (!asString(parsed.status)) {
       fixes.push({ field: 'status', oldValue: null, newValue: null, type: 'infer-status' });
@@ -40,9 +51,12 @@ export function runLint(argv, config, opts = {}) {
       fixes.push({ field: 'updated', oldValue: null, newValue: today, type: 'add' });
     }
 
-    // Status casing
+    // Status casing — check against type-specific or global valid statuses
     const status = asString(parsed.status);
-    if (status && status !== status.toLowerCase() && config.validStatuses.has(status.toLowerCase())) {
+    const docType = asString(parsed.type);
+    const typeSet = docType ? config.typeStatuses?.get(docType) : null;
+    const effectiveStatuses = typeSet ?? config.validStatuses;
+    if (status && status !== status.toLowerCase() && effectiveStatuses.has(status.toLowerCase())) {
       fixes.push({ field: 'status', oldValue: status, newValue: status.toLowerCase(), type: 'update' });
     }
 
@@ -153,12 +167,17 @@ export function runLint(argv, config, opts = {}) {
       // Apply infer-status fixes via AI
       for (const f of fixes.filter(f => f.type === 'infer-status')) {
         const raw = readFileSync(filePath, 'utf8');
+        const { frontmatter: fmInfer } = extractFrontmatter(raw);
+        const parsedInfer = parseSimpleFrontmatter(fmInfer);
+        const inferType = asString(parsedInfer.type);
+        const inferTypeSet = inferType ? config.typeStatuses?.get(inferType) : null;
+        const statusList = inferTypeSet ? [...inferTypeSet].join(', ') : config.statusOrder.join(', ');
         const { body } = extractFrontmatter(raw);
-        const statusList = config.statusOrder.join(', ');
         const prompt = `Given this markdown document, classify it into exactly one of these statuses: ${statusList}.\nReply with ONLY the status word, nothing else.\n\nFile: ${repoPath}\n\n${(body ?? '').slice(0, 4000)}`;
         const result = runMLX(prompt, { maxTokens: 10 });
         const suggested = result?.trim().toLowerCase().split(/\s+/)[0];
-        if (suggested && config.validStatuses.has(suggested)) {
+        const inferValid = inferTypeSet ?? config.validStatuses;
+        if (suggested && inferValid.has(suggested)) {
           updateFrontmatter(filePath, { status: suggested });
           f.newValue = suggested;
         }

package/src/new.mjs

@@ -7,32 +7,32 @@ import { isInteractive, promptText } from './prompt.mjs';
 const BUILTIN_TEMPLATES = {
   default: {
     description: 'Minimal document with status and updated date',
-    frontmatter: (s, d) => `status: ${s}\nupdated: ${d}`,
+    frontmatter: (s, d) => `type: doc\nstatus: ${s}\nupdated: ${d}`,
     body: (t) => `\n# ${t}\n`,
   },
   plan: {
     description: 'Execution plan with module, surface, and cross-references',
-    frontmatter: (s, d) => `status: ${s}\nupdated: ${d}\nsurface:\nmodule:\ncurrent_state:\nrelated_plans:`,
+    frontmatter: (s, d) => `type: plan\nstatus: ${s}\nupdated: ${d}\nsurface:\nmodule:\ncurrent_state:\nrelated_plans:`,
     body: (t) => `\n# ${t}\n\n## Overview\n\n\n\n## Implementation Plan\n\n- [ ] \n\n## Open Questions\n\n\n`,
   },
   adr: {
     description: 'Architecture Decision Record',
-    frontmatter: (s, d) => `status: ${s}\nupdated: ${d}\ndecision_date:\ndeciders:`,
+    frontmatter: (s, d) => `type: doc\nstatus: ${s}\nupdated: ${d}\ndecision_date:\ndeciders:`,
     body: (t) => `\n# ${t}\n\n## Context\n\n\n\n## Decision\n\n\n\n## Consequences\n\n\n`,
   },
   rfc: {
     description: 'Request for Comments',
-    frontmatter: (s, d) => `status: ${s}\nupdated: ${d}\nowner:\nreviewers:`,
+    frontmatter: (s, d) => `type: doc\nstatus: ${s}\nupdated: ${d}\nowner:\nreviewers:`,
     body: (t) => `\n# ${t}\n\n## Summary\n\n\n\n## Motivation\n\n\n\n## Detailed Design\n\n\n\n## Alternatives\n\n\n\n## Open Questions\n\n\n`,
   },
   audit: {
     description: 'Codebase audit or research investigation',
-    frontmatter: (s, d) => `status: research\nupdated: ${d}\naudited: ${d}\naudit_level: pass1\nmodule:\nsource_of_truth: code\nsupports_plans:`,
+    frontmatter: (s, d) => `type: research\nstatus: active\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: {
     description: 'Design document with goals, non-goals, and implementation plan',
-    frontmatter: (s, d) => `status: ${s}\nupdated: ${d}\nowner:\nsurface:\nmodule:\nrelated_plans:`,
+    frontmatter: (s, d) => `type: doc\nstatus: ${s}\nupdated: ${d}\nowner:\nsurface:\nmodule:\nrelated_plans:`,
     body: (t) => `\n# ${t}\n\n## Overview\n\n\n\n## Goals\n\n\n\n## Non-Goals\n\n\n\n## Design\n\n\n\n## Implementation Plan\n\n- [ ] \n`,
   },
 };

package/src/query.mjs

@@ -60,7 +60,7 @@ export function runQuery(index, argv, config) {
 
 export function parseQueryArgs(argv) {
   const filters = {
-    statuses: null, keyword: null, owner: null, surface: null,
+    types: null, statuses: null, keyword: null, owner: null, surface: null,
     module: null, domain: null, audience: null, executionMode: null,
     updatedSince: null, limit: 20, all: false, sort: 'updated',
     stale: false, hasNextStep: false, hasBlockers: false,
@@ -72,6 +72,7 @@ export function parseQueryArgs(argv) {
     const arg = argv[i];
     const next = argv[i + 1];
 
+    if (arg === '--type' && next) { filters.types = next.split(',').map(v => v.trim()).filter(Boolean); i += 1; continue; }
     if (arg === '--status' && next) { filters.statuses = next.split(',').map(v => v.trim()).filter(Boolean); i += 1; continue; }
     if (arg === '--keyword' && next) { filters.keyword = next; i += 1; continue; }
     if (arg === '--owner' && next) { filters.owner = next; i += 1; continue; }
@@ -101,6 +102,7 @@ export function parseQueryArgs(argv) {
 export function filterDocs(docs, filters, config) {
   let result = [...docs];
 
+  if (filters.types?.length) result = result.filter(d => filters.types.includes(d.type));
   if (filters.statuses?.length) result = result.filter(d => filters.statuses.includes(d.status));
 
   if (filters.keyword) {
@@ -151,6 +153,7 @@ function getDocSummary(doc, config) {
 function renderQueryResults(docs, filters, config) {
   process.stdout.write('Query\n\n');
   process.stdout.write(`- results: ${docs.length}\n`);
+  if (filters.types?.length) process.stdout.write(`- type: ${filters.types.join(', ')}\n`);
   if (filters.statuses?.length) process.stdout.write(`- status: ${filters.statuses.join(', ')}\n`);
   if (filters.keyword) process.stdout.write(`- keyword: ${filters.keyword}\n`);
   if (filters.owner) process.stdout.write(`- owner: ${filters.owner}\n`);
@@ -173,6 +176,7 @@ function renderQueryResults(docs, filters, config) {
   for (let idx = 0; idx < docs.length; idx++) {
     const doc = docs[idx];
     process.stdout.write(`- ${doc.title}\n`);
+    if (doc.type) process.stdout.write(`  type: ${doc.type}\n`);
     process.stdout.write(`  status: ${doc.status}\n`);
     process.stdout.write(`  updated: ${doc.updated ?? 'n/a'}\n`);
     if (doc.daysSinceUpdate != null) process.stdout.write(`  days-since-update: ${doc.daysSinceUpdate}\n`);

package/src/render.mjs

@@ -118,24 +118,20 @@ export function renderContext(index, config, opts = {}) {
   return defaultRenderer(index);
 }
 
-function _renderContext(index, config, opts = {}) {
-  const today = new Date().toISOString().slice(0, 10);
-  const lines = [`BRIEFING (${today})`, ''];
-  const ctx = config.context;
-
+function _renderContextSection(docs, ctx, opts, config, lines) {
   const byStatus = {};
-  for (const doc of index.docs) {
+  for (const doc of docs) {
     const s = doc.status ?? 'unknown';
     if (!byStatus[s]) byStatus[s] = [];
     byStatus[s].push(doc);
   }
 
   for (const status of (ctx.expanded || [])) {
-    const docs = byStatus[status];
-    if (!docs?.length) continue;
-    lines.push(bold(`${capitalize(status)} (${docs.length}):`));
-    const maxSlug = Math.min(24, Math.max(...docs.map(d => toSlug(d).length)));
-    for (const doc of docs) {
+    const sdocs = byStatus[status];
+    if (!sdocs?.length) continue;
+    lines.push(bold(`${capitalize(status)} (${sdocs.length}):`));
+    const maxSlug = Math.min(24, Math.max(...sdocs.map(d => toSlug(d).length)));
+    for (const doc of sdocs) {
       const slug = toSlug(doc).padEnd(maxSlug);
       const next = doc.nextStep
         ? truncate(doc.nextStep, ctx.truncateNextStep || 80)
@@ -160,9 +156,9 @@ function _renderContext(index, config, opts = {}) {
   }
 
   for (const status of (ctx.listed || [])) {
-    const docs = byStatus[status];
-    if (!docs?.length) continue;
-    lines.push(`${capitalize(status)} (${docs.length}): ${docs.map(toSlug).join(', ')}`);
+    const sdocs = byStatus[status];
+    if (!sdocs?.length) continue;
+    lines.push(`${capitalize(status)} (${sdocs.length}): ${sdocs.map(toSlug).join(', ')}`);
   }
 
   const counts = (ctx.counted || [])
@@ -171,7 +167,59 @@ function _renderContext(index, config, opts = {}) {
   if (counts.length) {
     lines.push(counts.join('  |  '));
   }
-  lines.push('');
+}
+
+function _renderContext(index, config, opts = {}) {
+  const today = new Date().toISOString().slice(0, 10);
+  const lines = [`BRIEFING (${today})`, ''];
+
+  // Group docs by type
+  const typeOrder = ['plan', 'doc', 'research'];
+  const byType = {};
+  const untyped = [];
+  for (const doc of index.docs) {
+    if (doc.type) {
+      if (!byType[doc.type]) byType[doc.type] = [];
+      byType[doc.type].push(doc);
+    } else {
+      untyped.push(doc);
+    }
+  }
+
+  const hasTypedDocs = Object.keys(byType).length > 0;
+  const typeLabels = { plan: 'PLANS', doc: 'DOCS', research: 'RESEARCH' };
+
+  if (hasTypedDocs) {
+    for (const typeName of typeOrder) {
+      const docs = byType[typeName];
+      if (!docs?.length) continue;
+      const typeCtx = config.typeContextConfig?.get(typeName) ?? config.context;
+      lines.push(bold(typeLabels[typeName] ?? typeName.toUpperCase()));
+      _renderContextSection(docs, typeCtx, opts, config, lines);
+      lines.push('');
+    }
+    // Any types not in typeOrder
+    for (const typeName of Object.keys(byType)) {
+      if (typeOrder.includes(typeName)) continue;
+      const docs = byType[typeName];
+      if (!docs?.length) continue;
+      const typeCtx = config.typeContextConfig?.get(typeName) ?? config.context;
+      lines.push(bold(typeName.toUpperCase()));
+      _renderContextSection(docs, typeCtx, opts, config, lines);
+      lines.push('');
+    }
+  }
+
+  // Render untyped docs (backward compat) or all docs if no types present
+  if (untyped.length > 0) {
+    if (hasTypedDocs) lines.push(bold('OTHER'));
+    _renderContextSection(untyped, config.context, opts, config, lines);
+    lines.push('');
+  } else if (!hasTypedDocs) {
+    // No types at all — fall back to original flat rendering
+    _renderContextSection(index.docs, config.context, opts, config, lines);
+    lines.push('');
+  }
 
   const stale = index.docs.filter(d => d.isStale && !config.lifecycle.skipStaleFor.has(d.status));
   if (stale.length) {
@@ -189,6 +237,7 @@ function _renderContext(index, config, opts = {}) {
     lines.push(`Non-compliant: ${parts.join(', ')} (run \`dotmd check\` for details)`);
   }
 
+  const ctx = config.context;
   const recentStatuses = new Set(ctx.recentStatuses || ['active', 'ready', 'planned']);
   const recentDays = ctx.recentDays ?? 3;
   const recentLimit = ctx.recentLimit ?? 10;
@@ -275,8 +324,9 @@ export function renderCoverage(index, config) {
 }
 
 export function buildCoverage(index, config) {
-  const scope = ['active', 'ready', 'planned', 'blocked'];
-  const scoped = index.docs.filter(doc => scope.includes(doc.status));
+  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 missingSurface = scoped.filter(doc => !doc.surface);
   const missingModule = scoped.filter(doc => !doc.module);
   const modulePlatform = scoped.filter(doc => doc.module === 'platform');

package/src/validate.mjs

@@ -6,20 +6,34 @@ import { toRepoPath } from './util.mjs';
 
 const NOW = new Date();
 
-function isValidStatus(status, root, config) {
+function isValidStatus(status, root, config, type) {
+  // Union type-specific + root-specific statuses (a doc can satisfy either)
+  if (type) {
+    const typeSet = config.typeStatuses?.get(type);
+    if (typeSet && typeSet.has(status)) return true;
+  }
   const rootSet = config.rootValidStatuses?.get(root);
   if (rootSet) return rootSet.has(status);
   return config.validStatuses.has(status);
 }
 
 export function validateDoc(doc, frontmatter, headingTitle, config) {
+  // Validate type field
+  if (doc.type && config.validTypes && !config.validTypes.has(doc.type)) {
+    doc.warnings.push({ path: doc.path, level: 'warning', message: `Unknown type \`${doc.type}\`; expected one of: ${[...config.validTypes].join(', ')}.` });
+  }
+
   if (!doc.status) {
     doc.errors.push({ path: doc.path, level: 'error', message: 'Missing frontmatter `status`.' });
-  } else if (!isValidStatus(doc.status, doc.root, config)) {
-    doc.warnings.push({ path: doc.path, level: 'warning', message: `Unknown status \`${doc.status}\`; not in statuses.order.` });
+  } else if (!isValidStatus(doc.status, doc.root, config, doc.type)) {
+    const typeSet = doc.type && config.typeStatuses?.get(doc.type);
+    const rootSet = config.rootValidStatuses?.get(doc.root);
+    const combined = new Set([...(typeSet ?? []), ...(rootSet ?? config.validStatuses)]);
+    const hint = `valid: ${[...combined].join(', ')}`;
+    doc.warnings.push({ path: doc.path, level: 'warning', message: `Unknown status \`${doc.status}\`; ${hint}.` });
   }
 
-  const knownStatus = isValidStatus(doc.status, doc.root, config);
+  const knownStatus = isValidStatus(doc.status, doc.root, config, doc.type);
 
   if (knownStatus && !config.lifecycle.skipWarningsFor.has(doc.status) && !doc.updated) {
     doc.errors.push({ path: doc.path, level: 'error', message: 'Missing frontmatter `updated` for non-archived doc.' });
@@ -65,11 +79,15 @@ export function validateDoc(doc, frontmatter, headingTitle, config) {
     doc.warnings.push({ path: doc.path, level: 'warning', message: 'Missing `summary` and no blockquote fallback found.' });
   }
 
-  if (['active', 'ready', 'planned', 'blocked'].includes(doc.status) && !asString(frontmatter.current_state)) {
+  // 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);
+
+  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.' });
   }
 
-  if (['active', 'ready', 'planned'].includes(doc.status) && !asString(frontmatter.next_step)) {
+  if (isWorkStatus && doc.status !== 'blocked' && !asString(frontmatter.next_step)) {
     doc.warnings.push({ path: doc.path, level: 'warning', message: 'Missing `next_step`; command output will omit a clear immediate action.' });
   }