create-quiver 0.17.2 → 0.17.4

package/CHANGELOG.md

@@ -6,6 +6,8 @@ All notable changes to this project will be documented in this file.
 
 ### Added
 
+- v55 analyze-project doc apply UX under `specs/quiver-v55-analyze-project-doc-apply-ux/`.
+- `ai analyze-project --apply-docs`, `--save-proposal`, `--diff`, `--allow-dirty-docs`, and `ai analyze-project apply --run <run-id>` for a safer reviewed docs-apply workflow.
 - v53 reliable deep project analysis and v54 deep analysis hardening specs under `specs/quiver-v53-reliable-deep-project-analysis/` and `specs/quiver-v54-deep-project-analysis-hardening/`.
 - v46 deep project analysis under `specs/quiver-v46-deep-project-analysis/`.
 - `ai analyze-project` for bounded, evidence-backed repository analysis with read-only `--dry-run`, JSON automation output, provider-backed `--review`, safe doc writes, snapshots, and post-write validation.
@@ -26,6 +28,8 @@ All notable changes to this project will be documented in this file.
 
 ### Changed
 
+- Existing-project docs now recommend the simple `--apply-docs` flow instead of forcing users into the advanced `--review` editor path.
+- English and Spanish CLI help now explain analyze-project docs apply options while preserving commands, flags, paths, providers, and model ids exactly.
 - `ai analyze-project --deep` now builds safer provider context by summarizing lockfiles as metadata, excluding generated/runtime directories, and prioritizing product source over Quiver-generated docs.
 - Existing-project AI onboarding now recommends `ai analyze-project --deep --dry-run` before context preparation so agents can see the intended read set, omissions, budgets, and privacy exclusions before any provider-backed docs update.
 - npm package hygiene now excludes local `.quiver/` run state from published tarballs.

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; `--review` exige JSON con evidencia, diff final, confirmacion, snapshot y validacion post-write. |
+| `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,10 +124,20 @@ 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 --review
+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 apply --run <run-id>
 ```
 
-`ai analyze-project` debe mantener estas garantias: en `--dry-run` no escribe ni ejecuta proveedor; 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:
+
+- `--apply-docs` en TTY muestra opciones explicadas: aplicar, ver diff, guardar propuesta, editar propuesta o cancelar.
+- `--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 y revalida el JSON editado antes de escribir.
 
 Modo deterministico:
 

package/docs/TROUBLESHOOTING.md

@@ -114,10 +114,49 @@ 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 --review --provider codex --model gpt-5.5
+npx --yes create-quiver@latest ai analyze-project --deep --provider codex --model gpt-5.5
+```
+
+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:
+
+```bash
+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>
+```
+
+`--review` sigue disponible como modo avanzado si querés editar la propuesta JSON manualmente antes de escribir.
+
+## `ai analyze-project` no completa `docs/CONTEXTO.md` ni crea `docs/ARCHITECTURE.md`
+
+### Síntoma
+
+Después de ejecutar:
+
+```bash
+npx --yes create-quiver@latest ai analyze-project --deep --provider codex --model gpt-5.5
+```
+
+los docs finales siguen con placeholders o falta `docs/ARCHITECTURE.md`.
+
+### Explicación
+
+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
+
+Revisá el error mostrado y los artifacts del run. Los caminos seguros son:
+
+```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 apply --run <run-id>
 ```
 
-`--review` abre una propuesta editable, revalida el JSON editado, muestra diff final, pide confirmación, crea snapshot y recién después escribe docs permitidos.
+- 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` | Read and explain a bounded project sample without provider execution or writes. |
+| 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,11 +199,12 @@ 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 --review
-npx --yes create-quiver@latest ai analyze-project --deep --review --strict
+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>
 ```
 
-El modo con proveedor exige JSON validado por schema, evidencia por conclusión, niveles `confirmed`, `inferred`, `unknown` o `conflict`, revisión editable, diff final, confirmación humana, snapshot previo en `.quiver/runs`, artefactos redactados y validación post-write. `--strict` convierte conflictos importantes de docs en error. El resultado puede quedar como `unknown` o `needs_confirmation` cuando el código no prueba una conclusión.
+El modo con proveedor exige JSON validado por schema, evidencia por conclusión, niveles `confirmed`, `inferred`, `unknown` o `conflict`, artifacts auditados en `.quiver/runs`, diff, snapshot previo cuando se escribe y validación post-write. `--strict` convierte conflictos importantes de docs en error. El resultado puede quedar como `unknown` o `needs_confirmation` cuando el código no prueba una conclusión.
 
 Garantías del flujo con proveedor:
 
@@ -215,7 +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`.
-- `--review` abre una propuesta editable, revalida el JSON editado, muestra diff final y pide confirmación antes de escribir docs permitidos.
+- 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` 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:
@@ -226,23 +232,30 @@ Benchmark recomendado:
 Smoke de release recomendado:
 
 ```bash
-cd "/Users/fabrijk/Documents/Work/Proyectos Personales/nika/nika-erp/nika-erp"
+mkdir -p /tmp/quiver-smoke
+rsync -a --delete --exclude .git --exclude node_modules --exclude .next --exclude .quiver "/Users/fabrijk/Documents/Work/Proyectos Personales/nika/nika-erp/nika-erp/" /tmp/quiver-smoke/nika-erp/
+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 --review --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>
 ```
 
+También podés usar una rama descartable en el repo real. No ejecutes el smoke de aplicación sobre el checkout principal de `nika-erp`.
+
 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 `--review`.
+- 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.
-- `--review` debe mostrar propuesta editable, diff final y confirmación antes de escribir docs permitidos.
+- `--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.
+- `apply --run <run-id>` debe aplicar la propuesta guardada sin volver a ejecutar proveedor.
 
 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.
 
@@ -250,8 +263,12 @@ 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. |
+| `npx --yes create-quiver@latest ai analyze-project apply --run <run-id>` | Aplica una propuesta guardada sin ejecutar proveedor ni requerir `--provider` o `--model`. |
 | `npx --yes create-quiver@latest ai analyze-project --scope apps/web --max-files 80 --max-bytes 300000 --include-tests --dry-run` | Acota el análisis por workspace/ruta y presupuesto de muestra. |
 | `npx --yes create-quiver@latest ai prepare-context --dry-run` | Previsualiza actualizaciones documentales de contexto para IA. |
 | `npx --yes create-quiver@latest ai prepare-context` | Escribe actualizaciones documentales de contexto para IA. |
@@ -331,6 +348,10 @@ Base branch policy: `--base <branch>` always wins. Without `--base`, slice readi
 | `--include-source` | En `ai analyze-project`, incluye código fuente sin requerir `--deep`. |
 | `--include-tests` | En `ai analyze-project`, incluye tests en la muestra. |
 | `--include-db` | En `ai analyze-project`, incluye schemas, migraciones y archivos DB. |
+| `--apply-docs` | En `ai analyze-project`, habilita el flujo seguro para aplicar propuestas documentales validadas. |
+| `--save-proposal` | En `ai analyze-project`, guarda la propuesta validada como artifacts sin escribir docs finales. |
+| `--diff` | En `ai analyze-project`, muestra o guarda el diff documental propuesto cuando el flujo lo soporta. |
+| `--allow-dirty-docs` | En `ai analyze-project`, permite continuar con docs destino modificados solo donde el flujo seguro lo soporte. |
 | `--scope <path\|name>` | En `ai analyze-project`, restringe el análisis a una ruta o workspace. |
 | `--strict` | En validaciones soportadas, convierte conflictos importantes en errores. |
 | `--with-planner` | Activa comportamiento asistido por planner solo en comandos que lo soportan. |

package/docs/workflows/existing-project.md

@@ -86,19 +86,34 @@ 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 --review --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` y valida JSON con evidencia;
+- 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;
-- `--review` abre propuesta editable y solo escribe docs permitidos después de confirmar.
+- si la propuesta final no es válida, falla sin escribir docs finales.
+
+Si preferís separar generación y aplicación:
+
+```bash
+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>
+```
+
+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 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.2",
+  "version": "0.17.4",
   "private": false,
   "description": "Quiver CLI for scaffolding projects from the packaged template",
   "license": "MIT",

package/specs/quiver-v43-cli-i18n-audit-release-readiness/command-language-mode-matrix.json

@@ -609,6 +609,10 @@
     { "command": "ai analyze-project --deep --dry-run --json", "profile": "ai-analyze-project", "critical": "pass" },
     { "command": "ai analyze-project --deep --review", "profile": "ai-analyze-project", "critical": "pass" },
     { "command": "ai analyze-project --deep --provider codex --model gpt-5.5", "profile": "ai-analyze-project", "critical": "pass" },
+    { "command": "ai analyze-project --deep --save-proposal --provider codex --model gpt-5.5", "profile": "ai-analyze-project", "critical": "pass" },
+    { "command": "ai analyze-project --deep --apply-docs --provider codex --model gpt-5.5", "profile": "ai-analyze-project", "critical": "pass" },
+    { "command": "ai analyze-project --deep --apply-docs --yes --provider codex --model gpt-5.5", "profile": "ai-analyze-project", "critical": "pass" },
+    { "command": "ai analyze-project apply --run <run-id>", "profile": "ai-analyze-project", "critical": "pass" },
     { "command": "ai analyze-project --scope apps/web --max-files 80 --max-bytes 300000 --include-tests --dry-run", "profile": "ai-analyze-project", "critical": "pass" },
     { "command": "ai prepare-context --dry-run", "profile": "ai-prepare-context", "critical": "pass" },
     { "command": "ai prepare-context", "profile": "ai-prepare-context", "critical": "pass" },

package/specs/quiver-v55-analyze-project-doc-apply-ux/EVIDENCE_REPORT.md

@@ -0,0 +1,209 @@
+# Evidence Report - Quiver v55 Analyze Project Doc Apply UX
+
+**Status:** In progress
+**Last updated:** 2026-06-12
+
+## Evidence Behind The Requirement
+
+- Live `nika-erp` run with `create-quiver@0.17.2` completed successfully and generated valid doc update proposals.
+- The normal provider command did not write final docs, by design.
+- Existing `docs/CONTEXTO.md` in `nika-erp` still contained placeholders because no apply/review flow was completed.
+- `--review` is safe but confusing because it opens a large JSON proposal in an editor.
+- Users need a simpler flow: summary, explained options, optional diff, save, apply, edit, or cancel.
+
+## Evidence To Capture During Implementation
+
+- Parser/flag tests for `--apply-docs`, `--save-proposal`, `--diff`, `--yes`, `--allow-dirty-docs`, and `ai analyze-project apply --run`. Captured in `slice-01`.
+- Proposal artifact schema tests. Captured in `slice-01`.
+- Save proposal command tests in TTY/no-TTY and JSON modes.
+- Non-interactive apply tests with snapshots, write manifests, and post-write validation.
+- Dirty/stale doc preflight tests.
+- Interactive selector tests for apply, diff, save, edit, and cancel.
+- Saved proposal apply tests without provider execution.
+- EN/ES i18n tests.
+- Docs/checks and package smoke before release.
+
+## Required Validation Before Closing Spec
+
+```bash
+node --test tests/commands/ai-analyze-project-review.test.js
+node --test tests/commands/ai-analyze-project-provider.test.js
+node --test tests/commands/ai-analyze-project.test.js
+node --test tests/lib/ai-analyze-project-validation.test.js
+node --test tests/lib/ai/analyze-project-repair.test.js
+npm run docs:check
+npm run schema:slice:check
+node bin/create-quiver.js spec validate specs/quiver-v55-analyze-project-doc-apply-ux --strict
+git diff --check
+```
+
+## Release Smoke Evidence
+
+Use a temporary copy or disposable branch of `nika-erp`:
+
+```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 --deep --apply-docs --yes --provider codex --model gpt-5.5
+npx --yes create-quiver@latest ai analyze-project apply --run <run-id>
+```
+
+Live provider smoke is release evidence only and must not become a CI gate.
+
+## Slice-01 Evidence
+
+Executed:
+
+```bash
+node --test tests/lib/ai-analyze-project-proposal.test.js
+node --test tests/commands/ai-analyze-project.test.js
+node --test tests/commands/cli-contract.test.js
+node --test tests/commands/parser-contract.test.js
+node --test tests/commands/ux-flags.test.js
+node --test tests/commands/ai-analyze-project-review.test.js
+node --test tests/commands/ai-analyze-project-provider.test.js
+node --test tests/lib/ai-analyze-project-docs.test.js tests/lib/ai-analyze-project-validation.test.js
+npm run docs:check
+npm run schema:slice:check
+```
+
+Result: all passed.
+
+## Slice-02 Evidence - slice-02-save-proposal-flow
+
+Executed:
+
+```bash
+node --test tests/lib/ai-analyze-project-proposal.test.js
+node --test tests/commands/ai-analyze-project-provider.test.js
+node --test tests/commands/ai-analyze-project.test.js tests/commands/cli-contract.test.js tests/commands/ux-flags.test.js
+node --test tests/commands/ai-analyze-project-review.test.js tests/lib/ai-analyze-project-validation.test.js tests/lib/ai-analyze-project-docs.test.js
+node bin/create-quiver.js spec validate specs/quiver-v55-analyze-project-doc-apply-ux --strict
+git diff --check
+```
+
+Result: all passed.
+
+Covered behavior:
+
+- `--save-proposal` persists proposal JSON, compact Markdown summary, full diff, and manifest.
+- `--save-proposal --json` emits clean parseable JSON.
+- Final docs remain unchanged.
+- Save-only flows do not create snapshots.
+- Invalid final provider JSON does not create usable proposal artifacts.
+
+## Slice-03 Evidence - slice-03-noninteractive-apply-engine
+
+Executed:
+
+```bash
+node --test tests/lib/ai-analyze-project-apply.test.js
+node --test tests/lib/ai-analyze-project-proposal.test.js
+node --test tests/commands/ai-analyze-project-review.test.js
+node --test tests/commands/ai-analyze-project.test.js tests/commands/cli-contract.test.js tests/commands/ux-flags.test.js
+node --test tests/commands/ai-analyze-project-provider.test.js
+node --test tests/lib/ai/analyze-project-repair.test.js
+npm run docs:check
+npm run schema:slice:check
+node bin/create-quiver.js spec validate specs/quiver-v55-analyze-project-doc-apply-ux --strict
+git diff --check
+npm test
+```
+
+Result: all passed. Full `npm test` passed with 730 tests.
+
+Covered behavior:
+
+- `--apply-docs --yes` applies validated allowed docs.
+- `--apply-docs --yes --json` returns run id, proposal artifacts, write plan, snapshot, written docs, post-write validation, and write manifest.
+- Dirty target docs block `--yes` unless `--allow-dirty-docs` is provided.
+- Stale target docs are blocked at the apply engine boundary.
+- Invalid provider doc proposals do not write final docs.
+- Existing `--review` behavior remains covered.
+
+## Slice-04 Evidence - slice-04-interactive-apply-ux
+
+Executed:
+
+```bash
+node --test tests/commands/ai-analyze-project-review.test.js
+node --test tests/lib/cli-ux.test.js
+node --test tests/commands/ai-analyze-project.test.js
+node --test tests/commands/cli-contract.test.js
+node --test tests/lib/i18n-catalog.test.js
+node --test tests/commands/ux-flags.test.js
+node --test tests/commands/ai-analyze-project-provider.test.js
+node --test tests/lib/ai-analyze-project-validation.test.js tests/lib/ai/analyze-project-repair.test.js
+npm run docs:check
+npm run schema:slice:check
+node bin/create-quiver.js spec validate specs/quiver-v55-analyze-project-doc-apply-ux --strict
+git diff --check
+npm test
+```
+
+Result: all passed. Full `npm test` passed with 741 tests.
+
+Covered behavior:
+
+- TTY `--apply-docs` shows an explained selector after provider validation.
+- Clean creates recommend `apply`; dirty/update targets recommend `view-diff`.
+- no-TTY `--apply-docs` without `--yes` fails before provider execution.
+- Cancel writes no final docs and records `apply-canceled`.
+- Save proposal writes proposal artifacts only.
+- View diff saves the full diff artifact, prints a bounded preview, and requires a second decision.
+- Edit proposal reuses the existing review/editor confirmation flow.
+- English and Spanish selector copy are covered.
+
+## Slice-05 Evidence - slice-05-apply-saved-proposal
+
+Executed:
+
+```bash
+node --test tests/commands/ai-analyze-project-review.test.js
+node --test tests/lib/ai-analyze-project-proposal.test.js
+node --test tests/commands/ai-analyze-project.test.js
+npm run docs:check
+npm run schema:slice:check
+node bin/create-quiver.js spec validate specs/quiver-v55-analyze-project-doc-apply-ux --strict
+git diff --check
+npm test
+```
+
+Result: all passed. Full `npm test` passed with 747 tests.
+
+Covered behavior:
+
+- `ai analyze-project apply --run <run-id>` applies a saved proposal without executing provider/model resolution.
+- Saved proposal manifests and proposal JSON are revalidated before write.
+- Missing or unsafe saved artifacts fail before final docs writes.
+- Dirty target docs block by default and can be applied only with `--allow-dirty-docs`.
+- Stale target docs block before any final docs write.
+- Manual proposal edits are accepted after revalidation and recorded in the write manifest.
+- `--run latest --yes` and `--run latest --json` are rejected to keep automation deterministic.
+
+## Slice-06 Evidence - slice-06-i18n-docs-release-smoke
+
+Executed:
+
+```bash
+node --test tests/commands/cli-contract.test.js
+node --test tests/lib/i18n-catalog.test.js
+node --test tests/commands/ai-analyze-project-review.test.js
+npm run docs:check
+npm run schema:slice:check
+node bin/create-quiver.js spec validate specs/quiver-v55-analyze-project-doc-apply-ux --strict
+git diff --check
+npm test
+```
+
+Result: all passed. Full `npm test` passed with 747 tests.
+
+Covered behavior:
+
+- English and Spanish help coverage includes the new analyze-project doc-apply flags.
+- Commands, flags, providers, models, and paths remain untranslated in localized output.
+- Command reference explains `--apply-docs`, `--save-proposal`, `--review`, `--yes`, `--diff`, and `apply --run`.
+- Existing-project workflow documents the recommended `--apply-docs` path and save/apply separation.
+- Troubleshooting explains why normal provider mode does not write final docs.
+- Release smoke guidance uses a temporary copy or disposable branch of `nika-erp`, not the main checkout.

package/specs/quiver-v55-analyze-project-doc-apply-ux/EXECUTION_PLAN.md

@@ -0,0 +1,49 @@
+# Execution Plan - Quiver v55 Analyze Project Doc Apply UX
+
+## Sequential Order
+
+1. `slice-01-cli-proposal-contract`
+2. `slice-02-save-proposal-flow`
+3. `slice-03-noninteractive-apply-engine`
+4. `slice-04-interactive-apply-ux`
+5. `slice-05-apply-saved-proposal`
+6. `slice-06-i18n-docs-release-smoke`
+
+## Parallelization Rules
+
+- `slice-01` must land first because it freezes the CLI and artifact contracts.
+- `slice-02` must wait for proposal artifact schema and paths.
+- `slice-03` must wait for saved proposal support so every apply can persist proposal artifacts first.
+- `slice-04` must wait for the non-interactive apply engine so the selector only orchestrates tested actions.
+- `slice-05` can start after `slice-03`; it must not duplicate apply/write logic.
+- `slice-06` closes documentation, i18n, command matrix, and release smoke after behavior is stable.
+
+## Critical Boundaries
+
+- CLI parse boundary: `slice-01`
+- Proposal artifact boundary: `slice-01`, `slice-02`
+- Write boundary: `slice-03`
+- Human UX boundary: `slice-04`
+- Saved-run trust boundary: `slice-05`
+- Release readiness boundary: `slice-06`
+
+## Rollback
+
+- Revert `slice-04` to remove interactive UX while keeping non-interactive save/apply behavior.
+- Revert `slice-05` if saved proposal application has stale-detection issues.
+- Revert `slice-03` to remove docs applying while retaining proposal save artifacts.
+- Preserve existing `--review` behavior throughout as fallback.
+
+## Required Validation
+
+```bash
+node --test tests/commands/ai-analyze-project-review.test.js
+node --test tests/commands/ai-analyze-project-provider.test.js
+node --test tests/commands/ai-analyze-project.test.js
+node --test tests/lib/ai-analyze-project-validation.test.js
+node --test tests/lib/ai/analyze-project-repair.test.js
+npm run docs:check
+npm run schema:slice:check
+node bin/create-quiver.js spec validate specs/quiver-v55-analyze-project-doc-apply-ux --strict
+git diff --check
+```