dotmd-cli 0.57.0 → 0.59.0

package/README.md

@@ -23,6 +23,8 @@ If you drive dotmd from Claude Code, install the **dotmd plugin**. It teaches ev
 
 The plugin bundles the hooks (`SessionStart`/`SubagentStart` priming, a `PreToolUse` guard) and a canonical workflow skill, so guidance travels to **every** repo automatically — no per-repo setup. It calls the `dotmd` CLI, so keep `npm install -g dotmd-cli` installed too. (Source: `plugins/dotmd/` in this repo.)
 
+> **Upgrading to 0.57.0+:** per-repo `.claude/commands/{plans,docs,baton}.md` scaffolding is retired — that guidance now ships via the plugin's workflow skill and `/plans`, `/docs`, `/prompts`, `/baton` commands. On the next `dotmd hud` (SessionStart), dotmd removes those generated files (only banner-stamped `<!-- dotmd-generated -->` ones — your hand-authored command files are never touched). If you'd committed them, you'll see deletions to commit — that's expected. Run `claude plugin update dotmd@dotmd` to pick up `/baton`.
+
 ## Quick Start
 
 ```bash
@@ -803,6 +805,11 @@ export const lifecycle = {
   skipStaleFor: ['archived'],
   skipWarningsFor: ['archived'],
   terminalStatuses: ['archived'],
+  // Types that archive into their own <typeDir>/<archiveDir> (e.g.
+  // docs/prompts/archived/) instead of the shared <root>/<archiveDir>.
+  // Defaults to ['prompt'] so session-local prompt churn doesn't bury
+  // plans and docs in the shared archive. Set to [] to disable.
+  archiveNestedTypes: ['prompt'],
 };
 
 export const taxonomy = {

package/bin/dotmd.mjs

@@ -507,11 +507,16 @@ Options:
   --json                 Output errors and warnings as JSON (always full detail)
   --dry-run, -n          Preview fixes without writing (with --fix)`,
 
-  archive: `dotmd archive <file> — archive a document
+  archive: `dotmd archive <file-or-slug> — archive a document
 
 Sets status to 'archived', moves to the archive directory, auto-updates
 references in other docs, and regenerates the index.
 
+<file-or-slug> resolves like \`dotmd use\`: an exact path wins, but a bare
+slug / basename (e.g. \`archive resume-foo\`) falls back to a recursive
+basename match under the doc roots. An ambiguous basename (the same name in
+two places) errors with the candidate list instead of guessing.
+
 Options:
   --no-index             Skip index regen. Use when multiple sessions are
                          working concurrently and you want a path-limited

package/dotmd.config.example.mjs

@@ -130,6 +130,9 @@ export const statuses = {
 //   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
+//   archiveNestedTypes: ['prompt'],     // types that archive under <typeDir>/<archiveDir>
+//                                       // (e.g. docs/prompts/archived/) instead of the
+//                                       // shared <root>/<archiveDir>; set [] to disable
 // };
 
 // Taxonomy validation — set fields to null to skip validation.

package/package.json

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

@@ -63,6 +63,12 @@ const DEFAULTS = {
     // statuses file under the owning type folder; archive remains a separate
     // primitive untouched.
     filedStatuses: { held: 'held', shelved: 'held', paused: 'held' },
+    // Types whose archive nests under their own type dir (<typeDir>/<archiveDir>,
+    // e.g. docs/prompts/archived/) instead of the shared <root>/<archiveDir>.
+    // Prompts are session-local churn — keeping their archive out of the shared
+    // docs/archived/ stops them from burying plans/docs there. Set to [] to send
+    // every type to the shared archive.
+    archiveNestedTypes: ['prompt'],
   },
 
   taxonomy: {
@@ -476,6 +482,9 @@ export async function resolveConfig(cwd, explicitConfigPath) {
   // F15: filedStatuses keyed by status name, value = directory name. Empty
   // object when no status opts in via `filed: true` (or `filed: '<dirname>'`).
   const filedStatuses = new Map(Object.entries(lifecycle.filedStatuses ?? {}));
+  // Types that archive into their own <typeDir>/<archiveDir> rather than the
+  // shared <root>/<archiveDir> (default: prompt).
+  const archiveNestedTypes = new Set(lifecycle.archiveNestedTypes ?? []);
 
   // Warn if rootStatuses keys don't match any configured root
   for (const rootKey of Object.keys(rootStatusesRaw)) {
@@ -507,7 +516,7 @@ export async function resolveConfig(cwd, explicitConfigPath) {
     rootValidStatuses,
     staleDaysByStatus,
 
-    lifecycle: { archiveStatuses, skipStaleFor, skipWarningsFor, terminalStatuses, filedStatuses },
+    lifecycle: { archiveStatuses, skipStaleFor, skipWarningsFor, terminalStatuses, filedStatuses, archiveNestedTypes },
 
     validSurfaces,
     validModules,

package/src/guard.mjs

@@ -25,11 +25,17 @@ const pkg = JSON.parse(readFileSync(path.join(__dirname, '..', 'package.json'),
 
 const SHELL_READERS = new Set(['cat', 'less', 'more', 'head', 'tail', 'bat', 'view', 'open']);
 
-// A path that ends in .md and sits under a `prompts/` directory is a saved
-// prompt regardless of which doc root it belongs to — robust across repos
-// without needing the resolved config.
+// A path that ends in .md and sits under a `prompts/` directory is a
+// session-local saved prompt regardless of which doc root it belongs to —
+// robust across repos without needing the resolved config. Archived prompts
+// (`…/prompts/archived/…`, the default nested archive for the prompt type) are
+// committable history, NOT session-local, so they're explicitly excluded — the
+// guard must not block committing or reading them.
 function isPromptPath(p) {
-  return typeof p === 'string' && p.endsWith('.md') && /(^|\/)prompts\//.test(p);
+  if (typeof p !== 'string' || !p.endsWith('.md')) return false;
+  if (!/(^|\/)prompts\//.test(p)) return false;
+  if (/(^|\/)archived\//.test(p)) return false;
+  return true;
 }
 
 // Loose "is this a dotmd-managed doc" test: a .md file under one of the

package/src/lifecycle.mjs

@@ -15,6 +15,29 @@ function findFileRoot(filePath, config) {
   return roots.find(r => filePath.startsWith(r + '/')) ?? config.docsRoot;
 }
 
+// Resolve an archive target like `dotmd use` resolves a pickup target: an exact
+// path wins (the resolveDocPath fast path), but a bare slug / basename falls
+// back to a recursive basename match under the doc roots. Mirrors
+// resolvePromptInput's basename pass so the closure verb is as forgiving about
+// naming as `use`/`prompts archive`. A basename shared by two files errors with
+// the candidate list rather than guessing which one to move.
+function resolveArchiveTarget(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 slug = input.replace(/\.md$/, '');
+  const byBasename = collectDocFiles(config).filter(f => path.basename(f, '.md') === slug);
+  if (byBasename.length === 1) return byBasename[0];
+  if (byBasename.length > 1) {
+    die(`Multiple docs match "${input}" by basename:\n${byBasename.map(f => '  ' + toRepoPath(f, config.repoRoot)).join('\n')}`);
+  }
+  return null;
+}
+
 function defaultTypeDir(docType, config) {
   if (docType === 'plan') return 'plans';
   if (docType === 'prompt') return 'prompts';
@@ -32,6 +55,17 @@ function findFilingRoot(filePath, fileRoot, docType, config) {
   return fileRoot;
 }
 
+// Base directory a doc archives under. Types in lifecycle.archiveNestedTypes
+// (default: prompt) archive into their own <typeDir>/ — yielding
+// <typeDir>/<archiveDir> (e.g. docs/prompts/archived/) — so session-local
+// prompt churn doesn't bury plans/docs in the shared <root>/<archiveDir>.
+// Everything else archives under fileRoot. Used by both runStatus (set
+// archived) and runArchive so the two paths stay in lockstep.
+function archiveBaseFor(filePath, fileRoot, docType, config) {
+  const nest = config.lifecycle?.archiveNestedTypes?.has(docType) ?? false;
+  return nest ? findFilingRoot(filePath, fileRoot, docType, config) : fileRoot;
+}
+
 // Best-effort index regen for any doc-set or doc-status mutation. The
 // generated block groups by status and embeds per-doc snapshots, so any
 // change that affects what would render leaves the index stale. Wrapped
@@ -172,8 +206,11 @@ export async function runStatus(argv, config, opts = {}) {
   }
 
   const today = nowIso();
-  const archiveDir = path.join(fileRoot, config.archiveDir);
   const filingRoot = findFilingRoot(filePath, fileRoot, docType, config);
+  // Type-aware archive base (prompts nest under their type dir by default);
+  // unarchive reuses archiveBase so a prompt restores to its type dir.
+  const archiveBase = archiveBaseFor(filePath, fileRoot, docType, config);
+  const archiveDir = path.join(archiveBase, config.archiveDir);
   const relFromFilingRoot = path.relative(filingRoot, filePath);
   const relSegments = relFromFilingRoot.split(path.sep);
   const inArchive = isArchivedPath(toRepoPath(filePath, config.repoRoot), config);
@@ -202,7 +239,7 @@ export async function runStatus(argv, config, opts = {}) {
       finalPath = targetPath;
     }
     if (isUnarchiving) {
-      const targetPath = path.join(fileRoot, path.basename(filePath));
+      const targetPath = path.join(archiveBase, path.basename(filePath));
       process.stdout.write(`${prefix} Would move: ${toRepoPath(filePath, config.repoRoot)} → ${toRepoPath(targetPath, config.repoRoot)}\n`);
       finalPath = targetPath;
     }
@@ -235,7 +272,7 @@ export async function runStatus(argv, config, opts = {}) {
   }
 
   if (isUnarchiving) {
-    const targetPath = path.join(fileRoot, path.basename(filePath));
+    const targetPath = path.join(archiveBase, path.basename(filePath));
     if (existsSync(targetPath)) { die(`Target already exists: ${toRepoPath(targetPath, config.repoRoot)}`); }
     const result = gitMv(filePath, targetPath, config.repoRoot);
     if (result.status !== 0) { die(result.stderr || 'git mv failed.'); }
@@ -387,7 +424,7 @@ export function runArchive(argv, config, opts = {}) {
 
   if (!input) { die('Usage: dotmd archive <file>'); }
 
-  const filePath = resolveDocPath(input, config);
+  const filePath = resolveArchiveTarget(input, config);
   if (!filePath) { die(`File not found: ${input}\nSearched: ${toRepoPath(config.repoRoot, config.repoRoot) || '.'}, ${toRepoPath(config.docsRoot, config.repoRoot)}`); }
 
   const archiveFileRoot = findFileRoot(filePath, config);
@@ -436,7 +473,9 @@ export function runArchive(argv, config, opts = {}) {
   const closeoutAction = closeoutTemplate ? planCloseoutInjection(body) : null;
 
   const today = nowIso();
-  const targetDir = path.join(archiveFileRoot, config.archiveDir);
+  // Type-aware: prompts archive under docs/prompts/archived/ by default (see
+  // archiveBaseFor); plans/docs keep the shared <root>/archived/.
+  const targetDir = path.join(archiveBaseFor(filePath, archiveFileRoot, asString(parsed.type), config), config.archiveDir);
   const targetPath = uniqueArchiveTarget(targetDir, path.basename(filePath));
   const oldRepoPath = toRepoPath(filePath, config.repoRoot);
   const newRepoPath = toRepoPath(targetPath, config.repoRoot);