create-quiver 0.12.0 → 0.12.1

package/src/create-quiver/commands/flow.js

@@ -289,10 +289,11 @@ function detectFlowState(projectRoot) {
       stage: 'criteria-draft',
       label: 'acceptance criteria need approval',
       blockers: ['Acceptance criteria draft exists but is not approved.'],
-      nextCommand: 'npx create-quiver ai approve --phase acceptance --input acceptance-approved.md',
+      nextCommand: 'npx create-quiver ai approve --phase acceptance --version <n>',
       suggestedCommands: [
         'npx create-quiver ai approvals',
-        'npx create-quiver ai approve --phase acceptance --input acceptance-approved.md',
+        'npx create-quiver ai revise --phase acceptance --input feedback.md --dry-run',
+        'npx create-quiver ai approve --phase acceptance --version <n>',
       ],
       facts,
     });
@@ -303,10 +304,11 @@ function detectFlowState(projectRoot) {
       stage: 'criteria-stale',
       label: 'acceptance criteria approval is stale',
       blockers: ['Acceptance criteria changed after approval.'],
-      nextCommand: 'npx create-quiver ai approve --phase acceptance --input acceptance-approved.md',
+      nextCommand: 'npx create-quiver ai approve --phase acceptance --version <n>',
       suggestedCommands: [
         'npx create-quiver ai approvals',
-        'npx create-quiver ai approve --phase acceptance --input acceptance-approved.md',
+        'npx create-quiver ai revise --phase acceptance --input feedback.md --dry-run',
+        'npx create-quiver ai approve --phase acceptance --version <n>',
       ],
       facts,
     });
@@ -407,7 +409,6 @@ function detectFlowState(projectRoot) {
       suggestedCommands: [
         'npx create-quiver ai review-plan --dry-run',
         'npx create-quiver ai review-plan',
-        'npx create-quiver ai approve --phase technical-plan --version <n>',
       ],
       facts,
     });

package/src/create-quiver/commands/graph.js

@@ -1,4 +1,4 @@
-const { buildGraph, computeLevels, detectFileConflicts, readAllSlices } = require('../lib/slice-graph');
+const { buildGraph, computeLevels, detectFileConflicts, readAllSlices, readSlicesForSpec } = require('../lib/slice-graph');
 const { renderDotGraph } = require('../lib/renderers/dot');
 const { renderMermaidGraph } = require('../lib/renderers/mermaid');
 const { renderTreeGraph, isUnicodeEnabled } = require('../lib/renderers/tree');
@@ -28,11 +28,13 @@ function buildConflictPayload(levelIndex, groups) {
 }
 
 function collectGraph(repoRoot, options = {}) {
-  const graph = buildGraph(readAllSlices(repoRoot));
-  computeLevels(graph);
+  const specSlug = options.specSlug ? String(options.specSlug).trim() : '';
+  const graph = buildGraph(specSlug ? readSlicesForSpec(repoRoot, specSlug) : readAllSlices(repoRoot));
+  if (!specSlug) {
+    computeLevels(graph);
+  }
   const includeCompleted = options.includeCompleted === true;
   const excluded = includeCompleted ? HISTORY_EXCLUDED_STATUSES : EXCLUDED_STATUSES;
-  const specSlug = options.specSlug ? String(options.specSlug).trim() : '';
   const pendingNodes = graph.nodes.filter((node) => {
     if (excluded.has(String(node.status || '').toLowerCase())) {
       return false;

package/src/create-quiver/commands/plan.js

@@ -1,7 +1,7 @@
 const fs = require('fs');
 const path = require('path');
 const { relativePosixPath } = require('../lib/paths');
-const { buildGraph, readAllSlices, topoSort } = require('../lib/slice-graph');
+const { buildGraph, readAllSlices, readSlicesForSpec, topoSort } = require('../lib/slice-graph');
 
 const EXCLUDED_STATUSES = new Set(['completed', 'skipped', 'cancelled']);
 const HISTORY_EXCLUDED_STATUSES = new Set(['skipped', 'cancelled']);
@@ -116,12 +116,12 @@ function buildCriticalPath(graph, refs) {
 }
 
 function collectPlan(repoRoot, options = {}) {
-  const allSlices = readAllSlices(repoRoot);
+  const specSlug = options.specSlug ? String(options.specSlug).trim() : '';
+  const allSlices = specSlug ? readSlicesForSpec(repoRoot, specSlug) : readAllSlices(repoRoot);
   const graph = buildGraph(allSlices);
   const topo = topoSort(graph);
   const includeCompleted = options.includeCompleted === true;
   const excluded = includeCompleted ? HISTORY_EXCLUDED_STATUSES : EXCLUDED_STATUSES;
-  const specSlug = options.specSlug ? String(options.specSlug).trim() : '';
 
   const pendingRefs = new Set(
     graph.nodes

package/src/create-quiver/index.js

@@ -9,7 +9,29 @@ const {
   collectDoctorReport,
   formatDoctorFixPlan,
 } = require('./lib/doctor');
-const { runAgent: runAiAgent, runApprovalStatus: runAiApprovalStatus, runApprove: runAiApprove, runDoctor: runAiDoctor, runExecutePlan: runAiExecutePlan, runExecuteSlice: runAiExecuteSlice, runOnboard, runPlan: runAiPlan, runPrepareContext: runAiPrepareContext, runPr: runAiPr, runPromptSlice: runAiPromptSlice, runReviewPlan: runAiReviewPlan } = require('./commands/ai');
+const {
+  runAgent: runAiAgent,
+  runApprovalStatus: runAiApprovalStatus,
+  runApprove: runAiApprove,
+  runDoctor: runAiDoctor,
+  runExecutePlan: runAiExecutePlan,
+  runExecuteSlice: runAiExecuteSlice,
+  runExport: runAiExport,
+  runInspect: runAiInspect,
+  runLifecycleResume: runAiLifecycleResume,
+  runLifecycleRun: runAiLifecycleRun,
+  runLifecycleStatus: runAiLifecycleStatus,
+  runOnboard,
+  runPlan: runAiPlan,
+  runPrepareContext: runAiPrepareContext,
+  runPr: runAiPr,
+  runPromptSlice: runAiPromptSlice,
+  runReviewPlan: runAiReviewPlan,
+  runRevise: runAiRevise,
+  runSlicesList: runAiSlicesList,
+  runSpecsList: runAiSpecsList,
+  runTraceReport: runAiTraceReport,
+} = require('./commands/ai');
 const { runDemo } = require('./commands/demo');
 const { runPrepare } = require('./commands/prepare');
 const { runEvidence } = require('./commands/evidence');
@@ -80,12 +102,21 @@ const SUPPORTED_AI_COMMANDS = new Set([
   'execute-plan',
   'execute-slice',
   'executor-prompt',
+  'export',
+  'inspect',
   'onboard',
   'plan',
   'prepare-context',
   'pr',
   'prompt-slice',
   'review-plan',
+  'revise',
+  'resume',
+  'run',
+  'slices',
+  'specs',
+  'status',
+  'trace',
 ]);
 
 const SUPPORTED_SPEC_COMMANDS = new Set(['close', 'create', 'start', 'status']);
@@ -100,6 +131,103 @@ function unsupportedCommandMessage(commandName) {
   ].join('\n');
 }
 
+const COMMAND_HELP_GROUPS = [
+  {
+    title: 'Bootstrap and project context',
+    commands: [
+      ['init', 'Create the default AI-first Quiver contract in the current project.'],
+      ['analyze', 'Scan the project and write docs/PROJECT_MAP.md plus .quiver scan data.'],
+      ['doctor', 'Validate the Quiver layout, generated docs, environment, and next safe steps.'],
+      ['flow', 'Show the read-only guided workflow stage, blockers, and next safe command.'],
+      ['prepare', 'Run setup diagnostics for providers, GitHub, SSH, and project readiness.'],
+      ['migrate', 'Upgrade an already initialized Quiver project to the current contract.'],
+    ],
+  },
+  {
+    title: 'Planning and slice navigation',
+    commands: [
+      ['plan', 'List slices in execution order with critical path and optional JSON output.'],
+      ['graph', 'Render slice dependencies as tree, Mermaid, DOT, or JSON-ready graph output.'],
+      ['next', 'Print the next ready slice or every ready slice with --all-ready.'],
+    ],
+  },
+  {
+    title: 'AI lifecycle',
+    commands: [
+      ['ai run create', 'Create a durable AI lifecycle run from a requirements file.'],
+      ['ai status', 'Show current AI lifecycle phase, approved versions, blockers, and next command.'],
+      ['ai resume', 'Resume guidance from the last valid lifecycle phase without chat memory.'],
+      ['ai onboard', 'Run or print the planner onboarding prompt with a token-aware context pack.'],
+      ['ai prepare-context', 'Preview or write docs-only AI context updates with assumptions and risks.'],
+      ['ai agent set|list|show', 'Manage planner, executor, reviewer, and doctor provider profiles without secrets.'],
+      ['ai plan', 'Generate versioned planner drafts for acceptance criteria, technical plan, or spec phase.'],
+      ['ai revise', 'Create a new planner draft from human feedback without approving it.'],
+      ['ai review-plan', 'Review the technical-plan draft for production readiness before approval.'],
+      ['ai approve', 'Approve a concrete saved draft version for the next planner phase.'],
+      ['ai approvals', 'Inspect approval status and saved planner drafts.'],
+      ['ai prompt-slice', 'Print a minimal executor prompt for one slice without provider execution.'],
+      ['ai execute-slice', 'Execute one slice with scope checks, redacted evidence, closure updates, and optional commit.'],
+      ['ai execute-plan', 'Print or execute dependency-safe waves in manual or delegated mode.'],
+      ['ai doctor', 'Run GitHub, SSH, and PR readiness preflight checks.'],
+      ['ai pr', 'Validate and optionally create a GitHub PR from the generated PR body.'],
+    ],
+  },
+  {
+    title: 'Inspection and export',
+    commands: [
+      ['ai inspect', 'Show dashboard-friendly lifecycle state for specs, slices, runs, agents, and blockers.'],
+      ['ai export', 'Export lifecycle state as JSON or Markdown for dashboards, PRs, or other agents.'],
+      ['ai specs list', 'List specs with status, progress, slice counts, and paths.'],
+      ['ai slices list', 'List slices with status, dependencies, blockers, and optional JSON.'],
+      ['ai trace report', 'Report AI runs, execution waves, and migration guidance.'],
+    ],
+  },
+  {
+    title: 'Specs, slices, and validation',
+    commands: [
+      ['spec create', 'Create the real spec tree from a reviewed approved technical plan.'],
+      ['spec start', 'Create or reuse the dedicated worktree and branch for one spec.'],
+      ['spec status', 'Show spec worktree, branch, slice-00 state, and pending slices.'],
+      ['spec close', 'Close a merged clean spec worktree and guide local sync.'],
+      ['start-slice', 'Start work on one slice and mark it active.'],
+      ['check-slice', 'Validate slice structure, dependencies, scope, and readiness.'],
+      ['check-pr', 'Validate PR readiness for a slice/spec workflow.'],
+      ['check-scope', 'Compare changed files against a slice scope.'],
+      ['cleanup-slice', 'Clean active-slice state after a slice finishes or is discarded.'],
+      ['refresh-active-slices', 'Refresh generated active-slice boards.'],
+      ['check-handoff', 'Validate a transfer handoff or per-slice execution/closure brief.'],
+      ['new-handoff', 'Create a handoff scaffold for exceptional context transfer.'],
+    ],
+  },
+  {
+    title: 'Evidence and demos',
+    commands: [
+      ['evidence run', 'Run a command and record exit code, duration, redacted output, and Markdown evidence.'],
+      ['demo create spec-viewer', 'Create or preview the optional static Quiver Spec Viewer demo scaffold.'],
+    ],
+  },
+  {
+    title: 'Shortcuts and compatibility',
+    commands: [
+      ['--name "<project>"', 'Compatibility alias for init when bootstrapping a project.'],
+      ['--version / -V', 'Print the installed create-quiver package version.'],
+      ['--help / help', 'Show this command reference.'],
+      ['quiver', 'Local installed alias to the same CLI; use npx create-quiver for bootstrap.'],
+    ],
+  },
+];
+
+function formatCommandHelpGroups() {
+  const lines = ['Commands:'];
+  for (const group of COMMAND_HELP_GROUPS) {
+    lines.push('', `${group.title}:`);
+    for (const [command, description] of group.commands) {
+      lines.push(`  ${command.padEnd(24)} ${description}`);
+    }
+  }
+  return lines.join('\n');
+}
+
 function printUsage() {
   console.log(`Usage:
   npx create-quiver [options]
@@ -108,8 +236,17 @@ function printUsage() {
   npx create-quiver flow [options]
   npx create-quiver plan [options]
   npx create-quiver ai <task> [options]
+  npx create-quiver ai run create --input <requirements.md>
+  npx create-quiver ai status [options]
+  npx create-quiver ai resume [options]
+  npx create-quiver ai inspect [options]
+  npx create-quiver ai export [--format json|markdown]
+  npx create-quiver ai specs list [--json]
+  npx create-quiver ai slices list [--json]
+  npx create-quiver ai trace report [options]
   npx create-quiver ai agent <set|list|show> [role] [options]
   npx create-quiver ai prepare-context [options]
+  npx create-quiver ai revise [options]
   npx create-quiver graph [options]
   npx create-quiver next [options]
   npx create-quiver migrate [options]
@@ -118,7 +255,7 @@ function printUsage() {
   npx create-quiver start-slice [options] <slice.json>
   npx create-quiver check-slice [options] <slice.json>
   npx create-quiver check-pr <slice.json>
-  npx create-quiver check-handoff <handoff.md>
+  npx create-quiver check-handoff <handoff-or-brief.md>
   npx create-quiver new-handoff <spec-slug>
   npx create-quiver cleanup-slice [options] <slice.json>
   npx create-quiver check-scope [options] <slice.json>
@@ -130,11 +267,13 @@ function printUsage() {
   npx create-quiver evidence run [options] -- <command>
   npx create-quiver demo create spec-viewer [options]
 
+${formatCommandHelpGroups()}
+
 Options:
   -n, --name <project-name>   Project name to generate
   -d, --dir <target-dir>      Target directory to scaffold into or inspect
       --spec <slug>           Restrict plan output to one spec
-      --format <name>         Graph output format (tree, mermaid, dot)
+      --format <name>         Graph or AI export output format (tree, mermaid, dot, json, markdown)
       --show-conflicts        Show shared file paths in graph output
       --level <n>             Restrict graph output to one level
       --json                  Emit machine-readable JSON
@@ -148,7 +287,8 @@ Options:
       --full                  Plan or run the full compatibility init profile
       --legacy-scripts        Include legacy Bash wrappers in init profile
       --include-templates     Export packaged templates in init profile
-      --dry-run               Preview init, prepare, spec create, demo, or AI work without executing writes/providers
+      --dry-run               Preview init, migrate, prepare, spec create/start/close, demo, or AI work without executing writes/providers
+      --print-prompt          Print the exact AI prompt and exit without executing provider CLIs
       --fix                   For doctor, apply safe non-destructive repairs
       --execute               For ai execute-plan, run the planned slices instead of printing commands
       --create                For ai pr, create the PR after preflight instead of printing the plan only
@@ -158,6 +298,7 @@ Options:
       --provider <name>       Provider CLI to preflight for prepare or AI commands
       --model <label>         Free-form model label for AI agent profiles
       --version <n>           Draft version to approve for AI planner phases
+      --run <id>              AI lifecycle run id
       --ssh-host-alias <name> SSH host alias to validate for prepare or AI commands
       --identity-file <path>  SSH identity file to validate for prepare or AI commands
       --remote <name>         Git remote name for check-slice or AI PR checks
@@ -166,6 +307,7 @@ Options:
       --max-output <n>        Maximum stdout/stderr chars per evidence section
       --title <text>          Override PR title for ai pr create
   -y, --yes                   Skip prompts and use the provided inputs
+  -V, --version               Show the installed create-quiver version
   -h, --help                  Show this help message
 
 Examples:
@@ -177,15 +319,27 @@ Examples:
   cd ./my-project && npx create-quiver analyze
   cd ./my-project && npx create-quiver plan --json
   cd ./my-project && npx create-quiver ai onboard --dry-run
+  cd ./my-project && npx create-quiver ai onboard --print-prompt
   cd ./my-project && npx create-quiver ai prepare-context --dry-run
+  cd ./my-project && npx create-quiver ai run create --input requirements.md
+  cd ./my-project && npx create-quiver ai status
+  cd ./my-project && npx create-quiver ai resume
+  cd ./my-project && npx create-quiver ai inspect
+  cd ./my-project && npx create-quiver ai export --format json
+  cd ./my-project && npx create-quiver ai export --format markdown
+  cd ./my-project && npx create-quiver ai specs list
+  cd ./my-project && npx create-quiver ai slices list --json
+  cd ./my-project && npx create-quiver ai trace report
   cd ./my-project && npx create-quiver ai agent set planner --provider codex --model gpt-5.5
   cd ./my-project && npx create-quiver ai agent list
   cd ./my-project && npx create-quiver ai plan --phase acceptance --input requirements.md --dry-run
-  cd ./my-project && npx create-quiver ai approve --phase acceptance --input acceptance.md
+  cd ./my-project && npx create-quiver ai revise --phase acceptance --input feedback.md --dry-run
+  cd ./my-project && npx create-quiver ai approve --phase acceptance --version 1
   cd ./my-project && npx create-quiver ai plan --phase technical-plan --dry-run
   cd ./my-project && npx create-quiver ai review-plan --dry-run
   cd ./my-project && npx create-quiver ai approve --phase technical-plan --version 1
   cd ./my-project && npx create-quiver spec create --dry-run
+  cd ./my-project && npx create-quiver spec start specs/my-project --dry-run
   cd ./my-project && npx create-quiver ai approvals
   cd ./my-project && npx create-quiver ai prompt-slice --slice specs/my-project/slices/slice-01/slice.json --dry-run
   cd ./my-project && npx create-quiver ai execute-slice --slice specs/my-project/slices/slice-01/slice.json --dry-run
@@ -207,6 +361,7 @@ Examples:
   cd ./my-project && npx create-quiver check-slice specs/my-project/slices/slice-01/slice.json
   cd ./my-project && npx create-quiver check-pr specs/my-project/slices/slice-01/slice.json
   cd ./my-project && npx create-quiver check-handoff specs/my-project/HANDOFF.md
+  cd ./my-project && npx create-quiver check-handoff specs/my-project/slices/slice-01/EXECUTION_BRIEF.md
   cd ./my-project && npx create-quiver new-handoff my-spec
   cd ./my-project && npx create-quiver cleanup-slice specs/my-project/slices/slice-01/slice.json
   cd ./my-project && npx create-quiver check-scope specs/my-project/slices/slice-01/slice.json
@@ -232,6 +387,7 @@ function parseArgs(argv) {
     discard: false,
     doctorFix: false,
     dryRun: false,
+    aiPrintPrompt: false,
     gate: 'execution',
     projectName: '',
     targetDir: '.',
@@ -245,12 +401,16 @@ function parseArgs(argv) {
     autoStart: false,
     specSlug: '',
     format: 'tree',
+    formatExplicit: false,
     showConflicts: false,
     level: null,
     unicode: false,
     aiCommand: '',
+    aiSecondaryCommand: '',
     aiAgentCommand: '',
     aiAgentRole: '',
+    aiRunCommand: '',
+    aiRunId: '',
     aiPhase: 'acceptance',
     aiProvider: 'codex',
     aiProviderExplicit: false,
@@ -396,6 +556,11 @@ function parseArgs(argv) {
       continue;
     }
 
+    if (arg === '--print-prompt') {
+      result.aiPrintPrompt = true;
+      continue;
+    }
+
     if (arg === '--commit') {
       result.aiCommit = true;
       continue;
@@ -476,6 +641,7 @@ function parseArgs(argv) {
         throw new Error(formatError('missing value for --format'));
       }
       result.format = value;
+      result.formatExplicit = true;
       continue;
     }
 
@@ -550,6 +716,15 @@ function parseArgs(argv) {
       continue;
     }
 
+    if (arg === '--run') {
+      const value = args[++index];
+      if (!value) {
+        throw new Error(formatError('missing value for --run'));
+      }
+      result.aiRunId = value;
+      continue;
+    }
+
     if (arg === '--role') {
       const value = args[++index];
       if (!value) {
@@ -748,6 +923,18 @@ function parseArgs(argv) {
         result.aiAgentRole = positional.shift();
       }
     }
+    if (result.aiCommand === 'run' && !result.aiRunCommand && positional.length > 0) {
+      result.aiRunCommand = positional.shift();
+    }
+    if ((result.aiCommand === 'specs' || result.aiCommand === 'slices' || result.aiCommand === 'trace') && !result.aiSecondaryCommand && positional.length > 0) {
+      result.aiSecondaryCommand = positional.shift();
+    }
+    if ((result.aiCommand === 'specs' || result.aiCommand === 'slices') && result.aiSecondaryCommand && result.aiSecondaryCommand !== 'list') {
+      throw new Error(formatError(`unsupported ai ${result.aiCommand} subcommand: ${result.aiSecondaryCommand}. Supported tasks: list`));
+    }
+    if (result.aiCommand === 'trace' && result.aiSecondaryCommand && result.aiSecondaryCommand !== 'report') {
+      throw new Error(formatError(`unsupported ai trace subcommand: ${result.aiSecondaryCommand}. Supported tasks: report`));
+    }
     if (positional.length > 0) {
       throw new Error(formatError('ai does not accept extra positional arguments'));
     }
@@ -1845,9 +2032,34 @@ function runMigrate(targetDir, options = {}) {
   const packageJson = loadPackageJson(projectRoot);
   const projectName = packageJson.name || path.basename(projectRoot) || 'Quiver Project';
   const packageRoot = path.resolve(__dirname, '../..');
-  const tempRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'quiver-migrate-'));
   const legacyLayout = inspectLegacyMigrationLayout(projectRoot);
 
+  if (options.dryRun) {
+    const migrationPlan = buildInitLayout(projectRoot, {
+      dryRun: true,
+      full: true,
+      legacyScripts: true,
+      projectName,
+      skipInstall: options.skipInstall === true,
+    });
+    console.log('Quiver migration dry-run');
+    console.log(`- Project: ${projectName}`);
+    console.log(`- Target: ${projectRoot}`);
+    console.log('- Writes: none');
+    console.log(`- Planned create: ${migrationPlan.summary.create}`);
+    console.log(`- Planned update: ${migrationPlan.summary.update}`);
+    console.log(`- Planned preserve: ${migrationPlan.summary.preserve}`);
+    if (legacyLayout.hasLegacyLayout) {
+      console.log(`- Legacy layout detected and preserved: ${legacyLayout.legacyPaths.join(', ')}`);
+    }
+    console.log('- Next command: npx create-quiver migrate --skip-install');
+    console.log('');
+    console.log(formatInitLayoutPlan(migrationPlan));
+    return;
+  }
+
+  const tempRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'quiver-migrate-'));
+
   try {
     const templateRoot = packTemplate(packageRoot, tempRoot);
     mergeDirectoryTree(templateRoot, path.join(projectRoot, 'docs-template'));
@@ -1958,6 +2170,11 @@ function runDoctor(targetDir, options = {}) {
     .filter((name) => typeof pkg.scripts?.[name] !== 'string');
   const missingAiScripts = [
     'quiver:ai:agent',
+    'quiver:ai:inspect',
+    'quiver:ai:export',
+    'quiver:ai:specs',
+    'quiver:ai:slices',
+    'quiver:ai:trace',
     'quiver:ai:onboard',
     'quiver:ai:plan',
     'quiver:ai:review-plan',
@@ -2045,6 +2262,16 @@ function printInitNextSteps(targetDir, projectName) {
 }
 
 async function run(argv) {
+  if (argv.length === 1 && argv[0] === 'help') {
+    printUsage();
+    return;
+  }
+
+  if (argv.length === 1 && (argv[0] === '-V' || argv[0] === '--version')) {
+    console.log(CLI_VERSION);
+    return;
+  }
+
   const args = parseArgs(argv);
 
   if (args.help) {
@@ -2087,7 +2314,69 @@ async function run(argv) {
 
   if (args.mode === 'ai') {
     if (!args.aiCommand) {
-      throw new Error(formatError('missing ai subcommand. Use: npx create-quiver ai onboard | prepare-context | plan | review-plan | approve | approvals | agent | prompt-slice | execute-slice | execute-plan | doctor | pr'));
+      throw new Error(formatError('missing ai subcommand. Use: npx create-quiver ai onboard | prepare-context | run | status | resume | inspect | export | specs | slices | trace | plan | revise | review-plan | approve | approvals | agent | prompt-slice | execute-slice | execute-plan | doctor | pr'));
+    }
+
+    if (args.aiCommand === 'run') {
+      runAiLifecycleRun(process.cwd(), {
+        command: args.aiRunCommand,
+        input: args.aiInput || undefined,
+        runId: args.aiRunId || undefined,
+        specSlug: args.specSlug || undefined,
+      });
+      return;
+    }
+
+    if (args.aiCommand === 'status') {
+      runAiLifecycleStatus(process.cwd(), {
+        runId: args.aiRunId || undefined,
+      });
+      return;
+    }
+
+    if (args.aiCommand === 'resume') {
+      runAiLifecycleResume(process.cwd(), {
+        runId: args.aiRunId || undefined,
+      });
+      return;
+    }
+
+    if (args.aiCommand === 'inspect') {
+      runAiInspect(process.cwd(), {
+        includeCompleted: args.includeCompleted,
+      });
+      return;
+    }
+
+    if (args.aiCommand === 'export') {
+      runAiExport(process.cwd(), {
+        format: args.formatExplicit ? args.format : 'json',
+        includeCompleted: args.includeCompleted,
+      });
+      return;
+    }
+
+    if (args.aiCommand === 'specs') {
+      runAiSpecsList(process.cwd(), {
+        includeCompleted: args.includeCompleted,
+        json: args.json,
+      });
+      return;
+    }
+
+    if (args.aiCommand === 'slices') {
+      runAiSlicesList(process.cwd(), {
+        includeCompleted: args.includeCompleted,
+        json: args.json,
+      });
+      return;
+    }
+
+    if (args.aiCommand === 'trace') {
+      runAiTraceReport(process.cwd(), {
+        includeCompleted: args.includeCompleted,
+      });
+      return;
     }
 
     if (args.aiCommand === 'agent') {
@@ -2107,6 +2396,7 @@ async function run(argv) {
         context: args.aiContext || undefined,
         dryRun: args.dryRun,
         input: args.aiInput || undefined,
+        printPrompt: args.aiPrintPrompt,
         provider: args.aiProvider,
         providerExplicit: args.aiProviderExplicit,
         role: args.aiRole,
@@ -2118,6 +2408,7 @@ async function run(argv) {
     if (args.aiCommand === 'prepare-context') {
       await runAiPrepareContext(process.cwd(), {
         dryRun: args.dryRun,
+        runId: args.aiRunId || undefined,
       });
       return;
     }
@@ -2128,9 +2419,11 @@ async function run(argv) {
         dryRun: args.dryRun,
         input: args.aiInput || undefined,
         phase: args.aiPhase,
+        printPrompt: args.aiPrintPrompt,
         provider: args.aiProvider,
         providerExplicit: args.aiProviderExplicit,
         role: args.aiRole,
+        runId: args.aiRunId || undefined,
         specSlug: args.specSlug || undefined,
         timeout: args.aiTimeout,
       });
@@ -2142,8 +2435,25 @@ async function run(argv) {
         context: args.aiContext || undefined,
         dryRun: args.dryRun,
         input: args.aiInput || undefined,
+        printPrompt: args.aiPrintPrompt,
+        provider: args.aiProvider,
+        providerExplicit: args.aiProviderExplicit,
+        timeout: args.aiTimeout,
+      });
+      return;
+    }
+
+    if (args.aiCommand === 'revise') {
+      await runAiRevise(process.cwd(), {
+        context: args.aiContext || undefined,
+        dryRun: args.dryRun,
+        input: args.aiInput || undefined,
+        phase: args.aiPhase,
+        printPrompt: args.aiPrintPrompt,
         provider: args.aiProvider,
         providerExplicit: args.aiProviderExplicit,
+        role: args.aiRole,
+        runId: args.aiRunId || undefined,
         timeout: args.aiTimeout,
       });
       return;
@@ -2154,6 +2464,7 @@ async function run(argv) {
         dryRun: args.dryRun,
         input: args.aiInput || undefined,
         phase: args.aiPhase,
+        runId: args.aiRunId || undefined,
         version: args.aiVersion || undefined,
       });
       return;
@@ -2228,7 +2539,7 @@ async function run(argv) {
       return;
     }
 
-    throw new Error(formatError(`unsupported ai subcommand: ${args.aiCommand}. Supported tasks: onboard, plan, review-plan, approve, approvals, agent, prompt-slice, execute-slice, execute-plan, doctor, pr`));
+    throw new Error(formatError(`unsupported ai subcommand: ${args.aiCommand}. Supported tasks: onboard, prepare-context, run, status, resume, inspect, export, specs, slices, trace, plan, revise, review-plan, approve, approvals, agent, prompt-slice, execute-slice, execute-plan, doctor, pr`));
   }
 
   if (args.mode === 'graph') {
@@ -2278,7 +2589,10 @@ async function run(argv) {
   }
 
   if (args.mode === 'migrate') {
-    runMigrate(args.targetDir, { skipInstall: args.skipInstall });
+    runMigrate(args.targetDir, {
+      dryRun: args.dryRun,
+      skipInstall: args.skipInstall,
+    });
     return;
   }
 
@@ -2315,10 +2629,10 @@ async function run(argv) {
     const repoRoot = process.cwd();
     const handoffInput = args.targetDir;
     if (!handoffInput || handoffInput === '.') {
-      throw new Error(formatError('missing handoff path. Use: npx create-quiver check-handoff specs/<spec-slug>/HANDOFF.md'));
+      throw new Error(formatError('missing handoff or brief path. Use: npx create-quiver check-handoff specs/<spec-slug>/HANDOFF.md or specs/<spec-slug>/slices/<slice-id>/EXECUTION_BRIEF.md'));
     }
     const resolved = checkHandoff(handoffInput, repoRoot);
-    console.log(`PASS: Handoff validated at ${resolved.relativePath}`);
+    console.log(`PASS: ${resolved.label} validated at ${resolved.relativePath}`);
     return;
   }
 
@@ -2366,7 +2680,9 @@ async function run(argv) {
     }
 
     if (args.specCommand === 'start') {
-      const report = startSpecWorktree(process.cwd(), args.targetDir);
+      const report = startSpecWorktree(process.cwd(), args.targetDir, {
+        dryRun: args.dryRun,
+      });
       process.stdout.write(formatSpecStartResult(report));
       return;
     }