create-quiver 0.17.4 → 0.17.5

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/src/create-quiver/commands/ai.js

@@ -528,6 +528,7 @@ function summarizeAnalyzeProjectWritePlan(writePlan = []) {
     before_sha256: item.before_sha256,
     after_sha256: item.after_sha256,
     reason: item.reason,
+    merge_report: item.merge_report,
   }));
 }
 
@@ -545,14 +546,46 @@ function formatAnalyzeProjectSavedProposalReport(report = {}) {
     `Proposal summary: ${artifacts.proposal_markdown || 'none'}`,
     `Proposal diff: ${artifacts.proposal_diff || 'none'}`,
     `Manifest: ${artifacts.manifest || 'none'}`,
+  ];
+  lines.push(...formatAnalyzeProjectMergeSummary(report.write_plan));
+  lines.push(
     '',
     'Next commands:',
     `- npx create-quiver ai analyze-project apply --run ${report.run_id || '<run-id>'}`,
     '- npx create-quiver ai analyze-project --deep --apply-docs --provider <provider> --model <model>',
-  ];
+  );
   return `${lines.join('\n')}\n`;
 }
 
+function formatAnalyzeProjectMergeSummary(writePlan = []) {
+  const changed = (Array.isArray(writePlan) ? writePlan : []).filter((item) => item.action !== 'skip');
+  if (changed.length === 0) {
+    return [];
+  }
+
+  const lines = ['', 'Merge decisions:'];
+  for (const item of changed.slice(0, 10)) {
+    const merge = item.merge_report || {};
+    const details = [
+      merge.classification ? `class=${merge.classification}` : '',
+      merge.scaffold_replaced ? 'scaffold replaced' : '',
+      merge.human_content_preserved ? 'human preserved' : '',
+      merge.context_prep_removed ? 'context-prep removed' : '',
+      Array.isArray(merge.critical_placeholders) && merge.critical_placeholders.length > 0
+        ? `placeholders=${merge.critical_placeholders.length}`
+        : '',
+    ].filter(Boolean);
+    lines.push(`- ${item.path}: ${merge.strategy || 'unknown'}${details.length > 0 ? ` (${details.join(', ')})` : ''}`);
+    for (const warning of Array.isArray(merge.warnings) ? merge.warnings.slice(0, 2) : []) {
+      lines.push(`  warning: ${warning}`);
+    }
+  }
+  if (changed.length > 10) {
+    lines.push(`- ... ${changed.length - 10} more doc merge decision${changed.length - 10 === 1 ? '' : 's'}`);
+  }
+  return lines;
+}
+
 function formatAnalyzeProjectPostWriteValidation(validation) {
   if (!validation) {
     return [];
@@ -592,6 +625,7 @@ function formatAnalyzeProjectReviewPlan({ writePlan, reviewPath, snapshot, writt
   for (const item of writePlan || []) {
     lines.push(`- ${item.path}: ${item.action}${item.reason ? ` (${item.reason})` : ''}`);
   }
+  lines.push(...formatAnalyzeProjectMergeSummary(writePlan));
   lines.push('', 'Final diff:');
   lines.push(...formatAnalyzeProjectDiffPreview(writePlan || []));
   lines.push('', 'Confirmation required before writing.');
@@ -617,6 +651,7 @@ function formatAnalyzeProjectApplyReport(report = {}) {
     `Proposal manifest: ${artifacts.manifest || 'none'}`,
     `Write manifest: ${writeManifest.path || 'none'}`,
   ].filter(Boolean);
+  lines.push(...formatAnalyzeProjectMergeSummary(report.write_plan));
   lines.push(...formatAnalyzeProjectPostWriteValidation(report.post_write_validation));
   return `${lines.join('\n')}\n`;
 }