create-quiver 0.12.1 → 0.14.0

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

@@ -2,11 +2,25 @@ const fs = require('node:fs');
 const path = require('node:path');
 
 const { listAgentProfiles } = require('../agent-profiles');
+const { PLANNER_APPROVAL_PHASES, readPhaseApproval } = require('../approvals');
 const { collectLayoutReport } = require('../doctor');
-const { buildGraph, computeLevels, detectFileConflicts, readAllSlices, SliceGraphError } = require('../slice-graph');
+const {
+  collectActiveSliceState,
+  filterSlicesForExecution,
+  groupSlicesBySpec: groupResolvedSlicesBySpec,
+  isBlockedStatus: isCanonicalBlockedStatus,
+  isCompletedStatus: isCanonicalCompletedStatus,
+  normalizeStatus,
+  progressForSlice: resolveProgressForSlice,
+  resolveProjectState,
+  summarizeGraph: summarizeResolvedGraph,
+  summarizeSliceProgress,
+} = require('../project-state-resolver');
+const { detectFileConflicts } = require('../slice-graph');
+const { readPlanReview } = require('./plan-review');
 const { listAiRuns, nextCommandForPhase } = require('./run-state');
 
-const EXPORT_SCHEMA_VERSION = 1;
+const EXPORT_SCHEMA_VERSION = 2;
 
 function toPosix(relativePath) {
   return String(relativePath || '').split(path.sep).join('/');
@@ -38,43 +52,19 @@ function readPackageSummary(projectRoot) {
 }
 
 function isCompletedStatus(status) {
-  return ['closed', 'completed', 'done'].includes(String(status || '').toLowerCase());
+  return isCanonicalCompletedStatus('slice', status);
 }
 
 function isBlockedStatus(slice) {
-  return String(slice?.status || '').toLowerCase() === 'blocked' || Boolean(slice?.json?.blocked_reason);
+  return isCanonicalBlockedStatus('slice', slice?.canonical_status || slice?.status, slice);
 }
 
 function progressForSlice(slice) {
-  const explicit = Number(slice?.json?.progress);
-  if (Number.isFinite(explicit)) {
-    return Math.max(0, Math.min(100, explicit));
-  }
-
-  const status = String(slice?.status || '').toLowerCase();
-  if (isCompletedStatus(status)) {
-    return 100;
-  }
-  if (status === 'in-progress' || status === 'active' || status === 'review') {
-    return 50;
-  }
-  return 0;
+  return resolveProgressForSlice(slice);
 }
 
 function summarizeProgress(items) {
-  const total = items.length;
-  const completed = items.filter((item) => isCompletedStatus(item.status)).length;
-  const blocked = items.filter((item) => isBlockedStatus(item)).length;
-  const open = Math.max(0, total - completed);
-  const percent = total === 0 ? 0 : Math.round((completed / total) * 100);
-
-  return {
-    total,
-    completed,
-    open,
-    blocked,
-    percent,
-  };
+  return summarizeSliceProgress(items);
 }
 
 function statusForSpec(specSlices) {
@@ -94,59 +84,11 @@ function statusForSpec(specSlices) {
 }
 
 function groupSlicesBySpec(slices) {
-  const groups = new Map();
-
-  for (const slice of slices) {
-    const key = `${slice.specFamily}/${slice.specSlug}`;
-    if (!groups.has(key)) {
-      groups.set(key, []);
-    }
-    groups.get(key).push(slice);
-  }
-
-  return Array.from(groups.entries())
-    .map(([key, specSlices]) => {
-      const [specFamily, specSlug] = key.split('/');
-      return { specFamily, specSlug, slices: specSlices };
-    })
-    .sort((left, right) => left.specSlug.localeCompare(right.specSlug));
+  return groupResolvedSlicesBySpec(slices);
 }
 
 function buildGraphSummary(slices) {
-  try {
-    const graph = buildGraph(slices);
-    const levels = computeLevels(graph).map((level, index) => ({
-      level: index,
-      slices: level.map((slice) => slice.ref),
-    }));
-
-    return {
-      ok: true,
-      edges: graph.edges.map((edge) => ({ from: edge.from, to: edge.to })),
-      levels,
-      conflicts: detectFileConflicts(graph.nodes).map((conflict) => ({
-        files: conflict.files,
-        slices: conflict.slices,
-      })),
-      error: null,
-      nodes: graph.nodes,
-    };
-  } catch (error) {
-    if (error instanceof SliceGraphError) {
-      return {
-        ok: false,
-        edges: [],
-        levels: [],
-        conflicts: [],
-        error: {
-          code: error.code,
-          message: error.message,
-        },
-        nodes: slices,
-      };
-    }
-    throw error;
-  }
+  return summarizeResolvedGraph(slices);
 }
 
 function filterGraphSummary(graph, selectedRefs) {
@@ -187,6 +129,7 @@ function normalizeSlice(projectRoot, slice, dependencyMap) {
     id: slice.sliceId,
     title: slice.title,
     status: slice.status,
+    canonical_status: slice.canonical_status || normalizeStatus('slice', slice.status, 'planned'),
     progress: progressForSlice(slice),
     spec_slug: slice.specSlug,
     spec_family: slice.specFamily,
@@ -209,6 +152,7 @@ function normalizeRuns(projectRoot) {
   return listAiRuns(projectRoot).map((run) => ({
     run_id: run.run_id,
     status: run.status,
+    canonical_status: normalizeStatus('run', run.status, 'draft'),
     phase: run.phase,
     spec_slug: run.spec_slug || null,
     requirement_path: run.requirement?.path || null,
@@ -219,9 +163,73 @@ function normalizeRuns(projectRoot) {
   }));
 }
 
+function safeReadApproval(projectRoot, phase) {
+  try {
+    return readPhaseApproval(projectRoot, phase);
+  } catch (error) {
+    return {
+      phase,
+      status: 'invalid',
+      draft: null,
+      approved: null,
+      meta: null,
+      error: error.message,
+    };
+  }
+}
+
+function safeReadPlanReview(projectRoot) {
+  try {
+    return readPlanReview(projectRoot);
+  } catch (error) {
+    return {
+      status: 'invalid',
+      review: null,
+      meta: null,
+      error: error.message,
+    };
+  }
+}
+
+function normalizeApproval(projectRoot, phase, approval) {
+  const drafts = Array.isArray(approval?.meta?.drafts) ? approval.meta.drafts : [];
+  return {
+    phase,
+    status: approval?.status || 'missing',
+    canonical_status: normalizeStatus('approval', approval?.status || 'missing', 'pending'),
+    draft_path: approval?.draft?.path || null,
+    approved_path: approval?.approved?.path || null,
+    latest_draft_version: Number(approval?.meta?.draft?.version || 0) || null,
+    approved_version: Number(approval?.meta?.approved?.version || 0) || null,
+    draft_count: drafts.length,
+    source_file: approval?.meta?.approved?.source_file || approval?.meta?.draft?.source_file || null,
+    error: approval?.error || null,
+  };
+}
+
+function normalizeApprovals(projectRoot) {
+  const plannerApprovals = PLANNER_APPROVAL_PHASES.map((phase) => normalizeApproval(projectRoot, phase, safeReadApproval(projectRoot, phase)));
+  const planReview = safeReadPlanReview(projectRoot);
+
+  return plannerApprovals.concat({
+    phase: 'plan-review',
+    status: planReview.status || 'missing',
+    canonical_status: normalizeStatus('approval', planReview.status || 'missing', 'pending'),
+    draft_path: null,
+    approved_path: planReview.review?.path || null,
+    latest_draft_version: Number(planReview.meta?.source_version || 0) || null,
+    approved_version: null,
+    draft_count: 0,
+    source_file: planReview.meta?.source_file || null,
+    error: planReview.error || null,
+  });
+}
+
 function normalizeAgents(projectRoot) {
   return listAgentProfiles(projectRoot).map((item) => ({
     role: item.role,
+    status: 'idle',
+    canonical_status: normalizeStatus('agent', 'idle', 'idle'),
     configured: item.configured,
     provider: item.profile?.provider || null,
     model: item.profile?.model || null,
@@ -231,10 +239,141 @@ function normalizeAgents(projectRoot) {
   }));
 }
 
+function collectEvidenceEntries(slices) {
+  return (Array.isArray(slices) ? slices : [])
+    .flatMap((slice) => {
+      const evidence = Array.isArray(slice.json?.evidence) ? slice.json.evidence : [];
+      return evidence.map((item, index) => ({
+        slice_ref: slice.ref,
+        index,
+        value: item,
+      }));
+    })
+    .sort((left, right) => left.slice_ref.localeCompare(right.slice_ref) || left.index - right.index);
+}
+
+function countByStatus(items, statusKey = 'canonical_status') {
+  return (Array.isArray(items) ? items : []).reduce((acc, item) => {
+    const key = item?.[statusKey] || item?.status || 'unknown';
+    acc[key] = (acc[key] || 0) + 1;
+    return acc;
+  }, {});
+}
+
+function collectWarnings({ graph, layout, specs, slices }) {
+  const warnings = [];
+
+  if (!graph.ok && graph.error?.message) {
+    warnings.push({
+      code: graph.error.code || 'GRAPH_ERROR',
+      message: graph.error.message,
+    });
+  }
+
+  if (layout.layout === 'legacy' || layout.layout === 'hybrid' || layout.layout === 'incomplete') {
+    warnings.push({
+      code: 'LAYOUT_REQUIRES_ATTENTION',
+      message: layout.recommendations.join(' '),
+    });
+  }
+
+  if (specs.length === 0) {
+    warnings.push({
+      code: 'NO_SPECS_FOUND',
+      message: 'No specs were found for the selected export filters.',
+    });
+  }
+
+  if (slices.length === 0) {
+    warnings.push({
+      code: 'NO_SLICES_FOUND',
+      message: 'No slices were found for the selected export filters.',
+    });
+  }
+
+  return warnings;
+}
+
+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'));
+
+  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',
+      reason: 'Inspect current slice state.',
+    });
+    commands.push({
+      id: 'export-json',
+      command: 'npx create-quiver ai export --format json',
+      reason: 'Export machine-readable lifecycle state.',
+    });
+  } else {
+    commands.push({
+      id: 'draft-acceptance',
+      command: 'npx create-quiver ai plan --phase acceptance --input <requirements.md> --dry-run',
+      reason: 'Preview acceptance criteria generation.',
+    });
+  }
+
+  if (data.migration.layout === 'legacy' || data.migration.layout === 'hybrid' || data.migration.layout === 'incomplete') {
+    commands.push({
+      id: 'preview-migration',
+      command: 'npx create-quiver migrate --dry-run',
+      reason: 'Preview migration to the current layout.',
+    });
+  }
+
+  return commands;
+}
+
 function collectLifecycleExport(projectRoot, options = {}) {
-  const allSlices = readAllSlices(projectRoot);
-  const slices = options.includeCompleted ? allSlices : allSlices.filter((slice) => !isCompletedStatus(slice.status));
-  const fullGraph = buildGraphSummary(allSlices);
+  const state = resolveProjectState(projectRoot, {
+    allowGraphErrors: true,
+    specSlug: options.specSlug,
+  });
+  const allSlices = state.graph.nodes;
+  const slices = filterSlicesForExecution(allSlices, {
+    includeCompleted: options.includeCompleted === true,
+  });
+  const fullGraph = buildGraphSummary(state.graph);
   const selectedRefs = new Set(slices.map((slice) => slice.ref));
   const graph = filterGraphSummary(fullGraph, selectedRefs);
   if (graph.ok) {
@@ -255,7 +394,8 @@ function collectLifecycleExport(projectRoot, options = {}) {
       spec_path: fs.existsSync(path.join(projectRoot, specPath, 'SPEC.md')) ? toPosix(path.join(specPath, 'SPEC.md')) : null,
       status_path: fs.existsSync(path.join(projectRoot, specPath, 'STATUS.md')) ? toPosix(path.join(specPath, 'STATUS.md')) : null,
       pr_path: fs.existsSync(path.join(projectRoot, specPath, 'pr.md')) ? toPosix(path.join(specPath, 'pr.md')) : null,
-      status: statusForSpec(spec.slices),
+      status: spec.status || statusForSpec(spec.slices),
+      canonical_status: spec.canonical_status || normalizeStatus('spec', spec.status || statusForSpec(spec.slices), 'planned'),
       progress,
       slices: spec.slices.map((slice) => slice.ref),
       blockers: spec.slices.filter((slice) => isBlockedStatus(slice)).map((slice) => ({
@@ -267,7 +407,10 @@ function collectLifecycleExport(projectRoot, options = {}) {
   const layout = collectLayoutReport(projectRoot);
   const runs = normalizeRuns(projectRoot);
   const agents = normalizeAgents(projectRoot);
+  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' }));
@@ -278,10 +421,22 @@ 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 });
+  }
 
-  return {
+  const exportData = {
     schema_version: EXPORT_SCHEMA_VERSION,
     generated_at: new Date().toISOString(),
+    source_metadata: {
+      generator: 'create-quiver',
+      command: 'ai export',
+      resolver: 'project-state-resolver',
+      project_root_name: path.basename(projectRoot),
+      include_completed: options.includeCompleted === true,
+      spec_filter: options.specSlug || null,
+      families: Array.from(new Set(allSlices.map((slice) => slice.specFamily))).sort((left, right) => left.localeCompare(right)),
+    },
     project: readPackageSummary(projectRoot),
     summary: {
       specs: specs.length,
@@ -292,8 +447,12 @@ function collectLifecycleExport(projectRoot, options = {}) {
       progress_percent: progress.percent,
       runs: runs.length,
       configured_agents: agents.filter((agent) => agent.configured).length,
+      approvals: approvals.length,
+      active_slice_sources: activeSlice.sources.length,
+      warnings: 0,
     },
     agents,
+    approvals,
     runs,
     specs,
     slices: normalizedSlices,
@@ -313,6 +472,27 @@ function collectLifecycleExport(projectRoot, options = {}) {
       recommendations: layout.recommendations,
       dry_run_command: 'npx create-quiver migrate --dry-run',
     },
+    evidence,
+    active_slice: activeSlice,
+    warnings: [],
+    blockers,
+    next_steps: [],
+    lifecycle: {
+      phase: runs.length > 0 ? runs[runs.length - 1].phase : 'no-active-run',
+      active_run_id: (runs.length > 0 ? [...runs].reverse().find((run) => run.status !== 'closed') : null)?.run_id || null,
+      include_completed: options.includeCompleted === true,
+      spec_filter: options.specSlug || null,
+      levels: graph.levels,
+    },
+    aggregates: {
+      specs_by_status: countByStatus(specs),
+      slices_by_status: countByStatus(normalizedSlices),
+      runs_by_status: countByStatus(runs),
+      approvals_by_status: countByStatus(approvals),
+      blockers: blockers.length,
+      evidence: evidence.length,
+      progress_percent: progress.percent,
+    },
     dashboard: {
       progress,
       blockers,
@@ -337,8 +517,21 @@ function collectLifecycleExport(projectRoot, options = {}) {
         blocker: slice.blocked_reason,
       })),
       dependencies: graph.edges,
+      active_slice: activeSlice,
     },
   };
+
+  exportData.warnings = collectWarnings({
+    graph,
+    layout,
+    specs,
+    slices: normalizedSlices,
+  });
+  exportData.summary.warnings = exportData.warnings.length;
+  exportData.next_steps = collectNextSteps(exportData);
+  exportData.lifecycle.next_commands = exportData.next_steps.map((step) => step.command);
+
+  return exportData;
 }
 
 function formatLifecycleInspect(data) {
@@ -354,18 +547,17 @@ function formatLifecycleInspect(data) {
     'Next safe commands',
   ];
 
-  const activeRun = [...data.runs].reverse().find((run) => run.status !== 'closed');
-  lines.push(`- ${activeRun ? activeRun.next_command : 'npx create-quiver ai run create --input <requirements.md>'}`);
-
-  if (data.summary.slices > 0) {
-    lines.push('- npx create-quiver ai slices list');
-    lines.push('- npx create-quiver ai export --format json');
-  } else {
-    lines.push('- npx create-quiver ai plan --phase acceptance --input <requirements.md> --dry-run');
+  for (const step of data.next_steps || collectNextSteps(data)) {
+    lines.push(`- ${step.command}`);
   }
 
-  if (data.migration.layout === 'legacy' || data.migration.layout === 'hybrid' || data.migration.layout === 'incomplete') {
-    lines.push('- npx create-quiver migrate --dry-run');
+  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) {

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

@@ -59,10 +59,75 @@ 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');
 }
 
+function quotePosixArg(arg) {
+  const value = String(arg);
+  return /^[A-Za-z0-9_./:=@-]+$/.test(value) ? value : `'${value.replace(/'/g, "'\\''")}'`;
+}
+
+function quotePowerShellArg(arg) {
+  const value = String(arg);
+  return /^[A-Za-z0-9_./:=@-]+$/.test(value) ? value : `'${value.replace(/'/g, "''")}'`;
+}
+
+function hasShellSensitivePath(...values) {
+  return values.some((value) => /\s/.test(String(value || '')));
+}
+
+function formatShellPathGuidance(optionName, examplePath) {
+  const fallbackPath = examplePath || '~/ssh/github work';
+  const windowsFallback = examplePath || '$HOME\\ssh\\github work';
+  return [
+    'Path guidance:',
+    `- macOS/Linux: ${optionName} ${quotePosixArg(fallbackPath)}`,
+    `- Windows PowerShell: ${optionName} ${quotePowerShellArg(windowsFallback)}`,
+    `- Git Bash/WSL: ${optionName} ${quotePosixArg(fallbackPath)}`,
+    '- Quote paths with spaces; do not remove spaces from real file names.',
+  ].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(' ')}`;
+}
+
+function classifyGhAuthFailure(output) {
+  const text = String(output || '').toLowerCase();
+  const issues = [];
+
+  if (/not logged|not authenticated|authentication required|no account/.test(text)) {
+    issues.push('no GitHub account is authenticated for this host');
+  }
+  if (/scope|permission|forbidden|403|oauth/.test(text)) {
+    issues.push('the active token may be missing repo/org scopes');
+  }
+  if (/account|user|login|host/.test(text) && !issues.some((issue) => issue.includes('account'))) {
+    issues.push('the active GitHub account or host may not match this repository');
+  }
+  if (/ssh|identity|alias|public key|permission denied/.test(text)) {
+    issues.push('the SSH alias or identity may not match the authenticated GitHub account');
+  }
+
+  if (issues.length === 0) {
+    issues.push('GitHub CLI authentication is not usable for this repository yet');
+  }
+
+  return `Likely issue: ${issues.join('; ')}.`;
+}
+
 function createError(code, message, details = {}) {
   return new GitHubPreflightError(code, message, details);
 }
@@ -150,7 +215,15 @@ function ensureGhAuthenticated(options = {}) {
     const details = [stderr, stdout].filter(Boolean).join('\n');
     throw createError(
       'GH_NOT_AUTHENTICATED',
-      `${formatError('gh auth status failed. Run gh auth login and then re-run the preflight.')}${details ? `\n${details}` : ''}`,
+      `${formatActionableError({
+        failure: 'gh auth status failed. GitHub CLI is not authenticated or the active account/scopes are not usable.',
+        impact: 'Quiver cannot verify the GitHub account, repository permissions, or PR readiness.',
+        fix: [
+          classifyGhAuthFailure(details),
+          'Run `gh auth login`, confirm the expected GitHub account and host, verify repo/org scopes, and if you use --ssh-host-alias run `ssh -T <alias>` to confirm the SSH identity.',
+        ].join(' '),
+        nextCommand: 'gh auth status',
+      })}${details ? `\nDetails:\n${details}` : ''}`,
       {
         command,
         authArgs,
@@ -240,7 +313,12 @@ function ensureIdentityFile(repoRoot, identityFile) {
   if (!fs.existsSync(resolved)) {
     throw createError(
       'MISSING_IDENTITY_FILE',
-      formatError(`missing SSH identity file at ${resolved}. Check the path you passed as identityFile.`),
+      formatActionableError({
+        failure: `missing SSH identity file at ${resolved}.`,
+        impact: 'Quiver cannot verify the SSH identity that should be used for GitHub PR commands.',
+        fix: `Check the path passed with --identity-file and quote it for your shell when it contains spaces.\n${formatShellPathGuidance('--identity-file', normalized)}`,
+        nextCommand: 'npx create-quiver ai doctor --dry-run --ssh-host-alias <alias> --identity-file <path>',
+      }),
       {
         identityFile: normalized,
         resolvedIdentityFile: resolved,
@@ -259,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: add a Host entry in ~/.ssh/config, for example `Host github-work`. Windows: add the Host entry in %USERPROFILE%\\.ssh\\config.',
+        fix: formatSshAliasGuidance('github-work'),
         nextCommand: 'ssh -T <alias>',
       }),
     );
@@ -531,6 +609,10 @@ function formatPreflightReport(report, options = {}) {
     lines.push(`Identity file: ${report.identityFile}`);
   }
 
+  if (hasShellSensitivePath(report.repoRoot, report.guidePath, report.identityFile)) {
+    lines.push(formatShellPathGuidance('--identity-file', report.identityFile || '<path with spaces>'));
+  }
+
   lines.push('Checks: gh, gh auth status, git remote, worktree branch, GitFlow guide, SSH identity file');
 
   if (dryRun) {
@@ -568,6 +650,12 @@ function formatPrCreateReport({ preflight, plan, result }, options = {}) {
     lines.push(`Identity file: ${preflight.identityFile}`);
   }
 
+  if (hasShellSensitivePath(preflight.repoRoot, preflight.identityFile, plan.prBodyPath, ...plan.args)) {
+    lines.push('Shell-safe command examples:');
+    lines.push(`- macOS/Linux/Git Bash/WSL: ${formatCommandForShell(plan.ghCommand, plan.args, quotePosixArg)}`);
+    lines.push(`- Windows PowerShell: ${formatCommandForShell(plan.ghCommand, plan.args, quotePowerShellArg)}`);
+  }
+
   if (dryRun) {
     lines.push('No PR will be created in dry-run mode.');
   } else if (!create) {
@@ -598,6 +686,7 @@ module.exports = {
   ensureWorktreeReady,
   findPrBodyCandidates,
   formatGhInstallGuidance,
+  formatSshAliasGuidance,
   formatPreflightReport,
   formatPrCreateReport,
   preflightGitHubPr,