dotmd-cli 0.68.0 → 0.70.0

package/src/commands.mjs

@@ -1,13 +1,327 @@
-// Canonical list of CLI verbs the dispatcher in bin/dotmd.mjs handles.
-// Source of truth for both the unknown-command suggester and the self-check
-// that asserts every `dotmd <verb>` reference in generated slash-command
-// templates points at a real command.
-export const KNOWN_COMMANDS = [
-  'list', 'json', 'check', 'coverage', 'stats', 'graph', 'deps', 'briefing', 'context', 'agent-context', 'hud',
-  'focus', 'query', 'grep', 'plans', 'prompts', 'stale', 'actionable', 'index', 'status', 'set', 'use', 'next', 'archive', 'bulk', 'bulk-tag', 'touch', 'doctor', 'runlist', 'runlists',
-  'unblocks', 'health', 'glossary', 'modules', 'module', 'surfaces',
-  'fix-refs', 'lint', 'rename', 'migrate', 'notion', 'export', 'summary',
-  'watch', 'diff', 'new', 'init', 'completions', 'statuses', 'journal',
-  'guard', 'misuse', 'update',
-  'ship', 'self-check', 'baton',
+// Canonical command grammar. Execution stays in bin/dotmd.mjs; this schema owns
+// names, aliases, visibility, options, positional arity, help groups, and policy.
+const none = Object.freeze({ mutation: 'none', pathPolicy: 'read-only' });
+const mutates = (pathPolicy) => Object.freeze({ mutation: 'conditional', pathPolicy });
+
+const flag = (...names) => Object.freeze({ names: Object.freeze(names), arity: 0 });
+const value = (...names) => Object.freeze({ names: Object.freeze(names), arity: 1 });
+const optionalValue = (...names) => Object.freeze({ names: Object.freeze(names), arity: 'optional' });
+const positionals = (min = 0, max = min) => Object.freeze({ min, max });
+const form = (syntax, { subcommands = [], args = positionals(), options = [], passthrough = false, dashPositionalsAfter = Infinity } = {}) => Object.freeze({
+  syntax,
+  subcommands: Object.freeze(subcommands),
+  positionals: args,
+  options: Object.freeze(options),
+  passthrough,
+  dashPositionalsAfter,
+});
+
+export const GLOBAL_OPTIONS = Object.freeze([
+  value('--config'), value('--root'), value('--type'),
+  flag('--dry-run', '-n'), flag('--verbose'), flag('--help', '-h'), flag('--version', '-v'),
+]);
+
+const QUERY_OPTIONS = Object.freeze([
+  value('--type'), value('--status'), value('--keyword'), flag('--body'), value('--owner'),
+  value('--surface'), value('--module'), value('--domain'), value('--audience'),
+  value('--execution-mode'), value('--updated-since'), value('--limit'), value('--sort'),
+  value('--group'), flag('--all'), flag('--include-archived'), flag('--exclude-archived'),
+  flag('--stale'), flag('--has-next-step'), flag('--has-blockers'), flag('--checklist-open'),
+  flag('--json'), flag('--git'), flag('--summarize'), value('--summarize-limit'), value('--model'),
+]);
+const LIFECYCLE_OPTIONS = Object.freeze([
+  value('--note'), flag('--no-index'), flag('--show-files'), flag('--force'),
+]);
+const STATUS_PROPERTY_OPTIONS = Object.freeze([
+  value('--type'), value('--like'), flag('--yes', '-y'), flag('--ignore-lifecycle-override'), flag('--json'),
+  value('--context'), value('--staleDays'),
+  flag('--requiresModule', '--no-requiresModule'), flag('--terminal', '--no-terminal'),
+  flag('--archive', '--no-archive'), flag('--skipStale', '--no-skipStale'),
+  flag('--skipWarnings', '--no-skipWarnings'), flag('--quiet', '--no-quiet'),
+]);
+
+const command = (name, policy, group, forms, extra = {}) => Object.freeze({
+  name,
+  policy,
+  group,
+  forms: Object.freeze(forms),
+  aliases: Object.freeze(extra.aliases ?? []),
+  visibility: extra.visibility ?? 'public',
+});
+
+const definitions = [
+  command('help', none, 'setup', [form('[topic]', { args: positionals(0, 1) })]),
+  command('completions', none, 'setup', [form('<bash|zsh>', { args: positionals(1, 1) })]),
+  command('init', mutates('repository setup paths and config files'), 'setup', [form('', { options: [flag('--force')] })]),
+  command('watch', mutates('proxy: child command policy applies'), 'setup', [form('[command...]', { args: positionals(0, Infinity), passthrough: true })]),
+
+  command('list', none, 'read', [form('', { options: [flag('--json'), flag('--verbose')] })]),
+  command('json', none, 'read', [form('')]),
+  command('coverage', none, 'read', [form('', { options: [flag('--json')] })]),
+  command('stats', none, 'read', [form('', { options: [flag('--json')] })]),
+  command('graph', none, 'read', [form('', { options: [flag('--dot'), flag('--json'), value('--status'), value('--module'), value('--surface')] })]),
+  command('deps', none, 'read', [form('[file]', { args: positionals(0, 1), options: [flag('--json'), value('--depth')] })]),
+  command('briefing', none, 'read', [form('', { options: [flag('--json')] })]),
+  command('context', none, 'read', [form('', { options: [flag('--json'), flag('--compact'), flag('--summarize'), value('--model')] })]),
+  command('agent-context', none, 'read', [form('', { options: [flag('--json')] })]),
+  command('hud', none, 'read', [form('', { options: [flag('--json'), flag('--subagent')] })]),
+  command('focus', none, 'read', [form('[status]', { args: positionals(0, 1), options: [flag('--json')] })]),
+  command('query', none, 'read', [form('[terms...]', { args: positionals(0, Infinity), options: QUERY_OPTIONS })]),
+  command('grep', none, 'read', [form('<term> [terms...]', { args: positionals(1, Infinity), options: QUERY_OPTIONS })]),
+  command('plans', none, 'read', [
+    form('[terms...]', { args: positionals(0, Infinity), options: QUERY_OPTIONS }),
+    form('status [terms...]', { subcommands: ['status'], args: positionals(0, Infinity), options: QUERY_OPTIONS }),
+  ]),
+  command('runlists', none, 'read', [form('', { options: [flag('--json'), value('--limit'), value('--sort')] })]),
+  command('roadmaps', none, 'read', [form('', { options: [flag('--json')] })]),
+  command('diff', none, 'read', [form('[file]', { args: positionals(0, 1), options: [flag('--stat'), value('--since'), flag('--summarize'), value('--model')] })]),
+  command('summary', none, 'read', [form('<file>', { args: positionals(1, 1), options: [value('--model'), value('--max-tokens'), flag('--json')] })]),
+  command('unblocks', none, 'read', [form('<file>', { args: positionals(1, 1), options: [flag('--json')] })]),
+  command('health', none, 'read', [form('', { options: [flag('--json')] })]),
+  command('glossary', none, 'read', [form('[term]', { args: positionals(0, 1), options: [flag('--list'), flag('--json')] })]),
+  command('modules', none, 'read', [form('', { options: [value('--sort'), value('--limit'), flag('--all'), flag('--json')] })]),
+  command('module', none, 'read', [form('<name>', { args: positionals(1, 1), options: [value('--sort'), flag('--json')] })]),
+  command('surfaces', none, 'read', [form('', { options: [flag('--json')] })]),
+  command('journal', none, 'read', [form('', { options: [value('--tail'), flag('--errors'), value('--session'), value('--since'), flag('--by-command'), flag('--json')] })]),
+  command('misuse', none, 'read', [form('', { options: [flag('--json'), value('--tail'), flag('--by-rule'), value('--repo')] })]),
+
+  command('roadmap', mutates('managed source when `next`; otherwise read-only'), 'workflow', [
+    form('[hub]', { args: positionals(0, 1), options: [flag('--json')] }),
+    form('next [hub]', { subcommands: ['next'], args: positionals(0, 1), options: [flag('--json'), flag('--full'), flag('--no-index')] }),
+  ]),
+  command('prompts', mutates('managed sources/destinations by subcommand'), 'workflow', [
+    form('', { options: [flag('--json'), value('--status'), flag('--include-archived'), value('--sort'), value('--limit'), flag('--all')] }),
+    form('list', { subcommands: ['list', 'status'], options: [flag('--json'), value('--status'), flag('--include-archived'), value('--sort'), value('--limit'), flag('--all')] }),
+    form('next', { subcommands: ['next'] }),
+    form('use [file]', { subcommands: ['use', 'resume'], args: positionals(0, 1), options: [flag('--no-index'), flag('--show-files'), flag('--force')] }),
+    form('show [file]', { subcommands: ['show', 'peek'], args: positionals(0, 1), options: [flag('--json')] }),
+    form('archive <file>', { subcommands: ['archive'], args: positionals(1, 1), options: [flag('--no-index'), flag('--show-files')] }),
+    form('new <slug> [body...]', { subcommands: ['new'], args: positionals(1, Infinity), options: [value('--body', '--message'), value('--title'), value('--status')] }),
+    form('hold <file>', { subcommands: ['hold', 'shelve'], args: positionals(1, 1) }),
+    form('unhold <file>', { subcommands: ['unhold', 'unshelve'], args: positionals(1, 1) }),
+  ], { aliases: ['prompt'] }),
+  command('use', mutates('managed source when starting/consuming; docs remain read-only'), 'workflow', [form('[file]', { args: positionals(0, 1), options: [flag('--json'), flag('--full'), flag('--no-index'), flag('--show-files'), flag('--force')] })]),
+  command('next', mutates('managed prompt source and same-root archive destination'), 'workflow', [form('', { options: [flag('--json'), flag('--no-index'), flag('--show-files'), flag('--force')] })]),
+  command('baton', mutates('managed plan/prompt sources and managed prompt destination'), 'workflow', [form('[plan|slug] <@draft|->', { args: positionals(0, 2), options: [value('--status'), value('--note'), value('--body', '--message'), flag('--force'), flag('--json')] })]),
+  command('runlist', mutates('managed hubs/children and managed scaffold destinations'), 'workflow', [
+    form('<hub>', { args: positionals(1, 1), options: [flag('--json')] }),
+    form('next <hub>', { subcommands: ['next'], args: positionals(1, 1), options: [flag('--json'), flag('--full'), flag('--no-index'), flag('--show-files')] }),
+    form('add <hub> <child...>', { subcommands: ['add'], args: positionals(2, Infinity), options: [flag('--json')] }),
+    form('remove <hub> <child...>', { subcommands: ['remove'], args: positionals(2, Infinity), options: [flag('--json'), flag('--clear-parent')] }),
+    form('reorder <hub> <child...>', { subcommands: ['reorder'], args: positionals(2, Infinity), options: [flag('--json'), value('--before'), value('--after')] }),
+  ]),
+
+  command('export', mutates('external output path intentionally unrestricted'), 'mutate', [form('[file]', { args: positionals(0, 1), options: [value('--format'), value('--output'), value('--status'), value('--module'), value('--root'), value('--type')] })]),
+  command('guard', mutates('global misuse log; no managed document writes'), 'mutate', [form('')]),
+  command('update', mutates('global CLI and plugin installation state'), 'mutate', [form('', { options: [flag('--check'), flag('--cli-only'), flag('--plugin-only')] })]),
+  command('status', mutates('managed source and same-root destination'), 'mutate', [form('<file> [status]', { args: positionals(1, 2), options: LIFECYCLE_OPTIONS })]),
+  command('set', mutates('managed source and same-root destination'), 'mutate', [form('<status> [file]', { args: positionals(1, 2), options: LIFECYCLE_OPTIONS })]),
+  command('ship', mutates('repository release/index paths and global release tooling'), 'mutate', [form('[patch|minor|major]', { args: positionals(0, 1) })]),
+  command('archive', mutates('managed source and same-root destination'), 'mutate', [form('<file>', { args: positionals(1, 1), options: [...LIFECYCLE_OPTIONS, flag('--closeout-template')] })]),
+  command('bulk', mutates('managed source sweep; archive destinations preserve roots'), 'mutate', [
+    form('archive <files...>', { subcommands: ['archive'], args: positionals(1, Infinity), options: [flag('--json'), flag('--no-index'), flag('--show-files')] }),
+    form('tag [files...]', { subcommands: ['tag'], args: positionals(0, Infinity), options: [value('--type'), value('--status'), flag('--json')] }),
+  ]),
+  command('bulk-tag', mutates('managed source sweep'), 'mutate', [form('[files...]', { args: positionals(0, Infinity), options: [value('--type'), value('--status'), flag('--json')] })]),
+  command('touch', mutates('managed source or managed source sweep'), 'mutate', [form('[file]', { args: positionals(0, 1), options: [flag('--git')] })]),
+  command('new', mutates('managed document destination; external body input unrestricted'), 'mutate', [form('[type] <name> [body...]', {
+    args: positionals(0, Infinity),
+    options: [value('--status'), value('--title'), value('--runlist'), flag('--coordination'), flag('--roadmap'), flag('--lite', '--minimal'), flag('--audit', '--findings'), value('--body', '--message'), value('--root'), flag('--show-files'), flag('--list-templates', '--list-types')],
+    dashPositionalsAfter: 1,
+  })]),
+  command('lint', mutates('managed source sweep with --fix; otherwise read-only'), 'mutate', [form('', { options: [flag('--fix')] })]),
+  command('rename', mutates('managed source, same-root destination, and rewrite sweep'), 'mutate', [form('<old> [new]', { args: positionals(1, 2), options: [flag('--show-files')] })]),
+  command('migrate', mutates('managed source sweep'), 'mutate', [form('<field> <old> <new> [files...]', { args: positionals(3, Infinity), options: [flag('--show-files')] })]),
+  command('fix-refs', mutates('managed source sweep'), 'mutate', [form('', { options: [flag('--show-files')] })]),
+  command('doctor', mutates('managed sweeps, repo index, and maintenance config paths by mode'), 'mutate', [form('[path]', { args: positionals(0, 1), options: [flag('--apply', '--yes'), flag('--statuses'), optionalValue('--migrate-template'), flag('--migrate-prompts'), flag('--frontmatter-fix'), flag('--project'), flag('--json'), flag('--include-archived')] })]),
+  command('statuses', mutates('project config path; document scan is read-only'), 'mutate', [
+    form('list', { subcommands: ['list'], options: [value('--type'), flag('--json')] }),
+    form('add <name>', { subcommands: ['add'], args: positionals(1, 1), options: STATUS_PROPERTY_OPTIONS }),
+    form('set <name>', { subcommands: ['set'], args: positionals(1, 1), options: STATUS_PROPERTY_OPTIONS }),
+    form('remove <name>', { subcommands: ['remove'], args: positionals(1, 1), options: STATUS_PROPERTY_OPTIONS }),
+    form('migrate <type>', { subcommands: ['migrate'], args: positionals(1, 1), options: [flag('--yes', '-y'), flag('--json'), flag('--ignore-lifecycle-override')] }),
+    form('', { options: [value('--type'), flag('--json')] }),
+  ]),
+  command('check', mutates('managed fix sweeps and repo-generated index; otherwise validation'), 'mutate', [form('[paths...]', { args: positionals(0, Infinity), options: [flag('--fix'), flag('--errors-only'), flag('--no-collapse'), flag('--json'), flag('--verbose')] })]),
+  command('index', mutates('repo-generated index destination; --print is read-only'), 'mutate', [form('', { options: [flag('--print')] })]),
+
+  command('self-check', none, 'internal', [form('', { options: [flag('--json')] })], { visibility: 'internal' }),
+  command('pickup', none, 'removed', [form('[args...]', { args: positionals(0, Infinity) })], { visibility: 'removed' }),
+  command('unpickup', none, 'removed', [form('[args...]', { args: positionals(0, Infinity) })], { visibility: 'removed' }),
+  command('release', none, 'removed', [form('[args...]', { args: positionals(0, Infinity) })], { visibility: 'removed' }),
+  command('finish', none, 'removed', [form('[args...]', { args: positionals(0, Infinity) })], { visibility: 'removed' }),
+  command('handoff', none, 'removed', [form('[args...]', { args: positionals(0, Infinity) })], { visibility: 'removed' }),
+
+  command('stale', none, 'preset', [form('[terms...]', { args: positionals(0, Infinity), options: QUERY_OPTIONS })]),
+  command('actionable', none, 'preset', [form('[terms...]', { args: positionals(0, Infinity), options: QUERY_OPTIONS })]),
 ];
+
+function schemaErrors(schema) {
+  const errors = [];
+  const names = new Set();
+  const aliases = new Set();
+  for (const entry of schema) {
+    if (!entry.name || names.has(entry.name)) errors.push(`duplicate or empty command name: ${entry.name}`);
+    names.add(entry.name);
+    if (!entry.group) errors.push(`${entry.name}: missing help group`);
+    if (!entry.forms.length) errors.push(`${entry.name}: missing forms`);
+    for (const alias of entry.aliases) {
+      if (!alias || names.has(alias) || aliases.has(alias)) errors.push(`${entry.name}: duplicate alias ${alias}`);
+      aliases.add(alias);
+    }
+    const formKeys = new Set();
+    for (const commandForm of entry.forms) {
+      const key = commandForm.subcommands.join('|') || '<default>';
+      if (formKeys.has(key)) errors.push(`${entry.name}: duplicate form ${key}`);
+      formKeys.add(key);
+      const { min, max } = commandForm.positionals;
+      if (!Number.isInteger(min) || min < 0 || !(max === Infinity || Number.isInteger(max)) || max < min) {
+        errors.push(`${entry.name} ${key}: malformed positional arity`);
+      }
+      const optionNames = new Set();
+      for (const option of commandForm.options) {
+        if (![0, 1, 'optional'].includes(option.arity) || !option.names.length) errors.push(`${entry.name} ${key}: malformed option`);
+        for (const optionName of option.names) {
+          if (!optionName.startsWith('-') || optionNames.has(optionName)) errors.push(`${entry.name} ${key}: duplicate or malformed option ${optionName}`);
+          optionNames.add(optionName);
+        }
+      }
+    }
+  }
+  for (const alias of aliases) if (names.has(alias)) errors.push(`alias collides with command: ${alias}`);
+  return errors;
+}
+
+const errors = schemaErrors(definitions);
+if (errors.length) throw new Error(`Invalid command schema:\n${errors.join('\n')}`);
+
+export const COMMAND_SCHEMA = Object.freeze(Object.fromEntries(definitions.map(entry => [entry.name, entry])));
+const ALIASES = Object.freeze(Object.fromEntries(definitions.flatMap(entry => entry.aliases.map(alias => [alias, entry.name]))));
+
+export const COMMAND_POLICIES = Object.freeze(Object.fromEntries(definitions.map(entry => [entry.name, entry.policy])));
+export const KNOWN_COMMANDS = Object.freeze(definitions.map(entry => entry.name));
+export const PUBLIC_COMMANDS = Object.freeze(definitions.filter(entry => entry.visibility === 'public').map(entry => entry.name));
+export const COMPLETION_COMMANDS = Object.freeze(definitions
+  .filter(entry => entry.visibility === 'public')
+  .flatMap(entry => [entry.name, ...entry.aliases]));
+export const MUTATION_CAPABLE_COMMANDS = Object.freeze(new Set(
+  definitions.filter(entry => entry.policy.mutation !== 'none').map(entry => entry.name),
+));
+
+export function canonicalCommand(name) {
+  return ALIASES[name] ?? name;
+}
+
+export function commandDefinition(name) {
+  return COMMAND_SCHEMA[canonicalCommand(name)] ?? null;
+}
+
+export function commandPolicy(name) {
+  return commandDefinition(name)?.policy ?? null;
+}
+
+export function commandOwnsOption(name, optionName) {
+  const definition = commandDefinition(name);
+  return Boolean(definition?.forms.some(commandForm => commandForm.options.some(option => option.names.includes(optionName))));
+}
+
+export function commandCompletionWords(name) {
+  const definition = commandDefinition(name);
+  if (!definition) return [];
+  const words = new Set();
+  for (const commandForm of definition.forms) {
+    for (const subcommand of commandForm.subcommands) words.add(subcommand);
+    for (const option of commandForm.options) for (const optionName of option.names) words.add(optionName);
+  }
+  return [...words];
+}
+
+export function commandUsage(name) {
+  const definition = commandDefinition(name);
+  if (!definition) return null;
+  return definition.forms.map(commandForm => `dotmd ${definition.name}${commandForm.syntax ? ` ${commandForm.syntax}` : ''}`).join('\n');
+}
+
+function optionMap(forms) {
+  const map = new Map();
+  for (const commandForm of forms) {
+    for (const option of commandForm.options) {
+      for (const optionName of option.names) map.set(optionName, option);
+    }
+  }
+  return map;
+}
+
+function scanArgs(name, argv, options, passthrough = false, dashPositionalsAfter = Infinity) {
+  const positional = [];
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i];
+    if (arg === '-') { positional.push(arg); continue; }
+    if (!arg.startsWith('-')) { positional.push(arg); continue; }
+    const option = options.get(arg);
+    if (!option) {
+      if (passthrough) continue;
+      if (positional.length >= dashPositionalsAfter) { positional.push(arg); continue; }
+      throw new Error(`Unknown flag for \`dotmd ${name}\`: ${arg}`);
+    }
+    if (option.arity === 1) {
+      const next = argv[i + 1];
+      if (next === undefined || options.has(next)) {
+        throw new Error(`Missing value for \`${arg}\` in \`dotmd ${name}\`.`);
+      }
+      i += 1;
+    } else if (option.arity === 'optional' && argv[i + 1] !== undefined && !argv[i + 1].startsWith('-')) {
+      i += 1;
+    }
+  }
+  return positional;
+}
+
+export function normalizeCommandArgs(name, argv) {
+  const canonical = canonicalCommand(name);
+  if (canonical !== 'roadmap') return [...argv];
+  const positionalIndexes = [];
+  const options = optionMap(commandDefinition(canonical).forms);
+  for (let i = 0; i < argv.length; i += 1) {
+    const option = options.get(argv[i]);
+    if (option) {
+      if (option.arity === 1) i += 1;
+      else if (option.arity === 'optional' && argv[i + 1] !== undefined && !argv[i + 1].startsWith('-')) i += 1;
+      continue;
+    }
+    if (!argv[i].startsWith('-')) positionalIndexes.push(i);
+  }
+  if (positionalIndexes.length === 2 && argv[positionalIndexes[1]] === 'next' && argv[positionalIndexes[0]] !== 'next') {
+    const normalized = [...argv];
+    const hub = normalized[positionalIndexes[0]];
+    normalized[positionalIndexes[0]] = 'next';
+    normalized[positionalIndexes[1]] = hub;
+    return normalized;
+  }
+  return [...argv];
+}
+
+export function validateCommandArgs(name, argv, { preset = false } = {}) {
+  const definition = preset ? COMMAND_SCHEMA.query : commandDefinition(name);
+  if (!definition) return argv;
+  const canonical = definition.name;
+  const normalized = normalizeCommandArgs(canonical, argv);
+  const allOptions = optionMap(definition.forms);
+  const allPassthrough = definition.forms.some(commandForm => commandForm.passthrough);
+  const dashPositionalsAfter = Math.min(...definition.forms.map(commandForm => commandForm.dashPositionalsAfter));
+  const preliminary = scanArgs(canonical, normalized, allOptions, allPassthrough, dashPositionalsAfter);
+  const selected = definition.forms.find(commandForm => commandForm.subcommands.includes(preliminary[0]))
+    ?? definition.forms.find(commandForm => commandForm.subcommands.length === 0);
+  if (!selected) throw new Error(`Unknown subcommand for \`dotmd ${canonical}\`: ${preliminary[0] ?? '(missing)'}`);
+  const selectedOptions = optionMap([selected]);
+  const positional = scanArgs(canonical, normalized, selectedOptions, selected.passthrough, selected.dashPositionalsAfter);
+  const args = selected.subcommands.includes(positional[0]) ? positional.slice(1) : positional;
+  if (args.length < selected.positionals.min || args.length > selected.positionals.max) {
+    throw new Error(`Usage: ${commandUsage(canonical)}`);
+  }
+  return normalized;
+}
+
+export function validateCommandSchema(schema = definitions) {
+  return schemaErrors(schema);
+}

package/src/completions.mjs

@@ -1,107 +1,41 @@
 import { die } from './util.mjs';
-import { KNOWN_COMMANDS } from './commands.mjs';
+import { COMPLETION_COMMANDS, GLOBAL_OPTIONS, PUBLIC_COMMANDS, commandCompletionWords } from './commands.mjs';
 
-// Derive the completable command list from the dispatcher's canonical verb list
-// so completions never drift behind new commands. A tiny denylist drops verbs
-// that exist but shouldn't be tab-completed (internal self-test).
-const COMPLETION_DENYLIST = new Set(['self-check']);
-const COMMANDS = KNOWN_COMMANDS.filter(c => !COMPLETION_DENYLIST.has(c));
-
-const GLOBAL_FLAGS = ['--config', '--dry-run', '--verbose', '--root', '--type', '--help', '--version'];
-
-// Shared filter flags for the query-style commands (mirrors QUERY_FLAGS in
-// bin/dotmd.mjs). Kept as one array so query/grep/stale/actionable/plans stay
-// in lockstep.
-const QUERY_FLAGS = [
-  '--type', '--status', '--keyword', '--body', '--owner', '--surface', '--module',
-  '--domain', '--audience', '--execution-mode', '--updated-since', '--limit', '--sort',
-  '--group', '--all', '--include-archived', '--exclude-archived', '--stale',
-  '--has-next-step', '--has-blockers', '--checklist-open', '--json', '--git',
-  '--summarize', '--summarize-limit', '--model',
-];
-
-const COMMAND_FLAGS = {
-  query: QUERY_FLAGS,
-  grep: QUERY_FLAGS,
-  stale: QUERY_FLAGS,
-  actionable: QUERY_FLAGS,
-  plans: ['status', ...QUERY_FLAGS],
-  list: ['--verbose', '--json'],
-  briefing: ['--json'],
-  context: ['--json', '--compact', '--summarize', '--model'],
-  'agent-context': ['--json'],
-  hud: ['--json', '--subagent'],
-  index: ['--write'],
-  coverage: ['--json'],
-  stats: ['--json'],
-  graph: ['--dot', '--json', '--status', '--module', '--surface'],
-  deps: ['--json', '--depth'],
-  unblocks: ['--json'],
-  health: ['--json'],
-  glossary: ['--list', '--json'],
-  modules: ['--sort', '--json'],
-  module: ['--json'],
-  surfaces: ['--json'],
-  runlists: ['--json', '--limit', '--sort'],
-  runlist: ['next', '--json', '--full', '--no-index', '--show-files'],
-  prompts: ['list', 'next', 'use', 'show', 'archive', 'new', 'hold', 'unhold',
-            '--json', '--status', '--include-archived', '--sort', '--limit', '--all'],
-  use: [],
-  next: [],
-  baton: ['--status', '--note', '--body', '--message', '--dry-run'],
-  set: [],
-  status: [],
-  archive: ['--note', '--no-index', '--show-files', '--closeout-template'],
-  bulk: ['archive', 'tag'],
-  statuses: ['list', 'add', '--type', '--like', '--json'],
-  update: ['--check', '--cli-only', '--plugin-only'],
-  misuse: ['--json', '--tail', '--by-rule', '--repo'],
-  journal: ['--tail', '--errors', '--session', '--since', '--by-command', '--json'],
-  new: ['--status', '--title', '--template', '--list-templates', '--root', '--message', '--body'],
-  notion: ['import', 'export', 'sync', '--force', '--dry-run'],
-  export: ['--format', '--output', '--status', '--module', '--root', '--type'],
-  focus: ['--json'],
-  summary: ['--model', '--max-tokens', '--json'],
-  diff: ['--stat', '--since', '--summarize', '--model'],
-  touch: ['--git'],
-  check: ['--fix', '--errors-only', '--no-collapse', '--json', '--verbose'],
-  doctor: ['--apply', '--yes', '--dry-run', '--statuses', '--migrate-template',
-           '--migrate-prompts', '--frontmatter-fix', '--project', '--json', '--include-archived'],
-  lint: ['--fix'],
-  ship: [],
-  rename: [],
-  migrate: [],
-  'fix-refs': [],
-};
+const GLOBAL_FLAGS = GLOBAL_OPTIONS.flatMap(option => option.names);
+const COMMAND_WORDS = Object.freeze(Object.fromEntries(
+  PUBLIC_COMMANDS.map(command => [command, commandCompletionWords(command)]),
+));
 
 function bashCompletion() {
   return `# dotmd bash completion
 # Add to ~/.bashrc: eval "$(dotmd completions bash)"
 _dotmd() {
-  local cur prev cmd
+  local cur cmd expect_value
   cur="\${COMP_WORDS[COMP_CWORD]}"
-  prev="\${COMP_WORDS[COMP_CWORD-1]}"
-
-  # Find the subcommand
   cmd=""
+  expect_value=0
+
+  # Find the command while skipping pre-command global flags and their values.
   for ((i=1; i < COMP_CWORD; i++)); do
+    if (( expect_value )); then expect_value=0; continue; fi
     case "\${COMP_WORDS[i]}" in
+      --config|--root|--type) expect_value=1 ;;
+      --dry-run|-n|--verbose|--help|-h|--version|-v) ;;
       -*) ;;
       *) cmd="\${COMP_WORDS[i]}"; break ;;
     esac
   done
 
-  # Complete commands if no subcommand yet
   if [[ -z "$cmd" ]]; then
-    COMPREPLY=( $(compgen -W "${COMMANDS.join(' ')} ${GLOBAL_FLAGS.join(' ')}" -- "$cur") )
+    COMPREPLY=( $(compgen -W "${COMPLETION_COMMANDS.join(' ')} ${GLOBAL_FLAGS.join(' ')}" -- "$cur") )
     return
   fi
 
-  # Per-command flag completion
   case "$cmd" in
-${Object.entries(COMMAND_FLAGS).map(([cmd, flags]) =>
-    `    ${cmd}) COMPREPLY=( $(compgen -W "${flags.join(' ')} ${GLOBAL_FLAGS.join(' ')}" -- "$cur") ) ;;`
+${Object.entries(COMMAND_WORDS).map(([command, words]) =>
+    `    ${command}) COMPREPLY=( $(compgen -W "${words.join(' ')} ${GLOBAL_FLAGS.join(' ')}" -- "$cur") ) ;;`
   ).join('\n')}
+    prompt) COMPREPLY=( $(compgen -W "${commandCompletionWords('prompts').join(' ')} ${GLOBAL_FLAGS.join(' ')}" -- "$cur") ) ;;
     *) COMPREPLY=( $(compgen -W "${GLOBAL_FLAGS.join(' ')}" -- "$cur") ) ;;
   esac
 }
@@ -114,23 +48,35 @@ function zshCompletion() {
 _dotmd() {
   local -a commands global_flags
   commands=(
-${COMMANDS.map(c => `    '${c}'`).join('\n')}
+${COMPLETION_COMMANDS.map(command => `    '${command}'`).join('\n')}
   )
   global_flags=(
-${GLOBAL_FLAGS.map(f => `    '${f}'`).join('\n')}
+${GLOBAL_FLAGS.map(option => `    '${option}'`).join('\n')}
   )
 
-  if (( CURRENT == 2 )); then
+  local cmd=''
+  local expect_value=0
+  for ((i=2; i < CURRENT; i++)); do
+    if (( expect_value )); then expect_value=0; continue; fi
+    case "\${words[i]}" in
+      --config|--root|--type) expect_value=1 ;;
+      --dry-run|-n|--verbose|--help|-h|--version|-v) ;;
+      -*) ;;
+      *) cmd="\${words[i]}"; break ;;
+    esac
+  done
+
+  if [[ -z "$cmd" ]]; then
     _describe 'command' commands
     _describe 'flag' global_flags
     return
   fi
 
-  local cmd=\${words[2]}
   case "$cmd" in
-${Object.entries(COMMAND_FLAGS).map(([cmd, flags]) =>
-    `    ${cmd}) _values 'flags' ${flags.map(f => `'${f}'`).join(' ')} ;;`
+${Object.entries(COMMAND_WORDS).map(([command, words]) =>
+    `    ${command}) _values 'arguments' ${words.map(word => `'${word}'`).join(' ')} ;;`
   ).join('\n')}
+    prompt) _values 'arguments' ${commandCompletionWords('prompts').map(word => `'${word}'`).join(' ')} ;;
   esac
 
   _describe 'flag' global_flags
@@ -140,14 +86,8 @@ compdef _dotmd dotmd`;
 
 export function runCompletions(argv) {
   const shell = argv[0];
-  if (!shell) {
-    die('Usage: dotmd completions <bash|zsh>');
-  }
-  if (shell === 'bash') {
-    process.stdout.write(bashCompletion() + '\n');
-  } else if (shell === 'zsh') {
-    process.stdout.write(zshCompletion() + '\n');
-  } else {
-    die(`Unsupported shell: ${shell}\nSupported: bash, zsh`);
-  }
+  if (!shell) die('Usage: dotmd completions <bash|zsh>');
+  if (shell === 'bash') process.stdout.write(bashCompletion() + '\n');
+  else if (shell === 'zsh') process.stdout.write(zshCompletion() + '\n');
+  else die(`Unsupported shell: ${shell}\nSupported: bash, zsh`);
 }

package/src/config.mjs

@@ -55,6 +55,7 @@ const DEFAULTS = {
   },
 
   lifecycle: {
+    startableStatuses: ['active', 'planned'],
     archiveStatuses: ['archived'],
     skipStaleFor: ['archived', 'reference', 'partial', 'queued-after'],
     skipWarningsFor: ['archived', 'partial', 'queued-after'],
@@ -112,8 +113,6 @@ const DEFAULTS = {
 
   glossary: null,
 
-  notion: null,
-
   // Opt-in JSONL command journal at .dotmd/journal.jsonl. Default off — agents
   // and users who want usage observability flip this on (or set DOTMD_JOURNAL=1).
   journal: false,
@@ -141,6 +140,7 @@ const VALID_CONTEXT_VALUES = new Set(['expanded', 'listed', 'counted']);
  */
 function normalizeRichStatuses(config, userConfig) {
   const derived = {
+    startableStatuses: [],
     archiveStatuses: [],
     skipStaleFor: [],
     skipWarningsFor: [],
@@ -199,6 +199,7 @@ function normalizeRichStatuses(config, userConfig) {
       }
 
       if (p.archive && !derived.archiveStatuses.includes(name)) derived.archiveStatuses.push(name);
+      if (p.startable && !derived.startableStatuses.includes(name)) derived.startableStatuses.push(name);
       if ((p.skipStale || quietImpliesSkipStale) && !derived.skipStaleFor.includes(name)) derived.skipStaleFor.push(name);
       if ((p.skipWarnings || quietImpliesSkipWarnings) && !derived.skipWarningsFor.includes(name)) derived.skipWarningsFor.push(name);
       if (p.terminal && !derived.terminalStatuses.includes(name)) derived.terminalStatuses.push(name);
@@ -241,6 +242,9 @@ function applyDerivedConfig(config, userConfig, derived) {
   }
 
   // lifecycle — each sub-key independently
+  if (!userConfig.lifecycle?.startableStatuses && derived.startableStatuses.length) {
+    config.lifecycle.startableStatuses = derived.startableStatuses;
+  }
   if (!userConfig.lifecycle?.archiveStatuses && derived.archiveStatuses.length) {
     config.lifecycle.archiveStatuses = derived.archiveStatuses;
   }
@@ -298,6 +302,15 @@ function validateConfig(userConfig, config, validStatuses, indexPath) {
     warnings.push('Config: archiveDir must be a string.');
   }
 
+  // Lifecycle status lists must reference configured statuses.
+  if (config.lifecycle?.startableStatuses) {
+    for (const s of config.lifecycle.startableStatuses) {
+      if (!validStatuses.has(s)) {
+        warnings.push(`Config: lifecycle.startableStatuses contains unknown status '${s}'.`);
+      }
+    }
+  }
+
   // lifecycle.archiveStatuses values must exist in validStatuses
   if (config.lifecycle?.archiveStatuses) {
     for (const s of config.lifecycle.archiveStatuses) {
@@ -486,6 +499,7 @@ export async function resolveConfig(cwd, explicitConfigPath) {
   // Lifecycle config
   const lifecycle = config.lifecycle;
   const archiveStatuses = new Set(lifecycle.archiveStatuses);
+  const startableStatuses = new Set(lifecycle.startableStatuses ?? ['active', 'planned']);
   const skipStaleFor = new Set(lifecycle.skipStaleFor);
   const skipWarningsFor = new Set(lifecycle.skipWarningsFor);
   const terminalStatuses = new Set(lifecycle.terminalStatuses);
@@ -526,7 +540,7 @@ export async function resolveConfig(cwd, explicitConfigPath) {
     rootValidStatuses,
     staleDaysByStatus,
 
-    lifecycle: { archiveStatuses, skipStaleFor, skipWarningsFor, terminalStatuses, filedStatuses, archiveNestedTypes },
+    lifecycle: { archiveStatuses, startableStatuses, skipStaleFor, skipWarningsFor, terminalStatuses, filedStatuses, archiveNestedTypes },
 
     validSurfaces,
     validModules,
@@ -542,6 +556,7 @@ export async function resolveConfig(cwd, explicitConfigPath) {
     display: config.display,
     referenceFields: config.referenceFields,
     presets: config.presets,
+    configuredPresetNames: new Set(Object.keys(userConfig.presets ?? {})),
     journal: config.journal === true,
     guard: { deny: config.guard?.deny !== false },
     hooks,

package/src/diff.mjs

@@ -75,16 +75,21 @@ function printFileDiff(relPath, since, diffOutput, opts) {
   process.stdout.write(bold(relPath) + dim(` (updated: ${since})`) + '\n');
 
   if (opts.summarize) {
+    const previewSkipped = Boolean(opts.config?._execution?.suppressSideEffects);
     let summary;
     try {
-      summary = opts.config?.hooks?.summarizeDiff
+      summary = previewSkipped
+        ? null
+        : opts.config?.hooks?.summarizeDiff
         ? opts.config.hooks.summarizeDiff(diffOutput, relPath)
         : summarizeDiffText(diffOutput, relPath, opts.model);
     } catch (err) {
       warn(`Hook 'summarizeDiff' threw: ${err.message}`);
       summary = null;
     }
-    if (summary) {
+    if (previewSkipped) {
+      process.stdout.write(dim('  [preview] Summary generation skipped; models and custom summarizeDiff hooks are not invoked.') + '\n');
+    } else if (summary) {
       process.stdout.write(dim(`  Summary: ${summary}`) + '\n');
     } else {
       warn('  Summary unavailable (model call failed)');
@@ -94,4 +99,3 @@ function printFileDiff(relPath, since, diffOutput, opts) {
   process.stdout.write(diffOutput);
   process.stdout.write('\n');
 }
-