create-quiver 0.17.3 → 0.17.4

package/docs/CLI_UX_GUIDE.md

@@ -94,7 +94,7 @@ Reglas:
 |---|---:|---:|---:|---|
 | `init` | no | si | no | Interactive guia modo de proyecto, metodologia `wdd-sdd`, perfil inicial y proximo paso de perfiles de agentes. |
 | `migrate` | no | no | no | En TTY confirma antes de escribir; en CI/no-TTY requiere `--yes`. `--dry-run` no pide confirmacion ni escribe. |
-| `ai analyze-project` | no | no | si | `--dry-run` es read-only y no ejecuta proveedor; `--apply-docs` muestra selector en TTY; `--review` queda como modo avanzado de edicion JSON. |
+| `ai analyze-project` | no | no | si | `--dry-run` es read-only y no ejecuta proveedor; el comando normal con provider aplica docs validados; `--review` queda como modo avanzado de edicion JSON. |
 | `ai prepare-context` | si | si | si | Modo deterministico por defecto; planner opcional con contrato docs-only. |
 | `ai plan` | si | si | si | El planner ya es implicito; `--with-planner` se acepta por consistencia. |
 | `spec create` | si | si | si | Consume un plan tecnico aprobado del planner; no vuelve a ejecutar proveedor. Review previsualiza el paquete antes de escribir. |
@@ -124,12 +124,12 @@ Analisis profundo de un proyecto existente:
 ```bash
 npx create-quiver ai analyze-project --deep --dry-run
 npx create-quiver ai analyze-project --deep --dry-run --json
+npx create-quiver ai analyze-project --deep --provider codex --model gpt-5.5
 npx create-quiver ai analyze-project --deep --save-proposal --provider codex --model gpt-5.5
-npx create-quiver ai analyze-project --deep --apply-docs --provider codex --model gpt-5.5
 npx create-quiver ai analyze-project apply --run <run-id>
 ```
 
-`ai analyze-project` debe mantener estas garantias: en `--dry-run` no escribe ni ejecuta proveedor; el modo provider normal genera auditoria y propuesta pero no escribe docs finales; con proveedor no lee `.env`, dependencias, caches, binarios ni outputs generados; toda conclusion importante cita evidencia o queda como `unknown`; las escrituras se limitan a docs aprobados, usan bloques gestionados por Quiver, muestran diff y crean snapshot previo.
+`ai analyze-project` debe mantener estas garantias: en `--dry-run` no escribe ni ejecuta proveedor; el modo provider normal genera auditoria, propuesta, snapshot y aplica docs finales validados; con proveedor no lee `.env`, dependencias, caches, binarios ni outputs generados; toda conclusion importante cita evidencia o queda como `unknown`; las escrituras se limitan a docs aprobados, usan bloques gestionados por Quiver y crean snapshot previo.
 
 Opciones de aplicacion:
 
@@ -137,7 +137,7 @@ Opciones de aplicacion:
 - `--apply-docs --yes` aplica en automatizacion despues de validar propuesta, hashes, snapshot y post-write.
 - `--save-proposal` guarda `.quiver/runs/<run-id>/proposal/*` sin escribir docs finales.
 - `ai analyze-project apply --run <run-id>` aplica una propuesta guardada sin ejecutar proveedor ni requerir `--provider` o `--model`.
-- `--review` se mantiene como modo avanzado: abre la propuesta JSON en editor, revalida el JSON editado, muestra diff final y pide confirmacion.
+- `--review` se mantiene como modo avanzado: abre la propuesta JSON en editor y revalida el JSON editado antes de escribir.
 
 Modo deterministico:
 

package/docs/TROUBLESHOOTING.md

@@ -114,13 +114,13 @@ npx --yes create-quiver@latest ai analyze-project --deep --max-files 40 --max-by
 
 Si `package-lock.json` aparece como problema, no deberías incluirlo completo. En versiones actuales debe aparecer resumido en `detected.lockfiles` y omitido como `sampling:lockfile-metadata`.
 
-Cuando el análisis sea válido y quieras escribir documentación:
+Cuando el análisis sea válido, el comando normal ya escribe documentación final validada:
 
 ```bash
-npx --yes create-quiver@latest ai analyze-project --deep --apply-docs --provider codex --model gpt-5.5
+npx --yes create-quiver@latest ai analyze-project --deep --provider codex --model gpt-5.5
 ```
 
-`--apply-docs` muestra opciones explicadas en TTY: aplicar documentación, ver diff, guardar propuesta, editar propuesta o cancelar. Si elegís aplicar, Quiver revalida la propuesta, crea snapshot y escribe solo docs permitidos.
+Quiver revalida la propuesta, crea artifacts auditados, snapshot, write manifest y escribe solo docs permitidos. `--apply-docs` queda disponible para scripts o flujos interactivos que necesiten el selector anterior.
 
 Para guardar primero y aplicar después sin volver a ejecutar el proveedor:
 
@@ -145,20 +145,18 @@ los docs finales siguen con placeholders o falta `docs/ARCHITECTURE.md`.
 
 ### Explicación
 
-Ese comando ejecuta el análisis, valida la respuesta IA y guarda artifacts auditados en `.quiver/runs`, pero no escribe documentación final por defecto. Es intencional: evita cambios sorpresivos en repos reales.
+En versiones actuales, ese comando debe escribir documentación final validada. Si los docs siguen con placeholders, el flujo se bloqueó antes de escribir o la propuesta IA no incluyó contenido útil para esos paths.
 
 ### Qué hacer
 
-Usá uno de estos caminos seguros:
+Revisá el error mostrado y los artifacts del run. Los caminos seguros son:
 
 ```bash
-npx --yes create-quiver@latest ai analyze-project --deep --apply-docs --provider codex --model gpt-5.5
-npx --yes create-quiver@latest ai analyze-project --deep --apply-docs --yes --provider codex --model gpt-5.5
+npx --yes create-quiver@latest ai analyze-project --deep --provider codex --model gpt-5.5
 npx --yes create-quiver@latest ai analyze-project --deep --save-proposal --provider codex --model gpt-5.5
 npx --yes create-quiver@latest ai analyze-project apply --run <run-id>
 ```
 
-- `--apply-docs` en TTY muestra opciones explicadas antes de escribir.
-- `--apply-docs --yes` aplica en automatización si la propuesta y los docs destino son seguros.
+- el comando normal aplica docs después de validar JSON, proposal, snapshot y post-write;
 - `--save-proposal` guarda `.quiver/runs/<run-id>/proposal/*` sin tocar docs finales.
 - `apply --run <run-id>` aplica una propuesta guardada sin ejecutar proveedor ni pedir `--provider` o `--model`.

package/docs/reference/commands.md

@@ -49,7 +49,7 @@ El contenido curado fuera de los marcadores se mantiene manual y no debe ser ree
 | AI lifecycle | `ai active-slice status\|reconcile` | Inspect or dry-run reconcile local active-slice state from every supported source. |
 | AI lifecycle | `ai status` | Show current AI lifecycle phase, approved versions, blockers, and next command. |
 | AI lifecycle | `ai resume` | Resume guidance from the last valid lifecycle phase without chat memory. |
-| AI lifecycle | `ai analyze-project` | Analyze a bounded project sample and generate audited documentation proposals. |
+| AI lifecycle | `ai analyze-project` | Analyze a bounded project sample and apply validated documentation updates. |
 | AI lifecycle | `ai onboard` | Run or print the planner onboarding prompt with a token-aware context pack. |
 | AI lifecycle | `ai prepare-context` | Preview or write docs-only AI context updates with assumptions and risks. |
 | AI lifecycle | `ai agent set\|list\|show\|doctor\|repair` | Manage, diagnose, and dry-run repair planner, executor, reviewer, and doctor provider profiles without secrets. |
@@ -199,8 +199,8 @@ En `--dry-run`, Quiver no escribe archivos, no ejecuta proveedor y muestra qué
 Para generar docs desde IA:
 
 ```bash
+npx --yes create-quiver@latest ai analyze-project --deep --provider codex --model gpt-5.5
 npx --yes create-quiver@latest ai analyze-project --deep --save-proposal --provider codex --model gpt-5.5
-npx --yes create-quiver@latest ai analyze-project --deep --apply-docs --provider codex --model gpt-5.5
 npx --yes create-quiver@latest ai analyze-project apply --run <run-id>
 ```
 
@@ -216,12 +216,12 @@ Garantías del flujo con proveedor:
 - Si el proveedor devuelve JSON con drift seguro como `notes`, `claim` usado como `name` faltante, o `confidence` en paths no permitidos, Quiver lo repara, registra el repair y revalida.
 - Si el JSON sigue inválido pero el error es retryable, Quiver hace 1 retry por defecto, con cap duro de 2 retries.
 - Si el JSON final es inválido, Quiver falla sin escribir docs finales y deja manifests de validación/retry/repair en `.quiver/runs`.
-- El modo provider normal no escribe docs finales por defecto; usá `--apply-docs`, `--save-proposal` o `--review` para decidir qué hacer con la propuesta validada.
+- El modo provider normal aplica docs finales por defecto después de validar la propuesta, crear proposal artifacts, snapshot, write manifest y validación post-write.
 - `--apply-docs` en TTY muestra opciones explicadas para aplicar, ver diff, guardar propuesta, editar propuesta o cancelar.
 - `--apply-docs --yes` aplica en automatización después de validar propuesta, paths permitidos, hashes, snapshot y post-write.
 - `--save-proposal` guarda `.quiver/runs/<run-id>/proposal/*` sin escribir docs finales.
 - `ai analyze-project apply --run <run-id>` aplica una propuesta guardada sin ejecutar proveedor ni requerir `--provider` o `--model`.
-- `--review` abre una propuesta JSON editable, revalida el JSON editado, muestra diff final y pide confirmación antes de escribir docs permitidos.
+- `--review` queda como modo avanzado para editar manualmente una propuesta JSON antes de escribir.
 - Las escrituras aprobadas crean snapshot con hashes y se escriben con rename atómico.
 
 Benchmark recomendado:
@@ -238,7 +238,6 @@ cd /tmp/quiver-smoke/nika-erp
 npx --yes create-quiver@latest ai analyze-project --deep --dry-run --json
 npx --yes create-quiver@latest ai analyze-project --deep --provider codex --model gpt-5.5
 npx --yes create-quiver@latest ai analyze-project --deep --save-proposal --provider codex --model gpt-5.5
-npx --yes create-quiver@latest ai analyze-project --deep --apply-docs --provider codex --model gpt-5.5
 npx --yes create-quiver@latest ai analyze-project apply --run <run-id>
 ```
 
@@ -248,7 +247,7 @@ Evidencia esperada:
 
 - `--dry-run --json` parsea como JSON, `provider_execution` queda `skipped`, `writes` queda vacío y no crea docs finales.
 - `package-lock.json` aparece en `detected.lockfiles` y en omitidos con `sampling:lockfile-metadata`, no en contenido enviado al provider.
-- El modo provider escribe artifacts auditados en `.quiver/runs`, redactados y con tamaño controlado, pero no escribe docs finales sin `--apply-docs`, `--review` o `apply --run`.
+- El modo provider escribe artifacts auditados en `.quiver/runs`, redactados y con tamaño controlado, y aplica docs finales validados por defecto.
 - Si el provider devuelve drift no reparable, el comando falla con path/tipo/causa probable y próximo comando seguro, sin escribir docs finales.
 - `--save-proposal` debe crear `.quiver/runs/<run-id>/proposal/*` sin modificar docs finales.
 - `--apply-docs` debe mostrar selector explicado en TTY o requerir `--yes` en automatización.
@@ -256,7 +255,7 @@ Evidencia esperada:
 
 Rollback de release:
 
-- Si el smoke live escribe docs inesperadamente sin `--review`, filtra secretos, omite artifacts críticos o falla con ruido masivo de schema, no publiques `latest`.
+- Si el smoke live no escribe docs validados en el comando normal, filtra secretos, omite artifacts críticos o falla con ruido masivo de schema, no publiques `latest`.
 - Publicá una corrección como canary o revertí la versión npm afectada según el proceso de release vigente.
 - Para usuarios impactados, indicar `npx create-quiver ai analyze-project --deep --dry-run --json` como siguiente comando seguro y pedir `.quiver/runs/run-.../validation/analyze-project-validation.json` redactado como evidencia.
 
@@ -264,8 +263,8 @@ Rollback de release:
 |---|---|
 | `npx --yes create-quiver@latest ai analyze-project --deep --dry-run` | Previsualiza descubrimiento y muestreo del repo sin escribir ni ejecutar proveedor. |
 | `npx --yes create-quiver@latest ai analyze-project --deep --dry-run --json` | Emite el plan de análisis como JSON parseable para automatización. |
-| `npx --yes create-quiver@latest ai analyze-project --deep --review` | Ejecuta proveedor, valida análisis JSON con evidencia, abre revisión humana y escribe solo docs permitidos tras confirmación. |
-| `npx --yes create-quiver@latest ai analyze-project --deep --provider codex --model gpt-5.5` | Ejecuta proveedor y genera propuesta auditada en `.quiver/runs`; no escribe docs finales sin `--review`. |
+| `npx --yes create-quiver@latest ai analyze-project --deep --review` | Modo avanzado: ejecuta proveedor, valida análisis JSON con evidencia y abre edición manual antes de escribir docs permitidos. |
+| `npx --yes create-quiver@latest ai analyze-project --deep --provider codex --model gpt-5.5` | Ejecuta proveedor, valida JSON y aplica docs finales con proposal artifacts, snapshot, write manifest y validación post-write. |
 | `npx --yes create-quiver@latest ai analyze-project --deep --save-proposal --provider codex --model gpt-5.5` | Guarda una propuesta validada en `.quiver/runs/<run-id>/proposal` sin escribir docs finales. |
 | `npx --yes create-quiver@latest ai analyze-project --deep --apply-docs --provider codex --model gpt-5.5` | En TTY debe mostrar opciones explicadas para aplicar, ver diff, guardar, editar o cancelar. |
 | `npx --yes create-quiver@latest ai analyze-project --deep --apply-docs --yes --provider codex --model gpt-5.5` | Aplica docs validados en modo automatizado, con snapshots y validación post-write. |

package/docs/workflows/existing-project.md

@@ -86,19 +86,19 @@ Si querés que Quiver infiera producto, arquitectura, funcionalidades y riesgos
 ```bash
 npx --yes create-quiver@latest ai analyze-project --deep --dry-run
 npx --yes create-quiver@latest ai analyze-project --deep --provider codex --model gpt-5.5
-npx --yes create-quiver@latest ai analyze-project --deep --apply-docs --provider codex --model gpt-5.5
 ```
 
 Qué hace:
 
 - `--dry-run` muestra qué leería y qué excluiría, sin proveedor ni escrituras;
-- el modo con proveedor guarda auditoría en `.quiver/runs`, valida JSON con evidencia y no escribe docs finales por defecto;
+- el modo con proveedor guarda auditoría en `.quiver/runs`, valida JSON con evidencia y aplica docs finales validados por defecto;
+- antes de escribir crea propuesta, snapshot, write manifest y validación post-write;
 - resume lockfiles como metadata para no consumir el presupuesto principal con `package-lock.json`, `pnpm-lock.yaml` o equivalentes;
 - prioriza entrypoints, componentes, contexts/state, lib/data layer, auth, DB/integraciones y documentación humana del producto por encima de docs generados por Quiver;
 - muestra loader en TTY y progreso lineal en no-TTY;
 - si hay drift seguro de schema, como `notes` extra, `claim` usado como `name` faltante o `confidence` donde no está permitido, lo repara de forma auditada;
 - si el error es retryable, hace un retry acotado con feedback compacto;
-- `--apply-docs` muestra un selector simple en TTY para aplicar, ver diff, guardar, editar o cancelar.
+- si la propuesta final no es válida, falla sin escribir docs finales.
 
 Si preferís separar generación y aplicación:
 
@@ -107,13 +107,13 @@ npx --yes create-quiver@latest ai analyze-project --deep --save-proposal --provi
 npx --yes create-quiver@latest ai analyze-project apply --run <run-id>
 ```
 
-Para automatización sin selector:
+Si necesitás conservar compatibilidad con scripts que ya usaban el flujo explícito:
 
 ```bash
 npx --yes create-quiver@latest ai analyze-project --deep --apply-docs --yes --provider codex --model gpt-5.5
 ```
 
-`--review` sigue disponible como modo avanzado: abre la propuesta JSON en editor, revalida el JSON editado y pide confirmación antes de escribir docs permitidos.
+`--review` sigue disponible como modo avanzado: abre la propuesta JSON en editor y revalida el JSON editado antes de escribir docs permitidos.
 
 No envía `.env`, `.git`, `.quiver`, dependencias, caches, binarios ni outputs generados. Si no puede probar una conclusión, debe quedar como `unknown` o `needs_confirmation`.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-quiver",
-  "version": "0.17.3",
+  "version": "0.17.4",
   "private": false,
   "description": "Quiver CLI for scaffolding projects from the packaged template",
   "license": "MIT",

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

@@ -2886,7 +2886,11 @@ async function runAnalyzeProject(repoRoot, options = {}) {
     run_status_path: path.join('.quiver', 'runs', auditRunId, 'status.json').split(path.sep).join('/'),
     selected_context_manifest: selectedContextManifest,
   };
-  const needsDocProposal = options.applyDocs === true || options.saveProposal === true || options.review === true;
+  const autoApplyDocs = options.applyDocs !== true
+    && options.saveProposal !== true
+    && options.review !== true
+    && options.json !== true;
+  const needsDocProposal = autoApplyDocs || options.applyDocs === true || options.saveProposal === true || options.review === true;
   const docProposal = needsDocProposal ? buildAnalyzeProjectDocProposal(parsed.analysis) : null;
   const docWritePlan = docProposal ? buildAnalyzeProjectWritePlan(repoRoot, docProposal) : [];
   const docActionContext = {
@@ -2911,6 +2915,15 @@ async function runAnalyzeProject(repoRoot, options = {}) {
     return emitAnalyzeProjectApplyReport(applyReport, options);
   }
 
+  if (autoApplyDocs) {
+    const applyReport = applyAnalyzeProjectDocProposalReport(repoRoot, {
+      ...docActionContext,
+      allowDirtyDocs: true,
+      interactiveAction: 'auto-apply',
+    });
+    return emitAnalyzeProjectApplyReport(applyReport, options);
+  }
+
   if (options.applyDocs === true) {
     return runAnalyzeProjectInteractiveApplySelector({
       report: completedReport,

package/src/create-quiver/index.js

@@ -230,7 +230,7 @@ const COMMAND_HELP_GROUPS = [
       ['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 analyze-project', 'Analyze a bounded project sample and generate audited documentation proposals.'],
+      ['ai analyze-project', 'Analyze a bounded project sample and apply validated documentation updates.'],
       ['ai onboard', 'Run or print the planner onboarding prompt with a token-aware context pack.'],
       ['ai prepare-context', 'Preview or write docs-only AI context updates with assumptions and risks.'],
       ['ai agent set|list|show|doctor|repair', 'Manage, diagnose, and dry-run repair planner, executor, reviewer, and doctor provider profiles without secrets.'],

package/src/create-quiver/lib/ai/analyze-project-docs.js

@@ -93,6 +93,21 @@ function mergeManagedBlock(currentContent, proposedContent) {
   return `${current.replace(/\s+$/g, '')}\n\n${block}`;
 }
 
+function redactSnapshotValue(value, repoRoot) {
+  if (typeof value === 'string') {
+    return redactSensitiveLocalValues(value, { projectRoot: repoRoot });
+  }
+  if (Array.isArray(value)) {
+    return value.map((item) => redactSnapshotValue(item, repoRoot));
+  }
+  if (value && typeof value === 'object') {
+    return Object.fromEntries(
+      Object.entries(value).map(([key, item]) => [key, redactSnapshotValue(item, repoRoot)]),
+    );
+  }
+  return value;
+}
+
 function validateDocPath(docPath) {
   let normalized;
   try {
@@ -303,7 +318,7 @@ function createAnalyzeProjectSnapshot(repoRoot, run, writePlan, options = {}) {
 
   const providerArtifactPath = path.join(rawRoot, 'analyze-project-provider-artifact.json');
   const providerArtifact = options.providerArtifact
-    ? JSON.parse(redactSensitiveLocalValues(JSON.stringify(options.providerArtifact), { projectRoot: repoRoot }))
+    ? redactSnapshotValue(options.providerArtifact, repoRoot)
     : null;
   fs.writeFileSync(providerArtifactPath, `${JSON.stringify(providerArtifact, null, 2)}\n`);
 

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

@@ -37,7 +37,7 @@ module.exports = {
         'ai active-slice status|reconcile': 'Inspecciona o simula reconciliar el estado local de active-slice desde todas las fuentes soportadas.',
         'ai status': 'Muestra fase actual del ciclo de vida de IA, versiones aprobadas, bloqueos y proximo comando.',
         'ai resume': 'Reanuda la guia desde la ultima fase valida del ciclo de vida sin memoria de chat.',
-        'ai analyze-project': 'Analiza una muestra acotada del proyecto y genera propuestas documentales auditadas.',
+        'ai analyze-project': 'Analiza una muestra acotada del proyecto y aplica actualizaciones documentales validadas.',
         'ai onboard': 'Ejecuta o imprime el prompt de onboarding del planner con contexto optimizado por tokens.',
         'ai prepare-context': 'Previsualiza o escribe actualizaciones docs-only del contexto de IA con supuestos y riesgos.',
         'ai agent set|list|show|doctor|repair': 'Gestiona, diagnostica y simula reparaciones de perfiles planner, executor, reviewer y doctor sin secretos.',