create-quiver 0.17.4 → 0.17.6

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.

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

@@ -0,0 +1,62 @@
+## Title
+
+QUIVER-56-02 apply integration validation contract
+
+## Summary
+
+Integrates the merge engine into all analyze-project write paths and post-write validation.
+
+## PR Policy
+
+Individual PR required.
+
+## Scope
+
+Slice 02 only.
+
+## Files
+
+See `slice.json`.
+
+## 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
+
+Live apply, saved proposal apply, review diff, JSON output, strict validation.
+
+### Technical Verification
+
+```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
+```
+
+## Evidence
+
+- `node --test tests/commands/ai-analyze-project-provider.test.js tests/commands/ai-analyze-project-review.test.js`: passed.
+- `node --test tests/lib/ai-analyze-project-docs.test.js tests/lib/ai-analyze-project-validation.test.js`: passed.
+- `node --test tests/lib/ai-analyze-project-proposal.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
+
+Depends on Slice 01.

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

@@ -0,0 +1,80 @@
+{
+  "slice_id": "slice-02-apply-integration-validation-contract",
+  "ticket": "QUIVER-56-02",
+  "type": "feature",
+  "title": "Apply Integration + Validation Contract",
+  "objective": "Integrate the merge engine across every analyze-project write path and validate visible output quality.",
+  "description": "Uses the shared merge engine in live auto-apply, --apply-docs, --save-proposal, --review, and apply --run paths; extends post-write validation for primary visible placeholders and exposes stable JSON merge metadata.",
+  "git": {
+    "branch_type": "feature",
+    "base_branch": "main",
+    "branch_slug": "v56-apply-integration-validation",
+    "branch_name": "feature/QUIVER-56-02-v56-apply-integration-validation"
+  },
+  "files": [
+    "src/create-quiver/commands/ai.js",
+    "src/create-quiver/lib/ai/analyze-project-apply.js",
+    "src/create-quiver/lib/ai/analyze-project-docs.js",
+    "src/create-quiver/lib/ai/analyze-project-proposal.js",
+    "src/create-quiver/lib/ai/analyze-project-validation.js",
+    "tests/commands/ai-analyze-project*.test.js",
+    "tests/lib/ai-analyze-project-*.test.js",
+    "specs/quiver-v56-analyze-project-usable-doc-merge/**"
+  ],
+  "expected_read_paths": [
+    "src/create-quiver/commands/ai.js",
+    "src/create-quiver/lib/ai/analyze-project-apply.js",
+    "src/create-quiver/lib/ai/analyze-project-proposal.js",
+    "src/create-quiver/lib/ai/analyze-project-validation.js",
+    "specs/quiver-v56-analyze-project-usable-doc-merge/slices/slice-01-document-classification-merge-engine/CLOSURE_BRIEF.md"
+  ],
+  "allowed_write_paths": [
+    "src/create-quiver/commands/ai.js",
+    "src/create-quiver/lib/ai/analyze-project-apply.js",
+    "src/create-quiver/lib/ai/analyze-project-docs.js",
+    "src/create-quiver/lib/ai/analyze-project-proposal.js",
+    "src/create-quiver/lib/ai/analyze-project-validation.js",
+    "tests/commands/ai-analyze-project-provider.test.js",
+    "tests/commands/ai-analyze-project-review.test.js",
+    "tests/lib/ai-analyze-project-docs.test.js",
+    "tests/lib/ai-analyze-project-validation.test.js",
+    "specs/quiver-v56-analyze-project-usable-doc-merge/**"
+  ],
+  "depends_on": [
+    "slice-01-document-classification-merge-engine"
+  ],
+  "parallel_safe": "never",
+  "parallel_safe_reason": "All write paths must share the same merge engine; integrating before slice 01 is complete would duplicate logic.",
+  "must": [
+    "Use the same merge engine in live apply and apply --run.",
+    "Expose merge metadata in JSON apply reports without removing existing fields.",
+    "Make --save-proposal include merge-plan metadata or final diff preview.",
+    "Make --review show final post-merge diff.",
+    "Detect critical placeholders in primary visible content.",
+    "Make --strict fail when critical visible placeholders remain."
+  ],
+  "not_included": [
+    "Final docs/troubleshooting polish.",
+    "Live provider smoke against nika-erp.",
+    "Changing provider prompt semantics."
+  ],
+  "acceptance": [
+    "Live auto-apply and apply --run produce the same result with the same proposal.",
+    "--json includes merge strategy and warnings.",
+    "--strict fails on critical visible placeholders.",
+    "--save-proposal artifacts include enough merge metadata to preview the final write.",
+    "--review diff reflects the final post-merge write."
+  ],
+  "tests": [
+    "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"
+  ],
+  "estimated_hours": 6,
+  "actual_hours": 3,
+  "status": "completed",
+  "blocked_reason": null,
+  "started_at": "2026-06-17",
+  "completed_at": "2026-06-17"
+}

package/specs/quiver-v56-analyze-project-usable-doc-merge/slices/slice-03-cli-docs-real-fixture-smoke/CLOSURE_BRIEF.md

@@ -0,0 +1,29 @@
+# CLOSURE_BRIEF - slice-03 CLI UX + Docs + Real Fixture Smoke
+
+## Status
+
+Completed.
+
+## Summary
+
+Finished the user-facing hardening for analyze-project usable doc merges.
+
+Key outcomes:
+
+- Human apply/save/review output now includes compact `Merge decisions`.
+- Troubleshooting explains how upgraded users recover docs that still show scaffold placeholders.
+- Command reference documents the deterministic merge contract and audit manifests.
+- CLI UX guide documents the merge feedback contract.
+- Changelog records the user-visible behavior change and nika-erp style regression coverage.
+- Deterministic provider test covers a nika-erp style `CONTEXTO.md` with visible placeholders, an old `quiver:context-prep` block, and `NIKA_ERP`/`stockflow`/`StockFlow` naming conflict signals.
+
+## Evidence
+
+- `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`
+
+## Validation
+
+Passed.

package/specs/quiver-v56-analyze-project-usable-doc-merge/slices/slice-03-cli-docs-real-fixture-smoke/EXECUTION_BRIEF.md

@@ -0,0 +1,32 @@
+# EXECUTION_BRIEF - slice-03 CLI UX + Docs + Real Fixture Smoke
+
+## Context
+
+Slice 03 depends on the integrated apply behavior from Slice 02 and focuses on user-facing output, docs, and regression evidence.
+
+## Objective
+
+Finish the user-facing output, docs, and nika-erp regression coverage after Slice 02 integration.
+
+## Acceptance Criteria
+
+- Output reports merge strategies and warnings.
+- Docs/troubleshooting explain how to fix old placeholder-heavy docs.
+- nika-erp style fixture proves final visible docs are usable.
+- Name conflicts are reported.
+
+## Validation
+
+```bash
+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
+```
+
+## Completion Checklist
+
+- Output copy is compact and actionable.
+- Docs and troubleshooting are updated.
+- Command reference is synchronized.
+- nika-erp style fixture proves visible placeholders are removed.

package/specs/quiver-v56-analyze-project-usable-doc-merge/slices/slice-03-cli-docs-real-fixture-smoke/pr.md

@@ -0,0 +1,61 @@
+## Title
+
+QUIVER-56-03 CLI docs real fixture smoke
+
+## Summary
+
+Adds user-facing output, docs, and fixture smoke evidence for the usable doc merge behavior.
+
+## PR Policy
+
+Individual PR required.
+
+## Scope
+
+Slice 03 only.
+
+## Files
+
+See `slice.json`.
+
+## 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
+
+CLI output, docs, troubleshooting, deterministic nika-erp style fixture.
+
+### Technical Verification
+
+```bash
+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
+```
+
+## Evidence
+
+- `node --test tests/commands/ai-analyze-project-provider.test.js tests/commands/cli-contract.test.js`: passed.
+- `npm run docs:check`: 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
+
+Depends on Slice 02.

package/specs/quiver-v56-analyze-project-usable-doc-merge/slices/slice-03-cli-docs-real-fixture-smoke/slice.json

@@ -0,0 +1,79 @@
+{
+  "slice_id": "slice-03-cli-docs-real-fixture-smoke",
+  "ticket": "QUIVER-56-03",
+  "type": "hardening",
+  "title": "CLI UX + Docs + Real Fixture Smoke",
+  "objective": "Make the new merge behavior understandable to users and prove the nika-erp regression is covered.",
+  "description": "Updates human output, docs, troubleshooting, changelog guidance, and deterministic nika-erp style fixture/smoke evidence.",
+  "git": {
+    "branch_type": "feature",
+    "base_branch": "main",
+    "branch_slug": "v56-cli-docs-real-fixture-smoke",
+    "branch_name": "feature/QUIVER-56-03-v56-cli-docs-real-fixture-smoke"
+  },
+  "files": [
+    "src/create-quiver/commands/ai.js",
+    "src/create-quiver/lib/i18n/messages/en.js",
+    "src/create-quiver/lib/i18n/messages/es.js",
+    "tests/commands/ai-analyze-project*.test.js",
+    "tests/fixtures/analyze-project/**",
+    "docs/CLI_UX_GUIDE.md",
+    "docs/TROUBLESHOOTING.md",
+    "docs/reference/commands.md",
+    "CHANGELOG.md",
+    "specs/quiver-v56-analyze-project-usable-doc-merge/**"
+  ],
+  "expected_read_paths": [
+    "specs/quiver-v56-analyze-project-usable-doc-merge/slices/slice-02-apply-integration-validation-contract/CLOSURE_BRIEF.md",
+    "docs/TROUBLESHOOTING.md",
+    "docs/reference/commands.md"
+  ],
+  "allowed_write_paths": [
+    "src/create-quiver/commands/ai.js",
+    "src/create-quiver/lib/i18n/messages/en.js",
+    "src/create-quiver/lib/i18n/messages/es.js",
+    "tests/commands/ai-analyze-project-provider.test.js",
+    "tests/fixtures/analyze-project/**",
+    "docs/CLI_UX_GUIDE.md",
+    "docs/TROUBLESHOOTING.md",
+    "docs/reference/commands.md",
+    "CHANGELOG.md",
+    "specs/quiver-v56-analyze-project-usable-doc-merge/**"
+  ],
+  "depends_on": [
+    "slice-02-apply-integration-validation-contract"
+  ],
+  "parallel_safe": "after_dependencies",
+  "parallel_safe_reason": "Docs can draft after Slice 01, but final fixture smoke and output assertions depend on Slice 02.",
+  "must": [
+    "Human output reports replaced scaffold, preserved human content, placeholder counts, conflicts, snapshot, and manifest paths.",
+    "Troubleshooting explains re-running analyze-project after upgrading.",
+    "Docs explain the merge contract without overpromising.",
+    "Deterministic fixture covers NIKA_ERP scaffold plus stockflow/StockFlow conflict and old context-prep block.",
+    "Evidence proves final CONTEXTO.md has no critical visible placeholders."
+  ],
+  "not_included": [
+    "Provider prompt redesign.",
+    "Publishing npm.",
+    "Product repository changes."
+  ],
+  "acceptance": [
+    "CLI output is compact and actionable.",
+    "Docs and command reference are synchronized.",
+    "nika-erp style fixture passes without visible scaffold placeholders.",
+    "Name conflict warning is visible.",
+    "Release smoke guidance is updated."
+  ],
+  "tests": [
+    "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"
+  ],
+  "estimated_hours": 4,
+  "actual_hours": 3,
+  "status": "completed",
+  "blocked_reason": null,
+  "started_at": "2026-06-17",
+  "completed_at": "2026-06-17"
+}

package/specs/quiver-v57-evidence-budget-recovery-ux/EVIDENCE_REPORT.md

@@ -0,0 +1,27 @@
+# Evidence Report - Quiver v57 Evidence Budget Recovery UX
+
+## Validation Log
+
+- PASS `node --test tests/lib/ai-analyze-project-recovery.test.js`
+- PASS `node bin/create-quiver.js spec validate specs/quiver-v57-evidence-budget-recovery-ux --strict`
+- Completed slice: `slice-01-recovery-contract-security-classifier`
+- Completed slice: `slice-02-budget-command-recommendation`
+- PASS `node --test tests/commands/ai-analyze-project-provider.test.js`
+- PASS `node --test tests/lib/i18n-catalog.test.js`
+- Completed slice: `slice-03-cli-json-i18n-output`
+- PASS `npm run docs:check`
+- Completed slice: `slice-04-integration-fixtures-docs-release-smoke`
+- PASS `node --test tests/lib/ai-analyze-project-recovery.test.js tests/commands/ai-analyze-project-provider.test.js tests/lib/ai-analyze-project-validation.test.js tests/lib/i18n-catalog.test.js`
+- PASS `node bin/create-quiver.js spec validate specs/quiver-v57-evidence-budget-recovery-ux --strict`
+- PASS `git diff --check`
+
+## Required Evidence Before Completion
+
+- Focused recovery unit tests. Completed for slice 01.
+- Budget and command recovery tests. Completed for slice 02.
+- Validation manifest compatibility tests. Completed for slice 03.
+- CLI output tests for English and Spanish. Completed for slice 03.
+- JSON recovery payload tests. Completed for slice 04 through `runAnalyzeProject --json` error payload coverage.
+- Sanitized nika-erp-style smoke. Covered by provider command fixture that reproduces omitted test evidence and metadata-only `.env.example` without private repo content.
+- Spec validation. Completed.
+- `git diff --check`. Completed.

package/specs/quiver-v57-evidence-budget-recovery-ux/EXECUTION_PLAN.md

@@ -0,0 +1,41 @@
+# Execution Plan - Quiver v57 Evidence Budget Recovery UX
+
+## Order
+
+1. `slice-01-recovery-contract-security-classifier`
+2. `slice-02-budget-command-recommendation`
+3. `slice-03-cli-json-i18n-output`
+4. `slice-04-integration-fixtures-docs-release-smoke`
+
+## Parallelism
+
+- Slice 01 is sequential and blocks everything else.
+- Slice 02 is sequential after Slice 01 because it consumes the classification contract.
+- Slice 03 is sequential after Slice 02 because it renders the recovery payload and must not recalculate safety or budget.
+- Slice 04 is final. Inside Slice 04, docs, release notes, and integration fixture work can be done in parallel once Slice 03 is complete.
+
+## PR Strategy
+
+- PR 1: Slice 01.
+- PR 2: Slice 02.
+- PR 3: Slice 03.
+- PR 4: Slice 04.
+
+## Validation Gates
+
+Each PR must run its focused tests plus:
+
+```bash
+git diff --check
+node bin/create-quiver.js spec validate specs/quiver-v57-evidence-budget-recovery-ux --strict
+```
+
+## Blocking Rule
+
+Do not start a later slice unless the previous slice has:
+
+- stable data contracts;
+- focused tests;
+- updated handoff status;
+- no unresolved safety ambiguity.
+