create-quiver 0.17.3 → 0.17.5

package/CHANGELOG.md

@@ -28,6 +28,7 @@ All notable changes to this project will be documented in this file.
 
 ### Changed
 
+- `ai analyze-project` human output now reports compact merge decisions so users can see scaffold replacement, human-content preservation, old `context-prep` cleanup, and warnings without opening manifests.
 - 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.
@@ -48,6 +49,7 @@ All notable changes to this project will be documented in this file.
 
 ### Fixed
 
+- `ai analyze-project` now replaces visible Quiver scaffold placeholders and old template `context-prep` blocks when a valid project proposal is available, with nika-erp style regression coverage for `NIKA_ERP`/`stockflow`/`StockFlow` naming conflicts.
 - `ai analyze-project --deep` now repairs common safe provider schema drift, retries with compact schema feedback, records redacted raw artifacts, and fails closed without final doc writes when JSON remains invalid.
 - `doctor --fix` now gives an actionable repair path for existing `AGENTS.md` files that are missing Quiver contract sections while preserving manual content.
 - `ai analyze-project` now shows human TTY progress while provider analysis runs and reports schema validation issues with actionable detail.

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,14 @@ 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.
+
+Feedback de merge:
+
+- Cuando hay docs modificados, la salida humana muestra `Merge decisions`.
+- Cada item informa estrategia, clasificacion, placeholders reemplazados, contenido humano preservado y bloques `context-prep` removidos cuando aplica.
+- La salida debe ser compacta; el detalle auditable queda en `.quiver/runs/<run-id>/proposal/manifest.json` y `.quiver/runs/<run-id>/writes/analyze-project-doc-writes.json`.
+- Conflictos de nombres o facts se muestran en `Post-write validation` como warnings o errores con `--strict`.
 
 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,28 @@ 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.
+
+Quiver clasifica cada doc antes de escribir:
+
+- `scaffold`: reemplaza el contenido visible de template y conserva frontmatter válido.
+- `partial_scaffold` o `mixed`: elimina placeholders críticos, conserva contenido humano real y consolida bloques gestionados.
+- `human_content`: conserva el contenido humano y agrega/actualiza el bloque `quiver:analyze-project`.
+
+Los bloques antiguos `quiver:context-prep` que todavía contienen placeholders se eliminan durante `analyze-project` para que no compitan con el contexto nuevo. Si hay conflicto de nombres, por ejemplo `NIKA_ERP`, `stockflow` y `StockFlow`, Quiver lo reporta como warning o error en `--strict` en vez de ocultarlo.
 
 ### 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`.
+
+Si venís de una versión anterior y tus docs tienen placeholders arriba y un bloque `quiver:analyze-project` útil abajo, volvé a ejecutar el comando normal. La salida debe mostrar `Merge decisions`, el strategy aplicado, si reemplazó scaffold, si preservó contenido humano y si removió `context-prep`.

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,13 +199,23 @@ 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>
 ```
 
 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.
 
+Al escribir docs, Quiver no pega la respuesta del proveedor sin más. Primero clasifica el contenido existente y aplica un merge determinístico:
+
+- reemplaza scaffolds con placeholders críticos en español o inglés;
+- preserva contenido humano real;
+- reemplaza un bloque `quiver:analyze-project` previo en lugar de duplicarlo;
+- remueve bloques `quiver:context-prep` viejos cuando todavía son template;
+- reporta `Merge decisions` con estrategia, placeholders reemplazados, contenido humano preservado y warnings.
+
+Los conflictos de nombres o facts, por ejemplo `NIKA_ERP`, `stockflow` y `StockFlow`, se reportan en la validación post-write. En modo normal aparecen como warnings; con `--strict` bloquean la ejecución.
+
 Garantías del flujo con proveedor:
 
 - `--dry-run` no escribe archivos ni ejecuta proveedor.
@@ -216,13 +226,14 @@ 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.
+- El write manifest guarda `merge_report` por archivo y el proposal manifest guarda `merge_plan` para auditoría.
 
 Benchmark recomendado:
 
@@ -238,7 +249,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,15 +258,17 @@ 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.
 - `apply --run <run-id>` debe aplicar la propuesta guardada sin volver a ejecutar proveedor.
+- La salida humana debe mostrar `Merge decisions` cuando haya docs modificados.
+- En fixtures tipo `nika-erp`, `docs/CONTEXTO.md` no debe conservar placeholders visibles ni bloques `quiver:context-prep` de template después de aplicar.
 
 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 +276,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.5",
   "private": false,
   "description": "Quiver CLI for scaffolding projects from the packaged template",
   "license": "MIT",

package/specs/quiver-v56-analyze-project-usable-doc-merge/EVIDENCE_REPORT.md

@@ -0,0 +1,11 @@
+# Evidence Report - Quiver v56 Analyze Project Usable Doc Merge
+
+Evidence is recorded per slice closure.
+
+## Slice Evidence
+
+| Slice | Evidence |
+|---|---|
+| slice-01-document-classification-merge-engine | `node --test tests/lib/ai-analyze-project-docs.test.js`; `node --test tests/commands/ai-analyze-project-provider.test.js`; `node --test tests/commands/ai-analyze-project-review.test.js`; `node bin/create-quiver.js spec validate specs/quiver-v56-analyze-project-usable-doc-merge --strict`; `git diff --check` |
+| slice-02-apply-integration-validation-contract | `node --test tests/commands/ai-analyze-project-provider.test.js tests/commands/ai-analyze-project-review.test.js`; `node --test tests/lib/ai-analyze-project-docs.test.js tests/lib/ai-analyze-project-validation.test.js`; `node --test tests/lib/ai-analyze-project-proposal.test.js`; `node bin/create-quiver.js spec validate specs/quiver-v56-analyze-project-usable-doc-merge --strict`; `git diff --check` |
+| slice-03-cli-docs-real-fixture-smoke | `node --test tests/commands/ai-analyze-project-provider.test.js tests/commands/cli-contract.test.js`; `npm run docs:check`; `node bin/create-quiver.js spec validate specs/quiver-v56-analyze-project-usable-doc-merge --strict`; `git diff --check` |

package/specs/quiver-v56-analyze-project-usable-doc-merge/EXECUTION_PLAN.md

@@ -0,0 +1,28 @@
+# Execution Plan - Quiver v56 Analyze Project Usable Doc Merge
+
+## Order
+
+1. `slice-01-document-classification-merge-engine`
+2. `slice-02-apply-integration-validation-contract`
+3. `slice-03-cli-docs-real-fixture-smoke`
+
+## Parallelism
+
+- Slice 01 is sequential and blocks everything else.
+- Slice 02 is sequential after Slice 01.
+- Slice 03 docs can draft after Slice 01, but final smoke and output validation depend on Slice 02.
+
+## PR Strategy
+
+- PR 1: Slice 01.
+- PR 2: Slice 02.
+- PR 3: Slice 03.
+
+## Validation Gates
+
+Each PR must run its focused tests plus:
+
+```bash
+git diff --check
+node bin/create-quiver.js spec validate specs/quiver-v56-analyze-project-usable-doc-merge --strict
+```

package/specs/quiver-v56-analyze-project-usable-doc-merge/SPEC.md

@@ -0,0 +1,96 @@
+# Quiver v56 - Analyze Project Usable Doc Merge
+
+**Date:** 2026-06-17
+**Status:** Completed
+**Source:** User-approved requirement, production review, stricter second-pass review, and execution plan for `ai analyze-project` usable documentation output.
+
+## Problem
+
+`ai analyze-project --deep --provider codex --model gpt-5.5` now writes documentation by default, but real projects can still end with unusable docs. In `nika-erp`, Quiver wrote a valid `quiver:analyze-project` block, but preserved scaffold placeholders at the top of `docs/CONTEXTO.md`, plus an older `quiver:context-prep` block. The command reported success even though the first visible content still looked unmodified.
+
+## Objective
+
+Make analyze-project doc writes produce usable human-facing context files by applying a deterministic documentation merge contract:
+
+```text
+classify existing doc -> merge by classification -> preserve real human content -> replace scaffold placeholders -> consolidate managed blocks -> validate visible output
+```
+
+## Scope
+
+### Included
+
+- Document classification contract for scaffold, partial scaffold, human content, managed-only, mixed, and unknown docs.
+- Deterministic merge strategy for `docs/CONTEXTO.md`, `docs/AI_CONTEXT.md`, and `docs/ARCHITECTURE.md`.
+- Critical placeholder detection in English and Spanish.
+- Idempotent managed block replacement.
+- Safe handling of old `quiver:context-prep` blocks.
+- Integration with live apply, saved proposal apply, review, JSON, and strict validation.
+- Human output, manifests, docs, troubleshooting, and nika-erp regression fixture/smoke.
+
+### Excluded
+
+- Product-code changes in analyzed repositories.
+- Writing outside the existing analyze-project documentation allowlist.
+- Automatic spec generation from project analysis.
+- Relaxing provider schema validation.
+- Translating technical evidence or provider claims semantically.
+
+## Requirements
+
+1. Quiver must not preserve critical scaffold placeholders as primary visible content when a valid proposal can replace them.
+2. Quiver must not delete real human content without preserving it or reporting a warning.
+3. Existing frontmatter must be preserved when it is parseable.
+4. If frontmatter is ambiguous, Quiver must preserve it and warn.
+5. `quiver:analyze-project` must be replaced in place on repeated runs, never duplicated.
+6. `quiver:context-prep` scaffold content must not remain as confusing primary content after analyze-project applies.
+7. The merge must be idempotent for the same proposal and input.
+8. `apply --run` and live provider apply must use the same merge engine.
+9. `--save-proposal` must persist a merge plan or enough metadata to preview the eventual write result.
+10. `--review` must show the final post-merge diff, not only raw provider Markdown.
+11. `--json` must expose merge strategy and warnings without removing existing fields.
+12. `--strict` must fail when critical placeholders remain in primary visible content.
+13. Name conflicts such as `NIKA_ERP`, `stockflow`, and `StockFlow` must be reported, not silently hidden.
+
+## Classification Contract
+
+| Classification | Condition | Action |
+|---|---|---|
+| `scaffold` | Quiver/template signals plus known placeholders, with no significant human text | Replace primary content while preserving frontmatter |
+| `partial_scaffold` | Some sections are placeholder-only and other sections have human text | Replace placeholder sections and preserve completed sections |
+| `human_content` | Significant non-placeholder text outside managed markers | Preserve human text and insert generated summary visibly |
+| `managed_only` | File is empty or only contains Quiver managed blocks | Replace managed content |
+| `mixed` | Human text plus Quiver blocks plus placeholders | Preserve human text, remove/replace scaffold portions, consolidate blocks |
+| `unknown` | Not safely classifiable | Preserve content, insert generated block visibly, warn |
+
+## Slice Roadmap
+
+| Slice | Title | Status | Dependencies | Parallel Guidance |
+|---|---|---|---|---|
+| slice-01-document-classification-merge-engine | Document Classification + Merge Engine | completed | none | sequential first |
+| slice-02-apply-integration-validation-contract | Apply Integration + Validation Contract | completed | slice-01 | sequential after slice-01 |
+| slice-03-cli-docs-real-fixture-smoke | CLI UX + Docs + Real Fixture Smoke | completed | slice-02 | final hardening; docs can draft after slice-01 |
+
+## Validation Strategy
+
+```bash
+node --test tests/lib/ai-analyze-project-docs.test.js
+node --test tests/commands/ai-analyze-project-provider.test.js tests/commands/ai-analyze-project-review.test.js
+npm run docs:check
+node bin/create-quiver.js spec validate specs/quiver-v56-analyze-project-usable-doc-merge --strict
+git diff --check
+```
+
+## Production Guardrails
+
+- Snapshot before writes remains mandatory.
+- Writes remain atomic.
+- Path allowlist remains unchanged.
+- Provider output remains untrusted until schema validation passes.
+- Merge decisions must be recorded in the write plan/report.
+- Critical placeholder validation checks primary visible content, not only managed blocks.
+
+## Open Questions
+
+- Whether `token_cost` should be recalculated immediately in v56 or deferred to a metadata cleanup.
+- Whether old `context-prep` human notes should be moved into a named preserved section or only marked as superseded.

package/specs/quiver-v56-analyze-project-usable-doc-merge/STATUS.md

@@ -0,0 +1,26 @@
+# Status - Quiver v56 Analyze Project Usable Doc Merge
+
+**Status:** Completed
+**Last updated:** 2026-06-17
+
+## Current State
+
+The requirement, acceptance criteria, production review, second stricter review, and execution plan are approved. All slices are complete.
+
+## Slice Status
+
+| Slice | Status | Notes |
+|---|---|---|
+| slice-01-document-classification-merge-engine | completed | Deterministic classification and merge engine implemented with unit and analyze-project flow tests. |
+| slice-02-apply-integration-validation-contract | completed | Merge metadata is exposed in JSON/write reports, proposal/write manifests persist merge plan/report, review diff uses post-merge output, and strict validation fails visible scaffold placeholders. |
+| slice-03-cli-docs-real-fixture-smoke | completed | Human output reports merge decisions, docs explain placeholder recovery, and deterministic nika-erp style fixture validates visible placeholder cleanup plus name-conflict warnings. |
+
+## Blockers
+
+- None.
+
+## Next Command
+
+```bash
+node --test tests/commands/ai-analyze-project-provider.test.js tests/commands/cli-contract.test.js
+```

package/specs/quiver-v56-analyze-project-usable-doc-merge/pr.md

@@ -0,0 +1,56 @@
+## Title
+
+Quiver v56 analyze-project usable doc merge
+
+## Summary
+
+Implements a deterministic document merge contract so `ai analyze-project` replaces scaffold placeholders, preserves real human content, consolidates managed blocks, and validates that final docs are usable.
+
+## PR Policy
+
+Individual PRs by slice. Runtime behavior changes must not be grouped with unrelated docs-only work.
+
+## Scope
+
+See the active slice `pr.md`.
+
+## Files
+
+See the active slice `slice.json`.
+
+## How to Test (DETAILED - REQUIRED)
+
+### Required Environment
+
+Node.js/npm and local checkout.
+
+### Worktree Access
+
+Use the branch created for the active slice.
+
+### Run the Project
+
+No dev server is required.
+
+### Use Cases
+
+See active slice.
+
+### Technical Verification
+
+```bash
+node bin/create-quiver.js spec validate specs/quiver-v56-analyze-project-usable-doc-merge --strict
+git diff --check
+```
+
+## Evidence
+
+See active slice closure.
+
+## Rollback
+
+Revert the slice PR.
+
+## Risks / Notes
+
+This spec changes doc merge behavior for `ai analyze-project`; preserve snapshots and allowlist protections.

package/specs/quiver-v56-analyze-project-usable-doc-merge/slices/slice-01-document-classification-merge-engine/CLOSURE_BRIEF.md

@@ -0,0 +1,61 @@
+# CLOSURE_BRIEF - slice-01 Document Classification + Merge Engine
+
+## Summary
+
+Implemented the Slice 01 merge engine contract for analyze-project docs.
+
+The engine now:
+
+- classifies existing docs as scaffold, partial scaffold, human content, managed-only, mixed, or unknown;
+- detects known critical Quiver scaffold placeholders in English and Spanish;
+- preserves parseable frontmatter;
+- replaces scaffold primary content with proposed analyze-project content;
+- preserves significant human content in partial/mixed docs;
+- replaces existing `quiver:analyze-project` blocks without duplication;
+- removes scaffold-only `quiver:context-prep` content when analyze-project content is applied;
+- exposes `merge_report` metadata on write plan items;
+- remains idempotent for the same proposal.
+
+## Evidence
+
+```bash
+node --test tests/lib/ai-analyze-project-docs.test.js
+```
+
+Result: 10 tests passed, 0 failed.
+
+```bash
+node --test tests/commands/ai-analyze-project-provider.test.js
+```
+
+Result: 23 tests passed, 0 failed.
+
+```bash
+node --test tests/commands/ai-analyze-project-review.test.js
+```
+
+Result: 20 tests passed, 0 failed.
+
+## Validation
+
+```bash
+node bin/create-quiver.js spec validate specs/quiver-v56-analyze-project-usable-doc-merge --strict
+git diff --check
+```
+
+Result: passed.
+
+## Acceptance Coverage
+
+- Scaffold docs no longer keep critical placeholders as primary visible content: covered by `mergeAnalyzeProjectDoc replaces Spanish Quiver scaffold primary content`.
+- Partial scaffold docs preserve completed human sections: covered by `mergeAnalyzeProjectDoc preserves completed human sections in partial scaffold`.
+- Human docs preserve human text: covered by `mergeAnalyzeProjectDoc preserves human docs and replaces existing analyze-project block`.
+- Existing analyze-project block is replaced in place: covered by unit test and provider/review command tests.
+- Context-prep scaffold does not remain confusing primary content: covered by `mergeAnalyzeProjectDoc removes scaffold context-prep block when applying analyze-project content`.
+- Same input/proposal is stable: covered by `mergeAnalyzeProjectDoc is idempotent for the same proposal`.
+- Write plan items include classification/strategy metadata: covered by `write plan preserves human content and snapshot manifest records hashes`.
+
+## Risks / Follow-ups
+
+- Slice 02 must wire this metadata into JSON/output and strict visible-placeholder validation.
+- Slice 03 must add the nika-erp style fixture and user-facing docs/output polish.

package/specs/quiver-v56-analyze-project-usable-doc-merge/slices/slice-01-document-classification-merge-engine/EXECUTION_BRIEF.md

@@ -0,0 +1,59 @@
+# EXECUTION_BRIEF - slice-01 Document Classification + Merge Engine
+
+## Objective
+
+Implement the deterministic merge engine for analyze-project docs.
+
+## Context
+
+The current `mergeManagedBlock` preserves the whole document and appends/replaces only the `quiver:analyze-project` block. This leaves scaffold placeholders visible above generated content. Slice 01 must solve the core merge contract before any CLI/output integration.
+
+## Scope
+
+- Add explicit critical placeholder detection for EN/ES Quiver scaffold text.
+- Add classification for existing docs.
+- Preserve parseable frontmatter.
+- Replace scaffold primary content with proposed Markdown.
+- Preserve human content.
+- Replace existing `quiver:analyze-project` block idempotently.
+- Remove or supersede scaffold-only `quiver:context-prep` blocks.
+- Add merge metadata to write plan items.
+
+## Acceptance Criteria
+
+- Scaffold docs no longer keep critical placeholders as primary visible content.
+- Partial scaffold docs preserve human-completed sections.
+- Human docs preserve human text.
+- Existing analyze-project block is replaced in place.
+- Context-prep scaffold does not remain as confusing primary content.
+- Same input/proposal produces stable output across repeated merges.
+- Unit tests cover the above.
+
+## Expected Files
+
+- `src/create-quiver/lib/ai/analyze-project-docs.js`
+- `tests/lib/ai-analyze-project-docs.test.js`
+- `specs/quiver-v56-analyze-project-usable-doc-merge/**`
+
+## Validation
+
+```bash
+node --test tests/lib/ai-analyze-project-docs.test.js
+node bin/create-quiver.js spec validate specs/quiver-v56-analyze-project-usable-doc-merge --strict
+git diff --check
+```
+
+## Completion Checklist
+
+- Classification helpers implemented and exported for tests.
+- Merge engine replaces scaffold primary content safely.
+- Merge engine preserves human content.
+- Idempotency tests pass.
+- Slice closure brief records validation evidence.
+
+## Constraints
+
+- Do not change provider schema.
+- Do not widen the analyze-project doc path allowlist.
+- Do not change CLI output in this slice except what write plan metadata naturally exposes to tests.
+- Do not implement post-write strict placeholder validation here; that belongs to Slice 02.