dotmd-cli 0.15.0 → 0.16.0

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
@@ -401,6 +423,34 @@ dotmd lint                   # report issues
 dotmd lint --fix             # fix all issues
 ```
 
+### Manage Statuses
+
+```bash
+dotmd statuses                                              # table view, all types
+dotmd statuses --type plan                                  # one type
+dotmd statuses --json                                       # machine-readable
+
+dotmd statuses add paused --type plan --like blocked --quiet  # clone blocked, then quiet
+dotmd statuses set archived --type plan --no-quiet            # tweak a flag
+dotmd statuses remove obsolete --type plan                    # refuses if any docs use it
+
+dotmd statuses migrate plan                                 # array-form → rich-form
+```
+
+`--like <existing>` is the affordance for "kinda like X but…" — clones every
+flag from another status, then user flags override. Write commands print a flag
+diff and prompt for confirmation; pass `--yes` to skip the prompt or
+`--dry-run` to preview without writing. Edits are atomic: the rewrite lands in
+a sibling temp file, is validated by re-importing it and running
+`resolveConfig`, then renamed into place — a syntax error or new warning
+leaves the original untouched.
+
+**Lifecycle-override gotcha.** If your config has both rich-form `types` and an
+explicit `export const lifecycle = {...}`, the explicit lifecycle silently
+overrides per-status flags at runtime. `dotmd statuses` write commands refuse
+to write into that state and recommend deleting the explicit `lifecycle` block;
+pass `--ignore-lifecycle-override` to write anyway.
+
 ### Rename
 
 ```bash
@@ -412,8 +462,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)
@@ -59,6 +59,7 @@ Create & Export:
 
 Setup:
   init                              Create starter config + docs directory
+  statuses [list|add|set|remove|migrate]  Manage per-project status taxonomy
   watch [command]                   Re-run a command on file changes
   completions <shell>               Shell completion script (bash, zsh)
 
@@ -236,6 +237,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 +370,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.`,
 
@@ -431,6 +450,53 @@ Options:
   --list                 List all glossary terms
   --json                 Output as JSON`,
 
+  statuses: `dotmd statuses — manage per-project status taxonomy
+
+Subcommands:
+  list [--type <t>] [--json]            Default. Table view of every status × type with all flags.
+                                        --type accepts comma-separated types.
+  add <name> --type <t> [--like <e>] [flags...]
+                                        Add a new status. --like <existing> clones every flag from
+                                        another status; user flags override. Inserts before the
+                                        first terminal/archive status. Refuses if name already
+                                        exists or is invalid.
+  set <name> --type <t> <flags...>      Edit flags on an existing status. Refuses if status doesn't
+                                        exist. Flags overwrite individually.
+  remove <name> --type <t>              Delete a status entry. Refuses if any docs use the status
+                                        (lists offenders, suggests \`dotmd migrate\`). Warns if an
+                                        explicit lifecycle export references the name.
+  migrate <type>                        One-shot conversion of array-form types.<t>.statuses to
+                                        rich form, pulling in peer staleDays/context and per-status
+                                        requiresModule from taxonomy.moduleRequiredFor.
+
+Flags accepted by add/set:
+  --context <expanded|listed|counted>   Briefing layout bucket
+  --staleDays <n|null>                  Stale threshold; null = never stale
+  --requiresModule / --no-requiresModule
+  --terminal / --no-terminal            Closure state — excluded from active-work scope
+  --archive / --no-archive              Auto-move to archive dir on transition
+  --skipStale / --no-skipStale
+  --skipWarnings / --no-skipWarnings
+  --quiet / --no-quiet                  Sugar for skipStale + skipWarnings (explicit overrides win)
+
+Workflow flags:
+  --yes                                 Skip the confirmation prompt
+  --dry-run, -n                         Show the diff without writing
+  --ignore-lifecycle-override           Write even when an explicit \`lifecycle\` export
+                                        would silently mask the per-status flags
+
+Examples:
+  dotmd statuses                                                  # list everything
+  dotmd statuses add paused --type plan --like blocked --quiet
+  dotmd statuses set archived --type plan --no-quiet
+  dotmd statuses remove obsolete --type plan
+  dotmd statuses migrate plan                                     # array → rich
+
+Lifecycle-override gotcha: if your config has both rich-form types and an explicit
+\`export const lifecycle\`, the runtime ignores per-status flags. The CLI refuses
+to write in that case unless you pass --ignore-lifecycle-override; the recommended
+fix is to delete the explicit \`lifecycle\` block so flags take effect.`,
+
   bulk: `dotmd bulk archive <f1> <f2> ... — archive multiple files at once
 
 Archives each file: sets status to archived, moves to archive
@@ -551,6 +617,7 @@ async function main() {
   if (command === 'migrate') { const { runMigrate } = await import('../src/migrate.mjs'); runMigrate(restArgs, config, { dryRun }); return; }
   if (command === 'fix-refs') { const { runFixRefs } = await import('../src/fix-refs.mjs'); runFixRefs(restArgs, config, { dryRun }); return; }
   if (command === 'doctor') { const { runDoctor } = await import('../src/doctor.mjs'); runDoctor(restArgs, config, { dryRun }); return; }
+  if (command === 'statuses') { const { runStatuses } = await import('../src/statuses.mjs'); await runStatuses(restArgs, config, { dryRun, type: typeArg }); return; }
 
   // All remaining commands need the index + render modules
   const { buildIndex } = await import('../src/index.mjs');
@@ -801,7 +868,7 @@ async function main() {
     'focus', 'query', 'plans', 'stale', 'actionable', 'index', 'pickup', 'finish', 'status', 'archive', 'bulk', 'touch', 'doctor',
     'unblocks', 'health', 'glossary',
     'fix-refs', 'lint', 'rename', 'migrate', 'notion', 'export', 'summary',
-    'watch', 'diff', 'new', 'init', 'completions',
+    'watch', 'diff', 'new', 'init', 'completions', 'statuses',
   ];
   const matches = allCommands
     .map(c => ({ cmd: c, dist: levenshtein(command, c) }))

package/dotmd.config.example.mjs

@@ -103,13 +103,20 @@ export const statuses = {
 };
 
 // Lifecycle behavior — which statuses trigger special handling.
-// When using rich status definitions, these are derived from per-status flags.
-export const lifecycle = {
-  archiveStatuses: ['archived'],      // auto-move to archiveDir on transition
-  skipStaleFor: ['archived'],         // skip staleness checks
-  skipWarningsFor: ['archived'],      // skip validation warnings (summary, etc.)
-  terminalStatuses: ['archived', 'deprecated', 'reference', 'done'],  // skip current_state/next_step warnings, exclude from stats scope
-};
+//
+// IMPORTANT: only enable this block if you're using ARRAY-form types (above) or
+// no `types` definition. With rich-form types, the runtime derives these from
+// per-status `terminal` / `archive` / `skipStale` / `skipWarnings` / `quiet`
+// flags. An explicit `lifecycle` export sitting alongside rich-form types will
+// SILENTLY OVERRIDE the per-status flags — `dotmd statuses` will warn you
+// before writing into a config in that state.
+//
+// export const lifecycle = {
+//   archiveStatuses: ['archived'],      // auto-move to archiveDir on transition
+//   skipStaleFor: ['archived'],         // skip staleness checks
+//   skipWarningsFor: ['archived'],      // skip validation warnings (summary, etc.)
+//   terminalStatuses: ['archived', 'deprecated', 'reference'],  // skip current_state/next_step warnings, exclude from stats scope
+// };
 
 // Taxonomy validation — set fields to null to skip validation.
 // moduleRequiredFor is derived from requiresModule when using rich status definitions.

package/package.json

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