create-quiver 0.17.4 → 0.17.6

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

@@ -139,6 +139,13 @@ Opciones de aplicacion:
 - `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.
 
+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:
 
 ```bash

package/docs/TROUBLESHOOTING.md

@@ -131,6 +131,58 @@ 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` falla con `evidence-not-selected`
+
+### Síntoma
+
+El comando:
+
+```bash
+npx --yes create-quiver@latest ai analyze-project --deep --provider codex --model gpt-5.5
+```
+
+falla con un mensaje como:
+
+```text
+provider analysis JSON failed evidence validation
+evidence-not-selected
+```
+
+### Explicación
+
+El provider citó una ruta que no estaba dentro de la muestra enviada. Quiver mantiene esa validación porque evita que el modelo afirme cosas usando archivos que no leyó.
+
+En versiones actuales, Quiver clasifica esas rutas antes de sugerir un fix:
+
+- rutas seguras omitidas por presupuesto pueden recomendar `--max-files` o `--max-bytes` mayores;
+- tests omitidos pueden recomendar `--include-tests`;
+- DB/schema omitidos pueden recomendar `--include-db`;
+- `.env`, secretos, `.git`, `.quiver`, dependencias, caches, dumps, binarios y outputs generados no se recomiendan;
+- `.env.example` se trata como metadata/redacted, no como contenido seguro completo.
+
+### Qué hacer
+
+Usá el comando exacto que Quiver imprime debajo de `Recommended fix` o `Solucion recomendada`. Por ejemplo:
+
+```bash
+npx --yes create-quiver@latest ai analyze-project --deep --max-files 120 --max-bytes 500000 --provider codex --model gpt-5.5
+```
+
+Si Quiver no puede recomendar un aumento seguro porque se exceden los caps o la evidencia no debe enviarse, inspeccioná la muestra y acotá el scope:
+
+```bash
+npx --yes create-quiver@latest ai analyze-project --deep --dry-run --json
+npx --yes create-quiver@latest ai analyze-project --deep --scope apps/web --provider codex --model gpt-5.5
+```
+
+La auditoría queda en:
+
+```text
+.quiver/runs/run-.../validation/analyze-project-validation.json
+```
+
+Ese manifest incluye `recovery`, con clasificación de rutas, presupuesto calculado, comando sugerido y warnings.
+
 ## `ai analyze-project` no completa `docs/CONTEXTO.md` ni crea `docs/ARCHITECTURE.md`
 
 ### Síntoma
@@ -147,6 +199,14 @@ los docs finales siguen con placeholders o falta `docs/ARCHITECTURE.md`.
 
 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
 
 Revisá el error mostrado y los artifacts del run. Los caminos seguros son:
@@ -160,3 +220,5 @@ npx --yes create-quiver@latest ai analyze-project apply --run <run-id>
 - 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

@@ -206,6 +206,16 @@ 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,6 +226,7 @@ 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`.
+- Si el proveedor cita evidencia fuera de la muestra seleccionada, Quiver clasifica esas rutas, no recomienda incluir secretos ni binarios, y muestra una `Recommended fix` / `Solucion recomendada` con un comando seguro cuando corresponde.
 - 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.
@@ -223,6 +234,7 @@ Garantías del flujo con proveedor:
 - `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.
+- El write manifest guarda `merge_report` por archivo y el proposal manifest guarda `merge_plan` para auditoría.
 
 Benchmark recomendado:
 
@@ -249,9 +261,12 @@ Evidencia esperada:
 - `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, 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.
+- Si el error es `evidence-not-selected`, el validation manifest incluye un bloque `recovery` con clasificación de rutas, presupuesto calculado, warnings y comando recomendado. Por ejemplo, si el provider citó tests omitidos, Quiver puede sugerir `--include-tests`; si faltó presupuesto seguro, puede sugerir `--max-files` y `--max-bytes` mayores. Si la evidencia es `.env`, dependencias, caches, dumps o binarios, no la recomienda.
 - `--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:
 
@@ -270,6 +285,7 @@ Rollback de release:
 | `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 analyze-project --deep --max-files 120 --max-bytes 500000 --provider codex --model gpt-5.5` | Ejemplo de rerun cuando Quiver recomienda ampliar una muestra segura después de `evidence-not-selected`. Usá el comando exacto que imprime el error. |
 | `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. |
 | `npx --yes create-quiver@latest ai prepare-context --with-planner --dry-run` | Previsualiza una propuesta docs-only generada por el planner sin escribir archivos. |

package/docs/workflows/existing-project-ai-quiver-setup.md

@@ -108,7 +108,6 @@ Archivos que puede crear o actualizar:
 ```bash
 npx --yes create-quiver@latest ai analyze-project \
   --deep \
-  --review \
   --provider codex \
   --model gpt-5.5
 ```

package/docs/workflows/existing-project.md

@@ -98,6 +98,7 @@ Qué hace:
 - 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;
+- si el provider cita evidencia fuera de la muestra, clasifica esas rutas y muestra una solución recomendada con `--include-tests`, `--include-db`, `--max-files` o `--max-bytes` solo cuando sea seguro;
 - si la propuesta final no es válida, falla sin escribir docs finales.
 
 Si preferís separar generación y aplicación:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-quiver",
-  "version": "0.17.4",
+  "version": "0.17.6",
   "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

@@ -610,6 +610,7 @@
     { "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 --max-files 120 --max-bytes 500000 --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" },

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.

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

@@ -0,0 +1,61 @@
+## Title
+
+QUIVER-56-01 document classification merge engine
+
+## Summary
+
+Implements deterministic document classification and merge behavior for analyze-project docs.
+
+## PR Policy
+
+Individual PR required because this changes CLI write behavior internals.
+
+## Scope
+
+Slice 01 only.
+
+## 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/**`
+
+## How to Test (DETAILED - REQUIRED)
+
+### Required Environment
+
+Node.js/npm.
+
+### Worktree Access
+
+Use the slice branch.
+
+### Run the Project
+
+No dev server required.
+
+### Use Cases
+
+Validate scaffold replacement, partial scaffold preservation, human content preservation, context-prep cleanup, and idempotency.
+
+### Technical Verification
+
+```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
+```
+
+## Evidence
+
+- `node --test tests/lib/ai-analyze-project-docs.test.js`: passed.
+- `node bin/create-quiver.js spec validate specs/quiver-v56-analyze-project-usable-doc-merge --strict`: passed.
+- `git diff --check`: passed.
+
+## Rollback
+
+Revert the PR.
+
+## Risks / Notes
+
+Later slices integrate this engine into all apply/review/strict CLI paths.