dotmd-cli 0.15.0 → 0.15.1

package/README.md

@@ -244,8 +244,30 @@ Shows: status counts, staleness, errors/warnings, freshness (today/week/month),
 ```bash
 dotmd doctor                 # fix refs → lint → sync git dates → regen index
 dotmd doctor --dry-run       # preview all changes
+dotmd doctor --statuses      # detect overloaded status buckets (read-only)
+dotmd doctor --statuses --json  # machine-readable suggestions
 ```
 
+`--statuses` is a read-only diagnostic. It scans each status with at least
+10 plans and groups their `current_state` / `next_step` text against cue
+keywords for `partial`, `paused`, `awaiting`, `queued-after`, and `blocked`.
+When a single bucket lands plans in two or more cue groups (each above 15%
+of the bucket), it prints a split suggestion:
+
+```
+47 plan/backlog plans cluster across 4 patterns — consider splitting:
+  ~22 → partial       (cues: "shipped", "landed", "tail", "deferred")
+  ~15 → paused        (cues: "paused", "on hold", "set aside")
+  ~ 6 → queued-after  (cues: "after", "once", "depends on", "waiting on <plan>")
+  ~ 4 →               (kept in backlog — no clear pattern match)
+
+Heuristic — verify before migrating.
+```
+
+The heuristic is intentionally conservative: small buckets are skipped, plans
+that match no cues stay in the original bucket, and the output is always a
+suggestion — never a verdict.
+
 ### Graph
 
 ```bash
@@ -412,8 +434,20 @@ dotmd rename old-name.md new-name        # renames + updates refs
 ```bash
 dotmd migrate status research scoping       # rename a status (e.g. for the 0.15 default-vocab change)
 dotmd migrate module auth identity           # rename a module
+
+# Per-file form: split one overloaded status into several distinct ones.
+# Only the listed files are rewritten; every other doc with the old value is left alone.
+dotmd migrate status backlog paused docs/plans/foo.md docs/plans/bar.md
+dotmd migrate status backlog partial docs/plans/payments-future.md  # one at a time also works
 ```
 
+With no file args, `migrate` rewrites every doc whose field matches
+`<old-value>` (whole-bucket rename). Pass file args to scope the
+rewrite — useful when one status has been doing several jobs and you
+want to split it across the new vocabulary. File args match the same
+way as `bulk archive`: exact path first, then substring fallback
+against full path or basename.
+
 ### Preset Aliases
 
 Built-in presets: `plans`, `stale`, `actionable`. Add your own in config:

package/bin/dotmd.mjs

@@ -49,7 +49,7 @@ Lifecycle:
   touch <file>                      Bump updated date
   touch --git                       Bulk-sync dates from git history
   rename <old> <new>                Rename doc and update all references
-  migrate <field> <old> <new>       Batch update a frontmatter field value
+  migrate <field> <old> <new> [f...]Batch update a frontmatter field value (optional file filter)
 
 Create & Export:
   new <name> [--template <t>]       Create doc from template (plan, adr, rfc, audit, design)
@@ -236,6 +236,16 @@ Options:
 Runs in sequence: fix broken references, lint --fix, sync dates from
 git, regenerate index, then show remaining issues.
 
+Modes:
+  (default)              Auto-fix pass (writes by default; honors --dry-run)
+  --statuses             Read-only diagnostic: detect overloaded status
+                         buckets where one status holds plans pursuing
+                         multiple distinct unstuck-actions. Suggests how
+                         a bucket might split (e.g. backlog → partial /
+                         paused / queued-after). Heuristic only — verify
+                         before migrating.
+  --statuses --json      Machine-readable suggestion shape for tooling.
+
 Use --dry-run (-n) to preview all changes without writing anything.`,
 
   'fix-refs': `dotmd fix-refs — auto-fix broken reference paths
@@ -359,14 +369,22 @@ in other docs that point to the old filename.
 Body markdown links are warned about but not auto-fixed.
 Use --dry-run (-n) to preview changes without writing anything.`,
 
-  migrate: `dotmd migrate <field> <old-value> <new-value> — batch update a frontmatter field
+  migrate: `dotmd migrate <field> <old-value> <new-value> [files...] — batch update a frontmatter field
 
 Finds all docs where the given field equals old-value and updates it
-to new-value.
+to new-value. With no file args, every matching doc in the project is
+rewritten (whole-bucket rename).
+
+Pass one or more file args to scope the rewrite — only those files
+are considered. This is how you split one overloaded status into
+several distinct ones (e.g. moving some \`backlog\` plans to
+\`paused\` and others to \`partial\`). File args use the same matching
+as \`bulk archive\`: exact path, then substring fallback.
 
 Examples:
   dotmd migrate status research scoping
   dotmd migrate module auth identity
+  dotmd migrate status backlog paused docs/plans/foo.md docs/plans/bar.md
 
 Use --dry-run (-n) to preview changes without writing anything.`,
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dotmd-cli",
-  "version": "0.15.0",
+  "version": "0.15.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/doctor.mjs

@@ -7,7 +7,41 @@ import { renderCheck } from './render.mjs';
 import { bold, dim, green, yellow } from './color.mjs';
 import { scaffoldClaudeCommands } from './claude-commands.mjs';
 
+// Tunable thresholds for `dotmd doctor --statuses` conflation detection.
+// MIN_BUCKET_SIZE: only flag buckets with at least this many docs (small buckets aren't worth nagging).
+// CUE_FLOOR_PCT: a target cue must claim at least this fraction of the bucket to be suggested.
+// A bucket is overloaded only when ≥2 distinct target cues each clear the floor.
+const MIN_BUCKET_SIZE = 10;
+const CUE_FLOOR_PCT = 0.15;
+
+// Cue patterns map keyword groups to candidate target statuses.
+// A doc is scored by counting regex hits in its current_state + next_step text;
+// the highest-scoring cue (if any) becomes its suggested bucket. Ties broken by
+// the iteration order below (deterministic). Patterns are intentionally simple
+// and tunable — false positives are fine, false confidence is not.
+const CUE_PATTERNS = {
+  partial: /\b(shipped|landed|merged|complete|tail|deferred|follow[- ]?up|left[- ]?over|remaining)\b/i,
+  paused: /\b(paused?|on hold|set aside|park(?:ed|ing)?|shelv(?:ed|ing)?|frozen|hibernat)/i,
+  'queued-after': /\b(after|once|when|depends on|behind|sequenced|wait(?:ing)? for [a-z\- ]+ to (?:ship|land|merge))\b/i,
+  awaiting: /\b(awaiting|need(?:s)? (?:input|decision|approval|sign[- ]?off)|pending (?:review|approval)|asked? (?:for|about))\b/i,
+  blocked: /\b(hardware|vendor|third[- ]?party|firmware|delivery|arrival|rollout)\b/i,
+};
+
+// Human-readable cue lists for the suggestion table.
+const CUE_LABELS = {
+  partial: '"shipped", "landed", "tail", "deferred"',
+  paused: '"paused", "on hold", "set aside"',
+  'queued-after': '"after", "once", "depends on", "waiting on <plan>"',
+  awaiting: '"awaiting", "needs decision", "pending review"',
+  blocked: '"hardware", "vendor", "third-party", "rollout"',
+};
+
 export function runDoctor(argv, config, opts = {}) {
+  if (argv.includes('--statuses')) {
+    runDoctorStatuses(config, { json: argv.includes('--json') });
+    return;
+  }
+
   const { dryRun } = opts;
   process.stdout.write(bold('dotmd doctor') + '\n\n');
 
@@ -53,3 +87,117 @@ export function runDoctor(argv, config, opts = {}) {
   const freshIndex = buildIndex(config);
   process.stdout.write(renderCheck(freshIndex, config));
 }
+
+export function analyzeStatusBuckets(docs) {
+  const buckets = new Map();
+  for (const doc of docs) {
+    if (!doc.status) continue;
+    const key = `${doc.type ?? 'unknown'}::${doc.status}`;
+    if (!buckets.has(key)) {
+      buckets.set(key, { type: doc.type ?? null, status: doc.status, docs: [] });
+    }
+    buckets.get(key).docs.push(doc);
+  }
+
+  const suggestions = [];
+
+  for (const bucket of buckets.values()) {
+    if (bucket.docs.length < MIN_BUCKET_SIZE) continue;
+    const floor = Math.max(1, Math.ceil(bucket.docs.length * CUE_FLOOR_PCT));
+
+    const targetCounts = {};
+    let unmatchedCount = 0;
+
+    for (const doc of bucket.docs) {
+      const text = `${doc.currentState ?? ''}\n${doc.nextStep ?? ''}`;
+      let bestCue = null;
+      let bestScore = 0;
+
+      for (const [cue, pattern] of Object.entries(CUE_PATTERNS)) {
+        if (cue === bucket.status) continue;
+        const globalPat = new RegExp(pattern.source, pattern.flags.includes('g') ? pattern.flags : pattern.flags + 'g');
+        const matches = text.match(globalPat);
+        const score = matches ? matches.length : 0;
+        if (score > bestScore) {
+          bestScore = score;
+          bestCue = cue;
+        }
+      }
+
+      if (bestCue == null) {
+        unmatchedCount++;
+      } else {
+        targetCounts[bestCue] = (targetCounts[bestCue] ?? 0) + 1;
+      }
+    }
+
+    const aboveFloor = Object.entries(targetCounts)
+      .filter(([, n]) => n >= floor)
+      .sort((a, b) => b[1] - a[1] || a[0].localeCompare(b[0]));
+
+    if (aboveFloor.length < 2) continue;
+
+    const splitCount = aboveFloor.reduce((s, [, n]) => s + n, 0);
+    const kept = bucket.docs.length - splitCount;
+
+    suggestions.push({
+      type: bucket.type,
+      status: bucket.status,
+      total: bucket.docs.length,
+      splits: aboveFloor.map(([target, count]) => ({
+        target,
+        count,
+        cues: CUE_LABELS[target] ?? '',
+      })),
+      kept,
+    });
+  }
+
+  suggestions.sort((a, b) => {
+    if ((a.type ?? '') !== (b.type ?? '')) return (a.type ?? '').localeCompare(b.type ?? '');
+    return a.status.localeCompare(b.status);
+  });
+
+  return suggestions;
+}
+
+function runDoctorStatuses(config, { json = false } = {}) {
+  const index = buildIndex(config);
+  const suggestions = analyzeStatusBuckets(index.docs);
+
+  if (json) {
+    process.stdout.write(JSON.stringify({
+      thresholds: { minBucketSize: MIN_BUCKET_SIZE, cueFloorPct: CUE_FLOOR_PCT },
+      suggestions,
+    }, null, 2) + '\n');
+    return;
+  }
+
+  process.stdout.write(bold('dotmd doctor --statuses') + '\n\n');
+
+  if (suggestions.length === 0) {
+    process.stdout.write(`No overloaded status buckets detected (min bucket size: ${MIN_BUCKET_SIZE}).\n`);
+    return;
+  }
+
+  for (const s of suggestions) {
+    const typeLabel = s.type ? `${s.type}/` : '';
+    const patternCount = s.splits.length + (s.kept > 0 ? 1 : 0);
+    process.stdout.write(
+      bold(`${s.total} ${typeLabel}${s.status} plans cluster across ${patternCount} patterns — consider splitting:`) + '\n'
+    );
+
+    const targetWidth = Math.max(...s.splits.map(x => x.target.length), 'kept'.length);
+    for (const split of s.splits) {
+      const target = green(split.target.padEnd(targetWidth));
+      process.stdout.write(`  ~${String(split.count).padStart(3)} → ${target}  (cues: ${split.cues})\n`);
+    }
+    if (s.kept > 0) {
+      const tail = dim(`(kept in ${s.status} — no clear pattern match)`);
+      process.stdout.write(`  ~${String(s.kept).padStart(3)} → ${' '.repeat(targetWidth)}  ${tail}\n`);
+    }
+    process.stdout.write('\n');
+  }
+
+  process.stdout.write(yellow('Heuristic — verify before migrating.') + '\n');
+}

package/src/migrate.mjs

@@ -1,6 +1,7 @@
 import { readFileSync } from 'node:fs';
+import path from 'node:path';
 import { extractFrontmatter, parseSimpleFrontmatter } from './frontmatter.mjs';
-import { asString, toRepoPath, die } from './util.mjs';
+import { asString, toRepoPath, resolveDocPath, die } from './util.mjs';
 import { collectDocFiles } from './index.mjs';
 import { updateFrontmatter } from './lifecycle.mjs';
 import { bold, green, dim } from './color.mjs';
@@ -18,15 +19,42 @@ export function runMigrate(argv, config, opts = {}) {
   const field = positional[0];
   const oldValue = positional[1];
   const newValue = positional[2];
+  const fileArgs = positional.slice(3);
 
   if (!field || !oldValue || !newValue) {
-    die('Usage: dotmd migrate <field> <old-value> <new-value>');
+    die('Usage: dotmd migrate <field> <old-value> <new-value> [files...]');
   }
 
   const allFiles = collectDocFiles(config);
+
+  // When file args are passed, resolve them to a filter set (mirrors runBulkArchive).
+  let fileFilter = null;
+  if (fileArgs.length > 0) {
+    const matched = [];
+    const unresolved = [];
+    for (const input of fileArgs) {
+      const filePath = resolveDocPath(input, config);
+      if (filePath) {
+        matched.push(filePath);
+        continue;
+      }
+      const hits = allFiles.filter(f => f.includes(input) || path.basename(f).includes(input));
+      if (hits.length === 0) {
+        unresolved.push(input);
+      } else {
+        matched.push(...hits);
+      }
+    }
+    if (unresolved.length > 0) {
+      die(`No matching file(s) for: ${unresolved.join(', ')}`);
+    }
+    fileFilter = new Set(matched);
+  }
+
   const matches = [];
 
   for (const filePath of allFiles) {
+    if (fileFilter && !fileFilter.has(filePath)) continue;
     const raw = readFileSync(filePath, 'utf8');
     const { frontmatter } = extractFrontmatter(raw);
     if (!frontmatter) continue;
@@ -38,7 +66,8 @@ export function runMigrate(argv, config, opts = {}) {
   }
 
   if (matches.length === 0) {
-    process.stdout.write(`No docs found with ${bold(field)}: ${oldValue}\n`);
+    const scope = fileFilter ? ` in the specified file(s)` : '';
+    process.stdout.write(`No docs found with ${bold(field)}: ${oldValue}${scope}\n`);
     return;
   }