dotmd-cli 0.14.3 → 0.14.4

package/README.md

@@ -430,27 +430,78 @@ When `dotmd init` runs in a directory with existing `.md` files, it scans them a
 
 ## Configuration
 
-Create `dotmd.config.mjs` at your project root (or run `dotmd init`):
+Create `dotmd.config.mjs` at your project root (or run `dotmd init`).
+
+### Rich status definitions (recommended)
+
+Define each status as an object that co-locates all behavioral properties. Adding a new status is one line in one place — no need to update separate `lifecycle`, `staleDays`, `context`, or `taxonomy` sections.
+
+```js
+export const root = 'docs/plans';
+export const archiveDir = 'archived';
+
+export const types = {
+  plan: {
+    statuses: {
+      'active':   { context: 'expanded', staleDays: 14, requiresModule: true },
+      'planned':  { context: 'listed', staleDays: 30, requiresModule: true },
+      'blocked':  { context: 'listed', staleDays: 30, skipStale: true },
+      'archived': { context: 'counted', archive: true, terminal: true, skipStale: true, skipWarnings: true },
+    },
+  },
+};
+```
+
+**Status properties:**
+
+| Property | Type | Default | Effect |
+|---|---|---|---|
+| `context` | `'expanded'` \| `'listed'` \| `'counted'` | `'counted'` | Display mode in `dotmd context` |
+| `staleDays` | `number` \| `null` | `null` | Days before doc is stale (`null` = never) |
+| `requiresModule` | `boolean` | `false` | Require `module` in frontmatter |
+| `terminal` | `boolean` | `false` | Skip `current_state`/`next_step` warnings |
+| `archive` | `boolean` | `false` | Auto-move to `archiveDir` on transition |
+| `skipStale` | `boolean` | `false` | Exempt from stale checks |
+| `skipWarnings` | `boolean` | `false` | Exempt from validation warnings |
+
+Object key order determines display order. The config resolver derives `statuses.order`, `lifecycle.*`, `taxonomy.moduleRequiredFor`, and `context.*` from these definitions. Explicit global sections still win when provided.
+
+### Array form (also supported)
+
+The traditional array form remains fully backwards compatible:
 
 ```js
-export const root = 'docs/plans';         // string or array of paths
-export const archiveDir = 'archived';     // subdirectory for archived docs
+export const types = {
+  plan: {
+    statuses: ['active', 'planned', 'blocked', 'archived'],
+    context: { expanded: ['active'], listed: ['planned', 'blocked'], counted: ['archived'] },
+    staleDays: { active: 14, planned: 30, blocked: 30 },
+  },
+};
 
+// When using array form, define behavior in separate sections:
 export const statuses = {
-  order: ['draft', 'active', 'approved', 'superseded', 'archived'],
-  staleDays: { draft: 7, active: 14, approved: 30 },
+  order: ['active', 'planned', 'blocked', 'archived'],
+  staleDays: { active: 14, planned: 30, blocked: 30 },
 };
 
 export const lifecycle = {
-  archiveStatuses: ['archived'],          // auto-move to archiveDir
+  archiveStatuses: ['archived'],
   skipStaleFor: ['archived'],
   skipWarningsFor: ['archived'],
-  terminalStatuses: ['archived', 'deprecated', 'reference', 'done'],
+  terminalStatuses: ['archived'],
+};
+
+export const taxonomy = {
+  moduleRequiredFor: ['active', 'planned', 'blocked'],
 };
+```
 
+### Other config
+
+```js
 export const taxonomy = {
   surfaces: ['web', 'ios', 'backend', 'api', 'platform'],
-  moduleRequiredFor: ['active', 'ready', 'planned', 'blocked'],
 };
 
 export const referenceFields = {
@@ -465,7 +516,7 @@ export const index = {
 };
 ```
 
-All exports are optional. Additional options: `types`, `context`, `display`, `presets`, `templates`, `excludeDirs`, `notion`. See [`dotmd.config.example.mjs`](dotmd.config.example.mjs) for the full reference.
+All exports are optional. Additional options: `context`, `display`, `presets`, `templates`, `excludeDirs`, `notion`. See [`dotmd.config.example.mjs`](dotmd.config.example.mjs) for the full reference.
 
 Config discovery walks up from cwd looking for `dotmd.config.mjs` or `.dotmd.config.mjs`.
 

package/dotmd.config.example.mjs

@@ -13,27 +13,58 @@ export const archiveDir = 'archived';
 // Directories to skip when scanning
 export const excludeDirs = ['evidence'];
 
-// Document types — each type has its own status vocabulary and context layout
+// Document types — each type has its own status vocabulary and context layout.
 // Defaults: plan, doc, research. Override to customize statuses per type.
+//
+// Statuses can be defined as an array (names only) or as an object (rich form).
+// The object form co-locates all behavioral properties with each status,
+// eliminating the need for separate lifecycle, staleDays, context, and taxonomy sections.
+
+// ─── Rich status definitions (recommended) ──────────────────────────────────
+// Each status is an object with optional properties:
+//   context:        'expanded' | 'listed' | 'counted' (default: 'counted')
+//   staleDays:      number | null — stale threshold (default: null = never stale)
+//   requiresModule: boolean — require `module` frontmatter (default: false)
+//   terminal:       boolean — skip current_state/next_step warnings (default: false)
+//   archive:        boolean — auto-move to archiveDir on transition (default: false)
+//   skipStale:      boolean — exempt from stale checks (default: false)
+//   skipWarnings:   boolean — exempt from validation warnings (default: false)
+//
 // export const types = {
 //   plan: {
-//     statuses: ['in-session', 'active', 'planned', 'blocked', 'done', 'archived'],
-//     context: { expanded: ['in-session', 'active'], listed: ['planned', 'blocked'], counted: ['done', 'archived'] },
-//     staleDays: { 'in-session': 1, active: 14, planned: 30, blocked: 30 },
+//     statuses: {
+//       'in-session': { context: 'expanded', staleDays: 1, requiresModule: true },
+//       'active':     { context: 'expanded', staleDays: 14, requiresModule: true },
+//       'planned':    { context: 'listed', staleDays: 30, requiresModule: true },
+//       'blocked':    { context: 'listed', staleDays: 30, requiresModule: true, skipStale: true },
+//       'done':       { context: 'counted', terminal: true, skipStale: true, skipWarnings: true },
+//       'archived':   { context: 'counted', archive: true, terminal: true, skipStale: true, skipWarnings: true },
+//     },
 //   },
 //   doc: {
-//     statuses: ['draft', 'active', 'review', 'reference', 'deprecated', 'archived'],
-//     context: { expanded: ['active'], listed: ['draft', 'review'], counted: ['reference', 'deprecated', 'archived'] },
-//     staleDays: { draft: 30, active: 14, review: 14 },
+//     statuses: {
+//       'draft':      { context: 'listed', staleDays: 30 },
+//       'active':     { context: 'expanded', staleDays: 14 },
+//       'review':     { context: 'listed', staleDays: 14 },
+//       'reference':  { context: 'counted', skipStale: true },
+//       'deprecated': { context: 'counted', terminal: true, skipStale: true },
+//       'archived':   { context: 'counted', archive: true, terminal: true, skipStale: true, skipWarnings: true },
+//     },
 //   },
-//   research: {
-//     statuses: ['active', 'reference', 'archived'],
-//     context: { expanded: ['active'], listed: [], counted: ['reference', 'archived'] },
-//     staleDays: { active: 30 },
+// };
+
+// ─── Array form (also supported) ────────────────────────────────────────────
+// When using array form, define behavior in separate statuses/lifecycle/taxonomy sections.
+// export const types = {
+//   plan: {
+//     statuses: ['in-session', 'active', 'planned', 'blocked', 'done', 'archived'],
+//     context: { expanded: ['in-session', 'active'], listed: ['planned', 'blocked'], counted: ['done', 'archived'] },
+//     staleDays: { 'in-session': 1, active: 14, planned: 30, blocked: 30 },
 //   },
 // };
 
 // Status workflow — fallback for docs without a type field. Order determines display grouping.
+// When using rich status definitions, statuses.order and staleDays are derived automatically.
 export const statuses = {
   order: ['active', 'ready', 'planned', 'research', 'blocked', 'reference', 'archived'],
   // Additional statuses valid only in specific roots (merged with order)
@@ -52,7 +83,8 @@ export const statuses = {
   },
 };
 
-// Lifecycle behavior — which statuses trigger special handling
+// 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
@@ -60,7 +92,8 @@ export const lifecycle = {
   terminalStatuses: ['archived', 'deprecated', 'reference', 'done'],  // skip current_state/next_step warnings, exclude from stats scope
 };
 
-// Taxonomy validation — set fields to null to skip validation
+// Taxonomy validation — set fields to null to skip validation.
+// moduleRequiredFor is derived from requiresModule when using rich status definitions.
 export const taxonomy = {
   surfaces: ['web', 'ios', 'android', 'mobile', 'full-stack', 'frontend', 'backend', 'api', 'docs', 'ops', 'platform', 'infra', 'design'],
   moduleRequiredFor: ['active', 'ready', 'planned', 'blocked'],

package/package.json

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