create-quiver 0.17.2 → 0.17.3

package/specs/quiver-v55-analyze-project-doc-apply-ux/SPEC.md

@@ -0,0 +1,276 @@
+# Quiver v55 - Analyze Project Doc Apply UX
+
+**Date:** 2026-06-12
+**Status:** Approved, not implemented
+**Source:** User-approved requirement, technical plan, production review, and stricter slice-cut review.
+
+## Problem
+
+`ai analyze-project --deep --provider codex --model gpt-5.5` now generates valid, auditable doc proposals, but users still do not get an easy path to apply those proposals. Without `--review`, no final docs are written. With `--review`, Quiver opens a large JSON proposal in `$VISUAL` or `$EDITOR`, which is safe but confusing for non-technical users, especially when the editor is `vim` or another console editor.
+
+The command needs a simpler product-grade flow that explains choices, supports English and Spanish, preserves auditability, and avoids accidental documentation writes.
+
+## Objective
+
+Add a safe, bilingual, user-friendly documentation application workflow for `ai analyze-project`:
+
+```bash
+npx create-quiver ai analyze-project --deep --apply-docs --provider codex --model gpt-5.5
+npx create-quiver ai analyze-project --deep --apply-docs --yes --provider codex --model gpt-5.5
+npx create-quiver ai analyze-project --deep --save-proposal --provider codex --model gpt-5.5
+npx create-quiver ai analyze-project apply --run <run-id>
+```
+
+The implementation must separate proposal generation, proposal persistence, apply logic, and interactive UX so future teams can evolve each part without duplicating write-gate logic.
+
+## Scope
+
+### Included
+
+- New CLI contract for `--apply-docs`, `--save-proposal`, `--diff`, `--yes`, `--allow-dirty-docs`, and `ai analyze-project apply --run <run-id>`.
+- Proposal artifact contract under `.quiver/runs/<run-id>/proposal/`.
+- Non-interactive save proposal flow.
+- Non-interactive apply flow with `--apply-docs --yes`.
+- Interactive TTY selector with explained options and dynamic recommendation.
+- Apply saved proposal flow with stale/dirty validation.
+- English and Spanish UX copy.
+- Docs, command matrix, and release smoke guidance.
+
+### Excluded
+
+- Changing the provider prompt semantics.
+- Relaxing the analyze-project schema.
+- Writing product code in analyzed repositories.
+- Generating specs automatically from project analysis.
+- Removing or breaking the existing `--review` editor flow.
+- Requiring live provider calls in CI.
+
+## Functional Requirements
+
+1. Normal provider mode without apply flags must clearly say that docs were not written and list the next commands.
+2. `--save-proposal` must generate and save a validated normalized proposal without writing final docs.
+3. `--apply-docs --yes` must apply validated doc updates without prompting and must be safe for automation.
+4. `--apply-docs` in TTY must show a selector with option descriptions.
+5. The selector must include:
+   - Apply documentation;
+   - View diff;
+   - Save proposal;
+   - Edit proposal;
+   - Cancel.
+6. The recommended option must be first and must change to View diff when docs are dirty or existing content creates higher overwrite risk.
+7. `--review` must preserve current behavior and be documented as advanced edit proposal mode.
+8. `ai analyze-project apply --run <run-id>` must apply a saved proposal without running a provider.
+9. `apply --run` must revalidate the saved proposal and current docs before writing.
+10. `--run latest` may be supported only in TTY and never with `--yes`.
+
+## Non-Functional Requirements
+
+- All writes must be audited.
+- All docs writes must use the existing safe write plan, snapshot, and post-write validation path.
+- Human console output must stay compact.
+- Full diff/proposal details must be saved as artifacts.
+- `--json` output must remain parseable and must never include interactive prompts.
+- The feature must work in English and Spanish.
+- Commands, flags, and paths must not be translated.
+
+## CLI Contract
+
+| Command | Behavior |
+|---|---|
+| `ai analyze-project --deep --provider ...` | Generates analysis and audited provider artifacts. Does not write final docs. Explains next apply/save commands. |
+| `ai analyze-project --deep --save-proposal --provider ...` | Runs provider, validates/repairs analysis, saves normalized proposal artifacts, writes no final docs. |
+| `ai analyze-project --deep --save-proposal --json --provider ...` | Same as above with clean JSON result. |
+| `ai analyze-project --deep --apply-docs --provider ...` | In TTY, shows explained selector. In no-TTY, fails unless `--yes`. |
+| `ai analyze-project --deep --apply-docs --yes --provider ...` | Applies valid docs directly after safety checks. |
+| `ai analyze-project --deep --apply-docs --yes --json --provider ...` | Applies valid docs and emits machine-readable result. |
+| `ai analyze-project --deep --review --provider ...` | Existing advanced editor review flow. |
+| `ai analyze-project apply --run <run-id>` | Applies saved proposal without provider execution. |
+
+## Flag Rules
+
+- `--apply-docs` and `--review` are mutually exclusive.
+- `--dry-run` is incompatible with `--apply-docs`, `--save-proposal`, and `apply --run`.
+- `--json + --save-proposal` is allowed.
+- `--json + --apply-docs` is allowed only with `--yes`.
+- `--json + --review` is prohibited.
+- `--json` with an interactive selector is prohibited.
+- `--allow-dirty-docs` only affects docs target dirty checks; it never permits product code writes.
+
+## Proposal Artifact Contract
+
+Every saved proposal must live under:
+
+```text
+.quiver/runs/<run-id>/proposal/
+```
+
+Required files:
+
+```text
+analyze-project-doc-proposal.json
+analyze-project-doc-proposal.md
+analyze-project-doc-proposal.diff
+manifest.json
+```
+
+Required manifest fields:
+
+```json
+{
+  "schema_version": 1,
+  "kind": "quiver-analyze-project-doc-proposal",
+  "run_id": "run-...",
+  "created_at": "...",
+  "language": "en|es",
+  "provider": "codex",
+  "proposal_json": ".quiver/runs/.../proposal/analyze-project-doc-proposal.json",
+  "proposal_markdown": ".quiver/runs/.../proposal/analyze-project-doc-proposal.md",
+  "proposal_diff": ".quiver/runs/.../proposal/analyze-project-doc-proposal.diff",
+  "selected_context_manifest": ".quiver/runs/.../context/selected-context.json",
+  "repair_manifest": ".quiver/runs/.../repair/analyze-project-repair.json",
+  "doc_paths": [],
+  "doc_before_hashes": {},
+  "proposal_sha256": "...",
+  "events": []
+}
+```
+
+The write manifest must be separate:
+
+```text
+.quiver/runs/<run-id>/writes/analyze-project-doc-writes.json
+```
+
+It must include actions, before/after hashes, snapshot path, validation result, and partial-write status if an unexpected write failure occurs.
+
+## Interactive UX
+
+Spanish example:
+
+```text
+Analisis completado.
+La IA genero una propuesta de documentacion basada en el codigo del proyecto.
+
+Archivos propuestos:
+- docs/CONTEXTO.md
+- docs/AI_CONTEXT.md
+- docs/ARCHITECTURE.md
+
+Que queres hacer?
+
+> Aplicar documentacion (Recomendado)
+  Escribe los archivos propuestos usando merge seguro y snapshot previo.
+
+  Ver diff
+  Muestra los cambios antes de decidir si aplicarlos.
+
+  Guardar propuesta
+  Guarda la propuesta en .quiver/runs sin modificar docs finales.
+
+  Editar propuesta
+  Abre la propuesta en tu editor para modificarla manualmente.
+
+  Cancelar
+  No escribe documentacion final.
+```
+
+English example:
+
+```text
+Analysis completed.
+AI generated a documentation proposal from the project source code.
+
+Proposed files:
+- docs/CONTEXTO.md
+- docs/AI_CONTEXT.md
+- docs/ARCHITECTURE.md
+
+What do you want to do?
+
+> Apply documentation (Recommended)
+  Writes the proposed files using safe merge and a prior snapshot.
+
+  View diff
+  Shows the changes before deciding whether to apply them.
+
+  Save proposal
+  Saves the proposal under .quiver/runs without modifying final docs.
+
+  Edit proposal
+  Opens the proposal in your editor for manual changes.
+
+  Cancel
+  Does not write final documentation.
+```
+
+## Safety Rules
+
+- No final docs write if final JSON/proposal is invalid.
+- No final docs write if any proposed path is outside the allowlist.
+- No silent partial apply.
+- Dirty docs block `--yes` unless `--allow-dirty-docs` is passed.
+- In repos without Git, use hash/snapshot checks and warn that Git dirty detection is unavailable.
+- `apply --run` must revalidate the current repo state before writing.
+- A saved proposal with stale doc hashes must warn in TTY and block `--yes` unless explicitly allowed.
+
+## Slice Roadmap
+
+| Slice | Title | Status | Dependencies | Parallel Guidance |
+|---|---|---|---|---|
+| slice-01-cli-proposal-contract | CLI Contract + Proposal Artifact Contract | pending | none | sequential first |
+| slice-02-save-proposal-flow | Save Proposal Flow | pending | slice-01 | sequential after contract |
+| slice-03-noninteractive-apply-engine | Non-Interactive Apply Engine | pending | slice-01, slice-02 | sequential safety gate |
+| slice-04-interactive-apply-ux | Interactive Apply UX | pending | slice-03 | sequential UI over engine |
+| slice-05-apply-saved-proposal | Apply Saved Proposal | pending | slice-02, slice-03 | after apply engine |
+| slice-06-i18n-docs-release-smoke | i18n, Docs, Release Smoke | pending | slice-04, slice-05 | final |
+
+## Execution Order
+
+```text
+01
+└─ 02
+   └─ 03
+      ├─ 04
+      └─ 05
+         └─ 06
+```
+
+## Validation Strategy
+
+Deterministic gates:
+
+```bash
+node --test tests/commands/ai-analyze-project-review.test.js
+node --test tests/commands/ai-analyze-project-provider.test.js
+node --test tests/commands/ai-analyze-project.test.js
+node --test tests/lib/ai-analyze-project-validation.test.js
+node --test tests/lib/ai/analyze-project-repair.test.js
+npm run docs:check
+npm run schema:slice:check
+node bin/create-quiver.js spec validate specs/quiver-v55-analyze-project-doc-apply-ux --strict
+git diff --check
+```
+
+Release smoke must use a temporary copy or disposable branch of `nika-erp`, never the main working copy.
+
+## Risks
+
+- Applying proposals over stale docs can overwrite human edits.
+- Adding selector logic directly inside `ai.js` can increase CLI debt.
+- A broad `--yes` implementation can approve more than intended.
+- Diff output can become too large and repeat the original UX problem.
+- `apply --run latest` can apply the wrong proposal if not constrained.
+
+## Resolved Decisions
+
+- Implement three layers: Proposal Layer, Apply Layer, UX Layer.
+- Keep `--review` backward compatible.
+- Permit `--json` for non-interactive save/apply flows.
+- Do not require provider/model for `apply --run`.
+- Save proposal artifacts before any apply.
+
+## Open Questions
+
+- Exact human diff truncation limit should be chosen during implementation.
+- Exact stale proposal warning copy should be finalized with i18n keys.
+- Whether `--run latest` ships in v55 or is deferred should be decided during slice-05.

package/specs/quiver-v55-analyze-project-doc-apply-ux/STATUS.md

@@ -0,0 +1,29 @@
+# Status - Quiver v55 Analyze Project Doc Apply UX
+
+**Status:** Completed
+**Last updated:** 2026-06-12
+
+## Current State
+
+The requirement, acceptance criteria, technical plan, production review, and stricter slice-cut review are approved. All six slices have been implemented and validated.
+
+## Slice Status
+
+| Slice | Status | Notes |
+|---|---|---|
+| slice-01-cli-proposal-contract | completed | CLI flags, subcommand contract, help/docs, and proposal/write manifest schema are implemented and tested. |
+| slice-02-save-proposal-flow | completed | `--save-proposal` persists JSON, Markdown summary, diff, and manifest artifacts without final docs writes. |
+| slice-03-noninteractive-apply-engine | completed | `--apply-docs --yes` applies valid docs through proposal artifacts, dirty/stale preflight, snapshot, write manifest, and post-write validation. |
+| slice-04-interactive-apply-ux | completed | Plain TTY `--apply-docs` now shows an explained selector with apply, view diff, save, edit, and cancel actions routed through tested flows. |
+| slice-05-apply-saved-proposal | completed | `ai analyze-project apply --run <run-id>` applies saved proposals without provider execution after manifest/proposal revalidation and dirty/stale checks. |
+| slice-06-i18n-docs-release-smoke | completed | EN/ES help coverage, user docs, command matrix, troubleshooting, and safe nika-erp release smoke guidance are updated and validated. |
+
+## Blockers
+
+- None.
+
+## Next Command
+
+```bash
+npm run docs:check
+```

package/specs/quiver-v55-analyze-project-doc-apply-ux/slices/slice-01-cli-proposal-contract/CLOSURE_BRIEF.md

@@ -0,0 +1,47 @@
+# CLOSURE_BRIEF - slice-01 CLI proposal contract
+
+## Summary
+
+Completed. The CLI contract now recognizes the v55 doc-apply flags and `ai analyze-project apply --run <run-id>` without implementing the later save/apply flows.
+
+Implemented:
+
+- Parser support for `--apply-docs`, `--save-proposal`, `--diff`, and `--allow-dirty-docs`.
+- Parser support for `ai analyze-project apply --run <run-id>`.
+- Pre-provider contract failures for invalid flag combinations.
+- Runtime contract guards that prevent provider execution for future save/apply flows until later slices implement them.
+- Proposal/write manifest schema helpers in `analyze-project-proposal.js`.
+- Help/reference documentation for the new command surface.
+- Regression coverage for existing `--review` UX support.
+
+## Required Evidence
+
+- Parser/flag tests pass.
+- Invalid combination tests pass before provider execution.
+- Proposal manifest schema tests pass.
+- Existing `--review` tests still pass.
+- Docs and slice schema checks pass.
+
+## Validation
+
+Executed:
+
+```bash
+node --test tests/lib/ai-analyze-project-proposal.test.js
+node --test tests/commands/ai-analyze-project.test.js
+node --test tests/commands/cli-contract.test.js
+node --test tests/commands/parser-contract.test.js
+node --test tests/commands/ux-flags.test.js
+node --test tests/commands/ai-analyze-project-review.test.js
+node --test tests/commands/ai-analyze-project-provider.test.js
+node --test tests/lib/ai-analyze-project-docs.test.js tests/lib/ai-analyze-project-validation.test.js
+npm run docs:check
+npm run schema:slice:check
+```
+
+Pending final gate after metadata close:
+
+```bash
+node bin/create-quiver.js spec validate specs/quiver-v55-analyze-project-doc-apply-ux --strict
+git diff --check
+```

package/specs/quiver-v55-analyze-project-doc-apply-ux/slices/slice-01-cli-proposal-contract/EXECUTION_BRIEF.md

@@ -0,0 +1,67 @@
+# EXECUTION_BRIEF - slice-01 CLI proposal contract
+
+## Context
+
+The new apply-docs workflow needs stable contracts before any write behavior or selector UX is implemented. This slice freezes parser behavior, flag incompatibilities, proposal artifact schemas, and command help expectations.
+
+## Objective
+
+Define and test the CLI contract and proposal artifact contract for v55 without writing final docs.
+
+## Scope
+
+- Parse/validate:
+  - `--apply-docs`
+  - `--save-proposal`
+  - `--diff`
+  - `--yes`
+  - `--allow-dirty-docs`
+  - `ai analyze-project apply --run <run-id>`
+- Define proposal manifest schema and write manifest schema.
+- Define allowed JSON combinations.
+- Update command registry/help metadata if needed.
+- Add contract tests only; no apply implementation.
+
+## Acceptance Criteria
+
+- Parser accepts the approved flags and subaction without breaking existing `ai analyze-project --deep`.
+- Invalid flag combinations fail before provider execution with actionable errors.
+- `--review` remains backward compatible.
+- Proposal manifest schema is documented and testable.
+- `apply --run` contract does not require provider/model.
+- No runtime docs write is introduced in this slice.
+
+## Expected Files To Modify
+
+- `src/create-quiver/commands/ai.js`
+- `src/create-quiver/lib/ai/analyze-project-*.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/lib/ai*.test.js`
+- `docs/reference/commands.md`
+- this slice closure/status/evidence files
+
+## Validation Required
+
+```bash
+node --test tests/commands/ai-analyze-project.test.js
+node --test tests/commands/ai-analyze-project-review.test.js
+node bin/create-quiver.js spec validate specs/quiver-v55-analyze-project-doc-apply-ux --strict
+git diff --check
+```
+
+## Completion Checklist
+
+- Parser and help contract updated.
+- Proposal/write manifest schema contract documented.
+- Contract tests added or updated.
+- Existing `--review` behavior verified.
+- Slice closure brief updated with evidence.
+
+## Constraints
+
+- Do not implement actual docs applying.
+- Do not call live providers.
+- Do not relax analyze-project schema.
+- Do not change `--review` semantics.

package/specs/quiver-v55-analyze-project-doc-apply-ux/slices/slice-01-cli-proposal-contract/pr.md

@@ -0,0 +1,129 @@
+## Title
+
+QUIVER-55-01 - Analyze Project CLI Proposal Contract
+
+## Summary
+
+Implements the first v55 slice for `ai analyze-project` doc-apply UX. This PR establishes the CLI contract, parser validation, help/docs surface, and proposal/write manifest schemas without implementing the later save/apply flows.
+
+## PR Policy
+
+- One slice: `slice-01-cli-proposal-contract`.
+- Runtime behavior change is limited to parser/contract guards and manifest schema helpers.
+- Later slices will implement saving proposals, applying docs, interactive UX, saved proposal apply, and release smoke.
+
+## Scope
+
+Included:
+
+- Recognize `--apply-docs`, `--save-proposal`, `--diff`, and `--allow-dirty-docs`.
+- Recognize `ai analyze-project apply --run <run-id>`.
+- Reject invalid combinations before provider execution.
+- Keep `--review` backward compatible.
+- Add proposal and write manifest schema validation helpers.
+- Add command help, command reference, and EN/ES help descriptions.
+- Add the approved v55 spec/slice package and mark `slice-01` completed.
+
+Excluded:
+
+- No proposal persistence implementation.
+- No docs apply implementation.
+- No interactive selector.
+- No saved proposal apply.
+- No live provider smoke.
+
+## Files
+
+- `src/create-quiver/index.js`
+- `src/create-quiver/commands/ai.js`
+- `src/create-quiver/lib/ai/analyze-project-proposal.js`
+- `src/create-quiver/lib/cli/ux-flags.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/commands/cli-contract.test.js`
+- `tests/lib/ai-analyze-project-proposal.test.js`
+- `docs/reference/commands.md`
+- `specs/quiver-v55-analyze-project-doc-apply-ux/**`
+
+## How to Test (DETAILED - REQUIRED)
+
+### Required Environment
+
+- Node.js supported by this repository.
+- npm dependencies installed.
+- No provider credentials are required for this slice.
+
+### Worktree Access
+
+```bash
+git checkout feature/QUIVER-55-01-v55-cli-proposal-contract
+```
+
+### Run the Project
+
+No dev server is required. This is a CLI contract slice.
+
+### Use Cases
+
+#### Case 1: Dry-run remains read-only
+
+```bash
+node bin/create-quiver.js ai analyze-project --deep --dry-run
+```
+
+Expected: reports read-only analysis and does not create final docs.
+
+#### Case 2: Invalid apply/review combination fails before provider
+
+```bash
+node bin/create-quiver.js ai analyze-project --deep --apply-docs --review
+```
+
+Expected: fails with an actionable contract error before provider execution.
+
+#### Case 3: Saved proposal apply contract is recognized
+
+```bash
+node bin/create-quiver.js ai analyze-project apply --run run-123
+```
+
+Expected: command is parsed without requiring provider/model and reports that execution is reserved for a later v55 slice.
+
+### Technical Verification
+
+```bash
+node --test tests/lib/ai-analyze-project-proposal.test.js
+node --test tests/commands/ai-analyze-project.test.js
+node --test tests/commands/cli-contract.test.js
+node --test tests/commands/parser-contract.test.js
+node --test tests/commands/ux-flags.test.js
+node --test tests/commands/ai-analyze-project-review.test.js
+node --test tests/commands/ai-analyze-project-provider.test.js
+node --test tests/lib/ai-analyze-project-docs.test.js tests/lib/ai-analyze-project-validation.test.js
+npm run docs:check
+npm run schema:slice:check
+node bin/create-quiver.js spec validate specs/quiver-v55-analyze-project-doc-apply-ux --strict
+git diff --check
+```
+
+## Evidence
+
+- All technical verification commands passed locally.
+- `slice-01` closure brief records executed evidence.
+- No live provider call was required.
+
+## Rollback
+
+Revert this PR:
+
+```bash
+git revert <merge-commit-sha>
+```
+
+Existing `ai analyze-project --deep`, `--dry-run`, provider mode, and `--review` behavior are isolated and covered by regression tests.
+
+## Risks / Notes
+
+- The new flags are recognized but intentionally blocked from executing save/apply behavior until later slices.
+- This PR includes the v55 spec package because the spec does not exist on `main` yet.

package/specs/quiver-v55-analyze-project-doc-apply-ux/slices/slice-01-cli-proposal-contract/slice.json

@@ -0,0 +1,82 @@
+{
+  "slice_id": "slice-01-cli-proposal-contract",
+  "ticket": "QUIVER-55-01",
+  "type": "contract",
+  "title": "CLI Contract + Proposal Artifact Contract",
+  "objective": "Freeze the parser, flag, subcommand, and artifact schema contracts before implementing save/apply behavior.",
+  "description": "Adds the command contract for --apply-docs, --save-proposal, --diff, --yes, --allow-dirty-docs, and ai analyze-project apply --run, plus proposal/write manifest schema definitions and tests.",
+  "git": {
+    "branch_type": "feature",
+    "base_branch": "main",
+    "branch_slug": "v55-cli-proposal-contract",
+    "branch_name": "feature/QUIVER-55-01-v55-cli-proposal-contract"
+  },
+  "files": [
+    "src/create-quiver/index.js",
+    "src/create-quiver/commands/ai.js",
+    "src/create-quiver/lib/ai/analyze-project-*.js",
+    "src/create-quiver/lib/cli/ux-flags.js",
+    "src/create-quiver/lib/i18n/messages/en.js",
+    "src/create-quiver/lib/i18n/messages/es.js",
+    "tests/commands/cli-contract.test.js",
+    "tests/commands/ai-analyze-project*.test.js",
+    "tests/lib/ai*.test.js",
+    "docs/reference/commands.md",
+    "specs/quiver-v43-cli-i18n-audit-release-readiness/command-language-mode-matrix.json",
+    "specs/quiver-v55-analyze-project-doc-apply-ux/**"
+  ],
+  "expected_read_paths": [
+    "src/create-quiver/commands/ai.js",
+    "src/create-quiver/lib/ai/analyze-project-review.js",
+    "src/create-quiver/lib/ai/analyze-project-docs.js",
+    "docs/CLI_UX_GUIDE.md"
+  ],
+  "allowed_write_paths": [
+    "src/create-quiver/index.js",
+    "src/create-quiver/commands/ai.js",
+    "src/create-quiver/lib/ai/analyze-project-proposal.js",
+    "src/create-quiver/lib/cli/ux-flags.js",
+    "src/create-quiver/lib/i18n/messages/en.js",
+    "src/create-quiver/lib/i18n/messages/es.js",
+    "tests/commands/cli-contract.test.js",
+    "tests/commands/ai-analyze-project.test.js",
+    "tests/commands/ai-analyze-project-review.test.js",
+    "tests/lib/ai-analyze-project-proposal.test.js",
+    "docs/reference/commands.md",
+    "specs/quiver-v43-cli-i18n-audit-release-readiness/command-language-mode-matrix.json",
+    "specs/quiver-v55-analyze-project-doc-apply-ux/**"
+  ],
+  "depends_on": [],
+  "parallel_safe": "never",
+  "parallel_safe_reason": "This slice defines contracts required by every later slice.",
+  "must": [
+    "Define exact flag compatibility rules.",
+    "Define proposal and write manifest schemas.",
+    "Keep --review backward compatible.",
+    "Ensure apply --run does not require provider/model."
+  ],
+  "not_included": [
+    "Saving proposal end-to-end.",
+    "Applying docs.",
+    "Interactive selector UX."
+  ],
+  "acceptance": [
+    "Parser accepts approved flags and subaction.",
+    "Invalid combinations fail before provider execution.",
+    "Proposal manifest schema is testable.",
+    "Existing --review tests remain green."
+  ],
+  "tests": [
+    "node --test tests/commands/ai-analyze-project.test.js",
+    "node --test tests/commands/ai-analyze-project-review.test.js",
+    "node --test tests/commands/i18n-audit-matrix.test.js",
+    "node bin/create-quiver.js spec validate specs/quiver-v55-analyze-project-doc-apply-ux --strict",
+    "git diff --check"
+  ],
+  "estimated_hours": 4,
+  "actual_hours": 4,
+  "status": "completed",
+  "blocked_reason": null,
+  "started_at": "2026-06-12T00:00:00.000Z",
+  "completed_at": "2026-06-12T00:00:00.000Z"
+}

package/specs/quiver-v55-analyze-project-doc-apply-ux/slices/slice-02-save-proposal-flow/CLOSURE_BRIEF.md

@@ -0,0 +1,39 @@
+# CLOSURE_BRIEF - slice-02 save proposal flow
+
+## Summary
+
+Implemented `--save-proposal` for `ai analyze-project`.
+
+The command now runs the existing provider analysis path, validates and repairs provider JSON through the current schema gates, builds a normalized documentation proposal, and persists proposal artifacts under `.quiver/runs/<run-id>/proposal/` without writing final docs or creating snapshots.
+
+Saved artifacts include:
+
+- `analyze-project-doc-proposal.json`
+- `analyze-project-doc-proposal.md`
+- `analyze-project-doc-proposal.diff`
+- `manifest.json`
+
+`--save-proposal --json` emits clean parseable JSON for automation.
+
+## Required Evidence
+
+- Save proposal command test passes.
+- JSON output test passes.
+- No-final-doc write test passes.
+- Invalid provider JSON creates no usable proposal artifacts.
+- Proposal Markdown summary stays compact and omits full doc contents.
+
+## Validation
+
+Executed:
+
+```bash
+node --test tests/lib/ai-analyze-project-proposal.test.js
+node --test tests/commands/ai-analyze-project-provider.test.js
+node --test tests/commands/ai-analyze-project.test.js tests/commands/cli-contract.test.js tests/commands/ux-flags.test.js
+node --test tests/commands/ai-analyze-project-review.test.js tests/lib/ai-analyze-project-validation.test.js tests/lib/ai-analyze-project-docs.test.js
+node bin/create-quiver.js spec validate specs/quiver-v55-analyze-project-doc-apply-ux --strict
+git diff --check
+```
+
+Result: all passed.