dotmd-cli 0.71.4 → 0.72.1

package/bin/dotmd.mjs

@@ -526,6 +526,10 @@ Options:
   --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 (always full detail)
+  --min-docs <n>         Fail if fewer than <n> docs were scanned — a floor that
+                         tells "nothing is wrong" apart from "nothing was looked
+                         at". Overrides \`minDocs\` in config for this run;
+                         skipped when checking specific paths.
   --dry-run, -n          Preview fixes without writing (with --fix)`,
 
   archive: `dotmd archive <file-or-slug> — archive a document
@@ -1760,7 +1764,19 @@ async function main() {
     const errorsOnly = args.includes('--errors-only');
     const noCollapse = args.includes('--no-collapse');
     const verbose = args.includes('--verbose');
-    const checkTargets = restArgs.filter(arg => !arg.startsWith('-'));
+    // `--min-docs N` overrides the configured floor for this run (CI passes it
+    // without editing config). Its value is not a path target.
+    const minDocsFlagIdx = restArgs.indexOf('--min-docs');
+    const minDocsRaw = minDocsFlagIdx === -1 ? null : restArgs[minDocsFlagIdx + 1];
+    if (minDocsFlagIdx !== -1 && !/^\d+$/.test(minDocsRaw ?? '')) {
+      die('`--min-docs` needs a positive integer, e.g. `dotmd check --min-docs 500`.');
+    }
+    const minDocsOverride = minDocsRaw == null ? null : Number(minDocsRaw);
+    const minDocsValueIdx = minDocsFlagIdx === -1 ? -1 : minDocsFlagIdx + 1;
+    const checkTargets = restArgs.filter((arg, i) => !arg.startsWith('-') && i !== minDocsValueIdx);
+    const { applyScanFloor } = await import('../src/validate.mjs');
+    const scanFloorConfig = minDocsOverride == null ? config : { ...config, minDocs: minDocsOverride };
+    const applyFloor = (idx) => applyScanFloor(idx, scanFloorConfig, { scoped: checkTargets.length > 0 });
     const skippedCheckHooks = config._execution?.suppressSideEffects
       ? ['validate', 'transformDoc', 'formatSnapshot', 'renderCheck']
           .filter(name => typeof config.hooks?.[name] === 'function')
@@ -1810,6 +1826,7 @@ async function main() {
       const freshIndex = buildIndex(config);
       applyIndexFilters(freshIndex);
       applyPathScopeToIndex(freshIndex, config, checkTargets);
+      applyFloor(freshIndex);
       if (args.includes('--json')) {
         process.stdout.write(JSON.stringify(checkJson(freshIndex), null, 2) + '\n');
       } else {
@@ -1821,6 +1838,7 @@ async function main() {
     }
 
     applyPathScopeToIndex(index, config, checkTargets);
+    applyFloor(index);
 
     if (args.includes('--json')) {
       process.stdout.write(JSON.stringify(checkJson(index), null, 2) + '\n');

package/dotmd.config.example.mjs

@@ -13,6 +13,14 @@ export const archiveDir = 'archived';
 // Directories to skip when scanning
 export const excludeDirs = ['evidence'];
 
+// Floor under the scan surface. `dotmd check` fails when it scans fewer docs than
+// this, so a broken root or an over-eager exclude can't read as a clean estate —
+// zero errors and zero docs look identical otherwise. Off when unset. Set it well
+// below your real count (round down hard); raise it as the corpus grows.
+// Override for one run with `dotmd check --min-docs <n>`; skipped for path-scoped
+// checks, which are deliberate subsets.
+// export const minDocs = 500;
+
 // Document types — each type has its own status vocabulary and context layout.
 // Defaults: plan, doc, prompt. Override to customize statuses per type, or add new types.
 //

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dotmd-cli",
-  "version": "0.71.4",
+  "version": "0.72.1",
   "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

@@ -142,7 +142,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')] })]),
+  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('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

@@ -20,6 +20,8 @@ const DEFAULTS = {
   root: '.',
   archiveDir: 'archived',
   excludeDirs: [],
+  // Floor under the scan surface; null = off. See `applyScanFloor` in validate.mjs.
+  minDocs: null,
 
   types: {
     plan: {
@@ -517,6 +519,18 @@ export async function resolveConfig(cwd, explicitConfigPath) {
     }
   }
 
+  // A floor under the scan surface. Unset (the default) is off, so no existing
+  // repo changes behavior. See `applyScanFloor` in src/validate.mjs for why a
+  // silent zero-doc pass is the failure mode worth spending a config key on.
+  let minDocs = null;
+  if (config.minDocs !== undefined && config.minDocs !== null) {
+    if (!Number.isInteger(config.minDocs) || config.minDocs < 1) {
+      earlyWarnings.push(`Config: minDocs must be a positive integer; ignoring \`${config.minDocs}\`.`);
+    } else {
+      minDocs = config.minDocs;
+    }
+  }
+
   const configWarnings = [...earlyWarnings, ...validateConfig(userConfig, config, validStatuses, indexPath)];
 
   return {
@@ -531,6 +545,7 @@ export async function resolveConfig(cwd, explicitConfigPath) {
     archiveDir: config.archiveDir,
     excludeDirs: new Set(config.excludeDirs),
     docsRootPrefix,
+    minDocs,
 
     statusOrder,
     validStatuses,

package/src/init.mjs

@@ -67,6 +67,55 @@ export const referenceFields = {
 };
 `;
 
+// A git repository cannot hold an empty directory, so scaffolding `docs/plans/`
+// and `docs/prompts/` and stopping there means both vanish for the next clone —
+// `dotmd init` produced three committable files and two directories that existed
+// only on the machine that ran it.
+//
+// plans/ gets a real sample rather than a keepfile: it is the one place a new user
+// benefits from seeing the frontmatter shape before running `dotmd new`. It is
+// written `status: planned` so it sits quietly in the pipeline instead of posing
+// as live work, and it says how to delete itself.
+//
+// prompts/ gets a keepfile instead, and cannot get a sample: the live queue is
+// gitignored by the rule this same command writes, and a committed prompt at
+// `status: pending` would be silently consumed by the next no-arg `dotmd use`.
+const SAMPLE_PLAN_NAME = 'example-plan.md';
+const samplePlan = (today) => `---
+type: plan
+status: planned
+created: ${today}
+updated: ${today}
+title: Example Plan
+summary: A scaffolded sample showing what a dotmd plan looks like — safe to delete.
+current_state: "Scaffolded by \`dotmd init\` as a shape reference. Nothing here is real work."
+next_step: "Delete this file, or edit it into your first real plan."
+---
+
+# Example Plan
+
+> A scaffolded sample showing what a dotmd plan looks like — safe to delete.
+
+## Problem
+
+\`dotmd init\` leaves this file behind so \`docs/plans/\` survives a clone (git cannot
+track an empty directory) and so the frontmatter above has something to point at.
+
+The fields that matter: \`status\` drives every listing, \`current_state\` and
+\`next_step\` are what \`dotmd briefing\` reads out, and \`updated\` drives staleness.
+Never hand-edit \`status:\` — \`dotmd set <status> <file>\` writes it, validates it
+against the type, and runs the lifecycle hooks.
+
+## Phases
+
+- [ ] Delete this file: \`dotmd archive docs/plans/${SAMPLE_PLAN_NAME}\`
+- [ ] Write a real one: \`dotmd new plan <name>\`
+
+## Version History
+
+- Scaffolded by \`dotmd init\`.
+`;
+
 const STARTER_INDEX = `# Docs
 
 <!-- GENERATED:dotmd:start -->
@@ -290,6 +339,21 @@ export async function runInit(cwd, config, opts = {}) {
       if (!dryRun) mkdirSync(subPath, { recursive: true });
       process.stdout.write(`  ${dryTag}${green('create')}  docs/${sub}/\n`);
     }
+
+    // Give the directory something git can carry — but only when it is genuinely
+    // empty. Re-running init over a populated tree must never drop a sample plan
+    // into someone's real estate.
+    const keeper = sub === 'plans'
+      ? { file: SAMPLE_PLAN_NAME, body: samplePlan(new Date().toISOString().slice(0, 10)) }
+      : { file: '.gitkeep', body: '' };
+    const keeperPath = path.join(subPath, keeper.file);
+    const dirIsEmpty = !existsSync(subPath) || readdirSync(subPath).length === 0;
+    if (existsSync(keeperPath)) {
+      process.stdout.write(`  ${dryTag}${dim('exists')}  docs/${sub}/${keeper.file}\n`);
+    } else if (dirIsEmpty || dryRun) {
+      if (!dryRun) writeFileSync(keeperPath, keeper.body, 'utf8');
+      process.stdout.write(`  ${dryTag}${green('create')}  docs/${sub}/${keeper.file}\n`);
+    }
   }
 
   if (existsSync(indexPath)) {
@@ -313,21 +377,38 @@ export async function runInit(cwd, config, opts = {}) {
     process.stdout.write(`                 export const root = [${subs.map(s => `'${s}'`).join(', ')}];\n`);
   }
 
-  // .gitignore: ensure .dotmd/ is ignored (session ownership records live there)
+  // .gitignore: two rules.
+  //
+  //   .dotmd/                 — session ownership records
+  //   <docs>/prompts/*.md     — the LIVE saved-prompt queue
+  //
+  // The second one is load-bearing. Saved prompts are session-local by design and
+  // the workflow docs say never to commit them, but nothing enforced that: a plain
+  // `git add -A` from any session swept the queue into the repo. Scoped with a
+  // single `*` so it stops at the directory — `prompts/archived/` is the committed
+  // historical record and must stay tracked. Anchored with a leading `/` so a
+  // `prompts/` directory elsewhere in the tree is unaffected.
   const gitignorePath = path.join(cwd, '.gitignore');
-  const ignoreLine = '.dotmd/';
+  const docsRel = path.relative(cwd, docsDir).split(path.sep).join('/');
+  const promptsIgnore = `/${docsRel ? `${docsRel}/` : ''}prompts/*.md`;
+  const ignoreRules = [
+    { line: '.dotmd/', accepts: (l) => l === '.dotmd/' || l === '.dotmd' },
+    { line: promptsIgnore, accepts: (l) => l === promptsIgnore || l === promptsIgnore.slice(1) },
+  ];
   if (existsSync(gitignorePath)) {
     const current = readFileSync(gitignorePath, 'utf8');
-    const has = current.split('\n').some(l => l.trim() === ignoreLine || l.trim() === '.dotmd');
-    if (!has) {
+    const present = new Set(current.split('\n').map(l => l.trim()));
+    const missing = ignoreRules.filter(r => ![...present].some(l => r.accepts(l)));
+    if (missing.length) {
       const sep = current.endsWith('\n') ? '' : '\n';
-      if (!dryRun) writeFileSync(gitignorePath, `${current}${sep}${ignoreLine}\n`, 'utf8');
-      process.stdout.write(`  ${dryTag}${green('update')}  .gitignore (+${ignoreLine})\n`);
+      const added = missing.map(r => `${r.line}\n`).join('');
+      if (!dryRun) writeFileSync(gitignorePath, `${current}${sep}${added}`, 'utf8');
+      process.stdout.write(`  ${dryTag}${green('update')}  .gitignore (+${missing.map(r => r.line).join(', ')})\n`);
     } else {
       process.stdout.write(`  ${dryTag}${dim('exists')}  .gitignore\n`);
     }
   } else {
-    if (!dryRun) writeFileSync(gitignorePath, `${ignoreLine}\n`, 'utf8');
+    if (!dryRun) writeFileSync(gitignorePath, ignoreRules.map(r => `${r.line}\n`).join(''), 'utf8');
     process.stdout.write(`  ${dryTag}${green('create')}  .gitignore\n`);
   }
 
@@ -397,6 +478,30 @@ export async function runInit(cwd, config, opts = {}) {
     }
   }
 
+  // Render the index against what we just scaffolded.
+  //
+  // `docs.md` ships a "no docs yet" placeholder, which stopped being true the
+  // moment this command also started writing a sample plan — so a fresh init
+  // committed an index that contradicted the tree beside it, and the user's first
+  // `dotmd check` opened with a stale-index warning. The config passed into
+  // runInit predates the file we just wrote, so re-resolve before rendering.
+  //
+  // Best-effort: a repo that scaffolds correctly but cannot render its index is
+  // still a successful init, and the next command regenerates it anyway.
+  if (!dryRun) {
+    try {
+      const { resolveConfig } = await import('./config.mjs');
+      const freshConfig = await resolveConfig(cwd);
+      if (freshConfig.indexPath) {
+        const { buildIndex } = await import('./index.mjs');
+        const { writeRenderedIndex } = await import('./index-file.mjs');
+        writeRenderedIndex(() => buildIndex(freshConfig, { fast: true }), freshConfig);
+      }
+    } catch {
+      // Leave the placeholder; `dotmd check` self-heals it on first run.
+    }
+  }
+
   process.stdout.write(`\nReady. A few starting points:\n`);
   process.stdout.write(`  dotmd new doc my-doc            # scaffold a reference doc\n`);
   process.stdout.write(`  dotmd new plan my-plan          # scaffold an execution plan\n`);

package/src/prompts.mjs

@@ -1,7 +1,7 @@
 import { readFileSync, existsSync } from 'node:fs';
 import path from 'node:path';
 import { extractFrontmatter, parseSimpleFrontmatter } from './frontmatter.mjs';
-import { asString, toRepoPath, die, resolveDocPath, isArchivedPath } from './util.mjs';
+import { asString, toRepoPath, die, resolveDocPath, resolveRefPath, isArchivedPath } from './util.mjs';
 import { buildIndex, resolveDocArg } from './index.mjs';
 import { runQuery } from './query.mjs';
 import { completePlanClaim, regenIndex, renderLifecycleMutation, runArchive, runStatus } from './lifecycle.mjs';
@@ -258,7 +258,7 @@ export async function consumePrompt(filePath, config, opts) {
 
   const planRef = asString(parsed.plan);
   let linkedClaim = null;
-  if (planRef) linkedClaim = prepareLinkedPromptClaim(planRef, config);
+  if (planRef) linkedClaim = prepareLinkedPromptClaim(planRef, config, path.dirname(filePath));
 
   if (dryRun) {
     const prefix = dim('[dry-run]');
@@ -353,8 +353,16 @@ export async function writeConsumedBody(body, archivedPath, write = null, linked
   }
 }
 
-function prepareLinkedPromptClaim(planRef, config) {
-  let planPath = resolveDocPath(planRef, config) ?? resolveDocArg(planRef, config, { dieOnMiss: false });
+// `planRef` is a reference written in the prompt's own frontmatter, so it obeys
+// the same convention every other ref field does: doc-relative first (baton's
+// `../plans/x.md` from `docs/prompts/`), repo-root-relative second. Resolving it
+// with `resolveDocPath` alone read only the repo-root form, so a doc-relative
+// link — the form nothing validates, since `plan` is not a `referenceFields`
+// entry — died as "missing" while pointing at a file that was plainly there.
+function prepareLinkedPromptClaim(planRef, config, promptDir) {
+  let planPath = resolveRefPath(planRef, promptDir, config.repoRoot)
+    ?? resolveDocPath(planRef, config)
+    ?? resolveDocArg(planRef, config, { dieOnMiss: false });
   if (!planPath || !existsSync(planPath)) die(`Linked plan is missing; prompt was not consumed: ${planRef}`);
   planPath = authorizeManagedSource(planPath, config, { kind: 'Prompt linked plan source' }).path;
   const raw = readFileSync(planPath, 'utf8');

package/src/query.mjs

@@ -396,14 +396,33 @@ function scanBodyForKeyword(doc, needle, config) {
   const lines = body.split('\n');
   const matches = [];
   for (let i = 0; i < lines.length && matches.length < MAX_BODY_MATCHES; i++) {
-    const text = lines[i].trim();
-    const at = text.toLowerCase().indexOf(needle);
+    const raw = lines[i].trim();
+    const at = raw.toLowerCase().indexOf(needle);
     if (at === -1) continue;
-    matches.push({ line: bodyLineOffset + i + 1, text: excerptAround(text, at, needle.length) });
+    const { text, at: shown } = displayableExcerptLine(raw, at, needle);
+    matches.push({ line: bodyLineOffset + i + 1, text: excerptAround(text, shown, needle.length) });
   }
   return matches;
 }
 
+// HTML comments are invisible when the markdown renders, so they are noise in an
+// excerpt — and dotmd's own conventions put them inline (a managed status token in
+// a hub table row reads as `| [x](x.md) | <!--s-->active<!--/s--> — next |`), which
+// is paid on every agent read of every search result.
+//
+// Matching still happens against the raw line, so a needle that only occurs INSIDE
+// a comment is never lost: if stripping would hide the match, the raw line is shown
+// instead. Whitespace is squeezed only on lines a strip actually touched.
+const HTML_COMMENT_RE = /<!--[\s\S]*?-->/g;
+
+export function displayableExcerptLine(raw, at, needle) {
+  if (!raw.includes('<!--')) return { text: raw, at };
+  const stripped = raw.replace(HTML_COMMENT_RE, '').replace(/[ \t]{2,}/g, ' ').trim();
+  const shown = stripped.toLowerCase().indexOf(needle);
+  if (shown === -1) return { text: raw, at };
+  return { text: stripped, at: shown };
+}
+
 // Window a long line around the match so the needle is always visible.
 function excerptAround(text, at, needleLen) {
   if (text.length <= EXCERPT_WIDTH) return text;

package/src/render.mjs

@@ -501,7 +501,8 @@ function _renderCheck(index, opts = {}) {
   if (index.errors.length > 0) {
     lines.push(red('Errors'));
     for (const issue of index.errors) {
-      lines.push(`- ${issue.path}: ${issue.message}`);
+      // Repo-level findings (e.g. the scan floor) carry no path.
+      lines.push(issue.path ? `- ${issue.path}: ${issue.message}` : `- ${issue.message}`);
     }
     lines.push('');
     const actions = renderManualFixes({ errors: index.errors, warnings: [] }).trimEnd();

package/src/validate.mjs

@@ -703,3 +703,34 @@ export function computeChecklistCompletionRate(checklist) {
   if (!checklist.total) return null;
   return Number((checklist.completed / checklist.total).toFixed(4));
 }
+
+// A floor under the scan surface.
+//
+// Every other check in this file asks "is this doc wrong?" — none of them can ask
+// "did we look at anything?". If the scan surface breaks (a root that stopped
+// resolving, a config edit that narrowed the tree, a rename that moved docs/ out
+// from under us), `dotmd check` reports zero errors, and that output is
+// byte-identical to a clean estate. A guard's whole failure mode is going quiet,
+// and this is the one that would go quiet silently.
+//
+// Off unless `minDocs` is configured — a floor is a claim about YOUR corpus size
+// and dotmd cannot guess it. Deliberately an error, not a warning: a warning exits
+// 0, which is the exact outcome this exists to prevent.
+export function applyScanFloor(index, config, { scoped = false } = {}) {
+  const floor = config?.minDocs;
+  if (!floor) return index;
+  // A path-scoped check (`dotmd check docs/plans/x.md`) is a deliberate subset, so
+  // the floor would fire on every single-file check. Not a corpus claim at all.
+  if (scoped) return index;
+  if (index.docs.length >= floor) return index;
+
+  index.errors.push({
+    path: null,
+    level: 'error',
+    message: `only ${index.docs.length} docs in the scan surface (expected at least ${floor}) — `
+      + 'the file list broke, so a pass here would mean nothing. Check `root`/`excludeDirs` in '
+      + 'your config, or lower `minDocs` if the corpus genuinely shrank.',
+    meta: { kind: 'scan-floor', found: index.docs.length, floor },
+  });
+  return index;
+}