dotmd-cli 0.45.1 → 0.45.3

package/package.json

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

package/src/frontmatter-fix.mjs

@@ -10,7 +10,7 @@ import { bold, green, dim } from './color.mjs';
 // the warning on the next few-word touch-up.
 const FIELDS = [
   { name: 'current_state', cap: 1500, target: 1200, heading: '## Current State' },
-  { name: 'next_step',     cap: 300,  target: 200,  heading: '## Next Step' },
+  { name: 'next_step',     cap: 800,  target: 600,  heading: '## Next Step' },
 ];
 
 export function runFrontmatterFix(config, opts = {}) {

package/src/lifecycle.mjs

@@ -552,12 +552,40 @@ export function runArchive(argv, config, opts = {}) {
 
   const archiveFileRoot = findFileRoot(filePath, config);
   const relFromRoot = path.relative(archiveFileRoot, filePath);
-  if (relFromRoot.startsWith(config.archiveDir + '/') || relFromRoot.startsWith(config.archiveDir + path.sep)) { die(`Already archived: ${toRepoPath(filePath, config.repoRoot)}`); }
+  // Segment-membership covers both single-root (`<root>/archived/foo.md`) and
+  // multi-root (`<type-root>/archived/foo.md`) layouts. The older
+  // startsWith-only check missed nested cases where archived/ wasn't the first
+  // segment under the resolved root.
+  const inArchiveDir = relFromRoot.split(path.sep).includes(config.archiveDir);
 
   const raw = readFileSync(filePath, 'utf8');
   const { frontmatter, body } = extractFrontmatter(raw);
   const parsed = parseSimpleFrontmatter(frontmatter);
   const oldStatus = asString(parsed.status) ?? 'unknown';
+
+  // Heal stuck frontmatter (issue #13): file is under archiveDir/ but its
+  // status hasn't been flipped. Flip in place; don't try to move (it's already
+  // archived on disk) and don't refuse — refusal leaves the drift permanent.
+  if (inArchiveDir) {
+    if (oldStatus === 'archived') {
+      die(`Already archived: ${toRepoPath(filePath, config.repoRoot)}`);
+    }
+    const today = nowIso();
+    const repoPathHeal = toRepoPath(filePath, config.repoRoot);
+    if (dryRun) {
+      const prefix = dim('[dry-run]');
+      out.write(`${prefix} Would heal frontmatter in place: status: ${oldStatus} → archived, updated: ${today}\n`);
+      out.write(`${prefix} Would skip git mv (file already under \`${config.archiveDir}/\`)\n`);
+      return;
+    }
+    updateFrontmatter(filePath, { status: 'archived', updated: today });
+    appendVersionHistory(filePath, `Archived (frontmatter healed in place from \`${oldStatus}\`).`);
+    if (!noIndex) regenIndex(config);
+    out.write(`${green('✓ Healed')}: ${repoPathHeal} (${oldStatus} → archived; file already under \`${config.archiveDir}/\`)\n`);
+    if (showFiles) emitFilesFooter([repoPathHeal, config.indexPath], config);
+    return;
+  }
+
   const closeoutAction = closeoutTemplate ? planCloseoutInjection(body) : null;
 
   const today = nowIso();

package/src/prompts.mjs

@@ -1,7 +1,7 @@
 import { readFileSync, statSync } from 'node:fs';
 import path from 'node:path';
 import { extractFrontmatter, parseSimpleFrontmatter } from './frontmatter.mjs';
-import { asString, toRepoPath, die, resolveDocPath } from './util.mjs';
+import { asString, toRepoPath, die, resolveDocPath, isArchivedPath } from './util.mjs';
 import { buildIndex } from './index.mjs';
 import { runQuery } from './query.mjs';
 import { runArchive, runStatus } from './lifecycle.mjs';
@@ -120,7 +120,11 @@ function renderPromptsVerbose(index, config, { hasStatusFlag, includeArchived })
 
 export function pendingPromptsOldestFirst(config) {
   const index = buildIndex(config);
-  const prompts = index.docs.filter(d => d.type === 'prompt' && d.status === 'pending');
+  const prompts = index.docs.filter(d =>
+    d.type === 'prompt'
+    && d.status === 'pending'
+    && !isArchivedPath(d.path, config),
+  );
 
   return prompts
     .map(d => {

package/src/query.mjs

@@ -1,6 +1,6 @@
 import { readFileSync } from 'node:fs';
 import path from 'node:path';
-import { capitalize, toSlug, truncate, warn, suggestCandidates } from './util.mjs';
+import { capitalize, toSlug, truncate, warn, suggestCandidates, isArchivedPath } from './util.mjs';
 import { renderProgressBar, formatCurrentState } from './render.mjs';
 import { computeDaysSinceUpdate, computeIsStale } from './validate.mjs';
 import { getGitLastModifiedBatch } from './git.mjs';
@@ -176,14 +176,15 @@ export function filterDocs(docs, filters, config) {
 
   if (filters.types?.length) result = result.filter(d => filters.types.includes(d.type));
   if (filters.statuses?.length) result = result.filter(d => filters.statuses.includes(d.status));
-  // --exclude-archived strips terminal/archive statuses unless the caller
-  // explicitly opted back in with --include-archived.
+  // --exclude-archived strips terminal/archive statuses AND any file physically
+  // located under `archiveDir/` (issue #13: status can drift out of sync with
+  // the file's directory; the path is the source of truth for "is archived").
   if (filters.excludeArchived && !filters.includeArchived) {
     const archived = new Set([
       ...(config.lifecycle?.archiveStatuses ?? []),
       ...(config.lifecycle?.terminalStatuses ?? []),
     ]);
-    result = result.filter(d => !archived.has(d.status));
+    result = result.filter(d => !archived.has(d.status) && !isArchivedPath(d.path, config));
   }
 
   if (filters.keyword) {

package/src/util.mjs

@@ -55,6 +55,16 @@ export function toRepoPath(absolutePath, repoRoot) {
   return path.relative(repoRoot, absolutePath).split(path.sep).join('/');
 }
 
+// True when any path segment equals `config.archiveDir`. Covers both
+// `docs/plans/archived/foo.md` and `docs/prompts/archived/foo.md` regardless
+// of whether the layout is single-root or flat-array. Read-side commands use
+// this to skip files whose frontmatter `status:` has drifted out of sync with
+// their archive location (issue #13).
+export function isArchivedPath(repoPath, config) {
+  if (!repoPath || !config?.archiveDir) return false;
+  return repoPath.split('/').includes(config.archiveDir);
+}
+
 // Emit a `files: a b c` line to stderr listing every doc / index path
 // the command touched (deduped, sorted, repo-relative). Lets agents do
 // `git add` with the exact set instead of guessing. Opt-in via

package/src/validate.mjs

@@ -112,9 +112,18 @@ export function validateDoc(doc, frontmatter, headingTitle, config) {
   }
 
   if (config.validSurfaces && !config.lifecycle.skipWarningsFor.has(doc.status)) {
+    const knownSurfaces = [...config.validSurfaces];
     for (const surface of doc.surfaces) {
       if (!config.validSurfaces.has(surface)) {
-        doc.warnings.push({ path: doc.path, level: 'warning', message: `Unknown surface \`${surface}\`; expected a known surface taxonomy value.` });
+        const suggestions = suggestCandidates(surface, knownSurfaces, 3);
+        const hint = suggestions.length
+          ? ` Did you mean: ${suggestions.map(s => `\`${s}\``).join(' | ')}?`
+          : '';
+        doc.warnings.push({
+          path: doc.path,
+          level: 'warning',
+          message: `Unknown surface \`${surface}\`; expected a known surface taxonomy value.${hint} Run \`dotmd surfaces\` to list all valid values.`,
+        });
       }
     }
   }
@@ -218,6 +227,27 @@ export function validateDoc(doc, frontmatter, headingTitle, config) {
     }
   }
 
+  // Inverse archive drift (issue #13): a doc whose path is under
+  // `<dir>/<archiveDir>/` but whose status is NOT an archive status. Without
+  // this check, the file is invisible to default queries (the path is below
+  // an archive bucket so it's filtered out by `--exclude-archived`), yet its
+  // `status: pending` (or similar) still makes it surface in pending-prompt
+  // scans. The heal is to flip the frontmatter via `dotmd <type-or-set>
+  // archive`, which now restores in place rather than failing.
+  if (doc.status && !config.lifecycle.archiveStatuses.has(doc.status)) {
+    const parentSegments = path.dirname(doc.path).split('/');
+    if (parentSegments.includes(config.archiveDir)) {
+      const heal = doc.type === 'prompt'
+        ? `dotmd prompts archive ${doc.path}`
+        : `dotmd set archived ${doc.path}`;
+      doc.errors.push({
+        path: doc.path,
+        level: 'error',
+        message: `File is under \`${config.archiveDir}/\` but \`status: ${doc.status}\` is not an archive status. Run \`${heal}\` to heal the frontmatter in place, or move the file out of the archive directory.`,
+      });
+    }
+  }
+
   // Validate reference fields resolve to existing files. Terminal statuses
   // (archived, deprecated, etc.) document historical state — their refs may
   // legitimately point at moved/deleted targets and shouldn't gate the
@@ -435,13 +465,17 @@ export function validatePlanShape(doc, body, frontmatter, config) {
   if (config.lifecycle.terminalStatuses.has(doc.status) || config.lifecycle.archiveStatuses.has(doc.status)) return;
   if (config.lifecycle.skipWarningsFor.has(doc.status)) return;
 
-  // 1. next_step length cap (300 chars)
+  // 1. next_step length cap (800 chars). Was 300; raised in parallel with
+  // current_state for the same reason: agents need to encode "what to do next"
+  // with enough specificity (which file, which decision, which branch) that
+  // 300 chars often forced truncation into the body where the briefing
+  // doesn't read it.
   const nextStep = typeof frontmatter.next_step === 'string' ? frontmatter.next_step : '';
-  if (nextStep.length > 300) {
+  if (nextStep.length > 800) {
     doc.warnings.push({
       path: doc.path,
       level: 'warning',
-      message: `\`next_step\` is ${nextStep.length} chars (cap: 300). Long prose belongs in the body — keep next_step as a 1-2 line pointer.`,
+      message: `\`next_step\` is ${nextStep.length} chars (cap: 800). Long prose belongs in the body — keep next_step as a 1-2 sentence pointer.`,
     });
   }