dotmd-cli 0.39.8 → 0.40.0

package/bin/dotmd.mjs

@@ -35,6 +35,7 @@ Analyze:
   deps [file] [--json]              Dependency tree or overview
   modules [--sort cleanup] [--json] Module dashboard (plans grouped by module)
   module <name> [--json]            Plans for one module, grouped by status
+  surfaces [--json]                 List configured surface taxonomy
   unblocks <file> [--json]          Show what completes when this doc ships
   diff [file] [--summarize]         Show changes since last updated date
   summary <file> [--json]           AI summary of a document
@@ -492,6 +493,17 @@ Options:
 
 Unknown module name suggests close matches (or lists what's available).`,
 
+  surfaces: `dotmd surfaces — list configured surface taxonomy
+
+Prints the values accepted in \`surfaces:\` frontmatter, one per line.
+Source: \`config.taxonomy.surfaces\` in dotmd.config.mjs.
+
+Options:
+  --json                 Machine-readable shape: { surfaces: [...] }
+
+When the project has no taxonomy configured, any surface value is accepted —
+the command says so instead of printing an empty list.`,
+
   doctor: `dotmd doctor — auto-fix everything in one pass
 
 Runs in sequence: fix broken references, lint --fix, sync dates from
@@ -760,12 +772,17 @@ Prompts are documents with \`type: prompt\`, typically saved under
 docs/prompts/. They seed future Claude sessions; consuming a prompt
 prints its body to stdout and atomically archives it (one-shot).
 
+\`dotmd prompt\` (singular) is an alias for \`dotmd prompts\` — every
+subcommand below works under either spelling.
+
 Subcommands:
   list                       List pending prompts (default)
   next                       Consume the oldest pending prompt:
                              print body to stdout, flip status to archived
   use <file-or-slug>         Consume a specific prompt (same as next, but
                              targets the named prompt instead of picking oldest)
+  resume <file-or-slug>      Alias for \`use\` — same behavior, easier name
+                             when continuing a session
   archive <file-or-slug>     Archive a prompt without printing its body
   shelve <file-or-slug>      Park a prompt (status → shelved): kept in list,
                              hidden from hud/briefing pending surfaces, skipped
@@ -792,6 +809,8 @@ Examples:
   claude "$(dotmd prompts next)"       # consume oldest pending + run claude
   claude "$(dotmd prompts use resume-foo)"           # by slug
   claude "$(dotmd prompts use docs/prompts/foo.md)"  # by path
+  claude "$(dotmd prompts resume resume-foo)"        # \`resume\` is an alias for \`use\`
+  dotmd prompt list                    # singular alias for \`dotmd prompts list\`
 
   dotmd prompts next --dry-run         # preview without consuming
   dotmd prompts archive old-thing
@@ -964,7 +983,7 @@ the whole docs tree is scanned.`,
 
 async function main() {
   const args = process.argv.slice(2);
-  const command = args[0] ?? 'list';
+  let command = args[0] ?? 'list';
 
   // Pre-config flags
   if (args.includes('--version') || args.includes('-v')) {
@@ -985,6 +1004,14 @@ async function main() {
     return;
   }
 
+  // Singular-form alias for the prompts subcommand namespace. Trivial
+  // no-collision collapse — `prompt` was previously "unknown command", now
+  // routes everywhere `prompts` does (incl. per-command --help below, and the
+  // subcommand dispatch at the `prompts` branch in the chain). The other
+  // singular/plural pairs (`plan`/`plans`, `module`/`modules`,
+  // `status`/`statuses`) are deliberately kept distinct — see F20 plan.
+  if (command === 'prompt') command = 'prompts';
+
   // Per-command help
   if (args.includes('--help') || args.includes('-h')) {
     process.stdout.write(`${HELP[command] ?? HELP._main}\n`);
@@ -1302,6 +1329,11 @@ async function main() {
     }
     return;
   }
+  if (command === 'surfaces') {
+    const { runSurfaces } = await import('../src/surfaces.mjs');
+    runSurfaces(restArgs, config);
+    return;
+  }
   if (command === 'briefing') {
     if (args.includes('--json')) {
       const plans = index.docs.filter(d => d.type === 'plan');

package/package.json

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

package/src/frontmatter-fix.mjs

@@ -9,8 +9,8 @@ import { bold, green, dim } from './color.mjs';
 // are deliberately under the cap so a fix-then-edit cycle doesn't reintroduce
 // the warning on the next few-word touch-up.
 const FIELDS = [
-  { name: 'current_state', cap: 500, target: 300, heading: '## Current State' },
-  { name: 'next_step',     cap: 300, target: 200, heading: '## Next Step' },
+  { name: 'current_state', cap: 1500, target: 1200, heading: '## Current State' },
+  { name: 'next_step',     cap: 300,  target: 200,  heading: '## Next Step' },
 ];
 
 export function runFrontmatterFix(config, opts = {}) {

package/src/hud.mjs

@@ -76,10 +76,13 @@ export function buildHud(config) {
   // Validation error count — hud's "silent when clean" contract should treat
   // `check` errors as not-clean. Without this, a SessionStart hook firing hud
   // can leave the agent with no visible signal that a check is failing.
-  // buildIndex wraps the same scan every other read command does; cost is fine.
+  // `errorsOnly: true` skips warning-only cross-doc passes (git staleness,
+  // bidirectional refs, claude-commands) that hud never reads — ~6× faster on
+  // SessionStart for platform-scale corpora. Per-file validation + checkIndex
+  // still run, so the error count matches `dotmd check`'s.
   let errors = 0;
   try {
-    const index = buildIndex(config);
+    const index = buildIndex(config, { errorsOnly: true });
     errors = index.errors.length;
   } catch { /* swallow — bad config shouldn't break the SessionStart hook */ }
 

package/src/index.mjs

@@ -7,14 +7,22 @@ import { validateDoc, validatePlanShape, validateDocShape, checkBidirectionalRef
 import { checkIndex } from './index-file.mjs';
 import { checkClaudeCommands } from './claude-commands.mjs';
 
-// `fast: true` skips every pass that only produces warnings/errors — the
-// rendered index file consumes only status/title/snapshot/etc., not the
-// validation output. Use it from `regenIndex` (post-mutation index refresh)
-// where validation has already run elsewhere (or will, next time the user
-// runs `dotmd check`). Saves the full-repo `git log` scan in
-// `checkGitStaleness` plus the bidirectional ref walk + claude-commands check.
+// `fast: true` skips every pass that produces warnings/errors — the rendered
+// index file consumes only status/title/snapshot/etc., not the validation
+// output. Use it from `regenIndex` (post-mutation index refresh) where
+// validation has already run elsewhere (or will, next time the user runs
+// `dotmd check`). Saves the full-repo `git log` scan in `checkGitStaleness`
+// plus the bidirectional ref walk + claude-commands check.
+//
+// `errorsOnly: true` runs every error-producing pass (per-file `validateDoc`,
+// `checkIndex`, the `validate` hook) but skips the warning-only cross-doc
+// passes (bidirectional refs, runlist back-pointers, git staleness, claude
+// commands). Use it from `dotmd hud` — the SessionStart hook only renders the
+// error COUNT, so the warning-only passes are pure overhead there. Preserves
+// the invariant that hud's "✗ N validation errors" line matches `dotmd check`.
 export function buildIndex(config, opts = {}) {
-  const { fast = false } = opts;
+  const { fast = false, errorsOnly = false } = opts;
+  const skipWarningOnlyChecks = fast || errorsOnly;
   const docs = collectDocFiles(config).map(f => parseDocFile(f, config, { fast }));
   if (!fast) {
     // Per-file validation (validateDoc) ran during parse without sibling
@@ -86,13 +94,13 @@ export function buildIndex(config, opts = {}) {
     countsByType[type][doc.status] = (countsByType[type][doc.status] ?? 0) + 1;
   }
 
-  if (!fast) {
-    if (config.indexPath) {
-      const indexCheck = checkIndex(transformedDocs, config);
-      warnings.push(...indexCheck.warnings);
-      errors.push(...indexCheck.errors);
-    }
+  if (!fast && config.indexPath) {
+    const indexCheck = checkIndex(transformedDocs, config);
+    warnings.push(...indexCheck.warnings);
+    errors.push(...indexCheck.errors);
+  }
 
+  if (!skipWarningOnlyChecks) {
     const refCheck = checkBidirectionalReferences(transformedDocs, config);
     warnings.push(...refCheck.warnings);
 

package/src/new.mjs

@@ -5,10 +5,23 @@ import { toRepoPath, die, warn, nowIso, emitFilesFooter } from './util.mjs';
 import { green, dim, bold } from './color.mjs';
 import { isInteractive, promptText } from './prompt.mjs';
 import { regenIndex } from './lifecycle.mjs';
+import { extractFrontmatter, parseSimpleFrontmatter } from './frontmatter.mjs';
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const pkg = JSON.parse(readFileSync(path.join(__dirname, '..', 'package.json'), 'utf8'));
 
+// Surface-taxonomy hint emitted above the `surfaces:` line in scaffolded docs.
+// Discoverable-by-default: the author sees valid values without leaving the file
+// and without grepping sibling docs (issue #12 trap 1). When the project has no
+// configured taxonomy, fall back to a bare `surfaces:` line.
+function surfacesScaffold(ctx) {
+  const valid = ctx?.validSurfaces;
+  if (Array.isArray(valid) && valid.length > 0) {
+    return `# surfaces — valid: ${valid.join(', ')}\nsurfaces:`;
+  }
+  return 'surfaces:';
+}
+
 const BUILTIN_TEMPLATES = {
   doc: {
     description: 'Reference doc, design note, module overview — build-up shape lite',
@@ -17,13 +30,15 @@ const BUILTIN_TEMPLATES = {
     // it lands in the Overview section. Without it, Overview is left blank
     // and the user fills it in.
     acceptsBody: true,
-    frontmatter: (s, d) => [
+    frontmatter: (s, d, ctx) => [
       'type: doc',
       `status: ${s}`,
       `created: ${d}`,
       `updated: ${d}`,
+      '# modules — real module name(s), or `none` for platform/infra docs',
       'modules:',
-      'surfaces:',
+      '  - none',
+      surfacesScaffold(ctx),
       'domain:',
       'audience: internal',
       'related_plans:',
@@ -54,13 +69,15 @@ ${ctx?.bodyInput?.trim() ?? ''}
     // Body input lands in the Problem section. Plans don't have an Overview;
     // Problem is the established opening section in the build-up shape.
     acceptsBody: true,
-    frontmatter: (s, d) => [
+    frontmatter: (s, d, ctx) => [
       'type: plan',
       `status: ${s}`,
       `created: ${d}`,
       `updated: ${d}`,
-      'surfaces:',
+      surfacesScaffold(ctx),
+      '# modules — real module name(s), or `none` for tooling/infra plans',
       'modules:',
+      '  - none',
       'domain:',
       'audience: internal',
       'parent_plan:',
@@ -164,6 +181,68 @@ Status markers (put in heading text):
   },
 };
 
+// Body inputs from agents often arrive as a full document (frontmatter + body)
+// written to a tempfile and passed via `@path` or stdin. Without this split,
+// `dotmd new` would prepend its scaffold frontmatter and treat the input's
+// frontmatter as literal body content — resulting in two `---` blocks and a
+// duplicated title. We instead parse the leading block (if any), merge its
+// keys onto the scaffold, and use only what follows as body. See issue #12
+// trap 4. Returns `{ frontmatter: object|null, body: string }`.
+function splitBodyFrontmatter(rawBody) {
+  if (!rawBody || typeof rawBody !== 'string') return { frontmatter: null, body: rawBody };
+  if (!rawBody.startsWith('---\n')) return { frontmatter: null, body: rawBody };
+  const { frontmatter: fmText, body } = extractFrontmatter(rawBody);
+  if (!fmText) return { frontmatter: null, body: rawBody };
+  const parsed = parseSimpleFrontmatter(fmText);
+  return { frontmatter: parsed, body };
+}
+
+// Serialize a single frontmatter key/value pair to a YAML block. Mirrors the
+// scaffold's shape so merged output reads naturally next to scaffold defaults.
+function serializeFmEntry(key, value) {
+  if (value === null || value === undefined || value === '') return `${key}:`;
+  if (Array.isArray(value)) {
+    if (value.length === 0) return `${key}:`;
+    return `${key}:\n${value.map(v => `  - ${v}`).join('\n')}`;
+  }
+  if (typeof value === 'string' && value.includes('\n')) {
+    const indented = value.split('\n').map(l => `  ${l}`).join('\n');
+    return `${key}: |\n${indented}`;
+  }
+  return `${key}: ${value}`;
+}
+
+// Replace each key in `overrides` within the scaffold-generated frontmatter
+// string. Keys not present in the scaffold are appended. `type:` is never
+// overwritten — the CLI's type arg wins (warning emitted on conflict).
+function mergeBodyFrontmatter(scaffoldFm, overrides, cliType) {
+  if (!overrides || Object.keys(overrides).length === 0) return scaffoldFm;
+  let fm = scaffoldFm;
+  const appended = [];
+  for (const [key, value] of Object.entries(overrides)) {
+    if (key === 'type') {
+      if (cliType && value && value !== cliType) {
+        warn(`Body frontmatter declares \`type: ${value}\` but CLI arg is \`${cliType}\`; using \`${cliType}\`.`);
+      }
+      continue;
+    }
+    if (key === 'created' || key === 'updated') continue; // scaffold owns timestamps
+    const serialized = serializeFmEntry(key, value);
+    // Match `key:` line + any indented continuation (block-array items or
+    // block-scalar bodies). Indented lines start with whitespace; scaffold keys
+    // never do, so this consumes only the right slice.
+    const escaped = key.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+    const re = new RegExp(`^${escaped}:.*(\\n[ \\t]+.*)*`, 'm');
+    if (re.test(fm)) {
+      fm = fm.replace(re, serialized);
+    } else {
+      appended.push(serialized);
+    }
+  }
+  if (appended.length > 0) fm = fm + '\n' + appended.join('\n');
+  return fm;
+}
+
 function readBodyInput(source) {
   if (source === '-') {
     try { return readFileSync(0, 'utf8'); } catch (err) { die(`Could not read body from stdin: ${err.message}`); }
@@ -261,6 +340,20 @@ export async function runNew(argv, config, opts = {}) {
     bodyInputSource = bodyArg === '-' ? 'stdin (`-`)' : (bodyArg.startsWith('@') ? `file (\`${bodyArg}\`)` : 'inline body argument');
   }
 
+  // If the body input has a leading `---…---` frontmatter block, lift its keys
+  // out so they override scaffold defaults; only the content after the closing
+  // `---` is treated as body. The natural agent pattern is to draft a full doc
+  // to a tempfile and pass `@path` — without this, the scaffold ends up with
+  // two `---` blocks. See issue #12 trap 4.
+  let bodyFrontmatter = null;
+  if (bodyInput !== null) {
+    const split = splitBodyFrontmatter(bodyInput);
+    if (split.frontmatter) {
+      bodyFrontmatter = split.frontmatter;
+      bodyInput = split.body;
+    }
+  }
+
   if (template.requiresBody && (!bodyInput || !bodyInput.trim())) {
     die(`\`${typeName}\` template requires a body. Pass inline, --message "...", - for stdin, or @path for a file.`);
   }
@@ -359,11 +452,13 @@ export async function runNew(argv, config, opts = {}) {
 
   // Generate content
   let content;
-  const tmplCtx = { status, title: docTitle, today, bodyInput };
+  const validSurfaces = config.raw?.taxonomy?.surfaces ?? (config.validSurfaces ? [...config.validSurfaces] : null);
+  const tmplCtx = { status, title: docTitle, today, bodyInput, validSurfaces };
   if (typeof template === 'function') {
     content = template(name, tmplCtx);
   } else {
-    const fm = template.frontmatter(status, today, tmplCtx);
+    let fm = template.frontmatter(status, today, tmplCtx);
+    if (bodyFrontmatter) fm = mergeBodyFrontmatter(fm, bodyFrontmatter, typeName);
     const body = template.body(docTitle, tmplCtx);
     content = `---\n${fm}\n---\n${body}`;
   }

package/src/prompts.mjs

@@ -8,7 +8,10 @@ import { runArchive, runStatus } from './lifecycle.mjs';
 import { runNew } from './new.mjs';
 import { green, dim } from './color.mjs';
 
-const SUBCOMMANDS = new Set(['list', 'next', 'use', 'archive', 'new', 'shelve', 'unshelve']);
+// `resume` is an alias for `use` — agents reach for "resume" when continuing a
+// session; `use` reads as internal mechanics. Both names stay valid; the
+// canonical output ("Consumed: …") is unchanged.
+const SUBCOMMANDS = new Set(['list', 'next', 'use', 'resume', 'archive', 'new', 'shelve', 'unshelve']);
 
 export async function runPrompts(argv, config, opts = {}) {
   const sub = argv[0];
@@ -22,6 +25,7 @@ export async function runPrompts(argv, config, opts = {}) {
     case 'list':     return runPromptsList(rest, config, opts);
     case 'next':     return runPromptsNext(rest, config, opts);
     case 'use':      return runPromptsUse(rest, config, opts);
+    case 'resume':   return runPromptsUse(rest, config, opts);
     case 'archive':  return runPromptsArchive(rest, config, opts);
     case 'new':      return runPromptsNew(rest, config, opts);
     case 'shelve':   return runPromptsShelve(rest, config, opts);

package/src/surfaces.mjs

@@ -0,0 +1,28 @@
+// `dotmd surfaces` — print the configured surface taxonomy.
+//
+// The surface taxonomy (`config.taxonomy.surfaces`) gates which `surfaces:`
+// values the validator accepts. Before this command existed the only way to
+// discover the valid set was to grep sibling plans or open the config file —
+// which sent agents into a retry loop of "guess a surface, run check, get
+// flagged, guess again." See issue #12 trap 1.
+import { dim } from './color.mjs';
+
+export function runSurfaces(argv, config) {
+  const json = argv.includes('--json');
+  // Read from raw user config (preserves declaration order) — `config.taxonomy`
+  // isn't exposed on the resolved object; only the derived `validSurfaces` Set is.
+  const surfaces = config.raw?.taxonomy?.surfaces ?? null;
+
+  if (json) {
+    process.stdout.write(JSON.stringify({ surfaces: surfaces ?? [] }, null, 2) + '\n');
+    return;
+  }
+
+  if (!surfaces || surfaces.length === 0) {
+    process.stdout.write(dim('No surface taxonomy configured. Any surface value is accepted.\n'));
+    process.stdout.write(dim('To restrict, set `taxonomy.surfaces` in dotmd.config.mjs.\n'));
+    return;
+  }
+
+  for (const s of surfaces) process.stdout.write(s + '\n');
+}

package/src/validate.mjs

@@ -444,13 +444,16 @@ export function validatePlanShape(doc, body, frontmatter, config) {
     });
   }
 
-  // 2. current_state length cap (500 chars)
+  // 2. current_state length cap (1500 chars). Was 500; raised because agents
+  // legitimately need ~150-250 words of resume-context (prior incidents, what
+  // shipped, what's verified, where to look) and the prior cap forced a
+  // truncate-and-move-to-body retry loop on non-trivial plans.
   const currentState = typeof frontmatter.current_state === 'string' ? frontmatter.current_state : '';
-  if (currentState.length > 500) {
+  if (currentState.length > 1500) {
     doc.warnings.push({
       path: doc.path,
       level: 'warning',
-      message: `\`current_state\` is ${currentState.length} chars (cap: 500). Long prose belongs in the body.`,
+      message: `\`current_state\` is ${currentState.length} chars (cap: 1500). Long prose belongs in the body.`,
     });
   }