create-quiver 0.13.0 → 0.14.0

package/src/create-quiver/index.js

@@ -10,6 +10,7 @@ const {
   formatDoctorFixPlan,
 } = require('./lib/doctor');
 const {
+  runActiveSlice: runAiActiveSlice,
   runAgent: runAiAgent,
   runApprovalStatus: runAiApprovalStatus,
   runApprove: runAiApprove,
@@ -25,6 +26,7 @@ const {
   runPlan: runAiPlan,
   runPrepareContext: runAiPrepareContext,
   runPr: runAiPr,
+  runRepairPlan: runAiRepairPlan,
   runPromptSlice: runAiPromptSlice,
   runReviewPlan: runAiReviewPlan,
   runRevise: runAiRevise,
@@ -99,6 +101,7 @@ const SUPPORTED_COMMAND_MODES = new Set([
 ]);
 
 const SUPPORTED_AI_COMMANDS = new Set([
+  'active-slice',
   'agent',
   'approve',
   'approval-status',
@@ -114,6 +117,7 @@ const SUPPORTED_AI_COMMANDS = new Set([
   'prepare-context',
   'pr',
   'prompt-slice',
+  'repair-plan',
   'review-plan',
   'revise',
   'resume',
@@ -159,7 +163,8 @@ const COMMAND_HELP_GROUPS = [
   {
     title: 'AI lifecycle',
     commands: [
-      ['ai run create', 'Create a durable AI lifecycle run from a requirements file.'],
+      ['ai run create|close', 'Create a durable AI lifecycle run or close/archive a completed or stale run without deleting evidence.'],
+      ['ai active-slice status|reconcile', 'Inspect or dry-run reconcile local active-slice state from every supported source.'],
       ['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.'],
@@ -167,6 +172,7 @@ const COMMAND_HELP_GROUPS = [
       ['ai agent set|list|show', 'Manage planner, executor, reviewer, and doctor provider profiles without secrets; use set --dry-run to preview.'],
       ['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 repair-plan', 'Repair an approved technical plan into a new structured draft without mutating the approved artifact.'],
       ['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.'],
@@ -243,6 +249,8 @@ function printUsage() {
   npx create-quiver plan [options]
   npx create-quiver ai <task> [options]
   npx create-quiver ai run create --input <requirements.md>
+  npx create-quiver ai run close --run <id>
+  npx create-quiver ai active-slice reconcile --dry-run
   npx create-quiver ai status [options]
   npx create-quiver ai resume [options]
   npx create-quiver ai inspect [options]
@@ -253,6 +261,7 @@ function printUsage() {
   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 ai repair-plan [options]
   npx create-quiver graph [options]
   npx create-quiver next [options]
   npx create-quiver migrate [options]
@@ -330,6 +339,7 @@ Examples:
   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 active-slice reconcile --dry-run
   cd ./my-project && npx create-quiver ai status
   cd ./my-project && npx create-quiver ai resume
   cd ./my-project && npx create-quiver ai inspect
@@ -345,12 +355,14 @@ Examples:
   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 repair-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 --yes create-quiver@${CLI_VERSION} 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
   cd ./my-project && npx create-quiver ai execute-slice --slice specs/my-project/slices/slice-01/slice.json --commit
   cd ./my-project && npx create-quiver ai execute-plan --dry-run --commit
@@ -936,7 +948,7 @@ function parseArgs(argv) {
     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) {
+    if ((result.aiCommand === 'specs' || result.aiCommand === 'slices' || result.aiCommand === 'trace' || result.aiCommand === 'active-slice') && !result.aiSecondaryCommand && positional.length > 0) {
       result.aiSecondaryCommand = positional.shift();
     }
     if ((result.aiCommand === 'specs' || result.aiCommand === 'slices') && result.aiSecondaryCommand && result.aiSecondaryCommand !== 'list') {
@@ -945,6 +957,9 @@ function parseArgs(argv) {
     if (result.aiCommand === 'trace' && result.aiSecondaryCommand && result.aiSecondaryCommand !== 'report') {
       throw new Error(formatError(`unsupported ai trace subcommand: ${result.aiSecondaryCommand}. Supported tasks: report`));
     }
+    if (result.aiCommand === 'active-slice' && result.aiSecondaryCommand && result.aiSecondaryCommand !== 'status' && result.aiSecondaryCommand !== 'reconcile') {
+      throw new Error(formatError(`unsupported ai active-slice subcommand: ${result.aiSecondaryCommand}. Supported tasks: status, reconcile`));
+    }
     if (positional.length > 0) {
       throw new Error(formatError('ai does not accept extra positional arguments'));
     }
@@ -2364,7 +2379,7 @@ 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 | run | status | resume | inspect | export | specs | slices | trace | plan | revise | 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 | active-slice | status | resume | inspect | export | specs | slices | trace | plan | revise | repair-plan | review-plan | approve | approvals | agent | prompt-slice | execute-slice | execute-plan | doctor | pr'));
     }
 
     if (args.aiCommand === 'run') {
@@ -2377,6 +2392,14 @@ async function run(argv) {
       return;
     }
 
+    if (args.aiCommand === 'active-slice') {
+      runAiActiveSlice(process.cwd(), {
+        command: args.aiSecondaryCommand || 'status',
+        dryRun: args.dryRun,
+      });
+      return;
+    }
+
     if (args.aiCommand === 'status') {
       runAiLifecycleStatus(process.cwd(), {
         runId: args.aiRunId || undefined,
@@ -2494,6 +2517,21 @@ async function run(argv) {
       return;
     }
 
+    if (args.aiCommand === 'repair-plan') {
+      await runAiRepairPlan(process.cwd(), {
+        context: args.aiContext || undefined,
+        dryRun: args.dryRun,
+        input: args.aiInput || undefined,
+        printPrompt: args.aiPrintPrompt,
+        provider: args.aiProvider,
+        providerExplicit: args.aiProviderExplicit,
+        role: args.aiRole,
+        runId: args.aiRunId || undefined,
+        timeout: args.aiTimeout,
+      });
+      return;
+    }
+
     if (args.aiCommand === 'revise') {
       await runAiRevise(process.cwd(), {
         context: args.aiContext || undefined,
@@ -2590,7 +2628,7 @@ async function run(argv) {
       return;
     }
 
-    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`));
+    throw new Error(formatError(`unsupported ai subcommand: ${args.aiCommand}. Supported tasks: onboard, prepare-context, run, active-slice, status, resume, inspect, export, specs, slices, trace, plan, revise, repair-plan, review-plan, approve, approvals, agent, prompt-slice, execute-slice, execute-plan, doctor, pr`));
   }
 
   if (args.mode === 'graph') {

package/src/create-quiver/lib/ai/context-packs.js

@@ -27,14 +27,14 @@ const CONTEXT_PACKS = Object.freeze({
     description: 'Executor context for a single slice handoff.',
     role: ROLES.EXECUTOR,
     tokenBudgetHint: 3200,
-    roleGuidance: 'Use slice handoff, allowed files, acceptance criteria, and validation commands only.',
+    roleGuidance: 'Use the slice.json, EXECUTION_BRIEF, CLOSURE_BRIEF, allowed files, acceptance criteria, and validation commands only. Do not request the full spec unless the slice brief explicitly requires it.',
   }),
   minimal: Object.freeze({
     name: 'minimal',
     description: 'Smallest executor context for narrowly-scoped tasks.',
     role: ROLES.EXECUTOR,
     tokenBudgetHint: 1200,
-    roleGuidance: 'Use the smallest safe set of slice details and avoid onboarding context.',
+    roleGuidance: 'Use the smallest safe set of slice details, avoid onboarding context, and avoid full-spec context by default.',
   }),
 });
 

package/src/create-quiver/lib/ai/export-state.js

@@ -5,6 +5,7 @@ const { listAgentProfiles } = require('../agent-profiles');
 const { PLANNER_APPROVAL_PHASES, readPhaseApproval } = require('../approvals');
 const { collectLayoutReport } = require('../doctor');
 const {
+  collectActiveSliceState,
   filterSlicesForExecution,
   groupSlicesBySpec: groupResolvedSlicesBySpec,
   isBlockedStatus: isCanonicalBlockedStatus,
@@ -296,14 +297,44 @@ function collectWarnings({ graph, layout, specs, slices }) {
 function collectNextSteps(data) {
   const activeRun = [...data.runs].reverse().find((run) => run.status !== 'closed');
   const commands = [];
+  const firstSpec = data.specs[0] || null;
+  const firstSlice = data.slices[0] || null;
+  const activeRunWantsSpecCreate = Boolean(activeRun?.next_command && activeRun.next_command.includes('spec create'));
 
-  commands.push({
-    id: activeRun ? 'continue-active-run' : 'create-ai-run',
-    command: activeRun ? activeRun.next_command : 'npx create-quiver ai run create --input <requirements.md>',
-    reason: activeRun ? `Continue AI run ${activeRun.run_id}.` : 'Start a new AI lifecycle run.',
-  });
+  if (activeRun && activeRunWantsSpecCreate && firstSpec) {
+    commands.push({
+      id: 'validate-existing-spec',
+      command: `npx create-quiver spec validate ${firstSpec.path}`,
+      reason: `A spec already exists while run ${activeRun.run_id} points to spec creation.`,
+    });
+    commands.push({
+      id: 'find-ready-slice',
+      command: 'npx create-quiver next --all-ready',
+      reason: 'Find ready slices before creating another spec.',
+    });
+    if (firstSlice?.slice_json) {
+      commands.push({
+        id: 'prompt-existing-slice',
+        command: `npx create-quiver ai prompt-slice --slice ${firstSlice.slice_json}`,
+        reason: 'Prepare a minimal executor prompt for the existing spec.',
+      });
+    }
+  } else {
+    commands.push({
+      id: activeRun ? 'continue-active-run' : 'create-ai-run',
+      command: activeRun ? activeRun.next_command : 'npx create-quiver ai run create --input <requirements.md>',
+      reason: activeRun ? `Continue AI run ${activeRun.run_id}.` : 'Start a new AI lifecycle run.',
+    });
+  }
 
   if (data.summary.slices > 0) {
+    if (data.active_slice?.reconciliation?.decision && data.active_slice.reconciliation.decision !== 'preserve') {
+      commands.push({
+        id: 'reconcile-active-slice',
+        command: 'npx create-quiver ai active-slice reconcile --dry-run',
+        reason: 'Review active-slice state before assigning more execution work.',
+      });
+    }
     commands.push({
       id: 'inspect-slices',
       command: 'npx create-quiver ai slices list',
@@ -379,6 +410,7 @@ function collectLifecycleExport(projectRoot, options = {}) {
   const approvals = normalizeApprovals(projectRoot);
   const progress = summarizeProgress(slices);
   const evidence = collectEvidenceEntries(slices);
+  const activeSlice = collectActiveSliceState(projectRoot, { slices: allSlices });
   const blockers = normalizedSlices
     .filter((slice) => slice.blocked_reason || String(slice.status).toLowerCase() === 'blocked')
     .map((slice) => ({ ref: slice.ref, reason: slice.blocked_reason || 'blocked' }));
@@ -389,6 +421,9 @@ function collectLifecycleExport(projectRoot, options = {}) {
   if (layout.layout === 'legacy' || layout.layout === 'hybrid' || layout.layout === 'incomplete') {
     blockers.push({ ref: 'migration', reason: layout.recommendations.join(' ') });
   }
+  if (activeSlice.reconciliation.decision === 'blocked') {
+    blockers.push({ ref: 'active-slice', reason: activeSlice.reconciliation.reason });
+  }
 
   const exportData = {
     schema_version: EXPORT_SCHEMA_VERSION,
@@ -413,6 +448,7 @@ function collectLifecycleExport(projectRoot, options = {}) {
       runs: runs.length,
       configured_agents: agents.filter((agent) => agent.configured).length,
       approvals: approvals.length,
+      active_slice_sources: activeSlice.sources.length,
       warnings: 0,
     },
     agents,
@@ -437,6 +473,7 @@ function collectLifecycleExport(projectRoot, options = {}) {
       dry_run_command: 'npx create-quiver migrate --dry-run',
     },
     evidence,
+    active_slice: activeSlice,
     warnings: [],
     blockers,
     next_steps: [],
@@ -480,6 +517,7 @@ function collectLifecycleExport(projectRoot, options = {}) {
         blocker: slice.blocked_reason,
       })),
       dependencies: graph.edges,
+      active_slice: activeSlice,
     },
   };
 
@@ -513,6 +551,15 @@ function formatLifecycleInspect(data) {
     lines.push(`- ${step.command}`);
   }
 
+  if (data.active_slice) {
+    lines.push(
+      '',
+      'Active slice state',
+      `- Sources: ${data.active_slice.sources.length}`,
+      `- Reconciliation: ${data.active_slice.reconciliation.decision} (${data.active_slice.reconciliation.reason})`,
+    );
+  }
+
   if (data.dashboard.blockers.length > 0) {
     lines.push('', 'Blockers');
     for (const blocker of data.dashboard.blockers) {

package/src/create-quiver/lib/ai/github.js

@@ -59,7 +59,8 @@ function formatGhInstallGuidance() {
     'GitHub CLI is not installed.',
     'macOS: brew install gh',
     'Linux: follow https://github.com/cli/cli/blob/trunk/docs/install_linux.md or use your distro package manager',
-    'Windows: winget install GitHub.cli',
+    'Windows PowerShell: winget install GitHub.cli',
+    'Git Bash/WSL: install gh inside the environment where the command will run, then authenticate there',
   ].join('\n');
 }
 
@@ -89,6 +90,16 @@ function formatShellPathGuidance(optionName, examplePath) {
   ].join('\n');
 }
 
+function formatSshAliasGuidance(alias = '<alias>') {
+  const resolvedAlias = alias || '<alias>';
+  return [
+    'SSH alias setup:',
+    `- macOS/Linux/Git Bash/WSL: edit ~/.ssh/config and add a Host entry such as \`Host ${resolvedAlias}\`, \`HostName github.com\`, \`User git\`, and \`IdentityFile ~/.ssh/<key>\`.`,
+    `- Windows PowerShell: edit $HOME\\.ssh\\config and add the same Host entry for ${resolvedAlias}.`,
+    `- Verify the alias with: ssh -T ${resolvedAlias}`,
+  ].join('\n');
+}
+
 function formatCommandForShell(command, args, quoter) {
   return `${command} ${args.map(quoter).join(' ')}`;
 }
@@ -326,7 +337,7 @@ function ensureSshHostAlias(sshHostAlias) {
       formatActionableError({
         failure: 'missing SSH host alias. Pass --ssh-host-alias <alias> before opening the PR.',
         impact: 'Quiver cannot verify which GitHub SSH identity should be used for this PR flow.',
-        fix: 'macOS/Linux/Git Bash/WSL: add a Host entry in ~/.ssh/config, for example `Host github-work`. Windows PowerShell: add the Host entry in $HOME\\.ssh\\config.',
+        fix: formatSshAliasGuidance('github-work'),
         nextCommand: 'ssh -T <alias>',
       }),
     );
@@ -675,6 +686,7 @@ module.exports = {
   ensureWorktreeReady,
   findPrBodyCandidates,
   formatGhInstallGuidance,
+  formatSshAliasGuidance,
   formatPreflightReport,
   formatPrCreateReport,
   preflightGitHubPr,

package/src/create-quiver/lib/ai/plan-review.js

@@ -5,6 +5,7 @@ const { readPhaseApproval, resolveApprovedPlannerInput } = require('../approvals
 const { quiverInternalPaths } = require('../init-layout');
 
 const PLAN_REVIEW_PROMPT_SOURCE = 'packaged production-readiness plan review template';
+const PLAN_REVIEW_RECOMMENDATIONS = Object.freeze(['approve', 'approve-with-risk', 'revise']);
 
 function formatError(message) {
   return `create-quiver: ${message}`;
@@ -50,6 +51,141 @@ function samePath(projectRoot, left, right) {
   return Boolean(left && right && resolvePath(projectRoot, left) === resolvePath(projectRoot, right));
 }
 
+function normalizeList(value) {
+  if (Array.isArray(value)) {
+    return value.map((item) => String(item || '').trim()).filter(Boolean);
+  }
+  if (typeof value === 'string' && value.trim()) {
+    return value.split(/\r?\n/).map((item) => item.replace(/^[-*]\s+/, '').trim()).filter(Boolean);
+  }
+  return [];
+}
+
+function normalizeRecommendation(value) {
+  const normalized = String(value || '').trim().toLowerCase().replace(/[_\s]+/g, '-');
+  if (PLAN_REVIEW_RECOMMENDATIONS.includes(normalized)) {
+    return normalized;
+  }
+  if (normalized === 'approved' || normalized === 'approvable') {
+    return 'approve';
+  }
+  if (normalized === 'approved-with-risk' || normalized === 'approvable-with-risk' || normalized === 'approve-with-risks') {
+    return 'approve-with-risk';
+  }
+  if (normalized === 'changes-required' || normalized === 'requires-revision' || normalized === 'needs-revision') {
+    return 'revise';
+  }
+  return '';
+}
+
+function recommendedNextCommand(recommendation, sourceVersion) {
+  if (recommendation === 'revise') {
+    return 'npx create-quiver ai revise --phase technical-plan --input <feedback.md> --dry-run';
+  }
+  return `npx create-quiver ai approve --phase technical-plan --version ${sourceVersion || '<n>'}`;
+}
+
+function parseJsonObject(value) {
+  try {
+    const parsed = JSON.parse(value);
+    return parsed && typeof parsed === 'object' && !Array.isArray(parsed) ? parsed : null;
+  } catch {
+    return null;
+  }
+}
+
+function extractStructuredReview(text) {
+  const raw = String(text || '').trim();
+  if (!raw) {
+    return null;
+  }
+
+  const direct = parseJsonObject(raw);
+  if (direct) {
+    return direct;
+  }
+
+  const fenced = raw.match(/```(?:json)?\s*([\s\S]*?)```/i);
+  if (!fenced) {
+    return null;
+  }
+  return parseJsonObject(fenced[1].trim());
+}
+
+function normalizeStructuredReview(parsed, sourceVersion) {
+  const review = parsed?.review || parsed?.plan_review || parsed;
+  const requiredFixes = normalizeList(review.required_fixes || review.requiredFixes || review.blocking_issues || review.blockingIssues);
+  const optionalHardening = normalizeList(review.optional_hardening || review.optionalHardening || review.non_blocking_issues || review.nonBlockingIssues);
+  const risks = normalizeList(review.risks || review.remaining_risks || review.remainingRisks);
+  let approvalRecommendation = normalizeRecommendation(review.approval_recommendation || review.approvalRecommendation || review.recommendation);
+  const blocking = review.blocking === true || review.has_blockers === true || review.hasBlockers === true || requiredFixes.length > 0;
+
+  if (!approvalRecommendation) {
+    approvalRecommendation = blocking ? 'revise' : optionalHardening.length > 0 || risks.length > 0 ? 'approve-with-risk' : 'approve';
+  }
+
+  const normalizedBlocking = blocking || approvalRecommendation === 'revise';
+
+  return {
+    schema_version: 1,
+    approval_recommendation: approvalRecommendation,
+    blocking: normalizedBlocking,
+    next_command: String(review.next_command || review.nextCommand || '').trim() || recommendedNextCommand(approvalRecommendation, sourceVersion),
+    optional_hardening: optionalHardening,
+    required_fixes: requiredFixes,
+    risks,
+    source: 'structured',
+  };
+}
+
+function classifyReviewText(text) {
+  const value = String(text || '').toLowerCase();
+  if (/\b(revise|revision|required fix|required fixes|blocking|blocker|not approvable|not ready)\b/.test(value)) {
+    return 'revise';
+  }
+  if (/\b(approve with risk|approvable with risk|non-blocking|optional hardening|p1|p2|risk)\b/.test(value)) {
+    return 'approve-with-risk';
+  }
+  if (/\b(approve|approved|approvable|no blockers|no blocking|production ready)\b/.test(value)) {
+    return 'approve';
+  }
+  return 'approve-with-risk';
+}
+
+function derivePlanReviewResult(contents, options = {}) {
+  const structured = extractStructuredReview(contents);
+  if (structured) {
+    return normalizeStructuredReview(structured, options.inputVersion);
+  }
+
+  const approvalRecommendation = classifyReviewText(contents);
+  const fallbackNote = approvalRecommendation === 'approve-with-risk'
+    ? ['Review output did not include structured metadata; treat approval as risky and inspect the human review text before approving.']
+    : [];
+  const requiredFixes = approvalRecommendation === 'revise'
+    ? ['Review output indicates the technical plan must be revised before approval.']
+    : [];
+
+  return {
+    schema_version: 1,
+    approval_recommendation: approvalRecommendation,
+    blocking: approvalRecommendation === 'revise',
+    next_command: recommendedNextCommand(approvalRecommendation, options.inputVersion),
+    optional_hardening: fallbackNote,
+    required_fixes: requiredFixes,
+    risks: [],
+    source: 'heuristic',
+  };
+}
+
+function reviewBlocksApproval(review) {
+  const result = review?.meta?.review_result || review?.review_result || null;
+  if (!result) {
+    return false;
+  }
+  return result.blocking === true || result.approval_recommendation === 'revise';
+}
+
 function latestTechnicalPlanDraft(approval) {
   const version = Number(approval.meta?.draft?.version || 0);
   if (!version) {
@@ -184,6 +320,9 @@ function savePlanReview(projectRoot, options = {}) {
   const now = new Date().toISOString();
   const contents = String(options.contents || '');
   const inputPath = options.inputPath || '';
+  const reviewResult = derivePlanReviewResult(contents, {
+    inputVersion: options.inputVersion,
+  });
 
   fs.writeFileSync(reviewPath, contents);
   const meta = {
@@ -194,6 +333,7 @@ function savePlanReview(projectRoot, options = {}) {
     path: toRelativePosix(projectRoot, reviewPath),
     raw_artifact_path: options.rawArtifactPath || null,
     output_source: options.outputSource || null,
+    review_result: reviewResult,
     reviewed_at: now,
   };
   fs.writeFileSync(planReviewMetaPath(projectRoot), `${JSON.stringify(meta, null, 2)}\n`);
@@ -216,6 +356,10 @@ function assertPlanReviewed(projectRoot) {
       : ' Preview the review first, then run `npx create-quiver ai review-plan` to persist it.';
     throw new Error(formatError(`ai plan phase 'spec' requires a reviewed and approved technical-plan input; current review status: ${review.status}. Run \`${nextCommand}\`.${followUp}`));
   }
+  if (reviewBlocksApproval(review)) {
+    const result = review.meta.review_result;
+    throw new Error(formatError(`ai plan phase 'spec' requires an approvable production review; current approval recommendation is ${result.approval_recommendation}. Run \`${result.next_command || recommendedNextCommand('revise')}\`.`));
+  }
   return review;
 }
 
@@ -243,6 +387,8 @@ function buildPlanReviewPrompt({ pack, inputText, inputPath }) {
     '- operational risks',
     '- recommended fixes to the plan',
     'If ambiguity is not blocking, state the safest assumption and continue.',
+    'Required output contract: include a fenced json block with `{ "review": { "blocking": boolean, "approvalRecommendation": "approve|approve-with-risk|revise", "requiredFixes": [], "optionalHardening": [], "risks": [], "nextCommand": "" } }`.',
+    'Use `approve` only when no required fixes remain. Use `approve-with-risk` when only optional hardening or accepted risks remain. Use `revise` when required fixes or blocking ambiguity remain.',
   ];
 
   if (inputPath) {
@@ -261,6 +407,7 @@ function buildPlanReviewPrompt({ pack, inputText, inputPath }) {
 
 function summarizePlanReview(projectRoot) {
   const review = readPlanReview(projectRoot);
+  const result = review.meta?.review_result || null;
   const lines = [
     'Phase: plan-review',
     `Status: ${review.status}`,
@@ -271,16 +418,28 @@ function summarizePlanReview(projectRoot) {
   if (review.meta?.source_file) {
     lines.push(`Source file: ${review.meta.source_file}`);
   }
+  if (result) {
+    const requiredFixes = normalizeList(result.required_fixes);
+    const optionalHardening = normalizeList(result.optional_hardening);
+    lines.push(`Approval recommendation: ${result.approval_recommendation}`);
+    lines.push(`Blocking: ${result.blocking ? 'yes' : 'no'}`);
+    lines.push(`Required fixes: ${requiredFixes.length}`);
+    lines.push(`Optional hardening: ${optionalHardening.length}`);
+    lines.push(`Next command: ${result.next_command}`);
+  }
   return `${lines.join('\n')}\n`;
 }
 
 module.exports = {
   PLAN_REVIEW_PROMPT_SOURCE,
+  PLAN_REVIEW_RECOMMENDATIONS,
   assertPlanReviewed,
   buildPlanReviewPrompt,
+  derivePlanReviewResult,
   planReviewMetaPath,
   planReviewPath,
   readPlanReview,
+  reviewBlocksApproval,
   resolveTechnicalPlanReviewInput,
   resolveReviewedTechnicalPlanInput,
   savePlanReview,

package/src/create-quiver/lib/ai/run-state.js

@@ -357,7 +357,9 @@ function formatAiRunStatus(projectRoot, run) {
     ].join('\n');
   }
 
-  return [
+  const openRuns = listAiRuns(projectRoot).filter((item) => item.status !== 'closed');
+  const otherOpenRuns = openRuns.filter((item) => item.run_id !== run.run_id);
+  const lines = [
     'AI run status',
     `Run: ${run.run_id}`,
     `Status: ${run.status}`,
@@ -366,9 +368,22 @@ function formatAiRunStatus(projectRoot, run) {
     `Requirement: ${run.requirement?.path || '(missing)'}`,
     `State: ${toRelativePosix(projectRoot, runStatePath(projectRoot, run.run_id))}`,
     `Approvals: ${run.approvals_path}`,
+    `Open runs: ${openRuns.length}`,
+  ];
+
+  if (otherOpenRuns.length > 0) {
+    lines.push('Other open runs:');
+    for (const item of otherOpenRuns) {
+      lines.push(`- ${item.run_id}: ${item.phase} (${item.status}) -> ${nextCommandForPhase(item.phase)}`);
+    }
+  }
+
+  lines.push(
     `Next safe command: ${nextCommandForPhase(run.phase)}`,
     '',
-  ].join('\n');
+  );
+
+  return lines.join('\n');
 }
 
 function formatAiRunResume(projectRoot, run) {

package/src/create-quiver/lib/ai/spec-generator.js

@@ -278,6 +278,20 @@ function buildSpecGenerationManifest({ inputText, inputPath, repoRoot, specSlug
   return manifest;
 }
 
+function validateTechnicalPlanSpecContract(repoRoot, options = {}) {
+  const inputPath = options.inputPath || options.input;
+  const inputText = typeof options.inputText === 'string'
+    ? options.inputText
+    : readSourceText(inputPath, repoRoot);
+
+  return buildSpecGenerationManifest({
+    inputPath,
+    inputText,
+    repoRoot,
+    specSlug: options.specSlug,
+  });
+}
+
 function validateSpecCollision(specDir) {
   if (fs.existsSync(specDir)) {
     throw new Error(formatError(`spec directory already exists: ${path.relative(process.cwd(), specDir)}`));
@@ -381,5 +395,6 @@ module.exports = {
   generateSpecArtifacts,
   parseApprovedManifest,
   readSourceText,
+  validateTechnicalPlanSpecContract,
   validateGeneratedSliceJson,
 };