npm - dotmd-cli - Versions diffs - 0.23.0 → 0.24.1 - Mend

dotmd-cli 0.23.0 → 0.24.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (8) hide show

package/bin/dotmd.mjs CHANGED Viewed

@@ -20,7 +20,8 @@ View & Query:
   context [--summarize] [--json]    Full briefing (LLM-oriented)
   focus [status] [--json]           Detailed view for one status group
   query [filters] [--json]          Filtered search (--status, --keyword, --stale, etc.)
-  plans                             All plans (preset)
+  plans                             Live plans (excludes archived; --include-archived for all)
+  prompts                           Pending prompts in docs/prompts/
   stale                             Stale docs (preset)
   actionable                        Docs with next steps (preset)
@@ -352,6 +353,11 @@ Modes:
                          Skips non-plans. Per-file diff. Doesn't touch
                          long next_step/current_state or unmarked phase
                          headings (those need human input).
+  --migrate-prompts      Retrofit pre-existing markdown files under any docs
+                         root's prompts/ subdirectory with proper prompt
+                         frontmatter (type, status, created from git
+                         history, dotmd_version, context, related_plans).
+                         Skips files that already have frontmatter.
   --migrate-template <file>  Migrate just one plan.
   --migrate-template --include-archived
                          Also touch plans in the archive directory.
@@ -530,24 +536,40 @@ directory. Skips any files that already exist.
 If docs/ already contains .md files, auto-detects statuses, surfaces,
 modules, and reference fields to pre-populate the config.`,
-  plans: `dotmd plans — list all plans
+  plans: `dotmd plans — list live plans (excludes archived by default)
-Shows all documents with type: plan, sorted by status.
-Supports all query flags (--status, --module, --json, --sort, --group, etc.)
+Shows documents with type: plan, excluding terminal/archive statuses,
+sorted by status. Supports all query flags (--status, --module, --json,
+--sort, --group, etc.).
 Default plan statuses: in-session, active, planned, blocked, partial,
 paused, awaiting, queued-after, archived. Run \`dotmd status --help\` for
 the unstuck-action behind each one.
 Examples:
-  dotmd plans                          # all plans
+  dotmd plans                          # live plans (default)
+  dotmd plans --include-archived       # all plans including archived
   dotmd plans --status active          # active plans only
   dotmd plans --status awaiting        # plans waiting on a human decision
   dotmd plans --status partial,paused  # shipped-tail and parked plans
   dotmd plans --module auth            # plans for the auth module
-  dotmd plans --group module           # all plans grouped by module
+  dotmd plans --group module           # plans grouped by module
   dotmd plans --json                   # JSON output`,
+  prompts: `dotmd prompts — list saved prompts (excludes archived by default)
+Shows documents with type: prompt, typically saved under docs/prompts/.
+Prompts are created with \`dotmd new prompt <name> "<body>"\` and seed
+future Claude sessions via \`claude "$(cat docs/prompts/<name>.md)"\`.
+Default prompt statuses: pending, claimed, archived.
+Examples:
+  dotmd prompts                        # pending prompts (default)
+  dotmd prompts --include-archived     # all prompts including archived
+  dotmd prompts --status claimed       # already-consumed prompts
+  dotmd prompts --json                 # JSON output`,
   stale: `dotmd stale — list stale documents
 Shows docs that haven't been updated within their staleness threshold.
@@ -718,7 +740,7 @@ async function main() {
     process.stderr.write(`Repo root: ${config.repoRoot}\n`);
   }
-  // Preset aliases
+  // Preset aliases (user config can override built-in commands below)
   if (config.presets[command]) {
     const { buildIndex } = await import('../src/index.mjs');
     const { runQuery } = await import('../src/query.mjs');
@@ -727,6 +749,43 @@ async function main() {
     return;
   }
+  // Built-in list commands — stable across projects regardless of preset config.
+  // Two views per type:
+  //   `dotmd plans`         triage — top 10 by recency, flat with right-aligned [TAG]
+  //   `dotmd plans status`  pipeline — grouped by status, no per-row tag, all plans
+  if (command === 'plans') {
+    const { buildIndex } = await import('../src/index.mjs');
+    const { runQuery } = await import('../src/query.mjs');
+    const index = buildIndex(config);
+    const sub = restArgs[0];
+    let defaults;
+    let extras = restArgs;
+    if (sub === 'status') {
+      defaults = ['--type', 'plan', '--exclude-archived', '--sort', 'status', '--all'];
+      extras = restArgs.slice(1);
+    } else {
+      defaults = ['--type', 'plan', '--exclude-archived', '--sort', 'updated', '--limit', '10'];
+    }
+    runQuery(index, [...defaults, ...extras], config, { preset: 'plans' });
+    return;
+  }
+  if (command === 'prompts') {
+    const { buildIndex } = await import('../src/index.mjs');
+    const { runQuery } = await import('../src/query.mjs');
+    const index = buildIndex(config);
+    const sub = restArgs[0];
+    let defaults;
+    let extras = restArgs;
+    if (sub === 'status') {
+      defaults = ['--type', 'prompt', '--exclude-archived', '--sort', 'status', '--all'];
+      extras = restArgs.slice(1);
+    } else {
+      defaults = ['--type', 'prompt', '--exclude-archived', '--sort', 'updated', '--limit', '10'];
+    }
+    runQuery(index, [...defaults, ...extras], config, { preset: 'prompts' });
+    return;
+  }
   // Commands that handle their own index building
   if (command === 'diff') { const { runDiff } = await import('../src/diff.mjs'); runDiff(restArgs, config); return; }
   if (command === 'summary') { const { runSummary } = await import('../src/summary.mjs'); runSummary(restArgs, config); return; }
@@ -1001,7 +1060,7 @@ async function main() {
   // Unknown command — suggest closest match
   const allCommands = [
     'list', 'json', 'check', 'coverage', 'stats', 'graph', 'deps', 'briefing', 'context', 'hud',
-    'focus', 'query', 'plans', 'stale', 'actionable', 'index', 'pickup', 'release', 'handoff', 'finish', 'status', 'archive', 'bulk', 'touch', 'doctor',
+    'focus', 'query', 'plans', 'prompts', 'stale', 'actionable', 'index', 'pickup', 'release', 'handoff', 'finish', 'status', 'archive', 'bulk', 'touch', 'doctor',
     'unblocks', 'health', 'glossary',
     'fix-refs', 'lint', 'rename', 'migrate', 'notion', 'export', 'summary',
     'watch', 'diff', 'new', 'init', 'completions', 'statuses',

package/package.json CHANGED Viewed

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

package/src/color.mjs CHANGED Viewed

@@ -6,5 +6,9 @@ const wrap = (code) => enabled ? (s) => `\x1b[${code}m${s}\x1b[0m` : (s) => s;
 export const bold = wrap('1');
 export const dim = wrap('2');
 export const red = wrap('31');
-export const yellow = wrap('33');
 export const green = wrap('32');
+export const yellow = wrap('33');
+export const blue = wrap('34');
+export const magenta = wrap('35');
+export const cyan = wrap('36');
+export const brightYellow = wrap('93');

package/src/config.mjs CHANGED Viewed

@@ -100,7 +100,6 @@ const DEFAULTS = {
   notion: null,
   presets: {
-    plans: ['--type', 'plan', '--sort', 'status', '--all'],
     stale: ['--status', 'active,ready,planned,blocked,scoping', '--stale', '--sort', 'updated', '--all'],
     actionable: ['--status', 'active,ready', '--has-next-step', '--sort', 'updated', '--all'],
   },

package/src/doctor.mjs CHANGED Viewed

@@ -7,6 +7,7 @@ import { renderCheck } from './render.mjs';
 import { bold, dim, green, yellow } from './color.mjs';
 import { scaffoldClaudeCommands } from './claude-commands.mjs';
 import { runMigrateTemplate } from './migrate-template.mjs';
+import { runMigratePrompts } from './migrate-prompts.mjs';
 // Tunable thresholds for `dotmd doctor --statuses` conflation detection.
 // MIN_BUCKET_SIZE: only flag buckets with at least this many docs (small buckets aren't worth nagging).
@@ -46,6 +47,10 @@ export function runDoctor(argv, config, opts = {}) {
     runMigrateTemplate(argv, config, opts);
     return;
   }
+  if (argv.includes('--migrate-prompts')) {
+    runMigratePrompts(argv, config, opts);
+    return;
+  }
   const { dryRun } = opts;
   process.stdout.write(bold('dotmd doctor') + '\n\n');

package/src/git.mjs CHANGED Viewed

@@ -19,6 +19,16 @@ export function getGitLastModified(relPath, repoRoot) {
   return result.stdout.trim();
 }
+export function getGitFirstAdded(relPath, repoRoot) {
+  const result = spawnSync('git', ['log', '--diff-filter=A', '--follow', '--format=%aI', '--', relPath], {
+    cwd: repoRoot, encoding: 'utf8',
+  });
+  if (result.error || result.status !== 0 || !result.stdout.trim()) return null;
+  // `git log` returns newest-first; the file's add commit is the LAST entry.
+  const lines = result.stdout.trim().split('\n').filter(Boolean);
+  return lines[lines.length - 1] ?? null;
+}
 export function getGitLastModifiedBatch(repoRoot) {
   const result = spawnSync('git', [
     'log', '--format=commit %aI', '--name-only', '--diff-filter=ACDMR', 'HEAD',

package/src/migrate-prompts.mjs ADDED Viewed

@@ -0,0 +1,169 @@
+import { readFileSync, writeFileSync, readdirSync, statSync, existsSync } from 'node:fs';
+import path from 'node:path';
+import { extractFrontmatter, parseSimpleFrontmatter } from './frontmatter.mjs';
+import { toRepoPath, nowIso } from './util.mjs';
+import { getGitFirstAdded } from './git.mjs';
+import { bold, green, dim } from './color.mjs';
+import { readFileSync as rfs } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const pkg = JSON.parse(rfs(path.join(__dirname, '..', 'package.json'), 'utf8'));
+function findPromptCandidates(config) {
+  const roots = config.docsRoots || [config.docsRoot];
+  // Build the set of directories to search: each root, plus each root's parent
+  // (catches `docs/prompts/` when roots are like `docs/plans/`, `docs/modules/`),
+  // plus the repo root itself.
+  const candidates = new Set();
+  for (const root of roots) {
+    candidates.add(path.join(root, 'prompts'));
+    candidates.add(path.join(path.dirname(root), 'prompts'));
+  }
+  candidates.add(path.join(config.repoRoot, 'prompts'));
+  const out = [];
+  const seen = new Set();
+  for (const dir of candidates) {
+    if (!existsSync(dir) || seen.has(dir)) continue;
+    seen.add(dir);
+    walkDir(dir, out);
+  }
+  return out;
+}
+function walkDir(dir, out) {
+  for (const entry of readdirSync(dir, { withFileTypes: true })) {
+    if (entry.name.startsWith('.')) continue;
+    const full = path.join(dir, entry.name);
+    if (entry.isDirectory()) { walkDir(full, out); continue; }
+    if (!entry.isFile() || !entry.name.endsWith('.md')) continue;
+    out.push(full);
+  }
+}
+function deriveContext(body, filePath) {
+  // Use first heading or filename as the context label.
+  const firstH1 = body.match(/^#\s+(.+?)\s*$/m);
+  if (firstH1) return firstH1[1].slice(0, 100);
+  // Fall back to slug, title-cased.
+  const slug = path.basename(filePath, '.md');
+  return slug.replace(/[-_]/g, ' ').replace(/\b\w/g, c => c.toUpperCase()).slice(0, 100);
+}
+export function migrateOnePrompt(raw, opts = {}) {
+  const { frontmatter, body: rawBody } = extractFrontmatter(raw);
+  const created = opts.created || nowIso();
+  // Case 1: no frontmatter at all → wrap with full fresh frontmatter.
+  if (!frontmatter || frontmatter.length === 0) {
+    const body = raw.trimStart();
+    const context = deriveContext(body, opts.filePath || 'unknown');
+    const fm = [
+      'type: prompt',
+      'status: pending',
+      `created: ${created}`,
+      `dotmd_version: ${pkg.version}`,
+      `context: "${context.replace(/"/g, '\\"')}"`,
+      'related_plans: []',
+    ].join('\n');
+    return {
+      changes: [{ kind: 'add-frontmatter', detail: `type=prompt, created=${created}, context="${context}"` }],
+      newRaw: `---\n${fm}\n---\n\n${body.trim()}\n`,
+    };
+  }
+  // Case 2: frontmatter exists. If it already has `type: prompt`, leave alone.
+  const parsed = parseSimpleFrontmatter(frontmatter);
+  if (parsed.type === 'prompt') {
+    return { changes: [], newRaw: raw, skipped: 'already-prompt' };
+  }
+  // Case 3: partial/ad-hoc frontmatter (e.g., `title:` + `purpose:` only).
+  // Add missing required fields while preserving existing keys.
+  const needed = [];
+  if (!parsed.type) needed.push(['type', 'prompt']);
+  if (!parsed.status) needed.push(['status', 'pending']);
+  if (!parsed.created) needed.push(['created', created]);
+  if (!parsed.dotmd_version) needed.push(['dotmd_version', pkg.version]);
+  if (!parsed.context) {
+    // Prefer existing `title:` if present, else derive from body/filename.
+    const ctx = typeof parsed.title === 'string' ? parsed.title : deriveContext(rawBody || raw, opts.filePath || 'unknown');
+    needed.push(['context', `"${ctx.replace(/"/g, '\\"')}"`]);
+  }
+  if (!parsed.related_plans) needed.push(['related_plans', '[]']);
+  if (needed.length === 0) {
+    return { changes: [], newRaw: raw, skipped: 'frontmatter-complete' };
+  }
+  // Prepend the missing fields (so `type` ends up at the top for grep-friendliness).
+  const addedLines = needed.map(([k, v]) => `${k}: ${v}`).join('\n');
+  const newFrontmatter = `${addedLines}\n${frontmatter}`;
+  const newRaw = `---\n${newFrontmatter}\n---\n${rawBody}`;
+  return {
+    changes: [{ kind: 'merge-frontmatter', detail: `added: ${needed.map(([k]) => k).join(', ')}` }],
+    newRaw,
+  };
+}
+export function runMigratePrompts(argv, config, opts = {}) {
+  const { dryRun } = opts;
+  const json = argv.includes('--json');
+  const fileArg = argv.find(a => !a.startsWith('-') && a !== 'doctor');
+  let files;
+  if (fileArg) {
+    const target = fileArg.endsWith('.md') ? fileArg : `${fileArg}.md`;
+    files = findPromptCandidates(config).filter(f => f.endsWith(target) || f === target);
+    if (files.length === 0) {
+      process.stderr.write(`File not found in any prompts/ subdir: ${fileArg}\n`);
+      process.exitCode = 1;
+      return;
+    }
+  } else {
+    files = findPromptCandidates(config);
+  }
+  const results = [];
+  let touched = 0;
+  for (const filePath of files) {
+    const raw = readFileSync(filePath, 'utf8');
+    const created = getGitFirstAdded(toRepoPath(filePath, config.repoRoot), config.repoRoot)
+      || new Date(statSync(filePath).birthtimeMs).toISOString().replace(/\.\d{3}Z$/, 'Z');
+    const result = migrateOnePrompt(raw, { created, filePath });
+    if (result.changes.length === 0) continue;
+    const repoPath = toRepoPath(filePath, config.repoRoot);
+    results.push({ path: repoPath, changes: result.changes });
+    touched++;
+    if (!dryRun) writeFileSync(filePath, result.newRaw, 'utf8');
+  }
+  if (json) {
+    process.stdout.write(JSON.stringify({
+      dryRun: Boolean(dryRun),
+      filesScanned: files.length,
+      filesTouched: touched,
+      results,
+    }, null, 2) + '\n');
+    return;
+  }
+  if (results.length === 0) {
+    process.stdout.write(green('No prompts need migration.') + dim(` (${files.length} scanned)`) + '\n');
+    return;
+  }
+  const prefix = dryRun ? dim('[dry-run] ') : '';
+  process.stdout.write(bold(`${prefix}${touched} prompt${touched === 1 ? '' : 's'} ${dryRun ? 'would be' : 'were'} migrated:\n\n`));
+  for (const r of results) {
+    process.stdout.write(`  ${r.path}\n`);
+    for (const c of r.changes) {
+      process.stdout.write(dim(`    [${c.kind}] ${c.detail}\n`));
+    }
+  }
+  if (dryRun) process.stdout.write(`\nRun ${bold('dotmd doctor --migrate-prompts')} without --dry-run to apply.\n`);
+}

package/src/query.mjs CHANGED Viewed

@@ -6,7 +6,30 @@ import { computeDaysSinceUpdate, computeIsStale } from './validate.mjs';
 import { getGitLastModifiedBatch } from './git.mjs';
 import { extractFrontmatter } from './frontmatter.mjs';
 import { summarizeDocBody } from './ai.mjs';
-import { bold, dim, yellow, red } from './color.mjs';
+import { bold, dim, yellow, red, green, blue, magenta, cyan, brightYellow } from './color.mjs';
+const STATUS_COLORS = {
+  'in-session': (s) => bold(red(s)),
+  'active': green,
+  'planned': blue,
+  'blocked': yellow,
+  'partial': (s) => dim(green(s)),
+  'paused': magenta,
+  'awaiting': brightYellow,
+  'queued-after': (s) => dim(cyan(s)),
+  'archived': dim,
+  'pending': bold,
+  'claimed': dim,
+};
+function colorTag(status) {
+  const tag = `[${(status ?? 'unknown').toUpperCase()}]`;
+  const fn = STATUS_COLORS[status] ?? dim;
+  return fn(tag);
+}
+// Strip ANSI for length math
+function visibleLen(s) { return s.replace(/\x1b\[[0-9;]*m/g, '').length; }
 export function runFocus(index, argv, config) {
   // Find first positional arg, skipping flag-value pairs like --root <name>
@@ -64,8 +87,8 @@ export function runQuery(index, argv, config, opts = {}) {
     return;
   }
-  if (opts.preset === 'plans') {
-    renderPlansOutput(docs, filters, config);
+  if (opts.preset === 'plans' || opts.preset === 'prompts') {
+    renderPlansOutput(docs, filters, config, { noun: opts.preset });
     return;
   }
@@ -81,6 +104,7 @@ export function parseQueryArgs(argv) {
     stale: false, hasNextStep: false, hasBlockers: false,
     checklistOpen: false, json: false, git: false,
     summarize: false, summarizeLimit: 5, model: undefined,
+    positionalTerms: [],
   };
   for (let i = 0; i < argv.length; i += 1) {
@@ -101,6 +125,8 @@ export function parseQueryArgs(argv) {
     if (arg === '--sort' && next) { filters.sort = next; i += 1; continue; }
     if (arg === '--group' && next) { filters.group = next; i += 1; continue; }
     if (arg === '--all') { filters.all = true; continue; }
+    if (arg === '--include-archived') { filters.includeArchived = true; continue; }
+    if (arg === '--exclude-archived') { filters.excludeArchived = true; continue; }
     if (arg === '--stale') { filters.stale = true; continue; }
     if (arg === '--has-next-step') { filters.hasNextStep = true; continue; }
     if (arg === '--has-blockers') { filters.hasBlockers = true; continue; }
@@ -110,6 +136,14 @@ export function parseQueryArgs(argv) {
     if (arg === '--summarize') { filters.summarize = true; continue; }
     if (arg === '--summarize-limit' && next) { filters.summarizeLimit = Number.parseInt(next, 10) || 5; i += 1; continue; }
     if (arg === '--model' && next) { filters.model = next; i += 1; continue; }
+    // Positional terms: anything else that's not a flag becomes a substring
+    // filter token (AND-matched against slug + title). Lets users do:
+    //   dotmd plans rls          → matches rls-platform-rows, rls-location-anchored
+    //   dotmd plans pii redesign → AND match: pii-data-model-redesign
+    if (typeof arg === 'string' && !arg.startsWith('-')) {
+      filters.positionalTerms.push(arg.toLowerCase());
+    }
   }
   return filters;
@@ -120,12 +154,29 @@ 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.
+  if (filters.excludeArchived && !filters.includeArchived) {
+    const archived = new Set([
+      ...(config.lifecycle?.archiveStatuses ?? []),
+      ...(config.lifecycle?.terminalStatuses ?? []),
+    ]);
+    result = result.filter(d => !archived.has(d.status));
+  }
   if (filters.keyword) {
     const needle = filters.keyword.toLowerCase();
     result = result.filter(d => [d.title, d.summary, d.currentState, d.nextStep, d.path, ...(d.blockers ?? [])].filter(Boolean).join(' ').toLowerCase().includes(needle));
   }
+  // Positional substring filter: AND match against slug + title.
+  if (filters.positionalTerms?.length) {
+    result = result.filter(d => {
+      const haystack = [d.path, d.title].filter(Boolean).join(' ').toLowerCase();
+      return filters.positionalTerms.every(term => haystack.includes(term));
+    });
+  }
   if (filters.owner) { const n = filters.owner.toLowerCase(); result = result.filter(d => (d.owner ?? '').toLowerCase().includes(n)); }
   if (filters.surface) { const n = filters.surface.toLowerCase(); result = result.filter(d => (d.surfaces ?? []).some(s => s.toLowerCase() === n)); }
   if (filters.module) { const n = filters.module.toLowerCase(); result = result.filter(d => (d.modules ?? []).some(m => m.toLowerCase() === n)); }
@@ -151,6 +202,15 @@ export function filterDocs(docs, filters, config) {
   if (filters.checklistOpen) result = result.filter(d => (d.checklist?.open ?? 0) > 0);
   result.sort(buildSorter(filters.sort, config));
+  // Stash pre-limit count and per-status breakdown on filters so renderers
+  // can show "N more" footers and accurate pipeline summaries even when the
+  // returned slice is limited.
+  filters._totalBeforeLimit = result.length;
+  filters._statusCounts = {};
+  for (const d of result) {
+    const s = d.status ?? 'unknown';
+    filters._statusCounts[s] = (filters._statusCounts[s] ?? 0) + 1;
+  }
   return filters.all ? result : result.slice(0, filters.limit);
 }
@@ -235,19 +295,28 @@ function compareUpdatedDesc(a, b) {
   return au !== bu ? bu.localeCompare(au) : 0;
 }
-function renderPlansOutput(docs, filters, config) {
+function renderPlansOutput(docs, filters, config, opts = {}) {
+  const noun = opts.noun ?? 'plans';
   if (docs.length === 0) {
-    process.stdout.write('No plans found.\n');
+    process.stdout.write(`No ${noun} found.\n`);
     return;
   }
-  // Summary line
-  const bySt = {};
-  for (const d of docs) { bySt[d.status] = (bySt[d.status] ?? 0) + 1; }
-  const counts = Object.entries(bySt).map(([s, n]) => `${n} ${s}`).join(', ');
-  process.stdout.write(`${bold('Plans')} ${dim(`(${docs.length})`)}  ${counts}\n`);
-  // Active filter note (only if user applied extra filters beyond the preset defaults)
+  // Summary line: middle-dot separator, ALWAYS based on the full pre-limit
+  // pipeline so the top-of-page numbers stay honest when --limit is applied.
+  const totalShown = docs.length;
+  const totalAll = filters._totalBeforeLimit ?? totalShown;
+  const bySt = filters._statusCounts ?? (() => {
+    const counts = {};
+    for (const d of docs) { counts[d.status] = (counts[d.status] ?? 0) + 1; }
+    return counts;
+  })();
+  // Sort statuses by count desc for a stable visual.
+  const counts = Object.entries(bySt).sort((a, b) => b[1] - a[1]).map(([s, n]) => `${n} ${s}`).join(' · ');
+  const header = `${totalAll} ${noun}${counts ? ' · ' + counts : ''}`;
+  process.stdout.write(dim(header) + '\n');
+  // Active filter note
   const activeFilters = [];
   if (filters.statuses?.length) activeFilters.push(`status: ${filters.statuses.join(', ')}`);
   if (filters.module) activeFilters.push(`module: ${filters.module}`);
@@ -260,29 +329,40 @@ function renderPlansOutput(docs, filters, config) {
   if (activeFilters.length) process.stdout.write(dim(`  filtered: ${activeFilters.join(' | ')}`) + '\n');
   const maxWidth = process.stdout.columns || 100;
+  const grouped = filters.sort === 'status' || filters.group;
-  // Group by module or status
   if (filters.group === 'module') {
+    process.stdout.write('\n');
     renderPlansByGroup(docs, d => d.modules?.length ? d.modules : ['(none)'], filters, maxWidth);
   } else if (filters.group === 'surface') {
+    process.stdout.write('\n');
     renderPlansByGroup(docs, d => d.surfaces?.length ? d.surfaces : ['(none)'], filters, maxWidth);
   } else if (filters.group === 'owner') {
+    process.stdout.write('\n');
     renderPlansByGroup(docs, d => [d.owner ?? '(none)'], filters, maxWidth);
-  } else {
-    // Default: group by status, ordered by config.statusOrder
+  } else if (grouped) {
+    // Pipeline view: group by status, ordered by config.statusOrder. Tag is implicit.
     const statusGroups = new Map();
     for (const d of docs) {
       const s = d.status ?? 'unknown';
       if (!statusGroups.has(s)) statusGroups.set(s, []);
       statusGroups.get(s).push(d);
     }
     const orderedStatuses = [...config.statusOrder.filter(s => statusGroups.has(s)), ...([...statusGroups.keys()].filter(s => !config.statusOrder.includes(s)))];
     for (const status of orderedStatuses) {
       const group = statusGroups.get(status);
       process.stdout.write(`\n${bold(`${capitalize(status)} (${group.length})`)}\n`);
-      renderPlanRows(group, filters, maxWidth);
+      renderPlanRows(group, filters, maxWidth, { showTag: false });
+    }
+  } else {
+    // Triage view: flat, sorted by recency, tag on right.
+    process.stdout.write('\n');
+    renderPlanRows(docs, filters, maxWidth, { showTag: true });
+    // Footer when the result was capped.
+    const hidden = totalAll - totalShown;
+    if (hidden > 0) {
+      process.stdout.write('\n');
+      process.stdout.write(dim(`  ${hidden} more ${noun}  ·  dotmd ${noun} --all  ·  dotmd ${noun} status\n`));
     }
   }
@@ -306,29 +386,53 @@ function renderPlansByGroup(docs, keyFn, filters, maxWidth) {
   }
 }
-function renderPlanRows(group, filters, maxWidth) {
+// Widest tag we render (status name in CAPS + brackets). Used to budget the
+// next-step column when right-aligning tags.
+const MAX_TAG_WIDTH = '[QUEUED-AFTER]'.length;
+function renderPlanRows(group, filters, maxWidth, opts = {}) {
+  const { showTag = false } = opts;
   const maxSlug = Math.min(30, Math.max(...group.map(d => toSlug(d).length)));
-  const showModule = !filters.module && filters.group !== 'module';
   for (const doc of group) {
     const slug = toSlug(doc).padEnd(maxSlug);
-    const age = doc.daysSinceUpdate != null ? `${doc.daysSinceUpdate}d` : ' —';
+    const age = doc.daysSinceUpdate != null ? `${doc.daysSinceUpdate}d` : '—';
     const ageStr = doc.daysSinceUpdate != null && doc.isStale ? red(age.padStart(4)) : dim(age.padStart(4));
-    const progress = renderProgressBar(doc.checklist);
-    const parts = [`  ${slug}  ${ageStr}`];
-    if (progress) parts.push(progress);
-    if (showModule && doc.modules?.length) parts.push(dim(`[${doc.modules.join(',')}]`));
+    // Compact percentage cell (always 5 chars: "100% " / " 99% " / "  5% " / "     ")
+    let pctCell = '     ';
+    if (doc.checklist?.total) {
+      const pct = Math.round((doc.checklist.completed / doc.checklist.total) * 100);
+      pctCell = `${pct.toString().padStart(3)}% `;
+    }
-    if (doc.blockers?.length && (doc.status === 'blocked')) {
-      parts.push(yellow(`blockers: ${doc.blockers.join('; ')}`));
+    const leftBlock = `  ${slug}  ${ageStr}  ${dim(pctCell)}`;
+    const leftLen = visibleLen(leftBlock);
+    // Next-step / blocker text. Budget = maxWidth - leftLen - separator - (tag column if shown).
+    let nextText = '';
+    if (doc.blockers?.length && doc.status === 'blocked') {
+      nextText = `blocked by ${doc.blockers.join('; ')}`;
     } else if (doc.nextStep) {
-      parts.push(`next: ${doc.nextStep}`);
-    } else {
-      parts.push(dim('(no next step)'));
+      nextText = doc.nextStep;
     }
-    const line = parts.join('  ');
-    process.stdout.write((line.length > maxWidth ? line.slice(0, maxWidth - 3) + '...' : line) + '\n');
+    const tagBudget = showTag ? MAX_TAG_WIDTH + 2 : 0; // 2 = gap before tag
+    const nextBudget = Math.max(10, maxWidth - leftLen - 2 - tagBudget); // -2 for `  ` separator
+    let nextRendered = nextText;
+    if (nextText.length > nextBudget) nextRendered = nextText.slice(0, nextBudget - 3) + '...';
+    // Coloring for "blocked by" stays yellow.
+    if (doc.blockers?.length && doc.status === 'blocked') nextRendered = yellow(nextRendered);
+    let line = `${leftBlock}  ${nextRendered}`;
+    if (showTag) {
+      // Pad next column to push tag to the right column boundary.
+      const consumed = visibleLen(line);
+      const targetCol = maxWidth - MAX_TAG_WIDTH;
+      const padCount = Math.max(2, targetCol - consumed);
+      line = `${line}${' '.repeat(padCount)}${colorTag(doc.status)}`;
+    }
+    process.stdout.write(line + '\n');
   }
 }