create-quiver 0.17.3 → 0.17.5

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.

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`;
 }
@@ -2886,7 +2921,11 @@ async function runAnalyzeProject(repoRoot, options = {}) {
     run_status_path: path.join('.quiver', 'runs', auditRunId, 'status.json').split(path.sep).join('/'),
     selected_context_manifest: selectedContextManifest,
   };
-  const needsDocProposal = options.applyDocs === true || options.saveProposal === true || options.review === true;
+  const autoApplyDocs = options.applyDocs !== true
+    && options.saveProposal !== true
+    && options.review !== true
+    && options.json !== true;
+  const needsDocProposal = autoApplyDocs || options.applyDocs === true || options.saveProposal === true || options.review === true;
   const docProposal = needsDocProposal ? buildAnalyzeProjectDocProposal(parsed.analysis) : null;
   const docWritePlan = docProposal ? buildAnalyzeProjectWritePlan(repoRoot, docProposal) : [];
   const docActionContext = {
@@ -2911,6 +2950,15 @@ async function runAnalyzeProject(repoRoot, options = {}) {
     return emitAnalyzeProjectApplyReport(applyReport, options);
   }
 
+  if (autoApplyDocs) {
+    const applyReport = applyAnalyzeProjectDocProposalReport(repoRoot, {
+      ...docActionContext,
+      allowDirtyDocs: true,
+      interactiveAction: 'auto-apply',
+    });
+    return emitAnalyzeProjectApplyReport(applyReport, options);
+  }
+
   if (options.applyDocs === true) {
     return runAnalyzeProjectInteractiveApplySelector({
       report: completedReport,

package/src/create-quiver/index.js

@@ -230,7 +230,7 @@ const COMMAND_HELP_GROUPS = [
       ['ai active-slice status|reconcile', 'Inspect or dry-run reconcile local active-slice state from every supported source.'],
       ['ai status', 'Show current AI lifecycle phase, approved versions, blockers, and next command.'],
       ['ai resume', 'Resume guidance from the last valid lifecycle phase without chat memory.'],
-      ['ai analyze-project', 'Analyze a bounded project sample and generate audited documentation proposals.'],
+      ['ai analyze-project', 'Analyze a bounded project sample and apply validated documentation updates.'],
       ['ai onboard', 'Run or print the planner onboarding prompt with a token-aware context pack.'],
       ['ai prepare-context', 'Preview or write docs-only AI context updates with assumptions and risks.'],
       ['ai agent set|list|show|doctor|repair', 'Manage, diagnose, and dry-run repair planner, executor, reviewer, and doctor provider profiles without secrets.'],