dotmd-cli 0.39.9 → 0.40.1

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
@@ -334,15 +335,19 @@ Use --dry-run (-n) to preview changes without writing anything.`,
 
   check: `dotmd check — validate frontmatter and references
 
+By default the warning list is suppressed: you see counts plus a one-line
+pointer to \`dotmd doctor\` (auto-fix) or \`dotmd check --verbose\`
+(per-doc detail). Errors are always shown in full.
+
 Options:
-  --errors-only          Show only errors, suppress warnings
+  --verbose              Show every warning per-doc (with category collapse
+                         applied — high-frequency auto-fixable categories
+                         summarize to a one-line bulk-fix hint).
+  --no-collapse          Like --verbose but disables category collapse too —
+                         every warning prints raw.
+  --errors-only          Show only errors, suppress warnings entirely
   --fix                  Auto-fix broken refs, lint issues, and regenerate index
-  --json                 Output errors and warnings as JSON
-  --no-collapse          Show every warning per-doc (since 0.37.0, high-frequency
-                         auto-fixable warning categories — singular module/surface
-                         deprecations, updated-behind-git — are collapsed into a
-                         one-line summary with the bulk-fix command). --json output
-                         is unchanged regardless.
+  --json                 Output errors and warnings as JSON (always full detail)
   --dry-run, -n          Preview fixes without writing (with --fix)`,
 
   archive: `dotmd archive <file> — archive a document
@@ -492,6 +497,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
@@ -1207,6 +1223,7 @@ async function main() {
     const fix = args.includes('--fix');
     const errorsOnly = args.includes('--errors-only');
     const noCollapse = args.includes('--no-collapse');
+    const verbose = args.includes('--verbose');
 
     if (fix) {
       // Auto-fix: broken refs, then lint, then rebuild index
@@ -1237,7 +1254,7 @@ async function main() {
           passed: freshIndex.errors.length === 0,
         }, null, 2) + '\n');
       } else {
-        process.stdout.write('\n' + renderCheck(freshIndex, config, { errorsOnly, noCollapse }));
+        process.stdout.write('\n' + renderCheck(freshIndex, config, { errorsOnly, noCollapse, verbose }));
       }
       if (freshIndex.errors.length > 0) process.exitCode = 1;
       return;
@@ -1256,7 +1273,7 @@ async function main() {
       return;
     }
 
-    process.stdout.write(renderCheck(index, config, { errorsOnly, noCollapse }));
+    process.stdout.write(renderCheck(index, config, { errorsOnly, noCollapse, verbose }));
     if (index.errors.length > 0) process.exitCode = 1;
     return;
   }
@@ -1317,6 +1334,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.9",
+  "version": "0.40.1",
   "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/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/render.mjs

@@ -377,7 +377,7 @@ export function renderCheck(index, config, opts = {}) {
 }
 
 function _renderCheck(index, opts = {}) {
-  const { errorsOnly, noCollapse } = opts;
+  const { errorsOnly, noCollapse, verbose } = opts;
   const lines = ['Check', ''];
   lines.push(`- docs scanned: ${index.docs.length}`);
   lines.push(`- errors: ${index.errors.length}`);
@@ -392,22 +392,32 @@ function _renderCheck(index, opts = {}) {
     lines.push('');
   }
 
+  // Warnings: terse by default — print count + pointer. The full per-doc list
+  // grew long enough on real projects that it drowned the summary; agents now
+  // see warnings as a single line and opt in to detail when they need it.
+  // --verbose / --no-collapse expand to the full list (with collapse-by-category
+  // still applied unless --no-collapse is set).
   if (!errorsOnly && index.warnings.length > 0) {
-    lines.push(yellow('Warnings'));
-    if (noCollapse) {
-      for (const issue of index.warnings) {
-        lines.push(`- ${issue.path}: ${issue.message}`);
+    if (verbose || noCollapse) {
+      lines.push(yellow('Warnings'));
+      if (noCollapse) {
+        for (const issue of index.warnings) {
+          lines.push(`- ${issue.path}: ${issue.message}`);
+        }
+      } else {
+        const { passthrough, collapsed } = categorizeWarnings(index.warnings);
+        for (const issue of passthrough) {
+          lines.push(`- ${issue.path}: ${issue.message}`);
+        }
+        for (const sum of collapsed) {
+          lines.push(`- ${sum.count} ${sum.label} — run \`${sum.fix}\` to bulk-fix`);
+        }
       }
+      lines.push('');
     } else {
-      const { passthrough, collapsed } = categorizeWarnings(index.warnings);
-      for (const issue of passthrough) {
-        lines.push(`- ${issue.path}: ${issue.message}`);
-      }
-      for (const sum of collapsed) {
-        lines.push(`- ${sum.count} ${sum.label} — run \`${sum.fix}\` to bulk-fix`);
-      }
+      lines.push(dim(`Run \`dotmd check --verbose\` for per-doc detail, or \`dotmd doctor\` to auto-fix where possible.`));
+      lines.push('');
     }
-    lines.push('');
   }
 
   if (index.errors.length === 0 && index.warnings.length === 0) {

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.`,
     });
   }