specweave 1.0.593 → 2.0.0

package/bin/specweave.js

@@ -315,13 +315,20 @@ program
     await pauseCommand(incrementId, options);
   });
 
+program
+  .command('start <increment-id>')
+  .description('Start a planned/backlog/paused increment (status -> active)')
+  .action(async (incrementId) => {
+    const { startCommand } = await import('../dist/src/cli/commands/start.js');
+    await startCommand(incrementId);
+  });
+
 program
   .command('resume <increment-id>')
-  .description('Resume a paused or abandoned increment')
-  .option('-f, --force', 'Force resume (bypass WIP limit checks)')
-  .action(async (incrementId, options) => {
+  .description('Resume a paused, abandoned or not-yet-started increment')
+  .action(async (incrementId) => {
     const { resumeCommand } = await import('../dist/src/cli/commands/resume.js');
-    await resumeCommand(incrementId, options);
+    await resumeCommand(incrementId);
   });
 
 program
@@ -336,34 +343,68 @@ program
 
 // Complete command - Mark increment(s) as complete (triggers external sync)
 program
-  .command('complete <increment-id> [more-ids...]')
+  .command('complete [increment-id] [more-ids...]')
   .alias('done')
   .description('Complete one or more increments (triggers GitHub/JIRA/ADO sync)')
   .option('-s, --silent', 'Silent mode (for auto mode stop hook)')
   .option('-y, --yes', 'Assume yes (silent confirmation)')
   .option('--skip-validation', 'Skip quality gate validation (DANGEROUS)')
+  .option('-r, --reason <text>', 'Close without a passing reports/verify.json (stored as metadata.closeReason)')
+  .option('--all', 'Close every active increment whose tasks are all done or skipped (requires --reason)')
   .action(async (incrementId, moreIds, options) => {
     const { completeCommand } = await import('../dist/src/cli/commands/complete.js');
     await completeCommand(incrementId, moreIds, options);
   });
 
+// Task command - multi-vendor task ledger (claim / done / release / block / skip)
+program
+  .command('task <action> [taskOrIncrement] [increment]')
+  .description('Task ledger: list | next | claim | done | release | block | skip | render | whoami')
+  .option('-f, --force', 'Override a live claim, unmet deps or a Files overlap')
+  .option('-e, --evidence <text>', 'Evidence for `done` (commit sha, test output)')
+  .option('--run <cmd>', 'Run <cmd> through the OS shell; exit 0 required, output stored as evidence')
+  .option('-n, --note <text>', 'Note (alias of --reason)')
+  .option('--reason <text>', 'Reason (required for skip / block)')
+  .option('--all-mine', 'With `release`: release every task claimed by this agent')
+  .option('--json', 'Machine-readable output')
+  .action(async (action, taskOrIncrement, increment, options) => {
+    const { taskCommand } = await import('../dist/src/cli/commands/task.js');
+    process.exitCode = await taskCommand(action, taskOrIncrement, increment, options);
+  });
+
+// Verify command - run the project's verification commands, write reports/verify.{md,json}
+program
+  .command('verify [incrementId]')
+  .description("Run the project's test/lint/build commands and write reports/verify.{md,json}")
+  .option('--cmd <command>', 'Command to run (repeatable; overrides config/auto-detection)', (val, acc) => { (acc || []).push(val); return acc || [val]; }, [])
+  .option('--json', 'Print the verify report as JSON')
+  .action(async (incrementId, options) => {
+    const { verifyCommand } = await import('../dist/src/cli/commands/verify.js');
+    process.exitCode = await verifyCommand(incrementId, options);
+  });
+
 // Create Increment command - Create template files for a new increment
 program
-  .command('create-increment')
-  .description('Create increment template files (metadata.json, spec.md, plan.md, tasks.md)')
+  .command('create-increment [title]')
+  .description('Create increment template files (metadata.json, spec.md, tasks.md). Short form: specweave create-increment "Add login form"')
   .option('--id <increment-id>', 'Increment ID (e.g., "0042-my-feature")')
-  .option('--auto-id', 'Auto-generate next available increment ID')
-  .option('--name <name>', 'Increment name suffix (used with --auto-id)')
-  .requiredOption('--title <title>', 'Feature title')
-  .requiredOption('--description <description>', 'Feature description')
-  .requiredOption('--project <project-id>', 'Project ID (from .specweave/config.json)')
+  .option('--auto-id', 'Auto-generate next available increment ID (default when --id is absent)')
+  .option('--name <name>', 'Increment name suffix (defaults to a slug of the title)')
+  .option('--title <title>', 'Feature title (defaults to the positional argument)')
+  .option('--description <description>', 'Feature description (defaults to the title)')
+  .option('--project <project-id>', 'Project ID (defaults to config project.name, else the folder name)')
   .option('--board <board-id>', 'Board ID for 2-level structures')
   .option('--type <type>', 'Increment type (feature, hotfix, bug, refactor, experiment)', 'feature')
   .option('--priority <priority>', 'Priority (P1, P2, P3)', 'P1')
   .option('--project-root <path>', 'Override project root directory')
   .option('--parallel', 'Opt into 3-agent fan-out planning (default: single-agent)')
+  .option('--with-plan', 'Also scaffold plan.md (optional overflow; spec.md carries the Approach)')
+  .option('--planned', 'Create as "planned" instead of "active" (backlog work; start it with specweave start <id>)')
+  .option('--supersedes <increment-id>', 'Increment this one replaces (the old one is abandoned with a closeReason)')
+  .option('--parent <increment-id>', 'Parent increment (recorded as metadata.parent)')
   .option('--json', 'Output result as JSON (for programmatic use)')
-  .action(async (options) => {
+  .action(async (title, options) => {
+    if (title && !options.title) options.title = title;
     if (options.projectRoot) {
       const configPath = (await import('path')).join(options.projectRoot, '.specweave', 'config.json');
       const fs = await import('fs');
@@ -536,29 +577,11 @@ Examples:
   specweave interview status 0021-auth-feature
 `);
 
-// Logs command - View hook execution logs
-program
-  .command('logs')
-  .description('View hook execution logs')
-  .option('--tail <number>', 'Number of log entries to show (default: 50)', '50')
-  .option('--hook <name>', 'Filter by hook name')
-  .option('--format <type>', 'Output format: json or table (default: table)', 'table')
-  .option('--follow', 'Follow new log entries (not yet implemented)')
-  .action(async (options) => {
-    const { logsCommand } = await import('../dist/src/cli/commands/logs.js');
-    await logsCommand({
-      tail: parseInt(options.tail, 10),
-      hook: options.hook,
-      format: options.format,
-      follow: options.follow
-    });
-  });
-
 // Decision log command - Query structured decision logs
 program
   .command('decision-log')
   .description('Query structured decision logs from hooks')
-  .option('--hook <name>', 'Filter by hook name (stop-auto, stop-reflect)')
+  .option('--hook <name>', 'Filter by hook name (e.g. stop-auto)')
   .option('--decision <type>', 'Filter by decision type (approve, block)')
   .option('--since <window>', 'Filter by time window (1h, 24h, 7d)')
   .option('--limit <number>', 'Number of entries to show (default: 20)', '20')
@@ -749,7 +772,7 @@ program
 // Check discipline command - Validate increment discipline
 program
   .command('check-discipline')
-  .description('Validate increment discipline compliance (WIP limits, hard cap)')
+  .description('Report increment status counts, advisory WIP note and metadata consistency')
   .option('-v, --verbose', 'Show detailed increment information')
   .option('--json', 'Output results as JSON')
   .option('--project-root <path>', 'Project root directory')
@@ -762,13 +785,16 @@ program
     await checkDisciplineCommand(options);
   });
 
-// Revert WIP limit command - Restore original WIP limit after temporary adjustment
+// GC command - purge junk from .specweave/state (dry-run by default)
 program
-  .command('revert-wip-limit')
-  .description('Revert WIP limit to original value after temporary adjustment')
-  .action(async () => {
-    const { revertWipLimitCommand } = await import('../dist/src/cli/commands/revert-wip-limit.js');
-    await revertWipLimitCommand();
+  .command('gc')
+  .description('Purge stale .specweave/state files (dry-run; --yes to delete), report .worktrees size and nested .specweave dirs')
+  .option('-y, --yes', 'Actually delete (default is dry-run)')
+  .option('--json', 'Output as JSON')
+  .option('--project-root <path>', 'Project root directory')
+  .action(async (options) => {
+    const { gcCommand } = await import('../dist/src/cli/commands/gc.js');
+    await gcCommand(options);
   });
 
 // QA command - Quality assessment
@@ -790,16 +816,6 @@ program
     await qaCommand(incrementId, options);
   });
 
-// Validate Jira command - Jira resource validation
-program
-  .command('validate-jira')
-  .description('Validate Jira connection, project, and issue-type configuration; create missing issue types if needed')
-  .option('--env <path>', 'Path to .env file', '.env')
-  .action(async (options) => {
-    const { runJiraValidation } = await import('../dist/src/cli/commands/validate-jira.js');
-    await runJiraValidation(options);
-  });
-
 // Link PR - Link pull requests to external tickets (JIRA remote links, ADO hyperlinks)
 program
   .command('link-pr')
@@ -998,147 +1014,148 @@ program
     await commitsCommand();
   });
 
-// Sync flush command - Flush or queue sync events (replaces PostToolUse/stop-sync hooks)
-const syncFlushCmd = program
+// Sync command group - the ONE external tracker sync surface (GitHub / Jira / ADO)
+const syncCmd = program
   .command('sync')
-  .description('Sync operations');
+  .description('Sync increments with GitHub, Jira or Azure DevOps: push | pull | status | setup');
 
-syncFlushCmd
-  .command('flush')
-  .description('Flush pending sync events or queue new ones (replaces PostToolUse hook)')
-  .option('--queue <json>', 'Queue a new event instead of flushing')
-  .option('--dry-run', 'Report what would be flushed without clearing')
-  .option('--json', 'Output as JSON')
-  .option('--silent', 'Suppress output')
-  .action(async (options) => {
-    const { syncFlushCommand } = await import('../dist/src/cli/commands/sync-flush.js');
-    const result = await syncFlushCommand({
-      projectRoot: process.cwd(),
-      queue: options.queue,
-      dryRun: options.dryRun,
-      json: options.json,
-      silent: options.silent,
+syncCmd
+  .command('push [increment-id]')
+  .description('Push local progress (tasks -> ACs -> living docs -> issues) to the configured tracker(s)')
+  .option('--reconcile', 'Reconcile stale/duplicate GitHub milestones before pushing')
+  .option('--dry-run', 'Preview without making changes')
+  .option('--no-create', 'Skip auto-creating missing external issues')
+  .option('--provider <name>', 'Only push to one provider (github|jira|ado)')
+  .option('--force', 'Force sync even if no changes detected')
+  .action(async (incrementId, opts) => {
+    const { syncPush, parseProvider } = await import('../dist/src/cli/commands/sync.js');
+    await syncPush({
+      incrementId,
+      reconcile: opts.reconcile,
+      dryRun: opts.dryRun,
+      create: opts.create,
+      provider: parseProvider(opts.provider),
+      force: opts.force,
     });
-    if (!result.success) process.exit(1);
   });
 
-// Sync-scheduled command - Execute due scheduled sync jobs (for cron/CI)
-program
-  .command('sync-scheduled')
-  .description('Execute due scheduled sync jobs (for cron/CI use)')
-  .option('--dry-run', 'Show what would run without executing')
-  .option('--force', 'Run all sync jobs regardless of schedule')
+syncCmd
+  .command('pull')
+  .description('Report external changes since --since (default 7 days); --create-increments imports issues as increments')
+  .option('--create-increments', 'Create SpecWeave increments from external issues (interactive)')
+  .option('--provider <name>', 'Only pull from one provider (github|jira|ado)')
+  .option('--since <date|days>', 'ISO date or number of days to look back', '7')
+  .action(async (opts) => {
+    const { syncPull, parseProvider } = await import('../dist/src/cli/commands/sync.js');
+    await syncPull({ createIncrements: opts.createIncrements, provider: parseProvider(opts.provider), since: opts.since });
+  });
+
+syncCmd
+  .command('status')
+  .description('Token source + account + can-push, provider health, retry queue, circuit breakers, sync gaps')
   .option('--json', 'Output as JSON')
-  .option('--silent', 'Suppress output (for cron)')
-  .action(async (options) => {
-    const { createSyncScheduledCommand } = await import('../dist/src/cli/commands/sync-scheduled.js');
-    const syncCmd = createSyncScheduledCommand();
-    await syncCmd.parseAsync(['node', 'sync-scheduled', ...process.argv.slice(3)], { from: 'user' });
+  .option('--provider <name>', 'Only report one provider (github|jira|ado)')
+  .option('--quick', 'Skip network probes')
+  .action(async (opts) => {
+    const { syncStatus, parseProvider } = await import('../dist/src/cli/commands/sync.js');
+    const report = await syncStatus({ json: opts.json, provider: parseProvider(opts.provider), quick: opts.quick });
+    process.exitCode = report.exitCode;
+  });
+
+syncCmd
+  .command('setup')
+  .description('Interactive wizard to connect GitHub Issues, Jira or Azure DevOps (--validate checks the existing config)')
+  .option('--provider <name>', 'Provider to configure (github|jira|ado) - skips selection prompt')
+  .option('--validate', 'Validate existing configuration and credentials instead of running the wizard')
+  .option('--quick', 'Non-interactive mode: print hint and exit (for CI environments)')
+  .action(async (opts) => {
+    const { syncSetup, parseProvider } = await import('../dist/src/cli/commands/sync.js');
+    process.exitCode = await syncSetup({ provider: parseProvider(opts.provider), validate: opts.validate, quick: opts.quick });
   });
 
-// Sync-progress command - Comprehensive progress sync with auto-create
+// Deprecated top-level sync verbs: hidden aliases that print a one-line notice and delegate
+async function deprecatedSync(oldVerb) {
+  const { deprecationNotice } = await import('../dist/src/cli/commands/sync.js');
+  console.error(deprecationNotice(oldVerb));
+}
+
 program
-  .command('sync-progress [increment-id]')
-  .description('Comprehensive progress sync: tasks → ACs → living docs → AUTO-CREATE external issues → sync')
-  .option('--dry-run', 'Preview without making changes')
-  .option('--no-create', 'Skip auto-creating external issues')
-  .option('--no-github', 'Skip GitHub sync')
-  .option('--no-jira', 'Skip JIRA sync')
-  .option('--no-ado', 'Skip Azure DevOps sync')
-  .option('--force', 'Force sync even if no changes detected')
-  .action(async (incrementId, options) => {
+  .command('sync-progress [increment-id]', { hidden: true })
+  .option('--dry-run')
+  .option('--no-create')
+  .option('--no-github')
+  .option('--no-jira')
+  .option('--no-ado')
+  .option('--force')
+  .action(async (incrementId, opts) => {
+    await deprecatedSync('sync-progress');
     const { syncProgress } = await import('../dist/src/cli/commands/sync-progress.js');
     const args = [];
     if (incrementId) args.push(incrementId);
-    if (options.dryRun) args.push('--dry-run');
-    if (!options.create) args.push('--no-create');
-    if (!options.github) args.push('--no-github');
-    if (!options.jira) args.push('--no-jira');
-    if (!options.ado) args.push('--no-ado');
-    if (options.force) args.push('--force');
+    if (opts.dryRun) args.push('--dry-run');
+    if (!opts.create) args.push('--no-create');
+    if (!opts.github) args.push('--no-github');
+    if (!opts.jira) args.push('--no-jira');
+    if (!opts.ado) args.push('--no-ado');
+    if (opts.force) args.push('--force');
     await syncProgress(args);
   });
 
-// Sync-living-docs command - Sync living docs for a specific increment
 program
-  .command('sync-living-docs [increment-id]')
-  .description('Sync living documentation for an increment (feature spec + user story files)')
-  .option('--dry-run', 'Preview without making changes')
-  .option('--force', 'Force sync even if no changes detected')
-  .action(async (incrementId, options) => {
+  .command('sync-living-docs [increment-id]', { hidden: true })
+  .option('--dry-run')
+  .option('--force')
+  .action(async (incrementId, opts) => {
+    await deprecatedSync('sync-living-docs');
     const { syncLivingDocs } = await import('../dist/src/cli/commands/sync-living-docs.js');
     const args = [];
     if (incrementId) args.push(incrementId);
-    if (options.dryRun) args.push('--dry-run');
-    if (options.force) args.push('--force');
+    if (opts.dryRun) args.push('--dry-run');
+    if (opts.force) args.push('--force');
     await syncLivingDocs(args);
   });
 
-// Sync-task command - Lightweight hook for task-ac-sync-guard.sh
 program
-  .command('sync-task <increment-id>')
-  .description('Trigger post-task-completion hooks (called by shell hook, not for manual use)')
-  .action(async (incrementId) => {
-    const { syncTask } = await import('../dist/src/cli/commands/sync-task.js');
-    await syncTask([incrementId]);
-  });
-
-// Sync-retry command - Process retry queue for failed syncs
-program
-  .command('sync-retry')
-  .description('Process the sync retry queue (retry failed external syncs with backoff)')
-  .option('--dry-run', 'Show what would be retried without executing')
-  .option('--force', 'Retry all entries regardless of backoff timing')
-  .option('--clear', 'Clear the entire retry queue')
-  .action(async (options) => {
+  .command('sync-retry', { hidden: true })
+  .option('--dry-run')
+  .option('--force')
+  .option('--clear')
+  .action(async (opts) => {
+    await deprecatedSync('sync-retry');
     const { syncRetryCommand } = await import('../dist/src/cli/commands/sync-retry.js');
-    const result = await syncRetryCommand(process.cwd(), options);
+    const result = await syncRetryCommand(process.cwd(), opts);
     if (result.failed > 0) process.exitCode = 1;
   });
 
-// Sync-gaps command - Detect increments with partial external sync
-program
-  .command('sync-gaps')
-  .description('Detect increments with partial external sync coverage')
-  .option('--json', 'Output as JSON')
-  .option('--fix', 'Attempt missing syncs for each gap')
-  .action(async (options) => {
-    const { syncGapsCommand } = await import('../dist/src/cli/commands/sync-gaps.js');
-    const result = await syncGapsCommand(process.cwd(), options);
-    process.exitCode = result.exitCode;
-  });
-
-// Sync-status command - Overall sync health report
-program
-  .command('sync-status')
-  .description('Show sync health: retry queue, circuit breakers, rate limits, recent errors')
-  .action(async () => {
-    const { syncStatusCommand } = await import('../dist/src/cli/commands/sync-status.js');
-    const result = await syncStatusCommand(process.cwd());
-    process.exitCode = result.exitCode;
-  });
+for (const oldVerb of ['sync-status', 'sync-health', 'sync-gaps']) {
+  program
+    .command(oldVerb, { hidden: true })
+    .option('--json')
+    .option('--provider <name>')
+    .action(async (opts) => {
+      await deprecatedSync(oldVerb);
+      const { syncStatus, parseProvider } = await import('../dist/src/cli/commands/sync.js');
+      const report = await syncStatus({ json: opts.json, provider: parseProvider(opts.provider) });
+      process.exitCode = report.exitCode;
+    });
+}
 
-// Sync-setup command - Interactive wizard to connect GitHub Issues, JIRA, or ADO
 program
-  .command('sync-setup')
-  .description('Interactive wizard to connect GitHub Issues, JIRA, or Azure DevOps')
-  .option('--provider <name>', 'Provider to configure (github|jira|ado) — skips selection prompt')
-  .option('--quick', 'Non-interactive mode: print hint and exit (for CI environments)')
+  .command('sync-setup', { hidden: true })
+  .option('--provider <name>')
+  .option('--quick')
   .action(async (opts) => {
-    const { syncSetupCommand } = await import('../dist/src/cli/commands/sync-setup.js');
-    await syncSetupCommand({ provider: opts.provider, quick: opts.quick });
+    await deprecatedSync('sync-setup');
+    const { syncSetup, parseProvider } = await import('../dist/src/cli/commands/sync.js');
+    process.exitCode = await syncSetup({ provider: parseProvider(opts.provider), quick: opts.quick });
   });
 
-// Sync-health command - Validate external integration health
 program
-  .command('sync-health')
-  .description('Validate external integration health (GitHub, JIRA, ADO)')
-  .option('--json', 'Output results as JSON for CI pipelines')
-  .option('--provider <name>', 'Check only a specific provider (github|jira|ado)')
-  .action(async (opts) => {
-    const { syncHealthCommand } = await import('../dist/src/cli/commands/sync-health.js');
-    const exitCode = await syncHealthCommand({ json: opts.json, provider: opts.provider });
-    process.exitCode = exitCode;
+  .command('validate-jira', { hidden: true })
+  .action(async () => {
+    await deprecatedSync('validate-jira');
+    const { syncSetup } = await import('../dist/src/cli/commands/sync.js');
+    process.exitCode = await syncSetup({ provider: 'jira', validate: true });
   });
 
 // Docs command - Documentation preview, build, validation
@@ -1245,25 +1262,27 @@ docsCmd
   });
 
 // Default action for 'specweave docs' without subcommand — launches internal preview
+docsCmd
+  .command('sync [increment-id]')
+  .description('Sync living documentation for an increment (feature spec + user story files)')
+  .option('--dry-run', 'Preview without making changes')
+  .option('--force', 'Force sync even if no changes detected')
+  .action(async (incrementId, options) => {
+    const { syncLivingDocs } = await import('../dist/src/cli/commands/sync-living-docs.js');
+    const args = [];
+    if (incrementId) args.push(incrementId);
+    if (options.dryRun) args.push('--dry-run');
+    if (options.force) args.push('--force');
+    await syncLivingDocs(args);
+  });
+
+
 docsCmd.action(async () => {
   const { docsPreviewCommand } = await import('../dist/src/cli/commands/docs.js');
   await docsPreviewCommand({ scope: 'internal' });
 });
 
 
-// Refresh marketplace command - Update marketplace with lazy loading support
-program
-  .command('refresh-marketplace')
-  .description('Refresh SpecWeave marketplace (lazy mode by default - router only)')
-  .option('--all', 'Install ALL plugins (legacy mode, ~60K tokens)')
-  .option('--minimal', 'Remove marketplace, install only core plugins (clean /plugin output, no lazy loading)')
-  .option('-f, --force', 'Force reinstall all plugins (clears cache, ensures fresh copy)')
-  .option('-v, --verbose', 'Show detailed error messages')
-  .action(async (options) => {
-    const { refreshMarketplaceCommand } = await import('../dist/src/cli/commands/refresh-marketplace.js');
-    await refreshMarketplaceCommand(options);
-  });
-
 // Refresh plugins command - Copy first-party plugins to ~/.claude/commands/
 program
   .command('refresh-plugins')
@@ -1287,6 +1306,7 @@ program
   .option('--quick', 'Skip slow checks (network, hook execution)')
   .option('--skip-external', 'Skip external tool connectivity checks')
   .option('--fix', 'Apply inline fixes (remove ghost files, stale cache, update lockfile hashes)')
+  .option('--fix-status', 'Fix metadata.json <-> spec.md status desyncs (formerly sw:sync-status)')
   .action(async (options) => {
     const { doctor } = await import('../dist/src/cli/commands/doctor.js');
     const report = await doctor(process.cwd(), {
@@ -1295,6 +1315,7 @@ program
       quick: options.quick,
       skipExternal: options.skipExternal,
       fix: options.fix,
+      fixStatus: options.fixStatus,
     });
 
     // Exit with appropriate code (failures = 1)
@@ -1345,7 +1366,7 @@ sessionCmd
 
 sessionCmd
   .command('end')
-  .description('End session: reflect check, auto scan, sync flush (replaces Stop hooks)')
+  .description('End session: auto scan, sync flush (replaces Stop hooks)')
   .option('--json', 'Output as JSON')
   .option('--silent', 'Suppress output')
   .action(async (options) => {
@@ -1367,15 +1388,8 @@ program
       const { handleHook } = await import('../dist/src/cli/commands/hook.js');
       await handleHook(eventType);
     } catch {
-      // Never crash — output safe default
-      const defaults = {
-        'user-prompt-submit': '{"decision":"approve"}',
-        'pre-tool-use': '{"decision":"allow"}',
-        'stop-reflect': '{"decision":"approve"}',
-        'stop-auto': '{"decision":"approve"}',
-        'stop-sync': '{"decision":"approve"}',
-      };
-      process.stdout.write(defaults[eventType] || '{"continue":true}');
+      // Never crash — `{}` is the schema-valid pass-through for every event
+      process.stdout.write('{}');
     }
     process.exit(0);
   });
@@ -1448,19 +1462,6 @@ program
     process.exit(result.success ? 0 : 1);
   });
 
-// Reflect stop command - Extract learnings at session end (internal, called by stop hook)
-program
-  .command('reflect-stop <transcript-path>')
-  .description('Extract learnings from session transcript (called by stop hook)')
-
-  .option('-s, --silent', 'Silent mode - output JSON only')
-  .option('-m, --model <model>', 'Model to use (haiku, sonnet, opus)')
-  .option('--migrate', 'Run migration of old memory files first')
-  .action(async (transcriptPath, options) => {
-    const { reflectStopCommand } = await import('../dist/src/cli/commands/reflect-stop.js');
-    await reflectStopCommand(transcriptPath, options);
-  });
-
 // Detect project command - Analyze project files and suggest plugins (internal)
 program
   .command('detect-project [path]')
@@ -1508,26 +1509,6 @@ program
     });
   });
 
-// Set sync target command - Set external tool sync target for increment (ADR-0211)
-program
-  .command('set-sync-target <increment-id>')
-  .description('Set external tool sync target for an increment (v1.0.31+)')
-  .option('-p, --project <project-id>', 'Project ID for project-based resolution')
-  .option('-v, --verbose', 'Show resolution path and details')
-  .option('--dry-run', 'Show what would be set without making changes')
-  .option('--validate-only', 'Only validate configuration, do not set')
-  .action(async (incrementId, options) => {
-    const { createSetSyncTargetCommand } = await import('../dist/src/cli/commands/set-sync-target.js');
-    const cmd = createSetSyncTargetCommand();
-    // Execute the action by parsing with the increment ID and options
-    const args = ['node', 'set-sync-target', incrementId];
-    if (options.project) args.push('-p', options.project);
-    if (options.verbose) args.push('-v');
-    if (options.dryRun) args.push('--dry-run');
-    if (options.validateOnly) args.push('--validate-only');
-    await cmd.parseAsync(args, { from: 'user' });
-  });
-
 // Help text
 program.on('--help', () => {
   console.log('');
@@ -1549,7 +1530,7 @@ program.on('--help', () => {
   console.log('  $ specweave qa 0008                         # Quick quality check');
   console.log('  $ specweave qa 0008 --pre                   # Pre-implementation check');
   console.log('  $ specweave qa 0008 --gate --export         # Quality gate + export to tasks');
-  console.log('  $ specweave validate-jira                   # Validate Jira configuration');
+  console.log('  $ specweave sync status                     # Token/account, provider health, sync gaps');
   console.log('  $ specweave jobs                            # Show active background jobs');
   console.log('  $ specweave jobs --follow <jobId>           # Follow job progress live');
   console.log('  $ specweave jobs --logs <jobId>             # View worker logs');
@@ -1558,12 +1539,12 @@ program.on('--help', () => {
   console.log('  $ specweave living-docs --depth deep-native # AI-powered analysis (FREE w/ MAX)');
   console.log('  $ specweave living-docs --full-scan         # Full deep scan (all phases)');
   console.log('  $ specweave living-docs --resume <jobId>    # Resume orphaned job');
-  console.log('  $ specweave sync-scheduled                  # Execute due sync jobs');
-  console.log('  $ specweave sync-scheduled --force          # Force sync all jobs');
+  console.log('  $ specweave sync push 0008                  # Push increment progress to GitHub/Jira/ADO');
+  console.log('  $ specweave sync pull --since 3             # Show external changes from the last 3 days');
   console.log('  $ specweave cache                           # Show cache status');
   console.log('  $ specweave cache --rebuild                 # Rebuild dashboard cache');
   console.log('  $ specweave cache --debug                   # Show cache debug info');
-  console.log('  $ specweave validate-jira --env .env.prod   # Validate with custom .env file');
+  console.log('  $ specweave sync setup --validate           # Validate tracker configuration + credentials');
   console.log('  $ specweave docs                            # Preview internal docs (port 3015)');
   console.log('  $ specweave docs public                     # Preview public docs (port 3016)');
   console.log('  $ specweave docs build                      # Build internal site');
@@ -1571,12 +1552,10 @@ program.on('--help', () => {
   console.log('  $ specweave docs validate                   # Check for docs errors');
   console.log('  $ specweave docs status                     # Show docs status');
   console.log('  $ specweave docs kill                       # Stop all docs servers');
-  console.log('  $ specweave set-sync-target 0008            # Set sync target for increment');
-  console.log('  $ specweave set-sync-target 0008 -v         # Show resolution path');
-  console.log('  $ specweave set-sync-target 0008 --validate-only  # Validate only');
-  console.log('  $ specweave refresh-marketplace             # Lazy mode: router only (~500 chars)');
-  console.log('  $ specweave refresh-marketplace --all       # Legacy mode: all plugins (~60K chars)');
-  console.log('  $ specweave refresh-marketplace --force     # Force reinstall (clears cache)');
+  console.log('  $ specweave doctor --fix-status             # Fix metadata/spec status desyncs');
+  console.log('  $ specweave refresh-plugins                 # Refresh core SpecWeave plugin');
+  console.log('  $ specweave refresh-plugins --all           # Refresh every installed plugin');
+  console.log('  $ specweave refresh-plugins --force         # Force reinstall (skip hash check)');
   console.log('  $ specweave update                          # Update CLI + instructions + config');
   console.log('  $ specweave update --plugins                # Also refresh marketplace plugins');
   console.log('  $ specweave update --no-self                # Skip CLI update, only project files');
@@ -1650,31 +1629,12 @@ program
     await dashboardCommand(options);
   });
 
-// Hooks command - Hook observability and management
-const hooksCmd = program.command('hooks').description('Hook observability and management');
-
-hooksCmd
-  .command('status')
-  .description('Check hook server status')
-  .action(async () => {
-    const { getHooksStatus, formatHooksStatus } = await import('../dist/src/hooks/hooks-status.js');
-    const result = await getHooksStatus(process.cwd());
-    console.log(formatHooksStatus(result));
-  });
-
-hooksCmd
-  .command('generate-settings')
-  .description('Generate .claude/settings.json hooks configuration')
-  .option('-p, --port <number>', 'Override port (default: 8340)')
-  .action(async (options) => {
-    const { writeSettings } = await import('../dist/src/hooks/generate-settings.js');
-    writeSettings(process.cwd(), options.port ? parseInt(options.port, 10) : undefined);
-    console.log('Hooks settings written to .claude/settings.json');
-  });
+// Hooks command - hook log viewer (hooks.json lives in the plugin; see `specweave doctor` for a dry-run)
+const hooksCmd = program.command('hooks').description('Hook observability');
 
 hooksCmd
   .command('log')
-  .description('View recent hook events')
+  .description('View recent hook warnings, errors and blocks (.specweave/logs/hooks.jsonl)')
   .option('--last <number>', 'Number of entries to show (default: 20)', '20')
   .option('--blocks-only', 'Show only block decisions')
   .option('--errors-only', 'Show only error entries')
@@ -1689,23 +1649,6 @@ hooksCmd
     });
   });
 
-hooksCmd
-  .command('health')
-  .description('Show hook health summary')
-  .option('--json', 'Output as JSON')
-  .action(async (options) => {
-    const { hooksHealthCommand } = await import('../dist/src/cli/commands/hooks-cmd.js');
-    await hooksHealthCommand({ format: options.json ? 'json' : 'console' });
-  });
-
-hooksCmd
-  .command('ls')
-  .description('List registered hooks')
-  .action(async () => {
-    const { hooksLsCommand } = await import('../dist/src/cli/commands/hooks-cmd.js');
-    await hooksLsCommand();
-  });
-
 // Context command - Show workspace project context for spec fields
 const contextCmd = program
   .command('context')
@@ -1752,7 +1695,7 @@ program
   await checkForDuplicates();
 
   // Hide internal-only commands from --help (still callable by hooks)
-  for (const name of ['hook', 'detect-intent', 'evaluate-completion', 'reflect-stop', 'detect-project']) {
+  for (const name of ['hook', 'detect-intent', 'evaluate-completion', 'detect-project']) {
     const cmd = program.commands.find(c => c.name() === name);
     if (cmd) cmd._hidden = true;
   }