create-quiver 0.17.4 → 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

@@ -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

@@ -147,6 +147,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 +168,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.
@@ -223,6 +233,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:
 
@@ -252,6 +263,8 @@ Evidencia esperada:
 - `--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:
 

package/package.json

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

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.

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

@@ -0,0 +1,71 @@
+{
+  "slice_id": "slice-01-document-classification-merge-engine",
+  "ticket": "QUIVER-56-01",
+  "type": "feature",
+  "title": "Document Classification + Merge Engine",
+  "objective": "Implement deterministic document classification and merge behavior for analyze-project docs without integrating every CLI path yet.",
+  "description": "Adds a shared merge engine that classifies existing docs, replaces scaffold placeholders when safe, preserves human content, consolidates managed analyze-project blocks, handles context-prep scaffolds, and records merge metadata in the write plan.",
+  "git": {
+    "branch_type": "feature",
+    "base_branch": "main",
+    "branch_slug": "v56-doc-classification-merge-engine",
+    "branch_name": "feature/QUIVER-56-01-v56-doc-classification-merge-engine"
+  },
+  "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/**"
+  ],
+  "expected_read_paths": [
+    "src/create-quiver/lib/ai/analyze-project-docs.js",
+    "src/create-quiver/lib/ai/analyze-project-validation.js",
+    "tests/lib/ai-analyze-project-docs.test.js",
+    "specs/quiver-v56-analyze-project-usable-doc-merge/SPEC.md"
+  ],
+  "allowed_write_paths": [
+    "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/**"
+  ],
+  "depends_on": [],
+  "parallel_safe": "never",
+  "parallel_safe_reason": "This slice defines the shared merge contract that every later integration path must use.",
+  "must": [
+    "Classify docs as scaffold, partial_scaffold, human_content, managed_only, mixed, or unknown.",
+    "Detect critical placeholders in English and Spanish using explicit known patterns only.",
+    "Preserve parseable frontmatter.",
+    "Replace scaffold primary content with proposed content.",
+    "Preserve human content and avoid deleting significant non-placeholder text.",
+    "Replace existing analyze-project block instead of duplicating it.",
+    "Handle context-prep scaffold blocks so they do not remain as confusing primary content.",
+    "Expose merge metadata on write plan items.",
+    "Keep the merge idempotent for the same input and proposal."
+  ],
+  "not_included": [
+    "CLI output copy changes.",
+    "Post-write strict validation changes.",
+    "Review selector changes.",
+    "Saved proposal merge-plan persistence.",
+    "Live nika-erp smoke."
+  ],
+  "acceptance": [
+    "A Quiver scaffold CONTEXTO.md with Spanish placeholders is replaced as primary visible content.",
+    "A partial scaffold preserves completed human sections and replaces placeholder sections.",
+    "Human content remains present after merge.",
+    "Existing analyze-project block is replaced, not duplicated.",
+    "Context-prep scaffold content is removed or superseded when analyze-project content is applied.",
+    "Two consecutive merges with the same proposal are stable.",
+    "Write plan items include classification and strategy metadata."
+  ],
+  "tests": [
+    "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"
+  ],
+  "estimated_hours": 5,
+  "actual_hours": 5,
+  "status": "completed",
+  "blocked_reason": null,
+  "started_at": "2026-06-17T00:00:00.000Z",
+  "completed_at": "2026-06-17T00:00:00.000Z"
+}

package/specs/quiver-v56-analyze-project-usable-doc-merge/slices/slice-02-apply-integration-validation-contract/CLOSURE_BRIEF.md

@@ -0,0 +1,30 @@
+# CLOSURE_BRIEF - slice-02 Apply Integration + Validation Contract
+
+## Status
+
+Completed.
+
+## Summary
+
+Integrated the Slice 01 merge engine metadata into analyze-project apply, saved proposal, review, JSON, proposal manifest, write manifest, and post-write validation paths.
+
+Key outcomes:
+
+- Live auto-apply and `apply --run` continue to use the same `buildAnalyzeProjectWritePlan` merge engine.
+- JSON/write-plan summaries now include `merge_report`.
+- Saved proposal manifests now include a `merge_plan` with merge strategy metadata.
+- Write manifests now persist per-action `merge_report`.
+- Review output continues to show the final post-merge diff preview.
+- Post-write validation now checks primary visible content and makes `--strict` fail if critical scaffold placeholders remain outside managed blocks.
+
+## Evidence
+
+- `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`
+
+## Validation
+
+Passed.

package/specs/quiver-v56-analyze-project-usable-doc-merge/slices/slice-02-apply-integration-validation-contract/EXECUTION_BRIEF.md

@@ -0,0 +1,39 @@
+# EXECUTION_BRIEF - slice-02 Apply Integration + Validation Contract
+
+## Context
+
+Slice 02 depends on the Slice 01 merge engine and wires it into every analyze-project write path.
+
+## Objective
+
+Integrate the Slice 01 merge engine across all analyze-project write paths and validation reports.
+
+## Acceptance Criteria
+
+- Live auto-apply and `apply --run` use the same merge logic.
+- `--save-proposal` persists merge metadata or final estimated diff.
+- `--review` shows final post-merge diff.
+- `--json` includes merge strategy/warnings without breaking existing fields.
+- `--strict` fails on critical visible placeholders.
+
+## Constraints
+
+- Do not change provider schema.
+- Do not widen path allowlist.
+- Do not implement final nika-erp smoke here.
+
+## Validation
+
+```bash
+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 bin/create-quiver.js spec validate specs/quiver-v56-analyze-project-usable-doc-merge --strict
+git diff --check
+```
+
+## Completion Checklist
+
+- Live apply and apply --run use the same merge engine.
+- JSON reports expose merge metadata without breaking existing fields.
+- Strict validation handles critical visible placeholders.
+- Review diff reflects final post-merge content.