create-quiver 0.13.0 → 0.14.1

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

@@ -2,6 +2,8 @@ const fs = require('node:fs');
 const path = require('node:path');
 
 const { checkHandoff } = require('../lib/handoff');
+const { openEditor } = require('../lib/cli/editor');
+const { createUx } = require('../lib/cli/ux');
 const { parseJsonWithComments } = require('../lib/json');
 const { assertPathInsideRoot, validateProjectRelativePaths } = require('../lib/paths');
 const { resolveReviewedTechnicalPlanInput } = require('../lib/ai/plan-review');
@@ -129,6 +131,12 @@ function detectCycle(nodes) {
   return null;
 }
 
+function missingGitFields(git) {
+  const data = git && typeof git === 'object' ? git : {};
+  return ['branch_type', 'base_branch', 'branch_slug', 'branch_name']
+    .filter((field) => !String(data[field] || '').trim());
+}
+
 function buildSpecValidationReport(repoRoot, specInput, options = {}) {
   const strict = options.strict === true;
   const specDir = resolveSpecDir(repoRoot, specInput);
@@ -190,6 +198,10 @@ function buildSpecValidationReport(repoRoot, specInput, options = {}) {
     if (!Array.isArray(writeScope) || writeScope.length === 0) {
       errors.push(`${relativeSliceFile} must declare files or allowed_write_paths`);
     }
+    const missingGit = missingGitFields(json.git);
+    if (missingGit.length > 0) {
+      errors.push(`${relativeSliceFile} must declare git.branch_type, git.base_branch, git.branch_slug, and git.branch_name for local execution (missing: ${missingGit.join(', ')}).`);
+    }
     try {
       validateProjectRelativePaths(writeScope, `${relativeSliceFile} write scope`);
       validateProjectRelativePaths(json.expected_read_paths, `${relativeSliceFile} expected_read_paths`);
@@ -352,6 +364,10 @@ function formatSpecCreateDryRun(preview) {
     lines.push(`- ${file}`);
   }
 
+  if (preview.reviewRequested) {
+    lines.push('Review requested: yes (dry-run preview only; no editor opened and no files written).');
+  }
+
   lines.push(...formatNextCommands(preview.relativeSpecDir));
   lines.push('No files will be written in dry-run mode.');
   return `${lines.join('\n')}\n`;
@@ -374,11 +390,63 @@ function formatSpecCreateResult(result, repoRoot) {
   return `${lines.join('\n')}\n`;
 }
 
-function runCreateSpec(repoRoot, options = {}) {
+function createSpecReviewFile(preview, options = {}) {
+  const os = require('node:os');
+  const reviewDir = options.reviewDir || fs.mkdtempSync(path.join(os.tmpdir(), 'quiver-spec-create-review-'));
+  const reviewPath = path.join(reviewDir, 'spec-create-preview.md');
+  fs.mkdirSync(reviewDir, { recursive: true });
+  fs.writeFileSync(reviewPath, formatSpecCreateDryRun({ ...preview, reviewRequested: false }));
+  return reviewPath;
+}
+
+async function confirmSpecCreate(message, options = {}) {
+  if (options.interactive !== true) {
+    return;
+  }
+
+  const ux = options.ux || createUx({
+    interactive: true,
+    promptConfirm: options.promptConfirm,
+    stdinIsTTY: options.stdinIsTTY,
+    stdoutIsTTY: options.stdoutIsTTY,
+    stderrIsTTY: options.stderrIsTTY,
+    write: options.write,
+  });
+  const confirmed = await ux.promptConfirm(message, { initialValue: false });
+  if (!confirmed) {
+    throw new Error(formatError('spec create interactive approval declined. No files were written.'));
+  }
+}
+
+async function reviewSpecCreatePreview(repoRoot, preview, options = {}) {
+  if (options.review !== true) {
+    return '';
+  }
+
+  const reviewPath = createSpecReviewFile(preview, options);
+  const hasEditorRunner = typeof options.openEditorFn === 'function';
+  const canOpenEditor = hasEditorRunner || options.stdinIsTTY === true || (options.stdinIsTTY !== false && Boolean(process.stdin.isTTY));
+
+  if (!canOpenEditor) {
+    throw new Error(formatError(`spec create --review requires an interactive terminal or an injected editor runner.\nReview artifact: ${reviewPath}`));
+  }
+
+  const editorResult = hasEditorRunner
+    ? options.openEditorFn(reviewPath, { cwd: repoRoot, env: options.env || process.env })
+    : openEditor(reviewPath, { cwd: repoRoot, env: options.env || process.env });
+
+  if (!editorResult || editorResult.ok !== true) {
+    throw new Error(formatError(`${editorResult?.reason || 'spec create review was canceled.'}\nReview artifact: ${reviewPath}`));
+  }
+
+  return reviewPath;
+}
+
+async function runCreateSpec(repoRoot, options = {}) {
   const preview = buildSpecCreatePreview(repoRoot, options);
 
   if (options.dryRun) {
-    process.stdout.write(formatSpecCreateDryRun(preview));
+    process.stdout.write(formatSpecCreateDryRun({ ...preview, reviewRequested: options.review === true }));
     return {
       task: 'spec-create',
       dryRun: true,
@@ -388,6 +456,9 @@ function runCreateSpec(repoRoot, options = {}) {
     };
   }
 
+  const reviewPath = await reviewSpecCreatePreview(repoRoot, preview, options);
+  await confirmSpecCreate(`Create spec '${preview.manifest.slug}'?`, options);
+
   const result = generateSpecArtifacts(repoRoot, {
     input: preview.inputPath,
     specSlug: options.specSlug,
@@ -401,6 +472,7 @@ function runCreateSpec(repoRoot, options = {}) {
     specDir: toRelativePosix(repoRoot, result.specDir),
     files: result.files.map((filePath) => toRelativePosix(repoRoot, filePath)),
     manifest: result.manifest,
+    reviewPath,
   };
 }
 

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,
@@ -51,6 +53,7 @@ const { checkPrReadiness, checkScope, checkSliceReadiness } = require('./lib/rea
 const { cleanupSlice, refreshActiveSlicesBoard, startSlice } = require('./lib/lifecycle');
 const { buildSpecStatus, closeSpecWorktree, formatSpecCloseResult, formatSpecStartResult, formatSpecStatus, startSpecWorktree } = require('./lib/spec-worktrees');
 const { getContextPathExclusionReason } = require('./lib/ai/safety');
+const { validateUxFlags } = require('./lib/cli/ux-flags');
 const { relativePosixPath, resolveTargetRoot } = require('./lib/paths');
 const {
   CURRENT_SCAN_RELATIVE_PATH,
@@ -99,6 +102,7 @@ const SUPPORTED_COMMAND_MODES = new Set([
 ]);
 
 const SUPPORTED_AI_COMMANDS = new Set([
+  'active-slice',
   'agent',
   'approve',
   'approval-status',
@@ -114,6 +118,7 @@ const SUPPORTED_AI_COMMANDS = new Set([
   'prepare-context',
   'pr',
   'prompt-slice',
+  'repair-plan',
   'review-plan',
   'revise',
   'resume',
@@ -159,7 +164,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 +173,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 +250,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 +262,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]
@@ -297,6 +307,10 @@ Options:
       --include-templates     Export packaged templates in init profile
       --dry-run               Preview init, analyze, migrate, prepare, spec create/start/close, demo, ai agent set, or AI work without executing writes/providers
       --print-prompt          Print the exact AI prompt and exit without executing provider CLIs
+      --with-planner          Enable planner-assisted behavior on commands that explicitly support it
+      --interactive           Enable prompts on commands that explicitly support interactive choices
+      --review                Open or prepare human review before persistent writes where supported
+      --no-color              Disable ANSI colors in human output
       --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
@@ -330,6 +344,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 +360,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
@@ -405,6 +422,10 @@ function parseArgs(argv) {
     strict: false,
     strictOverlap: false,
     json: false,
+    noColor: false,
+    withPlanner: false,
+    interactive: false,
+    review: false,
     includeCompleted: false,
     onlyReady: false,
     allReady: false,
@@ -635,6 +656,26 @@ function parseArgs(argv) {
       continue;
     }
 
+    if (arg === '--no-color') {
+      result.noColor = true;
+      continue;
+    }
+
+    if (arg === '--with-planner') {
+      result.withPlanner = true;
+      continue;
+    }
+
+    if (arg === '--interactive') {
+      result.interactive = true;
+      continue;
+    }
+
+    if (arg === '--review') {
+      result.review = true;
+      continue;
+    }
+
     if (arg === '--include-completed') {
       result.includeCompleted = true;
       continue;
@@ -936,7 +977,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 +986,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'));
     }
@@ -2327,6 +2371,8 @@ async function run(argv) {
     return;
   }
 
+  validateUxFlags(args);
+
   if (args.mode === 'analyze') {
     runAnalyze(args.targetDir, {
       dryRun: args.dryRun,
@@ -2364,7 +2410,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 +2423,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,
@@ -2458,8 +2512,17 @@ async function run(argv) {
 
     if (args.aiCommand === 'prepare-context') {
       await runAiPrepareContext(process.cwd(), {
+        context: args.aiContext || undefined,
         dryRun: args.dryRun,
+        interactive: args.interactive,
+        printPrompt: args.aiPrintPrompt,
+        provider: args.aiProvider,
+        providerExplicit: args.aiProviderExplicit,
+        review: args.review,
+        role: args.aiRole,
         runId: args.aiRunId || undefined,
+        timeout: args.aiTimeout,
+        withPlanner: args.withPlanner,
       });
       return;
     }
@@ -2473,10 +2536,13 @@ async function run(argv) {
         printPrompt: args.aiPrintPrompt,
         provider: args.aiProvider,
         providerExplicit: args.aiProviderExplicit,
+        interactive: args.interactive,
+        review: args.review,
         role: args.aiRole,
         runId: args.aiRunId || undefined,
         specSlug: args.specSlug || undefined,
         timeout: args.aiTimeout,
+        withPlanner: args.withPlanner,
       });
       return;
     }
@@ -2494,6 +2560,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,
@@ -2582,7 +2663,9 @@ async function run(argv) {
         create: args.aiCreate,
         dryRun: args.dryRun,
         input: args.aiInput || undefined,
+        interactive: args.interactive,
         remote: args.aiRemote || undefined,
+        review: args.review,
         sshHostAlias: args.aiSshHostAlias || undefined,
         identityFile: args.aiIdentityFile || undefined,
         title: args.aiTitle || undefined,
@@ -2590,7 +2673,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') {
@@ -2722,10 +2805,13 @@ async function run(argv) {
 
   if (args.mode === 'spec') {
     if (args.specCommand === 'create') {
-      runCreateSpec(process.cwd(), {
+      await runCreateSpec(process.cwd(), {
         dryRun: args.dryRun,
         input: args.aiInput || undefined,
+        interactive: args.interactive,
+        review: args.review,
         specSlug: args.specSlug || undefined,
+        withPlanner: args.withPlanner,
       });
       return;
     }

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.',
   }),
 });