@llman-sdd/cli 0.1.3 → 0.2.0

package/src/main.ts

@@ -1,7 +1,6 @@
 #!/usr/bin/env bun
-import { spawnSync } from 'node:child_process';
-import { existsSync, readFileSync, writeFileSync } from 'node:fs';
-import { join } from 'node:path';
+import { existsSync, mkdirSync, readFileSync, readdirSync, statSync, writeFileSync } from 'node:fs';
+import { join, resolve } from 'node:path';
 
 import {
   VERSION,
@@ -37,12 +36,34 @@ import {
   runList,
   runThaw,
   validateAllSpecs,
+  validateCapability,
   TEMPLATES_ROOT,
   resolveChatConfig,
   unavailableResult,
   type TemplateIo,
+  addReq,
+  addScenario,
+  archiveChange,
+  validateChange,
+  applyStrict,
+  evaluateStaleness,
+  buildReqRegistry,
+  splitVerb,
+  notApplicableStaleness,
+  compileChangeIdPattern,
+  renderChangeIdTemplate,
+  nextUniqueNumber,
+  changeDiffInfo,
+  STAGE_ORDER,
+  harvestUniqueNumbers,
+  planDedupe,
+  resolveReq,
+  renderConfigOverview,
+  skillsJson,
+  type StalenessInfo,
+  type ChangeIssue,
 } from '@llman-sdd/core';
-import { Command } from 'commander';
+import { Command, Option } from 'commander';
 
 import { makeCliGit, makeIo } from './io.ts';
 
@@ -67,51 +88,397 @@ function loadSpecEntries(): ReturnType<typeof discoverSpecs> {
   return discoverSpecs('llmanspec/specs', makeIo(process.cwd()));
 }
 
-function runValidateSpecs(options: { specs?: boolean; check: boolean }): number {
-  const report = validateAllSpecs(loadSpecEntries(), makeIo(process.cwd()));
-  for (const line of report.lines) console.log(line);
-
-  let failed = report.failed;
-  if (options.check && existsSync('llmanspec/config.yaml')) {
-    const config = loadConfig(readFileSync('llmanspec/config.yaml', 'utf8'));
-    const runCommand = config.bdd?.run_command;
-    if (runCommand) {
-      const proc = spawnSync(runCommand, { shell: true, stdio: 'inherit' });
-      if ((proc.status ?? 1) !== 0) failed = true;
-    }
+function loadCliConfig(): ReturnType<typeof loadConfig> | null {
+  if (!existsSync('llmanspec/config.yaml')) return null;
+  const config = loadConfig(readFileSync('llmanspec/config.yaml', 'utf8'));
+  compileChangeIdPattern(config.change_id?.pattern);
+  return config;
+}
+
+function cliMaxScanDepth(): number {
+  const raw = program.opts().maxScanDepth as string | undefined;
+  const n = raw !== undefined ? Number(raw) : 8;
+  if (!Number.isInteger(n) || n < 1) {
+    console.error(`Error: --max-scan-depth must be >= 1 (got ${raw})`);
+    process.exit(1);
   }
-  return failed ? 1 : 0;
+  return n;
 }
 
+function runValidateSweep(): boolean {
+  const report = validateAllSpecs(loadSpecEntries(), makeIo(process.cwd()));
+  return report.verdicts.some((v) => !v.ok);
+}
+
+const SKILL_DESCRIPTIONS: Record<string, string> = {
+  'llman-sdd-continue': 'Fill in missing change artifacts',
+  'llman-sdd-ff': 'Fast-forward propose: planning shell → Branch binding → Specs landing',
+  'llman-sdd-validate': 'Standalone validation skill',
+  'llman-sdd-arch-review': 'Scan shallow modules for deepening candidates',
+  'llman-sdd-wayfinder': 'Plan large foggy work as a decision map',
+  'llman-sdd-research': 'Delegate external research to a background agent',
+};
+const skillDesc = (name: string): string => SKILL_DESCRIPTIONS[name] ?? '';
+
 const program = new Command();
 
+// v1/clap parity for arg-parsing errors: `error: unexpected argument ...` rc=2.
+// Must run before subcommand registration (children copy _exitCallback at
+// creation time); exitOverride turns commander's process.exit into a throw.
+program.exitOverride();
+program.configureOutput({ outputError: () => {} });
+
 program.name('llman-sdd').description('Spec-driven development workflow').version(version);
+program.option(
+  '--max-scan-depth <n>',
+  'max depth when scanning llmanspec/changes/ for proposal.md (min 1, default 8)',
+  '8',
+);
+// v1 global flag surface parity: accepted everywhere; v2 has no interactive
+// prompts to disable, so it is a no-op.
+program.option('--no-interactive', 'disable interactive prompts (accepted for v1 parity)');
 
 program
   .command('init')
   .description('Initialize llmanspec in your project (--update to refresh existing)')
+  .argument('[path]', 'target directory (created when missing; defaults to cwd)')
   .option('--update', 'refresh an existing installation')
   .option('--locale <locale>', 'locale for generated templates (defaults to config or en)')
-  .action((options: { update?: boolean; locale?: string }) => {
-    const result = runInit(makeIo(process.cwd()), templateIo, {
-      update: options.update ?? false,
-      locale: options.locale,
-      version,
+  .option('--lang <locale>', 'alias of --locale')
+  .action(
+    (path: string | undefined, options: { update?: boolean; locale?: string; lang?: string }) => {
+      if (options.locale !== undefined && options.lang !== undefined) {
+        console.error('--locale and --lang are mutually exclusive (they are aliases)');
+        process.exitCode = 1;
+        return;
+      }
+      let root = process.cwd();
+      if (path !== undefined) {
+        root = resolve(path);
+        mkdirSync(root, { recursive: true });
+      }
+      const result = runInit(makeIo(root), templateIo, {
+        update: options.update ?? false,
+        locale: options.locale ?? options.lang,
+        version,
+      });
+      const removed = result.removed.length > 0 ? `, removed: ${result.removed.join(', ')}` : '';
+      console.log(`initialized llmanspec (${result.skills.length} skills${removed})`);
+    },
+  );
+
+interface VItem {
+  id: string;
+  type: string;
+  valid: boolean;
+  issues: ChangeIssue[];
+  durationMs: number;
+  staleness: StalenessInfo;
+  matchedViaPrefix: boolean;
+}
+
+function specV1Items(opts: { strict?: boolean }): VItem[] {
+  const io = makeIo(process.cwd());
+  const git = makeCliGit(process.cwd());
+  const entries = discoverSpecs('llmanspec/specs', io);
+  const registry = buildReqRegistry(entries);
+  const duplicateIds = new Set(registry.duplicates.flatMap((d) => d.reqId));
+  const structurallyClean = entries.every((e) => e.doc.errors.length === 0);
+  const duplicatesFor = (reqId: string): boolean => structurallyClean && duplicateIds.has(reqId);
+
+  const items: VItem[] = [];
+  for (const entry of entries) {
+    const cap = entry.doc.header.capability ?? entry.fileName.replace(/\.feature$/u, '');
+    const verdict = validateCapability(entry as never, duplicatesFor, io, {
+      strict: opts.strict === true,
     });
-    const removed = result.removed.length > 0 ? `, removed: ${result.removed.join(', ')}` : '';
-    console.log(`initialized llmanspec (${result.skills.length} skills${removed})`);
-  });
+    const specRel = entry.fileName.startsWith('llmanspec/')
+      ? entry.fileName
+      : `llmanspec/specs/${entry.fileName}`;
+    const staleness = evaluateStaleness({
+      git,
+      root: process.cwd(),
+      specRel,
+      scope: entry.doc.header.scope?.split(',').map((s) => s.trim()) ?? [],
+      baseRefEnv: process.env.LLMANSPEC_BASE_REF,
+    });
+    let issues: ChangeIssue[] = verdict.items.map((i) => ({
+      level: i.level,
+      path: i.id,
+      message: i.message,
+    }));
+    if (opts.strict === true) issues = [...issues, ...applyStrict(staleness.issues)];
+    else issues = [...issues, ...staleness.issues];
+    items.push({
+      id: cap,
+      type: 'spec',
+      valid: issues.every((i) => i.level !== 'ERROR'),
+      issues,
+      durationMs: 0,
+      staleness: staleness.info,
+      matchedViaPrefix: false,
+    });
+  }
+  items.sort((a, b) => (a.id < b.id ? -1 : a.id > b.id ? 1 : a.type.localeCompare(b.type)));
+  return items;
+}
+
+function changeV1Items(names: string[], opts: { stage?: string; strict?: boolean }): VItem[] {
+  const io = makeIo(process.cwd());
+  const config = loadCliConfig();
+  const items: VItem[] = [];
+  for (const name of names) {
+    const res = validateChange(
+      io,
+      process.cwd(),
+      name,
+      {
+        strict_defer: config?.archive?.strict_defer ?? null,
+        min_completion_ratio: config?.archive?.min_completion_ratio ?? null,
+        change_id_pattern: config?.change_id?.pattern ?? null,
+      },
+      { stage: opts.stage as never, strict: opts.strict === true },
+    );
+    items.push({
+      id: name,
+      type: 'change',
+      valid: res.valid,
+      issues: res.issues,
+      durationMs: 0,
+      staleness: notApplicableStaleness(),
+      matchedViaPrefix: false,
+    });
+  }
+  items.sort((a, b) => (a.id < b.id ? -1 : a.id > b.id ? 1 : a.type.localeCompare(b.type)));
+  return items;
+}
+
+function printStalenessLines(info: StalenessInfo): void {
+  if (info.status === 'NOTAPPLICABLE') return;
+  console.log(`Staleness: ${info.status}`);
+  if (info.touchedPaths.length > 0)
+    console.log(`Touched scope paths: ${info.touchedPaths.join(', ')}`);
+  if (info.specUpdated) console.log('Spec file updated since base.');
+  if (info.dirty) console.log('Working tree is dirty; results may be unreliable.');
+  for (const note of info.notes) console.log(`Note: ${note}`);
+}
+
+function renderValidateText(items: VItem[]): void {
+  const passed = items.filter((i) => i.valid).length;
+  const failed = items.length - passed;
+  for (const item of items) {
+    if (item.valid) {
+      console.log(`OK ${item.type}/${item.id}`);
+    } else {
+      console.error(`FAIL ${item.type}/${item.id}`);
+      for (const issue of item.issues) {
+        console.error(`  [${issue.level}] ${issue.path}: ${issue.message}`);
+      }
+    }
+    if (item.type === 'spec') printStalenessLines(item.staleness);
+  }
+  console.log(`Totals: ${passed} passed, ${failed} failed (${items.length} items)`);
+}
+
+function renderValidateJson(items: VItem[], compact: boolean): void {
+  const types = [...new Set(items.map((i) => i.type))] as string[];
+  const summary = {
+    totals: {
+      items: items.length,
+      passed: items.filter((i) => i.valid).length,
+      failed: items.filter((i) => !i.valid).length,
+    },
+    byType: types.reduce<Record<string, { items: number; passed: number; failed: number }>>(
+      (acc, t) => {
+        const of = items.filter((i) => i.type === t);
+        acc[t] = {
+          items: of.length,
+          passed: of.filter((i) => i.valid).length,
+          failed: of.filter((i) => !i.valid).length,
+        };
+        return acc;
+      },
+      {},
+    ),
+  };
+  const out = JSON.stringify({ items, summary, version: '1.0' }, null, compact ? 0 : 2);
+  console.log(compact ? JSON.stringify(JSON.parse(out)) : out);
+}
+
+const SPEC_NEXT_STEPS = [
+  '- Ensure spec ISON includes `purpose` and `requirements`',
+  '- Each requirement MUST include at least one scenario object',
+  '- Re-run with --json to see structured report',
+];
+const CHANGE_NEXT_STEPS = [
+  '- Edit live single-track specs (`llmanspec/specs/<capability>.feature`) on the feature branch (@human constraints and @executable acceptance share one track, linked via @req); run `llman sdd change start <id>` or `change attach <id>`',
+  '- Ensure proposal.md, design.md (if needed), and tasks.md are complete before apply',
+  '- Debug change state: llman sdd show <id> --json --type change',
+];
 
 program
   .command('validate')
-  .description('Validate specs under llmanspec/specs (structural gates)')
-  .option('--specs', 'validate specs (default and only scope for now)')
+  .description('Validate specs and changes (structural gates + stage/completion rules)')
+  .argument('[item]', 'spec id or change id (auto-disambiguated)')
+  .option('--all', 'validate all specs and all changes')
+  .option('--changes', 'restrict scope to changes')
+  .option('--specs', 'restrict scope to specs')
+  .option('--type <type>', 'force disambiguation: change | spec')
+  .option('--stage <stage>', 'change stage gate: draft | designed | planned | full')
+  .option('--strict', 'warnings also make the exit code non-zero')
+  .option('--json', 'emit {items:[{id,type,valid,issues}]}')
+  .option('--compact-json', 'single-line --json (requires --json)')
   .option('--no-check', 'skip the bdd.run_command check (structural validation only)')
-  .action((options: { specs?: boolean; check: boolean }) => {
-    // Node 下管道 stdout 写入异步,process.exit 会截断输出;exitCode 等价且安全。
-    process.exitCode = runValidateSpecs(options);
-  });
+  .option('--check', 'run the bdd.run_command check (default when configured; accepted alias)')
+  .action(
+    (
+      item: string | undefined,
+      options: {
+        all?: boolean;
+        changes?: boolean;
+        specs?: boolean;
+        type?: string;
+        stage?: string;
+        strict?: boolean;
+        json?: boolean;
+        compactJson?: boolean;
+        noCheck?: boolean;
+        check?: boolean;
+      },
+    ) => {
+      if (options.compactJson && !options.json) {
+        console.error('--compact-json requires --json');
+        process.exitCode = 1;
+        return;
+      }
+      if (options.type !== undefined && options.type !== 'change' && options.type !== 'spec') {
+        console.error(`invalid --type: ${options.type}`);
+        process.exitCode = 1;
+        return;
+      }
+      if (
+        options.stage !== undefined &&
+        !(STAGE_ORDER as readonly string[]).includes(options.stage)
+      ) {
+        console.error(`invalid --stage: ${options.stage}`);
+        process.exitCode = 1;
+        return;
+      }
+
+      // ---- single item (auto-disambiguate: spec first, then change) ----
+      if (item !== undefined) {
+        const entries = discoverSpecs('llmanspec/specs', makeIo(process.cwd()));
+        const specEntry =
+          options.type === 'change'
+            ? undefined
+            : entries.find(
+                (e) => (e.doc.header.capability ?? e.fileName.replace(/\.feature$/u, '')) === item,
+              );
+        if (specEntry !== undefined) {
+          const items = specV1Items({ strict: options.strict });
+          const mine = items.find((i) => i.id === item);
+          if (mine === undefined) {
+            console.error(`no spec or change matches: ${item}`);
+            process.exitCode = 1;
+            return;
+          }
+          if (options.json) {
+            renderValidateJson([mine], options.compactJson === true);
+            process.exitCode = mine.valid ? 0 : 1;
+            return;
+          }
+          if (mine.valid) {
+            console.log(`Specification '${item}' is valid`);
+          } else {
+            console.error(`Specification '${item}' has issues`);
+            for (const issue of mine.issues)
+              console.error(`  [${issue.level}] ${issue.path}: ${issue.message}`);
+            console.error('Next steps:');
+            for (const s of SPEC_NEXT_STEPS) console.error(s);
+          }
+          if (mine.type === 'spec') printStalenessLines(mine.staleness);
+          if (!mine.valid) console.error('Error: validation failed');
+          process.exitCode = mine.valid ? 0 : 1;
+          return;
+        }
+        // change single
+        const io = makeIo(process.cwd());
+        const root = process.cwd();
+        const res = validateChange(
+          io,
+          root,
+          item,
+          {
+            strict_defer: loadCliConfig()?.archive?.strict_defer ?? null,
+            min_completion_ratio: loadCliConfig()?.archive?.min_completion_ratio ?? null,
+            change_id_pattern: loadCliConfig()?.change_id?.pattern ?? null,
+          },
+          { stage: options.stage as never, strict: options.strict === true },
+        );
+        const infos = res.issues.filter((i) => i.level === 'INFO');
+        if (options.json) {
+          renderValidateJson(
+            [
+              {
+                id: item,
+                type: 'change',
+                valid: res.valid,
+                issues: res.issues,
+                durationMs: 0,
+                staleness: notApplicableStaleness(),
+                matchedViaPrefix: false,
+              },
+            ],
+            options.compactJson === true,
+          );
+          process.exitCode = res.valid ? 0 : 1;
+          return;
+        }
+        if (res.valid) {
+          console.log(`Change '${item}' is valid`);
+        } else {
+          console.error(`Change '${item}' has issues`);
+          for (const issue of res.issues.filter((i) => i.level !== 'INFO'))
+            console.error(`  [${issue.level}] ${issue.path}: ${issue.message}`);
+          console.error('Next steps:');
+          for (const s of CHANGE_NEXT_STEPS) console.error(s);
+        }
+        for (const info of infos) console.error(`[${info.level}] ${info.path}: ${info.message}`);
+        if (!res.valid) console.error('Error: validation failed');
+        process.exitCode = res.valid ? 0 : 1;
+        return;
+      }
+
+      // ---- bulk ----
+      const specScope = options.all || !options.changes || options.specs === true;
+      const changeScope = options.all || options.changes === true;
+      const defaultSpecsOnly = !options.all && !options.changes;
+      const effectiveSpecs = defaultSpecsOnly ? true : specScope;
+      const effectiveChanges = defaultSpecsOnly ? false : changeScope;
 
+      let items: VItem[] = [];
+      if (effectiveSpecs) items = items.concat(specV1Items({ strict: options.strict }));
+      if (effectiveChanges) {
+        const names = collectChanges(makeIo(process.cwd()), process.cwd(), new Date(), {
+          maxScanDepth: cliMaxScanDepth(),
+        }).map((c) => c.name);
+        items = items.concat(
+          changeV1Items(names, { stage: options.stage, strict: options.strict }),
+        );
+      }
+      items.sort((a, b) => (a.id < b.id ? -1 : a.id > b.id ? 1 : a.type.localeCompare(b.type)));
+
+      if (options.json) {
+        renderValidateJson(items, options.compactJson === true);
+        if (items.some((i) => !i.valid)) console.error('Error: validation failed');
+        process.exitCode = items.some((i) => !i.valid) ? 1 : 0;
+        return;
+      }
+      renderValidateText(items);
+      if (items.some((i) => !i.valid)) console.error('Error: validation failed');
+      process.exitCode = items.some((i) => !i.valid) ? 1 : 0;
+    },
+  );
 const change = program
   .command('change')
   .description('Change lifecycle: new / start / attach / next-id / diff / finalize');
@@ -121,128 +488,376 @@ change
   .description('Create a change draft (exactly one of <id> or --from)')
   .argument('[id]')
   .option('--from <description>', 'description the id is derived from')
-  .action((id: string | undefined, options: { from?: string }) => {
-    if ((id === undefined) === (options.from === undefined)) {
-      console.error('<CHANGE> and --from are mutually exclusive; pass one or the other');
-      process.exitCode = 1;
-      return;
-    }
-    const io = makeIo(process.cwd());
-    const result = newChange(io, { id, from: options.from });
-    if (options.from !== undefined) console.log(`derived change id: ${result.id}`);
-    console.log(result.path);
-  });
+  .option('--verb <verb>', 'explicit verb for change_id.template rendering')
+  .option('--force', 'overwrite an existing proposal.md')
+  .option('--dry-run', 'print the resulting id without creating anything')
+  .action(
+    (
+      id: string | undefined,
+      options: { from?: string; verb?: string; force?: boolean; dryRun?: boolean },
+    ) => {
+      if ((id === undefined) === (options.from === undefined)) {
+        console.error('<CHANGE> and --from are mutually exclusive; pass one or the other');
+        process.exitCode = 1;
+        return;
+      }
+      if (options.dryRun) {
+        console.log(id ?? deriveChangeId(options.from as string));
+        return;
+      }
+      const cliConfig = loadCliConfig();
+      const template = cliConfig?.change_id?.template;
+      if (options.from !== undefined && template) {
+        const slug = deriveChangeId(options.from);
+        const { verb, subject } = splitVerb(slug, (options as { verb?: string }).verb);
+        const derived = renderChangeIdTemplate(template, {
+          llman_sdd_unique_id: nextUniqueNumber(
+            {
+              listDir: (p) => readdirSync(resolve(p)),
+              isDirectory: (p) => statSync(resolve(p)).isDirectory(),
+            },
+            'llmanspec',
+          ),
+          verb,
+          subject,
+          date: new Date().toISOString().slice(0, 10),
+        });
+        console.log(`derived change id: ${derived}`);
+        const io = makeIo(process.cwd());
+        const result = newChange(io, { id: derived, force: options.force });
+        console.log(`./${result.path}`);
+        return;
+      }
+      const io = makeIo(process.cwd());
+      const result = newChange(io, { id, from: options.from, force: options.force });
+      if (options.from !== undefined) console.log(`derived change id: ${result.id}`);
+      console.log(`./${result.path}`);
+    },
+  );
 
 change
   .command('start')
   .description('Bind the change to a new feature branch (clean tree + default branch gates)')
   .argument('<id>')
-  .option('--branch-prefix <prefix>', 'feature branch prefix', 'sdd/')
-  .action((id: string, options: { branchPrefix: string }) => {
+  .option(
+    '--branch-prefix <prefix>',
+    'feature branch prefix (default: sdd.branch_prefix config, then sdd/)',
+  )
+  .action((id: string, options: { branchPrefix?: string }) => {
     const git = makeCliGit(process.cwd());
+    const config = loadCliConfig();
     const result = startChange(git, makeIo(process.cwd()), id, {
-      branchPrefix: options.branchPrefix,
+      branchPrefix: options.branchPrefix ?? config?.sdd?.branch_prefix ?? 'sdd/',
     });
     console.log(
-      `started change \`${id}\` → branch \`${result.branch}\` (base ${result.baseBranch}@${result.baseSha.slice(0, 7)})`,
+      `started change \`${id}\` → branch \`${result.branch}\` base \`${result.baseSha}\` base-branch \`${result.baseBranch}\``,
     );
   });
 
 change
   .command('attach')
-  .description('Bind the change to the current branch (no gates)')
+  .description('Bind the change to the current feature branch')
   .argument('<id>')
-  .action((id: string) => {
-    const result = attachChange(makeCliGit(process.cwd()), makeIo(process.cwd()), id);
-    console.log(`attached change \`${id}\` → branch \`${result.branch}\``);
+  .option('--force', 'rebind an already attached change to the current branch')
+  .option('--base <branch>', 'explicit fork-point branch to record')
+  .action((id: string, options: { force?: boolean; base?: string }) => {
+    const result = attachChange(makeCliGit(process.cwd()), makeIo(process.cwd()), id, {
+      force: options.force,
+      base: options.base,
+    });
+    console.log(
+      `attached change \`${id}\` → branch \`${result.branch}\` base \`${result.baseSha}\` base-branch \`${result.baseBranch}\``,
+    );
   });
 
 change
   .command('next-id')
-  .description('Preview the derived change id for a description')
-  .requiredOption('--from <description>', 'description the id is derived from')
-  .action((options: { from: string }) => {
-    console.log(deriveChangeId(options.from));
+  .description('Preview the next free change id number (read-only)')
+  .option('--json', 'emit {maxNumber, nextNumber, warnings}')
+  .action((options: { json?: boolean }) => {
+    const harvest = harvestUniqueNumbers(
+      {
+        listDir: (p) => readdirSync(resolve(p)),
+        isDirectory: (p) => statSync(resolve(p)).isDirectory(),
+      },
+      'llmanspec',
+    );
+    if (options.json) {
+      console.log(JSON.stringify(harvest, null, 2));
+      return;
+    }
+    if (harvest.maxNumber === null) console.log('no numbered change dirs found in tree');
+    else console.log(`max number in tree: ${harvest.maxNumber}`);
+    console.log(`next free number: ${harvest.nextNumber}`);
+    for (const w of harvest.warnings) console.error(`warning: ${w}`);
   });
 
+change
+  .command('archive')
+  .description('Independent seal-off: task gates + merge + archive rename + commit')
+  .argument('<id>')
+  .option('--into <branch>', 'target branch to merge into')
+  .option('--method <method>', 'merge method: squash | ff')
+  .option('--dry-run', 'print the rename plan only')
+  .option('--skip-specs', 'legacy flag accepted for v1 parity (no longer merges deltas)')
+  .addOption(new Option('--force', 'skip task and git gates').hideHelp())
+  .action(
+    (
+      id: string,
+      options: { into?: string; method?: string; dryRun?: boolean; force?: boolean },
+    ) => {
+      if (options.method !== undefined && options.method !== 'squash' && options.method !== 'ff') {
+        console.error(`invalid --method \`${options.method}\` (squash | ff)`);
+        process.exitCode = 1;
+        return;
+      }
+      const io = makeIo(process.cwd());
+      if (options.dryRun) {
+        const date = new Date().toISOString().slice(0, 10);
+        console.log(
+          `Would move llmanspec/changes/${id} -> llmanspec/changes/archive/${date}-${id}`,
+        );
+        return;
+      }
+      const config = existsSync('llmanspec/config.yaml')
+        ? loadConfig(readFileSync('llmanspec/config.yaml', 'utf8'))
+        : null;
+      // v1 task gate: blocked output + options list before the error.
+      if (!options.force) {
+        const tasksPath = `llmanspec/changes/${id}/tasks.md`;
+        if (existsSync(tasksPath)) {
+          const pending: string[] = [];
+          for (const line of readFileSync(tasksPath, 'utf8').split('\n')) {
+            const m = line.match(/^\s*-\s+\[ \]\s*(.*)$/u);
+            if (m && m[1] !== undefined) pending.push(m[1].trim());
+          }
+          if (pending.length > 0) {
+            console.error(`Archive blocked: ${pending.length} unchecked task(s).`);
+            for (const item of pending) console.error(`  - [ ] ${item}`);
+            console.error(
+              'Options:\n  1. Complete the remaining tasks\n  2. Use --force to archive anyway (not recommended)',
+            );
+            throw new Error('archive blocked by unchecked tasks');
+          }
+        }
+      }
+      const result = archiveChange(makeCliGit(process.cwd()), io, id, {
+        into: options.into,
+        method: options.method as 'squash' | 'ff' | undefined,
+        force: options.force,
+        minCompletionRatio: config?.archive?.min_completion_ratio ?? undefined,
+      });
+      const archiveName = (result.archiveDir ?? '').slice(
+        (result.archiveDir ?? '').lastIndexOf('/') + 1,
+      );
+      console.log(`Change '${id}' archived as '${archiveName}'.`);
+    },
+  );
+
 change
   .command('diff')
   .description('Print the bound branch diff vs base')
   .argument('<id>')
-  .action((id: string) => {
-    console.log(changeDiff(makeCliGit(process.cwd()), makeIo(process.cwd()), id));
+  .option('--json', 'emit {change, branch, base, commitCount}')
+  .option('--export-patch <path>', 'write the diff to a file instead of stdout')
+  .action((id: string, options: { json?: boolean; exportPatch?: string }) => {
+    const git = makeCliGit(process.cwd());
+    if (options.json) {
+      const info = changeDiffInfo(git, makeIo(process.cwd()), id);
+      console.log(JSON.stringify(info, null, 2));
+      return;
+    }
+    const diff = changeDiff(git, makeIo(process.cwd()), id);
+    if (options.exportPatch !== undefined) {
+      writeFileSync(options.exportPatch, diff);
+      console.log(`wrote ${options.exportPatch}`);
+      return;
+    }
+    console.log(diff);
   });
 
 change
   .command('finalize')
-  .description('Merge the feature branch, archive docs, and close out with one commit')
+  .description('Validate, merge the feature branch, archive docs, close out with one commit')
   .argument('<id>')
   .option('--into <branch>', 'merge target override (defaults to base_branch)')
-  .option('--method <method>', 'merge method: squash (default) or ff', 'squash')
-  .action((id: string, options: { into?: string; method: string }) => {
-    if (options.method !== 'squash' && options.method !== 'ff') {
-      console.error(`invalid --method: ${options.method}`);
-      process.exitCode = 1;
-      return;
-    }
-    const result = finalizeChange(makeCliGit(process.cwd()), makeIo(process.cwd()), id, {
-      into: options.into,
-      method: options.method,
-    });
-    for (const w of result.warnings) console.error(`[WARNING] ${w}`);
-    console.log(
-      `finalized \`${id}\` → ${result.archiveDir} (commit "${result.commitSubject}" on ${result.target})`,
-    );
-  });
+  .option(
+    '--method <method>',
+    'merge method: squash | ff (default: sdd.merge_method config, then squash)',
+  )
+  .option('--no-check', 'skip the pre-merge validation sweep')
+  .option('--no-commit', 'skip the close-out commit (manual/CI history)')
+  .action(
+    (
+      id: string,
+      options: { into?: string; method?: string; check?: boolean; commit?: boolean },
+    ) => {
+      if (options.method !== undefined && options.method !== 'squash' && options.method !== 'ff') {
+        console.error(`invalid --method: ${options.method}`);
+        process.exitCode = 1;
+        return;
+      }
+      if (options.check !== false) {
+        const failed = runValidateSweep();
+        if (failed) {
+          console.error('finalize aborted: validation sweep failed (use --no-check to skip)');
+          process.exitCode = 1;
+          return;
+        }
+      }
+      const config = loadCliConfig();
+      const method = options.method ?? config?.sdd?.merge_method ?? 'squash';
+      const result = finalizeChange(makeCliGit(process.cwd()), makeIo(process.cwd()), id, {
+        into: options.into,
+        method: method as 'squash' | 'ff',
+        noCommit: options.commit === false,
+      });
+      for (const w of result.warnings) console.error(`[WARNING] ${w}`);
+      if (options.commit === false) {
+        console.log(
+          `finalized \`${id}\` → ${result.archiveDir} on ${result.target} (close-out commit skipped — run: git add -A && git commit -m "archive(sdd): ${id}")`,
+        );
+        return;
+      }
+      console.log(
+        `finalized \`${id}\` → ${result.archiveDir} (commit "${result.commitSubject}" on ${result.target})`,
+      );
+    },
+  );
 
 program
   .command('list')
   .description('List changes or specs')
+  .option('--changes', 'list changes (v1 explicit scope flag; default)')
   .option('--specs', 'list specs instead of changes')
   .option('--json', 'machine-readable output')
-  .action((options: { specs?: boolean; json?: boolean }) => {
+  .option('--compact-json', 'single-line --json (requires --json)')
+  .option('--sort <order>', 'recent (mtime desc, default) | name')
+  .action((options: { specs?: boolean; json?: boolean; compactJson?: boolean; sort?: string }) => {
+    if (options.compactJson && !options.json) {
+      console.error('--compact-json requires --json');
+      process.exitCode = 1;
+      return;
+    }
+    if (options.sort !== undefined && options.sort !== 'recent' && options.sort !== 'name') {
+      console.error(`invalid --sort: ${options.sort}`);
+      process.exitCode = 1;
+      return;
+    }
+    const emit = (text: string): void => {
+      console.log(options.compactJson ? text.replaceAll('\n', '') : text);
+    };
     if (options.specs) {
       const summaries = collectSpecs(loadSpecEntries());
-      console.log(
-        options.json ? renderSpecsJson(summaries) : renderSpecsList(summaries).join('\n'),
-      );
+      emit(options.json ? renderSpecsJson(summaries) : renderSpecsList(summaries).join('\n'));
       return;
     }
-    const changes = collectChanges(makeIo(process.cwd()), process.cwd(), new Date());
-    console.log(
+    let changes = collectChanges(makeIo(process.cwd()), process.cwd(), new Date(), {
+      maxScanDepth: cliMaxScanDepth(),
+    });
+    if (options.sort === 'name') {
+      changes = [...changes].toSorted((a, b) => a.name.localeCompare(b.name));
+    }
+    emit(
       options.json ? renderChangesJson(changes) : renderChangesList(changes, new Date()).join('\n'),
     );
   });
 
 program
   .command('show')
-  .description('Show a change (JSON) or a spec (text)')
+  .description('Show a change or spec')
   .argument('<item>')
-  .option('--output <format>', 'output format: json, meta-only, reqs-only, no-scenarios')
+  .option('--output <format>', 'json | compact | meta-only | no-scenarios | deltas | reqs-only')
   .option('--type <itemType>', 'item type hint: change|spec')
-  .action((item: string, options: { output?: string; type?: string }) => {
+  .option('-r, --requirement <n>', 'spec only: show a specific requirement by 1-based index')
+  .action((item: string, options: { output?: string; type?: string; requirement?: string }) => {
+    const outTokens = new Set(
+      (options.output ?? '')
+        .split(',')
+        .map((t) => t.trim())
+        .filter((t) => t !== ''),
+    );
+    const asJson = outTokens.has('json');
+    const asCompact = outTokens.has('compact');
+    const metaOnly = outTokens.has('meta-only');
+    const noScenarios = outTokens.has('no-scenarios');
+    const reqsOnly = outTokens.has('reqs-only');
+    // v1: unknown output tokens are rejected by clap; script consumers rely on
+    // the deprecation being a no-op render rather than an error.
     const isSpec =
       options.type === 'spec' || existsSync(join('llmanspec', 'specs', `${item}.feature`));
+
     if (isSpec) {
-      const path = join('llmanspec', 'specs', `${item}.feature`);
-      if (!existsSync(path)) {
+      const specPath = join('llmanspec', 'specs', `${item}.feature`);
+      if (!existsSync(specPath)) {
         console.error(`spec not found: ${item}`);
         process.exitCode = 1;
         return;
       }
+      if (asJson) {
+        console.log(
+          JSON.stringify(
+            renderSpecJson(item, {
+              metaOnly,
+              noScenarios: noScenarios || reqsOnly,
+            }),
+            null,
+            asCompact ? 0 : 2,
+          ),
+        );
+        return;
+      }
+      // text mode: v1 ignores all output modifiers (meta-only/no-scenarios/-r)
+      // and renders the full source + morphology.
+      const raw = readFileSync(specPath, 'utf8').trimEnd();
       const summary = collectSpecs(loadSpecEntries()).find((x) => x.id === item);
       const morphology = summary
         ? `\n\n## Morphology\nruleCount=${summary.morphology.ruleCount} enforced=${summary.morphology.ruleEnforcedCount} manual=${summary.morphology.ruleManualCount} pending=${summary.morphology.rulePendingCount} acceptanceCount=${summary.morphology.acceptanceCount}`
         : '';
-      console.log(`## Spec\n${readFileSync(path, 'utf8').trimEnd()}${morphology}`);
+      console.log(`## Spec\n${raw}${morphology}`);
       return;
     }
-    if (options.output !== 'json') {
-      console.error('only --output json is supported for changes (text format pending)');
+
+    // ---- change ----
+    const proposalPath = join('llmanspec', 'changes', item, 'proposal.md');
+    if (!existsSync(proposalPath)) {
+      console.error(`change not found: ${item}`);
       process.exitCode = 1;
       return;
     }
-    const result = showChangeJson(
+    const proposal = readFileSync(proposalPath, 'utf8');
+    if (asJson) {
+      // v1 parse_change gates: Why first, then What Changes (json only).
+      if (!hasSection(proposal, 'Why')) {
+        process.exitCode = 1;
+        throw new Error('Change must have a Why section');
+      }
+      if (!hasSection(proposal, 'What Changes')) {
+        process.exitCode = 1;
+        throw new Error('Change must have a What Changes section');
+      }
+      const result = showChangeJson(
+        {
+          io: makeIo(process.cwd()),
+          git: makeCliGit(process.cwd()),
+          root: process.cwd(),
+          specsDir: 'llmanspec/specs',
+        },
+        item,
+      );
+      console.log(JSON.stringify(result, null, asCompact ? 0 : 2));
+      return;
+    }
+    // text: Stage / path / content / Gates trailer (no section gates).
+    const changes = collectChanges(makeIo(process.cwd()), process.cwd(), new Date(), {
+      maxScanDepth: cliMaxScanDepth(),
+    });
+    const change = changes.find((c) => c.name === item);
+    console.log(`Stage: ${change?.stage ?? 'draft'}`);
+    console.log(`path: ${item}`);
+    process.stdout.write(proposal);
+    if (!proposal.endsWith('\n')) console.log();
+    const gates = showChangeJson(
       {
         io: makeIo(process.cwd()),
         git: makeCliGit(process.cwd()),
@@ -250,22 +865,130 @@ program
         specsDir: 'llmanspec/specs',
       },
       item,
-    );
-    console.log(JSON.stringify(result, null, 2));
+    ).gateChecks as { name: string; pass: boolean; hint: string }[];
+    const passCount = gates.filter((g) => g.pass).length;
+    console.log(`Gates: ${passCount}/${gates.length} pass`);
+    for (const g of gates.filter((g) => !g.pass)) console.log(`✗ ${g.name}: ${g.hint}`);
   });
 
+function hasSection(proposal: string, heading: string): boolean {
+  return (
+    new RegExp(`^## ${heading.replace(/[/\\]/u, '')}\\s*$`, 'mu').test(proposal) ||
+    proposal.includes(`## ${heading}`)
+  );
+}
+
+function renderSpecJson(
+  item: string,
+  opts: { metaOnly: boolean; noScenarios: boolean },
+): Record<string, unknown> {
+  const entry = loadSpecEntries().find(
+    (e) => (e.doc.header.capability ?? e.fileName.replace(/\.feature$/u, '')) === item,
+  );
+  const doc = entry?.doc as
+    | {
+        header: { capability: string | null; purpose: string | null };
+        scenarios: {
+          name: string;
+          classification: string;
+          reqIds: string[];
+          statement: string;
+          steps: { kind: string; text: string }[];
+        }[];
+      }
+    | undefined;
+  const cap = entry ? (doc?.header.capability ?? item) : item;
+  const purpose = doc?.header.purpose ?? '';
+  const humans = doc?.scenarios.filter((s) => s.classification === 'human') ?? [];
+  const acceptances = doc?.scenarios.filter((s) => s.classification === 'executable') ?? [];
+  const morphology = {
+    ruleCount: humans.length,
+    ruleEnforcedCount: humans.filter((r) =>
+      acceptances.some((a) => a.reqIds.some((rid) => r.reqIds.includes(rid))),
+    ).length,
+    ruleManualCount: humans.filter(
+      (r) => r.reqIds.includes('manual') || r.statement.includes('@manual'),
+    ).length,
+    rulePendingCount: humans.filter(
+      (r) => !acceptances.some((a) => a.reqIds.some((rid) => r.reqIds.includes(rid))),
+    ).length,
+    acceptanceCount: acceptances.length,
+    orphanAcceptanceCount: acceptances.filter((a) => a.reqIds.length === 0).length,
+  };
+  if (opts.metaOnly) {
+    return {
+      id: item,
+      featureId: cap,
+      title: cap,
+      purpose,
+      overview: purpose,
+      requirementCount: humans.length,
+      morphology,
+    };
+  }
+  const requirements = humans.map((rule) => ({
+    reqId: rule.reqIds[0] ?? '',
+    title: rule.name,
+    text: rule.statement,
+    scenarios: opts.noScenarios
+      ? []
+      : acceptances
+          .filter((a) => a.reqIds.some((rid) => rule.reqIds.includes(rid)))
+          .map((a) => ({
+            id: a.name,
+            rawText: `GIVEN: ${a.steps
+              .filter((s) => s.kind === 'given')
+              .map((s) => s.text)
+              .join('\n')}\nWHEN: ${a.steps
+              .filter((s) => s.kind === 'when')
+              .map((s) => s.text)
+              .join('\n')}\nTHEN: ${a.steps
+              .filter((s) => s.kind === 'then')
+              .map((s) => s.text)
+              .join('\n')}`,
+            source: 'acceptance',
+            reqIds: a.reqIds,
+          })),
+  }));
+  return {
+    id: item,
+    title: cap,
+    purpose,
+    overview: purpose,
+    requirementCount: humans.length,
+    requirements,
+    morphology,
+  };
+}
+
 program
   .command('graph')
   .description('Generate a change dependency graph (mermaid)')
+  .argument('[change]', 'seed change id (BFS over depends_on)')
   .option('--format <format>', 'output format', 'mermaid')
-  .action((options: { format: string }) => {
-    if (options.format !== 'mermaid') {
-      console.error(`unsupported format: ${options.format}`);
-      process.exitCode = 1;
-      return;
-    }
-    console.log(graphMermaid(makeIo(process.cwd()), process.cwd()).join('\n'));
-  });
+  .option('--scope <scope>', 'active | archived | all (comma-combined)', 'active')
+  .option('--depth <n>', 'seed BFS depth (default: 1)')
+  .action(
+    (change: string | undefined, options: { format: string; scope?: string; depth?: string }) => {
+      if (options.format !== 'mermaid') {
+        process.exitCode = 1;
+        throw new Error(`Unsupported format: ${options.format}. Supported: mermaid`);
+      }
+      const depth = options.depth !== undefined ? Number(options.depth) : undefined;
+      if (depth !== undefined && (!Number.isInteger(depth) || depth < 0)) {
+        console.error(`invalid --depth: ${options.depth}`);
+        process.exitCode = 1;
+        return;
+      }
+      console.log(
+        graphMermaid(makeIo(process.cwd()), process.cwd(), {
+          scope: options.scope,
+          depth: depth ?? 1,
+          seed: change,
+        }).join('\n'),
+      );
+    },
+  );
 
 const spec = program.command('spec').description('Spec authoring helpers');
 
@@ -273,23 +996,71 @@ spec
   .command('skeleton')
   .description('Generate a single-track spec skeleton for a capability')
   .argument('<capability>')
-  .action((capability: string) => {
+  .option('--force', 'overwrite an existing spec file')
+  .action((capability: string, options: { force?: boolean }) => {
     const locale = existsSync('llmanspec/config.yaml')
       ? loadConfig(readFileSync('llmanspec/config.yaml', 'utf8')).locale
       : 'en';
-    const path = scaffoldSpec(makeIo(process.cwd()), 'llmanspec/specs', capability, locale);
-    console.log(`wrote ${path}`);
+    const path = join('llmanspec', 'specs', `${capability}.feature`);
+    if (!options.force && existsSync(path)) {
+      console.error(`spec already exists: ${path} (use --force to overwrite)`);
+      process.exitCode = 1;
+      return;
+    }
+    const written = scaffoldSpec(makeIo(process.cwd()), 'llmanspec/specs', capability, locale, {
+      force: options.force,
+    });
+    console.log(`wrote ${written}`);
   });
 
 spec
   .command('next-req-id')
   .description('Allocate the next free global req id (rN)')
-  .action(() => {
-    console.log(nextReqId(makeIo(process.cwd()), 'llmanspec/specs'));
+  .option('--json', 'emit {reqId}')
+  .action((options: { json?: boolean }) => {
+    const reqId = nextReqId(makeIo(process.cwd()), 'llmanspec/specs');
+    if (options.json) console.log(JSON.stringify({ reqId }, null, 2));
+    else console.log(reqId);
   });
 
 const project = program.command('project').description('Project management commands');
 
+project
+  .command('dedupe-req-ids')
+  .description('Remap globally duplicated req ids (report with --dry-run)')
+  .option('--dry-run', 'report the remap plan without writing')
+  .action((options: { dryRun?: boolean }) => {
+    // v1 parity: dedupe registry covers @human (rule) req ids only.
+    const entries = loadSpecEntries();
+    const owners = new Map<string, string[]>();
+    for (const e of entries) {
+      for (const sc of e.doc.scenarios) {
+        if (sc.classification !== 'human') continue;
+        for (const rid of sc.reqIds) {
+          const list = owners.get(rid) ?? [];
+          if (!list.includes(e.fileName)) list.push(e.fileName);
+          owners.set(rid, list);
+        }
+      }
+    }
+    const duplicates = [...owners.entries()]
+      .filter(([, files]) => files.length > 1)
+      .map(([reqId, files]) => ({ reqId, files }));
+    if (duplicates.length === 0) {
+      console.log('No colliding req_id values in llmanspec/specs.');
+      return;
+    }
+    const io = makeIo(process.cwd());
+    const plan = planDedupe(entries, io, 'llmanspec/specs', duplicates);
+    // v1 output: `{cap}: {from} → {to}` per remap (prefix in dry-run) + count line.
+    for (const item of plan) {
+      const cap = item.remapFile.replace(/^.*specs\//u, '').replace(/\.feature$/u, '');
+      const prefix = options.dryRun ? '[dry-run] ' : '';
+      console.log(`${prefix}${cap}: ${item.reqId} → ${item.newReqId}`);
+    }
+    console.log(`${plan.length} remapping(s)${options.dryRun ? ' (dry-run)' : ''}`);
+  });
+
 project
   .command('migrate')
   .description('Legacy migration entry (informational only)')
@@ -315,19 +1086,26 @@ archive
   .option('--list', 'list entries already in the cold-backup archive')
   .action(
     async (options: { before?: string; keepRecent: string; dryRun?: boolean; list?: boolean }) => {
-      const sz = await makeWasmSevenZip();
-      const root = process.cwd();
-      const io = makeIo(root);
-      if (options.list) {
-        for (const line of await runList(io, sz, root)) console.log(line);
-        return;
+      try {
+        const sz = await makeWasmSevenZip();
+        const root = process.cwd();
+        const io = makeIo(root);
+        if (options.list) {
+          for (const line of await runList(io, sz, root)) console.log(line);
+          return;
+        }
+        const result = await runFreeze(io, sz, root, {
+          before: options.before,
+          keepRecent: Number(options.keepRecent),
+          dryRun: options.dryRun,
+        });
+        for (const line of result.lines) console.log(line);
+      } catch (error) {
+        // Emscripten aborts (e.g. wasm load failure) throw raw RuntimeErrors —
+        // keep the CLI surface one-line like thaw does.
+        console.error((error as Error).message);
+        process.exitCode = 1;
       }
-      const result = await runFreeze(io, sz, root, {
-        before: options.before,
-        keepRecent: Number(options.keepRecent),
-        dryRun: options.dryRun,
-      });
-      for (const line of result.lines) console.log(line);
     },
   );
 
@@ -343,15 +1121,19 @@ archive
     },
     [] as string[],
   )
-  .action(async (options: { change: string[] }) => {
+  .option('--dest <path>', 'restore into this directory (created when missing)')
+  .action(async (options: { change: string[]; dest?: string }) => {
+    if (options.dest !== undefined) {
+      mkdirSync(resolve(options.dest), { recursive: true });
+    }
     const sz = await makeWasmSevenZip();
     const root = process.cwd();
     const io = makeIo(root);
     try {
-      const result = await runThaw(io, sz, root, options.change);
+      const result = await runThaw(io, sz, root, options.change, { dest: options.dest });
       for (const line of result.lines) console.log(line);
     } catch (error) {
-      console.error((error as Error).message);
+      console.error(`Error: ${(error as Error).message}`);
       process.exitCode = 1;
     }
   });
@@ -370,13 +1152,28 @@ review
       : null;
     const bindings = config?.bdd?.bindings?.filter((b) => b.kind === 'tags') ?? [];
     const io = makeIo(process.cwd());
+    const entries = loadSpecEntries();
+    if (options.capability !== undefined) {
+      const known = new Set(
+        entries.map((e) => e.doc.header.capability ?? e.fileName.replace(/\.feature$/u, '')),
+      );
+      if (!known.has(options.capability)) {
+        console.error(`capability \`${options.capability}\` not found`);
+        process.exitCode = 1;
+        return;
+      }
+    }
     const activeChanges = collectChanges(io, process.cwd(), new Date());
     const result = buildReview(
       {
-        entries: loadSpecEntries(),
+        entries,
         bindings: bindings.map((b) => ({ kind: 'tags', tags: b.tags })),
         boundChangeCount: activeChanges.filter((c) => c.hasBinding).length,
         activeChanges,
+        capability: options.capability,
+        git: makeCliGit(process.cwd()),
+        root: process.cwd(),
+        specsDir: 'llmanspec/specs',
       },
       io,
     );
@@ -393,6 +1190,121 @@ review
     if (result.exitCode !== 0) process.exitCode = result.exitCode;
   });
 
+spec
+  .command('add-req')
+  .alias('add-requirement')
+  .description('Append a @human rule scenario to a capability spec')
+  .argument('<capability>')
+  .argument('<req_id>')
+  .requiredOption('--title <title>', 'rule title')
+  .requiredOption('--statement <statement>', 'rule statement (must contain MUST/SHALL)')
+  .action((capability: string, reqId: string, options: { title: string; statement: string }) => {
+    const io = makeIo(process.cwd());
+    const path = addReq(io, 'llmanspec/specs', loadSpecEntries(), {
+      capability,
+      reqId,
+      title: options.title,
+      statement: options.statement,
+    });
+    console.log(path);
+  });
+
+spec
+  .command('add-scenario')
+  .description('Append an @executable acceptance scenario bound to a req')
+  .argument('<capability>')
+  .argument('<req_id>')
+  .argument('<scenario_id>')
+  .option('--given <given>', 'Given step (optional)')
+  .requiredOption('--when <when>', 'When step')
+  .requiredOption('--then <then>', 'Then step')
+  .action(
+    (
+      capability: string,
+      reqId: string,
+      scenarioId: string,
+      options: { given?: string; when: string; then: string },
+    ) => {
+      const io = makeIo(process.cwd());
+      const path = addScenario(io, 'llmanspec/specs', loadSpecEntries(), {
+        capability,
+        reqId,
+        scenarioId,
+        given: options.given,
+        when: options.when,
+        thenText: options.then,
+      });
+      console.log(path);
+    },
+  );
+
+spec
+  .command('resolve-req')
+  .description('Resolve an rN to its capability and statement')
+  .argument('<req_id>')
+  .action((reqId: string) => {
+    const resolved = resolveReq(loadSpecEntries(), reqId);
+    if (resolved === null) {
+      console.error(`req id not found: ${reqId}`);
+      process.exitCode = 1;
+      return;
+    }
+    console.log(`reqId: ${resolved.reqId}`);
+    console.log(`capability: ${resolved.capability}`);
+    console.log(`title: ${resolved.title}`);
+    console.log(`statement: ${resolved.statement.replaceAll('\n', ' ')}`);
+    console.log('harness:');
+    for (const h of resolved.harness) console.log(`  - ${h}`);
+  });
+
+const configCmd = program
+  .command('config')
+  .description('Project configuration commands (view/edit config.yaml)');
+
+configCmd.description('Print a read-only llmanspec/config.yaml overview').action(() => {
+  const source = readFileSync('llmanspec/config.yaml', 'utf8');
+  console.log(renderConfigOverview(source).join('\n'));
+});
+
+configCmd
+  .command('skills')
+  .description('Manage extra_skills (non-interactive)')
+  .option('--json', 'emit {enabled, available}')
+  .option('--no-interactive', 'print state instead of launching the interactive picker')
+  .action((options: { json?: boolean }) => {
+    const path = 'llmanspec/config.yaml';
+    const info = skillsJson(readFileSync(path, 'utf8'));
+    if (options.json) {
+      console.log(JSON.stringify(info, null, 2));
+      return;
+    }
+    const enabled = info.enabled;
+    const available = info.available;
+    console.log('Enabled optional skills:');
+    if (enabled.length === 0) console.log('  (none)');
+    else for (const s of enabled) console.log(`  [x] ${s}`);
+    console.log();
+    console.log('Available but not enabled:');
+    for (const s of available) {
+      if (!enabled.includes(s)) console.log(`  [ ] ${s} — ${skillDesc(s)}`);
+    }
+    console.log();
+    console.log('(Run without --no-interactive to edit interactively.)');
+  });
+
+function resolveBackend(flag: string | undefined): 'pageindex' {
+  const chosen = flag ?? process.env.LLMAN_SDD_INDEX_BACKEND ?? 'pageindex';
+  if (chosen === 'rag') {
+    throw new Error(
+      'Backend `rag` is no longer supported. Use the default pageindex backend instead:\nSet `LLMAN_SDD_INDEX_CHAT_MODEL` to a tool-calling chat model, then\nrun `llman sdd index rebuild`.',
+    );
+  }
+  if (chosen !== 'pageindex') {
+    throw new Error(`Unsupported backend: ${chosen}`);
+  }
+  return 'pageindex';
+}
+
 const indexCmd = program
   .command('index')
   .description('Index management commands (rebuild, check freshness)');
@@ -400,11 +1312,14 @@ const indexCmd = program
 indexCmd
   .command('rebuild')
   .description('Rebuild the pageindex tree from spec IR (no LLM)')
-  .action(() => {
+  .option('--backend <name>', 'index backend (pageindex only)')
+  .action((options: { backend?: string }) => {
+    resolveBackend(options.backend);
     const result = rebuildIndex(makeIo(process.cwd()), 'llmanspec/specs', loadSpecEntries(), {
       chatModel: process.env.LLMAN_SDD_INDEX_CHAT_MODEL ?? '',
     });
-    for (const line of result.lines) console.log(line);
+    for (const line of result.lines.slice(0, -1)) console.error(line);
+    if (result.lines.length > 0) console.log(result.lines.at(-1));
   });
 
 indexCmd
@@ -422,7 +1337,9 @@ program
   .option('--task <task>', 'natural language task description')
   .option('--paths <paths>', 'comma-separated file paths')
   .option('--top <n>', 'max entries per tier', '5')
-  .action(async (options: { task?: string; paths?: string; top?: string }) => {
+  .option('--backend <name>', 'retrieval backend (pageindex only)')
+  .action(async (options: { task?: string; paths?: string; top?: string; backend?: string }) => {
+    resolveBackend(options.backend);
     if (!options.task && !options.paths) {
       console.error('at least one of --task or --paths is required');
       process.exitCode = 1;
@@ -453,8 +1370,54 @@ program
     console.log(JSON.stringify(result, null, 2));
   });
 
+function commandChain(argv: string[]): string {
+  let node: Command = program;
+  let chain = '';
+  let rest = argv.slice(2);
+  while (rest.length > 0) {
+    const child = node.commands.find((c) => c.name() === rest[0]);
+    if (child === undefined) break;
+    chain += ` ${child.name()}`;
+    node = child;
+    rest = rest.slice(1);
+    // eslint-disable-next-line no-loop-func
+  }
+  return chain;
+}
+
 async function main(): Promise<void> {
-  await program.parseAsync(process.argv);
+  try {
+    await program.parseAsync(process.argv);
+  } catch (error) {
+    const comErr = error as { code?: string; exitCode?: number; message?: string };
+    if (
+      comErr?.code === 'commander.version' ||
+      comErr?.code === 'commander.help' ||
+      comErr?.code === 'commander.helpDisplayed' ||
+      comErr?.exitCode === 0
+    ) {
+      // version/help already rendered to stdout; exit code stays 0.
+      return;
+    }
+    if (comErr?.code === 'commander.unknownOption') {
+      const raw = String(comErr.message ?? '');
+      const arg = raw.replace(/^error: unknown option ['"]/u, '').replace(/['"]?\s*$/u, '') ?? '';
+      const chain = commandChain(process.argv);
+      console.error(`error: unexpected argument '${arg}' found`);
+      console.error('');
+      console.error(`Usage: llman-sdd${chain} [OPTIONS]`);
+      console.error('');
+      console.error("For more information, try '--help'.");
+      process.exitCode = 2;
+      return;
+    }
+
+    // v1 parity: expected domain errors surface as a single `Error: <message>`
+    // line on stderr with exit code 1 (no Bun stack trace).
+    const message = error instanceof Error ? error.message : String(error);
+    console.error(message.startsWith('Error: ') ? message : `Error: ${message}`);
+    process.exitCode = 1;
+  }
 }
 
 await main();