create-quiver 0.15.1 → 0.15.3

package/specs/quiver-v36-ai-run-watch-portable/slices/slice-05-main-progress-user-guidance/slice.json

@@ -0,0 +1,71 @@
+{
+  "slice_id": "slice-05-main-progress-user-guidance",
+  "ticket": "QUIVER-36-05",
+  "type": "feature",
+  "title": "Main progress and user guidance",
+  "objective": "Show run id and watch command in the main human UX while preserving automation-safe output modes.",
+  "description": "Updates planner-oriented live AI commands to surface the generated run id, keep stable progress, and guide users to the portable watcher.",
+  "git": {
+    "branch_type": "feature",
+    "base_branch": "main",
+    "branch_slug": "v36-main-progress-user-guidance",
+    "branch_name": "feature/QUIVER-36-05-v36-main-progress-user-guidance"
+  },
+  "files": [
+    "src/create-quiver/commands/ai.js",
+    "src/create-quiver/lib/cli/ux.js",
+    "tests/commands/ai-plan.test.js",
+    "tests/commands/ai-revise.test.js",
+    "tests/commands/ai-run-watch.test.js"
+  ],
+  "expected_read_paths": [
+    "src/create-quiver/commands/ai.js",
+    "src/create-quiver/lib/ai/run-state.js",
+    "src/create-quiver/lib/ai/run-events.js",
+    "src/create-quiver/lib/cli/ux.js",
+    "specs/quiver-v36-ai-run-watch-portable/SPEC.md"
+  ],
+  "allowed_write_paths": [
+    "src/create-quiver/commands/ai.js",
+    "src/create-quiver/lib/cli/ux.js",
+    "tests/commands/ai-plan.test.js",
+    "tests/commands/ai-revise.test.js",
+    "tests/commands/ai-run-watch.test.js",
+    "specs/quiver-v36-ai-run-watch-portable/**"
+  ],
+  "depends_on": [
+    "slice-03-provider-streaming-integration",
+    "slice-04-ai-run-watch-command"
+  ],
+  "parallel_safe": "never",
+  "parallel_safe_reason": "Depends on the completed provider streaming and watcher contracts to avoid partial user guidance.",
+  "must": [
+    "Show the generated run id in human TTY output.",
+    "Show the exact watch command for the current run.",
+    "Keep raw provider output out of the main terminal by default.",
+    "Preserve CI, no-TTY, --json, --print-prompt, and --dry-run behavior.",
+    "Update run status on provider failure or main-command cancellation."
+  ],
+  "not_included": [
+    "Watcher implementation.",
+    "Provider event persistence.",
+    "Documentation updates."
+  ],
+  "acceptance": [
+    "Users can copy the displayed watch command and observe the same run.",
+    "Machine-readable output contains no human headings, spinners, or colors.",
+    "Dry-run and print-prompt do not create unexpected live run artifacts.",
+    "Failure and cancellation guidance is actionable and redacted."
+  ],
+  "tests": [
+    "node --test tests/commands/ai-plan.test.js tests/commands/ai-revise.test.js tests/commands/ai-run-watch.test.js",
+    "git diff --check"
+  ],
+  "validation_hints": [
+    "Test TTY and no-TTY paths separately.",
+    "Test provider failure and SIGINT after run creation."
+  ],
+  "estimated_hours": 4,
+  "status": "planned",
+  "blocked_reason": null
+}

package/specs/quiver-v36-ai-run-watch-portable/slices/slice-06-docs-generated-guidance/CLOSURE_BRIEF.md

@@ -0,0 +1,19 @@
+# CLOSURE_BRIEF - slice-06 Docs and generated guidance
+
+## Summary
+
+Pending implementation.
+
+## Validation
+
+- [ ] `node --test tests/commands/cli-contract.test.js tests/lib/init-docs.test.js`
+- [ ] `npx create-quiver spec validate specs/quiver-v36-ai-run-watch-portable --strict`
+- [ ] `git diff --check`
+
+## Pending
+
+- Update docs after public runtime behavior is implemented.
+
+## Remaining Risks
+
+- Documentation can drift if generated templates are not updated with the same examples as canonical docs.

package/specs/quiver-v36-ai-run-watch-portable/slices/slice-06-docs-generated-guidance/EXECUTION_BRIEF.md

@@ -0,0 +1,45 @@
+# EXECUTION_BRIEF - slice-06 Docs and generated guidance
+
+## Context
+
+The watcher introduces public commands, artifacts, and safety expectations. User-facing docs and generated project guidance must match the implemented behavior.
+
+## Objective
+
+Document `ai run watch`, run artifacts, JSONL mode, portability limits, and safe usage in canonical docs and generated guidance.
+
+## Scope
+
+- CLI UX documentation
+- AI guidance documentation
+- Command reference documentation
+- Generated docs/templates
+- Notes for legacy runs, stale runs, JSONL, and security
+
+## Acceptance Criteria
+
+- Docs explain what the Quiver run id is and that it is not a provider session id.
+- Docs include `npx create-quiver ai run watch --run <run-id>`.
+- Docs include `npx create-quiver ai run watch --latest`.
+- Docs include JSONL usage and state that `--json` emits JSONL only.
+- Docs explain completed, failed, canceled, stale, legacy, and missing-run behavior at a user level.
+- Docs explicitly state Quiver does not embed provider TUIs or require terminal multiplexers.
+- Generated guidance matches public command behavior.
+- Missing `docs/INDEX.md` debt is not hidden if the documentation workflow requires index updates.
+
+## Technical Plan Summary
+
+Update docs after runtime behavior stabilizes, then update generated guidance/templates so new projects receive the same command references.
+
+## Restrictions
+
+- Do not document behavior that has not been implemented.
+- Do not add architecture claims that contradict the SPEC.
+- Do not duplicate large sections across docs when a command reference link is enough.
+
+## Completion Checklist
+
+- [ ] Canonical docs updated.
+- [ ] Generated guidance updated.
+- [ ] Command examples verified.
+- [ ] Documentation debt captured if `docs/INDEX.md` remains absent.

package/specs/quiver-v36-ai-run-watch-portable/slices/slice-06-docs-generated-guidance/slice.json

@@ -0,0 +1,77 @@
+{
+  "slice_id": "slice-06-docs-generated-guidance",
+  "ticket": "QUIVER-36-06",
+  "type": "documentation",
+  "title": "Docs and generated guidance",
+  "objective": "Document the portable watcher in canonical docs, command references, and generated guidance.",
+  "description": "Adds user-facing and generated documentation for run ids, watch commands, JSONL mode, artifacts, portability, and safety expectations.",
+  "git": {
+    "branch_type": "docs",
+    "base_branch": "main",
+    "branch_slug": "v36-docs-generated-guidance",
+    "branch_name": "docs/QUIVER-36-06-v36-docs-generated-guidance"
+  },
+  "files": [
+    "docs/CLI_UX_GUIDE.md",
+    "README_FOR_AI.md",
+    "docs/reference/commands.md",
+    "docs/COMMANDS.md.template",
+    "src/create-quiver/lib/init-docs.js",
+    "tests/commands/cli-contract.test.js",
+    "tests/lib/init-docs.test.js"
+  ],
+  "expected_read_paths": [
+    "docs/CLI_UX_GUIDE.md",
+    "README_FOR_AI.md",
+    "docs/reference/commands.md",
+    "docs/COMMANDS.md.template",
+    "src/create-quiver/lib/init-docs.js",
+    "specs/quiver-v36-ai-run-watch-portable/SPEC.md"
+  ],
+  "allowed_write_paths": [
+    "docs/CLI_UX_GUIDE.md",
+    "README_FOR_AI.md",
+    "docs/reference/commands.md",
+    "docs/COMMANDS.md.template",
+    "src/create-quiver/lib/init-docs.js",
+    "tests/commands/cli-contract.test.js",
+    "tests/lib/init-docs.test.js",
+    "specs/quiver-v36-ai-run-watch-portable/**"
+  ],
+  "depends_on": [
+    "slice-04-ai-run-watch-command",
+    "slice-05-main-progress-user-guidance"
+  ],
+  "parallel_safe": "conditional",
+  "parallel_safe_reason": "Can proceed after command behavior is stable; generated docs and canonical docs should be updated in one pass.",
+  "must": [
+    "Document run id semantics.",
+    "Document --run and --latest usage.",
+    "Document JSONL-only behavior for --json.",
+    "Document stale, legacy, completed, failed, canceled, and missing-run behavior.",
+    "Document that Quiver does not embed provider TUIs or require terminal multiplexers.",
+    "Update generated guidance/templates with matching command examples."
+  ],
+  "not_included": [
+    "Runtime behavior changes.",
+    "Spec redesign."
+  ],
+  "acceptance": [
+    "Docs match the implemented public CLI behavior.",
+    "Generated guidance includes the same essential watcher commands.",
+    "No docs claim platform-specific terminal automation as core behavior.",
+    "Documentation debt around missing docs/INDEX.md is surfaced if still applicable."
+  ],
+  "tests": [
+    "node --test tests/commands/cli-contract.test.js tests/lib/init-docs.test.js",
+    "npx create-quiver spec validate specs/quiver-v36-ai-run-watch-portable --strict",
+    "git diff --check"
+  ],
+  "validation_hints": [
+    "Generate a fresh sandbox project and inspect AI guidance files.",
+    "Check that documented commands are accepted by CLI parsing tests."
+  ],
+  "estimated_hours": 3,
+  "status": "planned",
+  "blocked_reason": null
+}

package/specs/quiver-v36-ai-run-watch-portable/slices/slice-07-tests-cross-platform-readiness/CLOSURE_BRIEF.md

@@ -0,0 +1,22 @@
+# CLOSURE_BRIEF - slice-07 Tests and cross-platform readiness
+
+## Summary
+
+Pending implementation.
+
+## Validation
+
+- [ ] `node --test tests/**/*.test.js`
+- [ ] `git diff --check`
+- [ ] `npx create-quiver spec validate specs/quiver-v36-ai-run-watch-portable --strict`
+- [ ] `npm run package:quiver`
+- [ ] `npm run smoke:create-quiver`
+- [ ] `node scripts/ci/smoke-cross-platform.js`
+
+## Pending
+
+- Execute after runtime and docs slices are complete.
+
+## Remaining Risks
+
+- Cross-platform behavior can regress if validation depends on POSIX-only shell behavior instead of Node-based smoke coverage.

package/specs/quiver-v36-ai-run-watch-portable/slices/slice-07-tests-cross-platform-readiness/EXECUTION_BRIEF.md

@@ -0,0 +1,46 @@
+# EXECUTION_BRIEF - slice-07 Tests and cross-platform readiness
+
+## Context
+
+The feature changes long-running AI command observability and touches persistence, redaction, command UX, and docs. Final validation must prove the full workflow is production-ready across supported terminals and platforms.
+
+## Objective
+
+Add and run final automated validation, package smoke tests, and cross-platform smoke coverage for the portable watcher.
+
+## Scope
+
+- Focused unit and command tests
+- Integration-style simulated provider streaming tests
+- Package smoke validation
+- Cross-platform smoke script updates
+- Final evidence report updates
+
+## Acceptance Criteria
+
+- Tests cover path traversal and malformed run ids.
+- Tests cover missing run, `--latest`, completed, failed, canceled, stale, and legacy runs.
+- Tests cover partial JSONL lines during append.
+- Tests cover split secrets, ANSI/control character sanitization, and log truncation.
+- Tests cover no-TTY, CI, JSON, dry-run, and print-prompt behavior.
+- Tests cover paths with spaces.
+- Simulated provider streaming proves stdout/stderr capture, event persistence, cancellation, and failure handling.
+- Package smoke proves `npx create-quiver ai run watch ...` resolves from the packaged CLI.
+- Final evidence records commands run and any remaining risks.
+
+## Technical Plan Summary
+
+Close gaps left by earlier slices with targeted tests first, then run full project validation and package smokes. Prefer deterministic local simulations over external provider calls.
+
+## Restrictions
+
+- Do not require real provider credentials for validation.
+- Do not require `tmux`, `zellij`, Windows Terminal automation, or `node-pty`.
+- Do not rely on platform-specific shell syntax in required smoke tests.
+
+## Completion Checklist
+
+- [ ] Focused tests added or updated.
+- [ ] Cross-platform smoke covers watcher behavior.
+- [ ] Package smoke covers packaged command resolution.
+- [ ] Evidence report updated with command results.

package/specs/quiver-v36-ai-run-watch-portable/slices/slice-07-tests-cross-platform-readiness/slice.json

@@ -0,0 +1,87 @@
+{
+  "slice_id": "slice-07-tests-cross-platform-readiness",
+  "ticket": "QUIVER-36-07",
+  "type": "validation",
+  "title": "Tests and cross-platform readiness",
+  "objective": "Prove the portable watcher is covered by automated tests, package smoke, and cross-platform smoke validation.",
+  "description": "Adds final coverage for persistence, watcher behavior, security, automation modes, package execution, and platform portability.",
+  "git": {
+    "branch_type": "test",
+    "base_branch": "main",
+    "branch_slug": "v36-tests-cross-platform-readiness",
+    "branch_name": "test/QUIVER-36-07-v36-tests-cross-platform-readiness"
+  },
+  "files": [
+    "tests/commands/ai-run-watch.test.js",
+    "tests/commands/ai-plan.test.js",
+    "tests/lib/ai-run-state.test.js",
+    "tests/lib/ai-run-events.test.js",
+    "tests/lib/ai-provider-streaming.test.js",
+    "scripts/ci/smoke-create-quiver.sh",
+    "scripts/ci/smoke-cross-platform.js",
+    "specs/quiver-v36-ai-run-watch-portable/EVIDENCE_REPORT.md"
+  ],
+  "expected_read_paths": [
+    "tests/commands/ai-run-watch.test.js",
+    "tests/commands/ai-plan.test.js",
+    "tests/lib/ai-run-state.test.js",
+    "tests/lib/ai-run-events.test.js",
+    "scripts/ci/smoke-create-quiver.sh",
+    "scripts/ci/smoke-cross-platform.js",
+    "specs/quiver-v36-ai-run-watch-portable/SPEC.md"
+  ],
+  "allowed_write_paths": [
+    "tests/commands/ai-run-watch.test.js",
+    "tests/commands/ai-plan.test.js",
+    "tests/lib/ai-run-state.test.js",
+    "tests/lib/ai-run-events.test.js",
+    "tests/lib/ai-provider-streaming.test.js",
+    "scripts/ci/smoke-create-quiver.sh",
+    "scripts/ci/smoke-cross-platform.js",
+    "specs/quiver-v36-ai-run-watch-portable/**"
+  ],
+  "depends_on": [
+    "slice-02-event-writer-redacted-logs",
+    "slice-03-provider-streaming-integration",
+    "slice-04-ai-run-watch-command",
+    "slice-05-main-progress-user-guidance",
+    "slice-06-docs-generated-guidance"
+  ],
+  "parallel_safe": "never",
+  "parallel_safe_reason": "Final readiness must run after runtime and docs behavior stabilizes.",
+  "must": [
+    "Cover path traversal and malformed run ids.",
+    "Cover missing, latest, completed, failed, canceled, stale, and legacy runs.",
+    "Cover partial JSONL lines.",
+    "Cover split secrets, ANSI/control sanitization, and log truncation.",
+    "Cover no-TTY, CI, JSON, dry-run, and print-prompt behavior.",
+    "Cover paths with spaces.",
+    "Cover simulated provider streaming for stdout, stderr, cancellation, and failure.",
+    "Run package smoke and cross-platform smoke."
+  ],
+  "not_included": [
+    "Real provider credential tests.",
+    "Publishing to npm."
+  ],
+  "acceptance": [
+    "Required validation commands complete or documented blockers are recorded.",
+    "No required smoke depends on a terminal multiplexer.",
+    "Evidence report lists final commands and outcomes.",
+    "All P0 safety criteria from the SPEC have automated coverage."
+  ],
+  "tests": [
+    "node --test tests/**/*.test.js",
+    "git diff --check",
+    "npx create-quiver spec validate specs/quiver-v36-ai-run-watch-portable --strict",
+    "npm run package:quiver",
+    "npm run smoke:create-quiver",
+    "node scripts/ci/smoke-cross-platform.js"
+  ],
+  "validation_hints": [
+    "Use simulated providers instead of external AI CLIs.",
+    "Run package smoke from a path containing spaces."
+  ],
+  "estimated_hours": 6,
+  "status": "planned",
+  "blocked_reason": null
+}

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

@@ -85,6 +85,10 @@ const {
   savePlannerDraft,
   summarizePlannerApproval,
 } = require('../lib/approvals');
+const {
+  buildApprovalCandidateReport,
+  formatApprovalDecisionLines,
+} = require('../lib/ai/approval-candidates');
 const { assertPlannerPhaseReady, getPlannerPhaseDetails, normalizePlannerPhase, PlannerPhaseError } = require('../lib/ai/phase-gates');
 const { collectActiveSliceState, resolveProjectState } = require('../lib/project-state-resolver');
 
@@ -1224,7 +1228,11 @@ function formatApprovalStatusReport(repoRoot) {
   for (const phase of PLANNER_APPROVAL_PHASES) {
     const summary = summarizePlannerApproval(repoRoot, phase).trimEnd();
     const relation = classifyGlobalApprovalRelation(readPhaseApproval(repoRoot, phase), runApprovalRows);
-    sections.push(`${summary}\nRun relation: ${relation}`);
+    const candidates = buildApprovalCandidateReport(repoRoot, phase);
+    const decisionLines = formatApprovalDecisionLines(candidates)
+      .map((line) => `- ${line}`)
+      .join('\n');
+    sections.push(`${summary}\nRun relation: ${relation}${decisionLines ? `\nApproval candidates:\n${decisionLines}` : ''}`);
   }
   sections.push(summarizePlanReview(repoRoot).trimEnd());
   return `${sections.join('\n\n')}\n`;
@@ -1657,7 +1665,7 @@ async function runPlan(repoRoot, options = {}) {
 
   if (options.revise === true) {
     if (!inputPath) {
-      throw new Error(formatError(`missing feedback input file for ai revise phase '${phase}'`));
+      throw new Error(formatError(`missing feedback input file for ai revise phase '${phase}'. Use: npx create-quiver ai revise --phase ${phase} --input <feedback.md> --dry-run`));
     }
     const feedbackText = readTextFile(inputPath, repoRoot);
     const revisionInput = buildRevisionInput({
@@ -2190,20 +2198,112 @@ async function runRevise(repoRoot, options = {}) {
   });
 }
 
+function formatApprovalCandidateHint(candidate) {
+  const parts = [];
+  if (candidate.current) {
+    parts.push('current');
+  }
+  if (candidate.created_at) {
+    parts.push(candidate.created_at);
+  }
+  if (candidate.review?.recommendation) {
+    parts.push(`review=${candidate.review.recommendation}`);
+  }
+  if (candidate.review?.required_fixes_count) {
+    parts.push(`required fixes=${candidate.review.required_fixes_count}`);
+  }
+  if (candidate.review?.optional_hardening_count) {
+    parts.push(`optional=${candidate.review.optional_hardening_count}`);
+  }
+  if (candidate.review?.risks_count) {
+    parts.push(`risks=${candidate.review.risks_count}`);
+  }
+  parts.push(candidate.reason);
+  return parts.filter(Boolean).join(', ');
+}
+
+function approvalSelectionOptions(report) {
+  return report.candidates.map((candidate) => ({
+    label: `${candidate.label}${candidate.recommended ? ' (recommended)' : candidate.current ? ' (current)' : ' (history)'}`,
+    value: String(candidate.version || ''),
+    hint: formatApprovalCandidateHint(candidate),
+    default: candidate.recommended === true,
+    raw: candidate,
+  }));
+}
+
+async function resolveApprovalVersion(repoRoot, phase, options = {}) {
+  if (options.version) {
+    return options.version;
+  }
+
+  const canPrompt = isInteractiveAgentPromptAvailable(options);
+  const shouldPrompt = options.interactive === true || canPrompt;
+  const report = buildApprovalCandidateReport(repoRoot, phase);
+
+  if (!shouldPrompt || !canPrompt) {
+    const recommended = report.recommended?.version || report.latest_version || '<n>';
+    throw new Error(formatActionableError({
+      failure: `ai approve --phase ${phase} requires --version <n> when prompts are not available.`,
+      impact: 'Quiver cannot safely guess which saved planner draft the human approved.',
+      fix: 'Review drafts with `npx create-quiver ai approvals`, then pass the version explicitly.',
+      nextCommand: `npx create-quiver ai approve --phase ${phase} --version ${recommended}`,
+    }));
+  }
+
+  if (report.candidates.length === 0) {
+    throw new Error(formatActionableError({
+      failure: `ai approve --phase ${phase} has no saved drafts to approve.`,
+      impact: 'There is no planner artifact that can pass the approval gate.',
+      fix: `Generate a ${phase} draft first.`,
+      nextCommand: `npx create-quiver ai plan --phase ${phase}${phase === 'acceptance' ? ' --input <requirements.md>' : ''} --dry-run`,
+    }));
+  }
+
+  const selected = await selectOption(`¿Qué ${phase} draft querés aprobar?`, approvalSelectionOptions(report), {
+    env: options.env,
+    error: options.error,
+    input: options.input,
+    interactive: true,
+    noColor: options.noColor,
+    output: options.output,
+    prompts: options.prompts,
+    promptSelect: options.promptSelect,
+    stdinIsTTY: options.stdinIsTTY,
+    stdoutIsTTY: options.stdoutIsTTY,
+    stderrIsTTY: options.stderrIsTTY,
+    defaultValue: report.recommended?.version ? String(report.recommended.version) : undefined,
+    flag: '--version',
+    name: `${phase} approval version`,
+  });
+
+  const candidate = selected.raw;
+  if (!candidate?.approvable) {
+    throw new Error(formatActionableError({
+      failure: `${phase} draft ${selected.label} is not approvable.`,
+      impact: candidate?.review?.blocking
+        ? 'The current review gate blocks technical-plan approval.'
+        : 'Quiver only approves the current eligible draft version.',
+      fix: candidate?.reason || 'Inspect planner approvals before approving.',
+      nextCommand: candidate?.next_command || `npx create-quiver ai approvals`,
+    }));
+  }
+
+  return selected.value;
+}
+
 async function runApprove(repoRoot, options = {}) {
   const phase = normalizePlannerPhase(options.phase || DEFAULT_PLAN_PHASE);
   if (phase === 'spec') {
     throw new Error(formatError(`ai approve does not support phase '${phase}'`));
   }
 
-  if (!options.version) {
-    throw new Error(formatError(`ai approve --phase ${phase} requires --version <n>. Review drafts with \`npx create-quiver ai approvals\`.`));
-  }
-
   if (options.input) {
     throw new Error(formatError(`ai approve --phase ${phase} approves saved draft versions only. Use \`npx create-quiver ai revise --phase ${phase} --input ${options.input}\` to create a new draft first.`));
   }
 
+  const version = await resolveApprovalVersion(repoRoot, phase, options);
+
   if (phase === 'technical-plan') {
     const review = readPlanReview(repoRoot);
     if (review.status !== 'unapproved' && review.status !== 'reviewed') {
@@ -2214,24 +2314,24 @@ async function runApprove(repoRoot, options = {}) {
       const requiredFixes = Array.isArray(result.required_fixes) ? result.required_fixes.length : 0;
       throw new Error(formatError(`ai approve --phase technical-plan is blocked by plan review; approval recommendation is ${result.approval_recommendation}. Required fixes: ${requiredFixes}. Next command: ${result.next_command}`));
     }
-    assertTechnicalPlanDraftHasSpecContract(repoRoot, options.version);
+    assertTechnicalPlanDraftHasSpecContract(repoRoot, version);
   }
 
   const inputText = '';
 
   if (options.dryRun) {
-    process.stdout.write(formatApprovalDryRunResult({ phase, input: options.input, version: options.version }));
+    process.stdout.write(formatApprovalDryRunResult({ phase, input: options.input, version }));
     return {
       task: 'approve',
       phase,
       input: options.input,
-      version: options.version || null,
+      version: version || null,
       dryRun: true,
     };
   }
 
   const result = approvePlannerPhase(repoRoot, phase, options.input || '', inputText, {
-    version: options.version || undefined,
+    version: version || undefined,
   });
   const lifecycleRun = ensureAiRun(repoRoot, {
     command: `ai approve --phase ${phase}`,
@@ -2241,7 +2341,7 @@ async function runApprove(repoRoot, options = {}) {
   recordAiRunApproval(repoRoot, lifecycleRun.run_id, {
     artifact: path.relative(repoRoot, result.filePath).split(path.sep).join('/'),
     phase,
-    source_file: options.input || `draft version ${options.version}`,
+    source_file: options.input || `draft version ${version}`,
     version: result.version || null,
   });
   updateAiRunPhase(repoRoot, lifecycleRun.run_id, phase === 'acceptance' ? 'acceptance-approved' : 'technical-plan-approved', {
@@ -2250,7 +2350,7 @@ async function runApprove(repoRoot, options = {}) {
   });
   process.stdout.write(formatApprovalResult({
     ...result,
-    sourceFile: options.input || `draft version ${options.version}`,
+    sourceFile: options.input || `draft version ${version}`,
   }, repoRoot));
 
   return {

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

@@ -0,0 +1,31 @@
+const {
+  buildErrorPayload,
+  collectDashboardReport,
+  formatHumanDashboard,
+  normalizeDashboardOptions,
+} = require('../lib/dashboard');
+
+function runDashboard(repoRoot, options = {}) {
+  try {
+    normalizeDashboardOptions(options);
+    const report = collectDashboardReport(repoRoot, options);
+    if (options.json) {
+      process.stdout.write(`${JSON.stringify(report, null, 2)}\n`);
+      return report;
+    }
+
+    process.stdout.write(formatHumanDashboard(report, options));
+    return report;
+  } catch (error) {
+    if (options.json) {
+      process.stdout.write(`${JSON.stringify(buildErrorPayload(error), null, 2)}\n`);
+      process.exitCode = 1;
+      return null;
+    }
+    throw error;
+  }
+}
+
+module.exports = {
+  runDashboard,
+};