create-quiver 0.15.4 → 0.17.0

package/src/create-quiver/lib/i18n/messages/es.js

@@ -62,6 +62,8 @@ module.exports = {
         'spec status': 'Muestra worktree, branch, estado de slice-00 y slices pendientes de una spec.',
         'spec validate': 'Valida docs de spec, slices, briefs, evidencia, estado, dependencias y rutas seguras.',
         'spec close': 'Cierra un worktree de spec mergeado y limpio, y guia la sincronizacion local.',
+        'slice start|check|pr|scope|cleanup|refresh-active': 'Namespace canonico para ciclo de vida, validacion, scope y tableros de slices.',
+        'handoff check|new': 'Namespace canonico para validar o crear artefactos de handoff.',
         'start-slice': 'Inicia trabajo en un slice y lo marca activo.',
         'check-slice': 'Valida estructura, dependencias, scope y preparacion de un slice.',
         'check-pr': 'Valida preparacion de PR para un workflow de slice/spec.',
@@ -89,7 +91,7 @@ module.exports = {
         'For config language set, write the global user config': 'En config language set, escribe la configuracion global del usuario',
         'Include completed slices in dashboard, plan, graph, or next history output': 'Incluye slices completados en dashboard, plan, graph o historial de next',
         'Show the full human dashboard report': 'Muestra el reporte humano completo de dashboard',
-        'Show one human dashboard section': 'Muestra una seccion humana de dashboard',
+        'Show one human dashboard section': 'Muestra una seccion humana de dashboard (overview, specs, slices, blockers, warnings, agents, approvals, runs, active-slice, next-steps)',
         'Limit dashboard human lists (1-100)': 'Limita listas humanas de dashboard (1-100)',
         'Show only slices with no pending dependencies': 'Muestra solo slices sin dependencias pendientes',
         'List every ready slice returned by next': 'Lista todos los slices listos devueltos por next',
@@ -121,11 +123,11 @@ module.exports = {
         'SSH host alias to validate for prepare or AI commands': 'Alias de host SSH a validar para prepare o comandos de IA',
         'SSH identity file to validate for prepare or AI commands': 'Archivo de identidad SSH a validar para prepare o comandos de IA',
         'Git remote name for check-slice or AI PR checks': 'Nombre del remote Git para check-slice o checks de PR de IA',
-        'Base branch for check-slice, check-scope, ai pr, or spec close (default: main)': 'Branch base para check-slice, check-scope, ai pr o spec close (default: main)',
+        'Base branch override for check-slice, check-scope, check-pr, ai pr, spec start, or spec close': 'Override de branch base para check-slice, check-scope, check-pr, ai pr, spec start o spec close',
         'Output file for evidence run': 'Archivo de salida para evidence run',
         'Maximum stdout/stderr chars per evidence section': 'Maximo de caracteres stdout/stderr por seccion de evidencia',
         'Override PR title for ai pr create': 'Anula el titulo del PR para ai pr create',
-        'Skip prompts and use the provided inputs': 'Omite prompts y usa los inputs provistos',
+        'Skip prompts and confirm write prompts such as migrate': 'Omite prompts y confirma escrituras como migrate',
         'Show the installed create-quiver version': 'Muestra la version instalada de create-quiver',
         'Show this help message': 'Muestra este mensaje de ayuda',
       },
@@ -143,6 +145,9 @@ module.exports = {
     'common.unknown': 'desconocido',
     'common.warning': 'Advertencia: {message}',
     'common.yes': 'si',
+    'config.error.unsupported_language': 'idioma no compatible: {language}. Idiomas soportados: {supported}. Ejecuta: npx create-quiver config language set {fallback}',
+    'config.error.unsupported_language_command': 'comando de idioma de config no compatible: {command}. Comandos soportados: show, set',
+    'config.error.unsupported_section': 'seccion de config no compatible: {section}. Secciones soportadas: language',
     'ai_task.command': 'Comando: {command}',
     'ai_task.context_pack': 'Pack de contexto: {context}',
     'ai_task.documentation_debt': 'Deuda documental: {count}',
@@ -435,6 +440,14 @@ module.exports = {
     'analyze.detected_package_manager': 'Package manager detectado: {manager}',
     'analyze.detected_primary_stack': 'Stack principal detectado: {stack}',
     'analyze.dry_run_for': 'Dry-run de analisis del proyecto para {path}',
+    'analyze.progress.artifacts_written': 'Artefactos de analisis escritos',
+    'analyze.progress.context_refreshed': 'Contexto de IA actualizado',
+    'analyze.progress.refreshing_context': 'Actualizando contexto de IA...',
+    'analyze.progress.scanned': 'Escaneo del proyecto completado',
+    'analyze.progress.scanning': 'Escaneando proyecto...',
+    'analyze.progress.state_updated': 'Estado de analisis actualizado',
+    'analyze.progress.updating_state': 'Actualizando estado de Quiver...',
+    'analyze.progress.writing_artifacts': 'Escribiendo artefactos de analisis...',
     'analyze.would_refresh': 'Actualizaria {path}',
     'analyze.would_write': 'Escribiria {path}',
     'analyze.writes_none': 'Escrituras: ninguna',
@@ -467,7 +480,11 @@ module.exports = {
     'demo.title.created': 'Demo de Quiver creado',
     'demo.title.dry_run': 'Dry-run de demo Quiver',
     'evidence.command': 'Comando: {command}',
+    'evidence.error.missing_command': 'evidence run requiere un comando despues de --',
+    'evidence.error.missing_subcommand': 'falta el subcomando de evidence. Usa: npx create-quiver evidence <run|list|show>',
     'evidence.exit_code': 'Codigo de salida: {code}',
+    'evidence.list.empty': 'No se encontraron archivos de evidencia.',
+    'evidence.list.title': 'Archivos de evidencia de Quiver',
     'evidence.output': 'Salida: {path}',
     'evidence.recorded': 'Evidencia de Quiver registrada',
     'init.agent_guidance.show.hint': 'No guarda credenciales ni ejecuta providers',
@@ -494,6 +511,14 @@ module.exports = {
     'init.next_steps.review_agents': 'Revisa AGENTS.md y despues {path}',
     'init.next_steps.review_workflow': 'Revisa {path}',
     'init.next_steps.title': 'Proximos pasos:',
+    'init.progress.docs_written': 'Docs de init escritos',
+    'init.progress.exporting_templates': 'Exportando templates de compatibilidad...',
+    'init.progress.install_checked': 'Instalacion del paquete verificada',
+    'init.progress.installing_package': 'Verificando instalacion de create-quiver...',
+    'init.progress.preparing_templates': 'Preparando templates empaquetados...',
+    'init.progress.templates_exported': 'Templates de compatibilidad exportados',
+    'init.progress.templates_ready': 'Templates empaquetados listos',
+    'init.progress.writing_docs': 'Escribiendo docs de init...',
     'init.profile.default.hint': 'Contrato AI-first recomendado',
     'init.profile.full.hint': 'Incluye compatibilidad historica y templates visibles',
     'init.profile.minimal.hint': 'Solo documentos esenciales',
@@ -511,6 +536,9 @@ module.exports = {
     'init.summary.project': 'Proyecto',
     'init.summary.title': 'Configuracion elegida',
     'migrate.completed_for': 'Migracion de Quiver completada para {path}',
+    'migrate.confirm.declined': 'migrate cancelado. No se escribieron archivos.',
+    'migrate.confirm.prompt': 'Este comando modificara archivos del proyecto en {path}. Ejecuta `npx create-quiver migrate --dry-run` para previsualizar. Continuar?',
+    'migrate.confirm.required': 'migrate requiere confirmacion antes de modificar archivos del proyecto. Ejecuta `npx create-quiver migrate --dry-run` para previsualizar, o pasa `--yes` para continuar en automatizacion.',
     'migrate.dry_run_title': 'Dry-run de migracion de Quiver',
     'migrate.legacy_preserved': 'Layout legacy detectado y preservado: {paths}',
     'migrate.next_command': 'Proximo comando: {command}',
@@ -577,7 +605,9 @@ module.exports = {
     'flow.stage.technical-plan-stale': 'el plan tecnico necesita revision',
     'flow.suggested_sequence': 'Secuencia sugerida',
     'flow.title': 'Flujo guiado de Quiver',
+    'graph.empty.level': 'No se encontraron slices para el nivel de graph {level}.',
     'graph.empty.pending': 'No se encontraron slices pendientes.',
+    'graph.error.unsupported_format': 'formato de graph no compatible: {format}',
     'graph.level': 'Nivel {level}',
     'graph.lots_count': {
       one: '{count} lote',
@@ -609,6 +639,10 @@ module.exports = {
     'plan.header.status': 'ESTADO',
     'plan.header.ticket': 'TICKET',
     'plan.header.title': 'TITULO',
+    'plan.missing_estimates_note': {
+      one: 'Nota: {count} slice no tiene estimated_hours positivo y cuenta como 0h.',
+      other: 'Nota: {count} slices no tienen estimated_hours positivo y cuentan como 0h.',
+    },
     'plan.title': 'Plan de Quiver',
     'plan.title.including_completed': 'Plan de Quiver (incluye completados)',
     'plan.title.ready': 'Slices listos',
@@ -780,11 +814,11 @@ module.exports = {
     'lifecycle.cleanup.dry_run.branch': 'DRY RUN: git branch {flag} {branch}',
     'lifecycle.cleanup.dry_run.slice': 'DRY RUN: slice={slice} branch={branch}',
     'lifecycle.cleanup.dry_run.worktree': 'DRY RUN: git worktree remove {force}{path}',
-    'lifecycle.cleanup.error.branch': 'el cleanup normal debe correrse desde develop. Rama actual: {branch}',
-    'lifecycle.cleanup.error.develop_stale': 'develop local no esta actualizado. Ejecuta git pull --ff-only antes del cleanup.',
+    'lifecycle.cleanup.error.branch': 'el cleanup normal debe correrse desde {base}. Rama actual: {branch}',
+    'lifecycle.cleanup.error.base_stale': '{base} local no esta actualizado respecto de {ref}. Ejecuta git pull --ff-only antes del cleanup.',
     'lifecycle.cleanup.error.dirty': 'el checkout actual no esta limpio. Limpialo antes del cleanup.',
     'lifecycle.cleanup.error.missing': "no existe worktree ni rama local para '{slice}'.",
-    'lifecycle.cleanup.error.unmerged': "la rama '{branch}' no esta mergeada en origin/develop. Usa --discard si el slice se descarta.",
+    'lifecycle.cleanup.error.unmerged': "la rama '{branch}' no esta mergeada en {ref}. Usa --discard si el slice se descarta.",
     'lifecycle.cleanup.finished': "PASS: Cleanup finalizado para '{slice}'.",
     'lifecycle.cleanup.removed_active_slice': 'PASS: ACTIVE_SLICE.md eliminado',
     'lifecycle.cleanup.removed_branch': 'PASS: Rama local eliminada: {branch}',
@@ -839,15 +873,15 @@ module.exports = {
     'readiness.pr.branch.pass': 'PASS: La rama actual coincide con la rama declarada por el slice.',
     'readiness.pr.case.pass': 'PASS: Al menos un caso de uso documentado.',
     'readiness.pr.clean.pass': 'PASS: El worktree esta limpio.',
-    'readiness.pr.commits.pass': 'PASS: La rama tiene commits propios contra origin/develop.',
-    'readiness.pr.error.absorbed': 'La rama ya fue absorbida por origin/develop. Este gate aplica antes del merge.',
+    'readiness.pr.commits.pass': 'PASS: La rama tiene commits propios contra {ref}.',
+    'readiness.pr.error.absorbed': 'La rama ya fue absorbida por {ref}. Este gate aplica antes del merge.',
     'readiness.pr.error.dirty': 'El worktree no esta limpio. Cerra la implementacion antes de abrir el PR.',
     'readiness.pr.error.missing_branch': 'Falta git.branch_name en el slice.',
     'readiness.pr.error.missing_pr': 'Falta pr.md junto al slice.',
     'readiness.pr.error.missing_section': "Falta la seccion obligatoria '{heading}' en pr.md.",
     'readiness.pr.error.missing_subsection': "Falta la subseccion '{subheading}' dentro de How to Test.",
     'readiness.pr.error.no_case': 'How to Test debe tener al menos un caso de uso documentado (#### Case 1: ...).',
-    'readiness.pr.error.no_commits': 'La rama no tiene commits propios respecto de origin/develop.',
+    'readiness.pr.error.no_commits': 'La rama no tiene commits propios respecto de {ref}.',
     'readiness.pr.error.rollback': 'Rollback debe incluir al menos un comando git revert.',
     'readiness.pr.error.wrong_branch': 'Debes ejecutar este check desde la rama del slice. Actual: {actual} Esperada: {expected}',
     'readiness.pr.how_to_test.pass': 'PASS: How to Test incluye entorno, acceso al worktree, arranque, casos de uso y verificacion tecnica.',
@@ -865,6 +899,11 @@ module.exports = {
     'readiness.spec_docs.pass': 'PASS: El spec local tiene SPEC.md, STATUS.md y EVIDENCE_REPORT.md.',
     'readiness.warn': 'WARN: {message}',
     'spec_create.confirm_create': 'Crear spec "{slug}"?',
+    'spec_create.error.approval_declined': 'aprobacion interactiva de spec create rechazada. No se escribieron archivos.',
+    'spec_create.error.interactive_tty_required': 'spec create --interactive requiere una TTY interactiva. Usa --input, --spec, --review y --dry-run para automatizacion no interactiva.',
+    'spec_create.error.review_canceled': '{reason}\nArtefacto de revision: {path}',
+    'spec_create.error.review_canceled.default_reason': 'la revision de spec create fue cancelada.',
+    'spec_create.error.review_tty_required': 'spec create --review requiere una terminal interactiva o un editor inyectado.\nArtefacto de revision: {path}',
     'spec_create.input.approved_plan_hint': 'Plan tecnico revisado y aprobado',
     'spec_create.label.files_written': 'Archivos escritos: {count}',
     'spec_create.label.input_file': 'Archivo de entrada: {path}',
@@ -932,6 +971,12 @@ module.exports = {
     'spec_validate.strict': 'Estricto: {value}',
     'spec_validate.title': 'Validacion de spec de Quiver',
     'spec_validate.warnings': 'Advertencias:',
+    'spec.error.directory_not_found': 'directorio de spec no encontrado: {path}',
+    'spec.error.directory_already_exists': 'el directorio de spec ya existe: {path}',
+    'spec.error.missing_approved_plan_input': 'falta el input de plan revisado y aprobado: {path}',
+    'spec.error.missing_directory_command': 'falta el directorio de spec. Usa: npx create-quiver spec <start|status|validate|close> <spec-dir>',
+    'spec.error.missing_directory_validate': 'falta el directorio de spec. Usa: npx create-quiver spec validate specs/<spec-slug>',
+    'spec.error.validate_failed': 'fallo spec validate para {path}',
     'status.blocked': 'bloqueado',
     'status.cancelled': 'cancelado',
     'status.active': 'activo',

package/src/create-quiver/lib/init-docs.js

@@ -645,7 +645,7 @@ Use this section only for projects generated with the full compatibility layout.
 5. Check the next ready slice with \`{{NEXT_COMMAND}}\` or \`npm run quiver:next\`.
 6. Start work with \`{{START_SLICE_COMMAND}}\` or \`npm run quiver:start-slice -- <slice.json>\`.
 7. Make one commit per slice.
-8. Open one PR per spec.
+8. Open one PR per slice by default; group slices only when \`docs/GITFLOW_PR_GUIDE.md\` allows it.
 
 ## Verification Checklist
 

package/src/create-quiver/lib/init-layout.js

@@ -214,14 +214,15 @@ function resolveInitPackageScripts(profile, options = {}) {
     'quiver:spec:status': 'npx create-quiver spec status',
     'quiver:spec:validate': 'npx create-quiver spec validate',
     'quiver:spec:close': 'npx create-quiver spec close',
-    'quiver:start-slice': 'npx create-quiver start-slice',
-    'quiver:check-slice': 'npx create-quiver check-slice',
-    'quiver:check-pr': 'npx create-quiver check-pr',
-    'quiver:check-handoff': 'npx create-quiver check-handoff',
-    'check-handoff': 'npx create-quiver check-handoff',
-    'quiver:cleanup-slice': 'npx create-quiver cleanup-slice',
-    'quiver:check-scope': 'npx create-quiver check-scope',
-    'quiver:refresh-active-slices': 'npx create-quiver refresh-active-slices',
+    'quiver:start-slice': 'npx create-quiver slice start',
+    'quiver:check-slice': 'npx create-quiver slice check',
+    'quiver:check-pr': 'npx create-quiver slice pr',
+    'quiver:check-handoff': 'npx create-quiver handoff check',
+    'check-handoff': 'npx create-quiver handoff check',
+    'quiver:new-handoff': 'npx create-quiver handoff new',
+    'quiver:cleanup-slice': 'npx create-quiver slice cleanup',
+    'quiver:check-scope': 'npx create-quiver slice scope',
+    'quiver:refresh-active-slices': 'npx create-quiver slice refresh-active',
   };
 
   if (profile === 'full' || options.legacyScripts === true) {

package/src/create-quiver/lib/lifecycle.js

@@ -1,6 +1,6 @@
 const fs = require('fs');
 const path = require('path');
-const { branchDelete, catFileExists, currentBranch, fetchBranch, fetchRemote, hasLocalBranch, hasRemoteBranch, isGitWorktree, isLinkedWorktree, lsRemoteHeads, mergeBaseIsAncestor, revListCount, runGit, statusPorcelain, worktreeAdd, worktreeList, worktreePrune, worktreeRemove } = require('./git');
+const { branchDelete, catFileExists, currentBranch, fetchBranch, fetchRemote, hasLocalBranch, isGitWorktree, isLinkedWorktree, lsRemoteHeads, mergeBaseIsAncestor, resolveBaseRef: resolveGitBaseRef, revListCount, runGit, statusPorcelain, worktreeAdd, worktreeList, worktreePrune, worktreeRemove } = require('./git');
 const { parseJsonWithComments } = require('./json');
 const { createTranslator } = require('./i18n/catalog');
 const { writeFrontMatter } = require('./init-docs');
@@ -273,21 +273,14 @@ function refreshActiveSlicesBoard(repoRoot) {
 }
 
 function resolveBaseRef(repoRoot, baseBranch, translator = lifecycleTranslator()) {
-  if (hasLocalBranch(repoRoot, baseBranch)) {
-    return baseBranch;
-  }
-  if (hasRemoteBranch(repoRoot, baseBranch)) {
-    return `origin/${baseBranch}`;
-  }
-  if (lsRemoteHeads(repoRoot, baseBranch)) {
-    try {
-      fetchBranch(repoRoot, baseBranch);
-      return `origin/${baseBranch}`;
-    } catch {
-      throw new Error(`create-quiver: ${translator.t('lifecycle.base_ref.fetch_failed', { base: baseBranch })}`);
-    }
+  const resolution = resolveGitBaseRef(repoRoot, {
+    explicitBaseBranch: baseBranch,
+    missingOk: true,
+  });
+  if (resolution.baseRef) {
+    return resolution.baseRef;
   }
-  throw new Error(`create-quiver: ${translator.t('lifecycle.base_ref.missing', { base: baseBranch, remoteRef: `origin/${baseBranch}` })}`);
+  throw new Error(`create-quiver: ${translator.t('lifecycle.base_ref.missing', { base: resolution.baseBranch || baseBranch, remoteRef: `origin/${resolution.baseBranch || baseBranch}` })}`);
 }
 
 function findExistingWorktreeForBranch(repoRoot, branchName) {
@@ -470,29 +463,34 @@ function cleanupSlice(sliceInput, options = {}) {
   }
 
   if (!discard) {
+    const base = resolveGitBaseRef(repoRoot, {
+      preferredBaseBranch: slice.baseBranch,
+    });
     const branch = currentBranch(repoRoot);
-    if (branch !== 'develop') {
-      throw new Error(`create-quiver: ${translator.t('lifecycle.cleanup.error.branch', { branch })}`);
+    if (branch !== base.baseBranch) {
+      throw new Error(`create-quiver: ${translator.t('lifecycle.cleanup.error.branch', { branch, base: base.baseBranch })}`);
     }
     if (statusPorcelain(repoRoot) !== '') {
       throw new Error(`create-quiver: ${translator.t('lifecycle.cleanup.error.dirty')}`);
     }
 
-    try {
-      fetchRemote(repoRoot, 'origin', ['develop']);
-    } catch {
-      // ignore
+    if (base.remote) {
+      try {
+        fetchRemote(repoRoot, base.remote, [base.baseBranch]);
+      } catch {
+        // Local-only test repos and offline environments can still validate against the current remote ref.
+      }
     }
 
     const localDevelopSha = runGit(['rev-parse', 'HEAD'], repoRoot);
-    const remoteDevelopSha = runGit(['rev-parse', 'origin/develop'], repoRoot);
-    if (localDevelopSha !== remoteDevelopSha) {
-      throw new Error(`create-quiver: ${translator.t('lifecycle.cleanup.error.develop_stale')}`);
+    const remoteDevelopSha = runGit(['rev-parse', base.baseRef], repoRoot);
+    if (base.remote && localDevelopSha !== remoteDevelopSha) {
+      throw new Error(`create-quiver: ${translator.t('lifecycle.cleanup.error.base_stale', { base: base.baseBranch, ref: base.baseRef })}`);
     }
 
     if (hasLocalBranch(repoRoot, slice.branchName)) {
-      if (!mergeBaseIsAncestor(repoRoot, slice.branchName, 'origin/develop')) {
-        throw new Error(`create-quiver: ${translator.t('lifecycle.cleanup.error.unmerged', { branch: slice.branchName })}`);
+      if (!mergeBaseIsAncestor(repoRoot, slice.branchName, base.baseRef)) {
+        throw new Error(`create-quiver: ${translator.t('lifecycle.cleanup.error.unmerged', { branch: slice.branchName, ref: base.baseRef })}`);
       }
     }
   }

package/src/create-quiver/lib/readiness.js

@@ -1,6 +1,6 @@
 const fs = require('fs');
 const path = require('path');
-const { catFileExists, currentBranch, hasLocalBranch, hasRemoteBranch, mergeBaseIsAncestor, revListCount, runGit, statusPorcelain, worktreeList } = require('./git');
+const { catFileExists, currentBranch, mergeBaseIsAncestor, resolveBaseRef, revListCount, runGit, statusPorcelain, worktreeList } = require('./git');
 const { parseJsonWithComments } = require('./json');
 const { createTranslator } = require('./i18n/catalog');
 const { buildGraph, normalizeDeclaredDependencies, readAllSlices, SliceGraphError, topoSort } = require('./slice-graph');
@@ -62,7 +62,7 @@ function parseWorktrees(text) {
   return entries;
 }
 
-function collectOverlapWarnings(repoRoot, currentBranchName, currentFiles, baseRef = 'origin/develop') {
+function collectOverlapWarnings(repoRoot, currentBranchName, currentFiles, baseRef) {
   const sliceMap = new Map();
   walkSlices(path.join(repoRoot, 'specs'), sliceMap, repoRoot);
   walkSlices(path.join(repoRoot, 'specs-fix'), sliceMap, repoRoot);
@@ -130,6 +130,15 @@ function baseRecoveryMessage(remote, baseBranch, translator) {
   return translator.t('readiness.base.recovery', { base: baseBranch, remote, remoteRef: `${remote}/${baseBranch}` });
 }
 
+function resolveReadinessBase(repoRoot, slice, options = {}) {
+  return resolveBaseRef(repoRoot, {
+    explicitBaseBranch: options.baseBranch,
+    missingOk: true,
+    preferredBaseBranch: slice.baseBranch,
+    remote: options.remote || 'origin',
+  });
+}
+
 function resolveReadinessRoot(localMode) {
   try {
     return runGit(['rev-parse', '--show-toplevel'], process.cwd());
@@ -145,23 +154,23 @@ function validateSliceDocumentedOnBase(repoRoot, slice, options = {}) {
   const translator = readinessTranslator(options);
   const gate = options.gate || 'execution';
   const remote = options.remote || 'origin';
-  const baseBranch = options.baseBranch || slice.baseBranch || 'develop';
-  const remoteRef = `${remote}/${baseBranch}`;
-  const hasRemoteBase = hasRemoteBranch(repoRoot, baseBranch, remote);
-  const hasLocalBase = hasLocalBranch(repoRoot, baseBranch);
+  const base = resolveReadinessBase(repoRoot, slice, {
+    baseBranch: options.baseBranch,
+    remote,
+  });
 
-  if (hasRemoteBase && catFileExists(repoRoot, `${remoteRef}:${slice.sliceRel}`)) {
-    console.log(translator.t('readiness.documented.remote.pass', { ref: remoteRef }));
-    return remoteRef;
+  if (base.baseRef && base.remote && catFileExists(repoRoot, `${base.baseRef}:${slice.sliceRel}`)) {
+    console.log(translator.t('readiness.documented.remote.pass', { ref: base.baseRef }));
+    return base.baseRef;
   }
 
-  if (hasLocalBase && catFileExists(repoRoot, `${baseBranch}:${slice.sliceRel}`)) {
-    console.log(translator.t('readiness.documented.local.pass', { branch: baseBranch }));
-    return baseBranch;
+  if (base.baseRef && !base.remote && catFileExists(repoRoot, `${base.baseRef}:${slice.sliceRel}`)) {
+    console.log(translator.t('readiness.documented.local.pass', { branch: base.baseRef }));
+    return base.baseRef;
   }
 
-  if (!hasRemoteBase && !hasLocalBase) {
-    const guidance = baseRecoveryMessage(remote, baseBranch, translator);
+  if (!base.baseRef) {
+    const guidance = baseRecoveryMessage(remote, base.baseBranch || base.candidates.map((candidate) => candidate.branch).join(', '), translator);
     if (gate === 'validation') {
       console.log(translator.t('readiness.warn', { message: guidance }));
       return null;
@@ -170,13 +179,12 @@ function validateSliceDocumentedOnBase(repoRoot, slice, options = {}) {
     throw new Error(`create-quiver: ${guidance}`);
   }
 
-  const expectedBase = hasRemoteBase ? remoteRef : baseBranch;
   if (gate === 'validation') {
-    console.log(translator.t('readiness.documented.missing_validation.warn', { ref: expectedBase }));
-    return expectedBase;
+    console.log(translator.t('readiness.documented.missing_validation.warn', { ref: base.baseRef }));
+    return base.baseRef;
   }
 
-  throw new Error(`create-quiver: ${translator.t('readiness.documented.missing.error', { ref: expectedBase })}`);
+  throw new Error(`create-quiver: ${translator.t('readiness.documented.missing.error', { ref: base.baseRef })}`);
 }
 
 function validateDeclaredDependencyContract(repoRoot, slice) {
@@ -246,7 +254,11 @@ function checkSliceReadiness(sliceInput, options = {}) {
   const remote = options.remote || 'origin';
   const repoRoot = resolveReadinessRoot(localMode);
   const slice = resolveSliceContext(repoRoot, sliceInput);
-  const baseBranch = options.baseBranch || slice.baseBranch || 'develop';
+  const base = resolveReadinessBase(repoRoot, slice, {
+    baseBranch: options.baseBranch,
+    remote,
+  });
+  const baseBranch = base.baseBranch || options.baseBranch || slice.baseBranch || 'main';
 
   for (const specFile of ['SPEC.md', 'STATUS.md', 'EVIDENCE_REPORT.md']) {
     ensureExists(path.join(repoRoot, slice.specDirRel, specFile), `create-quiver: falta '${slice.specDirRel}/${specFile}'.`);
@@ -268,7 +280,7 @@ function checkSliceReadiness(sliceInput, options = {}) {
   }
 
   if (!localMode) {
-    const overlapWarnings = collectOverlapWarnings(repoRoot, currentBranch(repoRoot), slice.files, baseRef || `${remote}/${baseBranch}`);
+    const overlapWarnings = collectOverlapWarnings(repoRoot, currentBranch(repoRoot), slice.files, baseRef || base.baseRef);
     if (overlapWarnings.length === 0) {
       console.log(translator.t('readiness.overlap.none.pass'));
     } else {
@@ -330,13 +342,31 @@ function checkSliceReadiness(sliceInput, options = {}) {
 function checkPrReadiness(sliceInput, options = {}) {
   const translator = readinessTranslator(options);
   const repoRoot = runGit(['rev-parse', '--show-toplevel'], process.cwd());
-  const scriptDir = path.dirname(__filename);
   const slice = resolveSliceContext(repoRoot, sliceInput);
   const current = currentBranch(repoRoot);
   const prPath = path.join(path.dirname(slice.sliceAbs), 'pr.md');
+  const remote = options.remote || 'origin';
+  const base = resolveReadinessBase(repoRoot, slice, {
+    baseBranch: options.baseBranch,
+    remote,
+  });
 
-  checkSliceReadiness(slice.sliceRel, { gate: 'validation', language: options.language });
-  checkScope(slice.sliceRel, { language: options.language, strict: true });
+  if (!base.baseRef) {
+    throw new Error(`create-quiver: ${baseRecoveryMessage(remote, base.baseBranch || base.candidates.map((candidate) => candidate.branch).join(', '), translator)}`);
+  }
+
+  checkSliceReadiness(slice.sliceRel, {
+    baseBranch: base.baseBranch,
+    gate: 'validation',
+    language: options.language,
+    remote,
+  });
+  checkScope(slice.sliceRel, {
+    baseBranch: base.baseBranch,
+    language: options.language,
+    remote,
+    strict: true,
+  });
 
   if (!slice.branchName) {
     throw new Error(`create-quiver: ${translator.t('readiness.pr.error.missing_branch')}`);
@@ -353,14 +383,14 @@ function checkPrReadiness(sliceInput, options = {}) {
   }
   console.log(translator.t('readiness.pr.clean.pass'));
 
-  const aheadCount = revListCount(repoRoot, 'origin/develop..HEAD');
+  const aheadCount = revListCount(repoRoot, `${base.baseRef}..HEAD`);
   if (aheadCount <= 0) {
-    if (mergeBaseIsAncestor(repoRoot, 'HEAD', 'origin/develop')) {
-      throw new Error(`create-quiver: ${translator.t('readiness.pr.error.absorbed')}`);
+    if (mergeBaseIsAncestor(repoRoot, 'HEAD', base.baseRef)) {
+      throw new Error(`create-quiver: ${translator.t('readiness.pr.error.absorbed', { ref: base.baseRef })}`);
     }
-    throw new Error(`create-quiver: ${translator.t('readiness.pr.error.no_commits')}`);
+    throw new Error(`create-quiver: ${translator.t('readiness.pr.error.no_commits', { ref: base.baseRef })}`);
   }
-  console.log(translator.t('readiness.pr.commits.pass'));
+  console.log(translator.t('readiness.pr.commits.pass', { ref: base.baseRef }));
 
   const prText = fs.readFileSync(prPath, 'utf8');
   for (const heading of ['## Title', '## Summary', '## Scope', '## Files', '## How to Test (DETAILED - REQUIRED)', '## Evidence', '## Rollback', '## Risks / Notes']) {
@@ -403,41 +433,22 @@ function checkScope(sliceInput, options = {}) {
   const declared = slice.files;
   validateProjectRelativePaths(declared, 'slice scope path');
 
-  const explicitBaseBranch = typeof options.baseBranch === 'string' ? options.baseBranch.trim() : '';
-  const candidateBaseBranches = Array.from(new Set([
-    explicitBaseBranch,
-    slice.baseBranch,
-    'main',
-    'develop',
-    'master',
-  ].filter(Boolean)));
-
-  let baseRef = '';
-  let baseSource = '';
-  for (const candidate of candidateBaseBranches) {
-    if (hasRemoteBranch(repoRoot, candidate, remote)) {
-      baseRef = `${remote}/${candidate}`;
-      baseSource = explicitBaseBranch === candidate ? '--base' : candidate === slice.baseBranch ? 'slice.git.base_branch' : 'fallback';
-      break;
-    }
-    if (hasLocalBranch(repoRoot, candidate)) {
-      baseRef = candidate;
-      baseSource = explicitBaseBranch === candidate ? '--base' : candidate === slice.baseBranch ? 'slice.git.base_branch' : 'fallback';
-      break;
-    }
-  }
+  const base = resolveReadinessBase(repoRoot, slice, {
+    baseBranch: options.baseBranch,
+    remote,
+  });
 
   let touchedRaw = '';
-  if (baseRef) {
-    touchedRaw = runGit(['diff', '--name-only', `${baseRef}...HEAD`], repoRoot);
-    console.log(translator.t('readiness.scope.base.info', { ref: baseRef, source: baseSource }));
+  if (base.baseRef) {
+    touchedRaw = runGit(['diff', '--name-only', `${base.baseRef}...HEAD`], repoRoot);
+    console.log(translator.t('readiness.scope.base.info', { ref: base.baseRef, source: base.source }));
   } else {
-    console.log(translator.t('readiness.scope.base.warn', { branches: candidateBaseBranches.join(', ') }));
+    console.log(translator.t('readiness.scope.base.warn', { branches: base.candidates.map((candidate) => candidate.branch).join(', ') }));
     return;
   }
 
   if (!touchedRaw) {
-    console.log(translator.t('readiness.scope.empty.warn', { ref: baseRef }));
+    console.log(translator.t('readiness.scope.empty.warn', { ref: base.baseRef }));
     return;
   }
 

package/src/create-quiver/lib/spec-worktrees.js

@@ -5,12 +5,11 @@ const {
   currentBranch,
   fetchRemote,
   hasLocalBranch,
-  hasRemoteBranch,
   isGitWorktree,
   isLinkedWorktree,
   isCleanWorktree,
-  lsRemoteHeads,
   mergeBaseIsAncestor,
+  resolveBaseRef: resolveGitBaseRef,
   runGit,
   statusPorcelain,
   worktreeAdd,
@@ -175,41 +174,24 @@ function formatDirtyCheckoutRecovery(repoRoot) {
   return lines.filter((line) => line !== '').join('\n');
 }
 
-function resolveBaseRef(repoRoot, preferred = '') {
-  const candidates = [preferred, 'main', 'develop'].filter(Boolean);
-  for (const candidate of candidates) {
-    if (hasLocalBranch(repoRoot, candidate)) {
-      return candidate;
-    }
-    if (hasRemoteBranch(repoRoot, candidate)) {
-      return `origin/${candidate}`;
-    }
-    if (lsRemoteHeads(repoRoot, candidate)) {
-      return `origin/${candidate}`;
-    }
-  }
-  throw new Error(formatError('missing base branch. Expected local or remote main/develop.'));
+function resolveBaseRef(repoRoot, preferred = '', remote = 'origin') {
+  const resolution = resolveGitBaseRef(repoRoot, {
+    explicitBaseBranch: preferred,
+    remote,
+  });
+  return resolution.baseRef;
 }
 
 function resolveMergedBaseRef(repoRoot, preferred = '', remote = 'origin') {
-  const candidates = [preferred, 'main', 'develop'].filter(Boolean);
-  for (const candidate of candidates) {
-    if (hasRemoteBranch(repoRoot, candidate, remote)) {
-      return {
-        baseBranch: candidate,
-        baseRef: `${remote}/${candidate}`,
-        remote,
-      };
-    }
-    if (hasLocalBranch(repoRoot, candidate)) {
-      return {
-        baseBranch: candidate,
-        baseRef: candidate,
-        remote: '',
-      };
-    }
-  }
-  throw new Error(formatError('missing merge base branch. Expected local or remote main/develop.'));
+  const resolution = resolveGitBaseRef(repoRoot, {
+    explicitBaseBranch: preferred,
+    remote,
+  });
+  return {
+    baseBranch: resolution.baseBranch,
+    baseRef: resolution.baseRef,
+    remote: resolution.remote,
+  };
 }
 
 function buildSpecStatus(repoRoot, specInput) {