dotmd-cli 0.48.0 → 0.48.2

package/package.json

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

package/src/config.mjs

@@ -66,6 +66,11 @@ const DEFAULTS = {
 
   taxonomy: {
     surfaces: null,
+    // modules: when null (default), the project doesn't enumerate product
+    // modules — the modules-required validator silently skips. When set to
+    // an array, modules are taxonomy-enforced AND moduleRequiredFor activates.
+    // Mirrors the long-standing semantics of `taxonomy.surfaces`.
+    modules: null,
     moduleRequiredFor: ['partial', 'paused', 'awaiting', 'queued-after'],
   },
 
@@ -444,6 +449,9 @@ export async function resolveConfig(cwd, explicitConfigPath) {
   const validSurfaces = config.taxonomy.surfaces
     ? new Set(config.taxonomy.surfaces)
     : null;
+  const validModules = config.taxonomy.modules
+    ? new Set(config.taxonomy.modules)
+    : null;
   const moduleRequiredStatuses = new Set(config.taxonomy.moduleRequiredFor);
 
   const indexPath = config.index?.path
@@ -497,6 +505,7 @@ export async function resolveConfig(cwd, explicitConfigPath) {
     lifecycle: { archiveStatuses, skipStaleFor, skipWarningsFor, terminalStatuses, filedStatuses },
 
     validSurfaces,
+    validModules,
     moduleRequiredStatuses,
 
     indexPath,

package/src/new.mjs

@@ -22,6 +22,23 @@ function surfacesScaffold(ctx) {
   return 'surfaces:';
 }
 
+// Module-taxonomy parallel of surfacesScaffold. When `taxonomy.modules` is set,
+// scaffold lists valid values + a `- none` placeholder so the validator's
+// modules-required check passes by default and the author can swap to a real
+// module from the listed taxonomy. When unset, the project doesn't enumerate
+// modules — drop the placeholder entirely so new plans aren't sprinkled with a
+// meaningless sentinel.
+function modulesScaffold(ctx, kind /* 'doc' | 'plan' */) {
+  const valid = ctx?.validModules;
+  if (Array.isArray(valid) && valid.length > 0) {
+    const comment = kind === 'plan'
+      ? `# modules — valid: ${valid.join(', ')} (or \`none\` for tooling/infra plans)`
+      : `# modules — valid: ${valid.join(', ')} (or \`none\` for platform/infra docs)`;
+    return `${comment}\nmodules:\n  - none`;
+  }
+  return 'modules:';
+}
+
 const BUILTIN_TEMPLATES = {
   doc: {
     description: 'Reference doc, design note, module overview — build-up shape lite',
@@ -35,9 +52,7 @@ const BUILTIN_TEMPLATES = {
       `status: ${s}`,
       `created: ${d}`,
       `updated: ${d}`,
-      '# modules — real module name(s), or `none` for platform/infra docs',
-      'modules:',
-      '  - none',
+      modulesScaffold(ctx, 'doc'),
       surfacesScaffold(ctx),
       'domain:',
       'audience: internal',
@@ -75,9 +90,7 @@ ${ctx?.bodyInput?.trim() ?? ''}
       `created: ${d}`,
       `updated: ${d}`,
       surfacesScaffold(ctx),
-      '# modules — real module name(s), or `none` for tooling/infra plans',
-      'modules:',
-      '  - none',
+      modulesScaffold(ctx, 'plan'),
       'domain:',
       'audience: internal',
       'parent_plan:',
@@ -477,7 +490,8 @@ export async function runNew(argv, config, opts = {}) {
   // Generate content
   let content;
   const validSurfaces = config.raw?.taxonomy?.surfaces ?? (config.validSurfaces ? [...config.validSurfaces] : null);
-  const tmplCtx = { status, title: docTitle, today, bodyInput, validSurfaces };
+  const validModules = config.raw?.taxonomy?.modules ?? (config.validModules ? [...config.validModules] : null);
+  const tmplCtx = { status, title: docTitle, today, bodyInput, validSurfaces, validModules };
   if (typeof template === 'function') {
     content = template(name, tmplCtx);
   } else {

package/src/runlist.mjs

@@ -1,4 +1,4 @@
-import { readFileSync } from 'node:fs';
+import { existsSync, readFileSync } from 'node:fs';
 import path from 'node:path';
 import { extractFrontmatter, parseSimpleFrontmatter } from './frontmatter.mjs';
 import {
@@ -14,6 +14,34 @@ import { bold, cyan, dim, green, red, yellow } from './color.mjs';
 
 const PICKUPABLE_STATUSES = new Set(['active', 'planned', 'in-session']);
 
+// resolveDocPath only tries cwd / repo-root / docs-root joins, so bare plan
+// slugs like `clear-the-deck` don't resolve when plans live under
+// `<docsRoot>/plans/`. The other commands (`dotmd set <slug>`, `dotmd plans`)
+// take slugs — runlist should too. Try the direct resolve first, then
+// fall back to `<root>/plans/<slug>.md` under each configured doc root.
+function resolveHubInput(input, config) {
+  const direct = resolveDocPath(input, config);
+  if (direct) return direct;
+
+  if (!input.endsWith('.md')) {
+    const withExt = resolveDocPath(input + '.md', config);
+    if (withExt) return withExt;
+  }
+
+  const slugFile = input.endsWith('.md') ? input : `${input}.md`;
+  const roots = config.docsRoots || (config.docsRoot ? [config.docsRoot] : []);
+  for (const root of roots) {
+    const candidate = path.join(root, 'plans', slugFile);
+    if (existsSync(candidate)) return candidate;
+    // Multi-root layouts may already have a `plans` root, so also try the
+    // root itself.
+    const rootCandidate = path.join(root, slugFile);
+    if (existsSync(rootCandidate)) return rootCandidate;
+  }
+
+  return null;
+}
+
 // Read a hub plan's `runlist:` and resolve each entry to a repo-relative path
 // plus its current status. Missing files are reported with `missing: true`;
 // callers decide how to render them. Pure: no IO beyond file reads.
@@ -112,7 +140,7 @@ export async function runRunlist(argv, config, opts = {}) {
       : 'Usage: dotmd runlist <hub-plan>');
   }
 
-  const hubAbs = resolveDocPath(hubInput, config);
+  const hubAbs = resolveHubInput(hubInput, config);
   if (!hubAbs) die(`Hub plan not found: ${hubInput}`);
   const hubRepoPath = toRepoPath(hubAbs, config.repoRoot);
 

package/src/validate.mjs

@@ -117,8 +117,13 @@ export function validateDoc(doc, frontmatter, headingTitle, config) {
     doc.errors.push({ path: doc.path, level: 'error', message: '`modules` must be a YAML list when present.' });
   }
 
-  if (config.moduleRequiredStatuses.has(doc.status) && !doc.modules?.length) {
-    doc.errors.push({ path: doc.path, level: 'error', message: '`modules` is required for active/ready/planned/blocked docs; use a real module, `platform`, or `none`.' });
+  // modules-required gate: only fires when the project has actively declared
+  // a module taxonomy (`taxonomy.modules` is an array). Repos with no product
+  // modules (CLIs, dev tooling, single-domain apps) shouldn't be forced to
+  // sprinkle `modules: [none]` on every plan as a sentinel. Mirrors the
+  // long-standing `taxonomy.surfaces` opt-in semantics.
+  if (config.validModules && config.moduleRequiredStatuses.has(doc.status) && !doc.modules?.length) {
+    doc.errors.push({ path: doc.path, level: 'error', message: '`modules` is required for this status; declare a real module from `taxonomy.modules`, or `none` as the explicit no-module sentinel.' });
   }
 
   if (config.validSurfaces && !config.lifecycle.skipWarningsFor.has(doc.status)) {