create-quiver 0.17.1 → 0.17.3

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

@@ -0,0 +1,209 @@
+# Evidence Report - Quiver v55 Analyze Project Doc Apply UX
+
+**Status:** In progress
+**Last updated:** 2026-06-12
+
+## Evidence Behind The Requirement
+
+- Live `nika-erp` run with `create-quiver@0.17.2` completed successfully and generated valid doc update proposals.
+- The normal provider command did not write final docs, by design.
+- Existing `docs/CONTEXTO.md` in `nika-erp` still contained placeholders because no apply/review flow was completed.
+- `--review` is safe but confusing because it opens a large JSON proposal in an editor.
+- Users need a simpler flow: summary, explained options, optional diff, save, apply, edit, or cancel.
+
+## Evidence To Capture During Implementation
+
+- Parser/flag tests for `--apply-docs`, `--save-proposal`, `--diff`, `--yes`, `--allow-dirty-docs`, and `ai analyze-project apply --run`. Captured in `slice-01`.
+- Proposal artifact schema tests. Captured in `slice-01`.
+- Save proposal command tests in TTY/no-TTY and JSON modes.
+- Non-interactive apply tests with snapshots, write manifests, and post-write validation.
+- Dirty/stale doc preflight tests.
+- Interactive selector tests for apply, diff, save, edit, and cancel.
+- Saved proposal apply tests without provider execution.
+- EN/ES i18n tests.
+- Docs/checks and package smoke before release.
+
+## Required Validation Before Closing Spec
+
+```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 Evidence
+
+Use a temporary copy or disposable branch of `nika-erp`:
+
+```bash
+npx --yes create-quiver@latest ai analyze-project --deep --provider codex --model gpt-5.5
+npx --yes create-quiver@latest ai analyze-project --deep --save-proposal --provider codex --model gpt-5.5
+npx --yes create-quiver@latest ai analyze-project --deep --apply-docs --provider codex --model gpt-5.5
+npx --yes create-quiver@latest ai analyze-project --deep --apply-docs --yes --provider codex --model gpt-5.5
+npx --yes create-quiver@latest ai analyze-project apply --run <run-id>
+```
+
+Live provider smoke is release evidence only and must not become a CI gate.
+
+## Slice-01 Evidence
+
+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
+```
+
+Result: all passed.
+
+## Slice-02 Evidence - slice-02-save-proposal-flow
+
+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.
+
+Covered behavior:
+
+- `--save-proposal` persists proposal JSON, compact Markdown summary, full diff, and manifest.
+- `--save-proposal --json` emits clean parseable JSON.
+- Final docs remain unchanged.
+- Save-only flows do not create snapshots.
+- Invalid final provider JSON does not create usable proposal artifacts.
+
+## Slice-03 Evidence - slice-03-noninteractive-apply-engine
+
+Executed:
+
+```bash
+node --test tests/lib/ai-analyze-project-apply.test.js
+node --test tests/lib/ai-analyze-project-proposal.test.js
+node --test tests/commands/ai-analyze-project-review.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-provider.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
+npm test
+```
+
+Result: all passed. Full `npm test` passed with 730 tests.
+
+Covered behavior:
+
+- `--apply-docs --yes` applies validated allowed docs.
+- `--apply-docs --yes --json` returns run id, proposal artifacts, write plan, snapshot, written docs, post-write validation, and write manifest.
+- Dirty target docs block `--yes` unless `--allow-dirty-docs` is provided.
+- Stale target docs are blocked at the apply engine boundary.
+- Invalid provider doc proposals do not write final docs.
+- Existing `--review` behavior remains covered.
+
+## Slice-04 Evidence - slice-04-interactive-apply-ux
+
+Executed:
+
+```bash
+node --test tests/commands/ai-analyze-project-review.test.js
+node --test tests/lib/cli-ux.test.js
+node --test tests/commands/ai-analyze-project.test.js
+node --test tests/commands/cli-contract.test.js
+node --test tests/lib/i18n-catalog.test.js
+node --test tests/commands/ux-flags.test.js
+node --test tests/commands/ai-analyze-project-provider.test.js
+node --test tests/lib/ai-analyze-project-validation.test.js 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
+npm test
+```
+
+Result: all passed. Full `npm test` passed with 741 tests.
+
+Covered behavior:
+
+- TTY `--apply-docs` shows an explained selector after provider validation.
+- Clean creates recommend `apply`; dirty/update targets recommend `view-diff`.
+- no-TTY `--apply-docs` without `--yes` fails before provider execution.
+- Cancel writes no final docs and records `apply-canceled`.
+- Save proposal writes proposal artifacts only.
+- View diff saves the full diff artifact, prints a bounded preview, and requires a second decision.
+- Edit proposal reuses the existing review/editor confirmation flow.
+- English and Spanish selector copy are covered.
+
+## Slice-05 Evidence - slice-05-apply-saved-proposal
+
+Executed:
+
+```bash
+node --test tests/commands/ai-analyze-project-review.test.js
+node --test tests/lib/ai-analyze-project-proposal.test.js
+node --test tests/commands/ai-analyze-project.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
+npm test
+```
+
+Result: all passed. Full `npm test` passed with 747 tests.
+
+Covered behavior:
+
+- `ai analyze-project apply --run <run-id>` applies a saved proposal without executing provider/model resolution.
+- Saved proposal manifests and proposal JSON are revalidated before write.
+- Missing or unsafe saved artifacts fail before final docs writes.
+- Dirty target docs block by default and can be applied only with `--allow-dirty-docs`.
+- Stale target docs block before any final docs write.
+- Manual proposal edits are accepted after revalidation and recorded in the write manifest.
+- `--run latest --yes` and `--run latest --json` are rejected to keep automation deterministic.
+
+## Slice-06 Evidence - slice-06-i18n-docs-release-smoke
+
+Executed:
+
+```bash
+node --test tests/commands/cli-contract.test.js
+node --test tests/lib/i18n-catalog.test.js
+node --test tests/commands/ai-analyze-project-review.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
+npm test
+```
+
+Result: all passed. Full `npm test` passed with 747 tests.
+
+Covered behavior:
+
+- English and Spanish help coverage includes the new analyze-project doc-apply flags.
+- Commands, flags, providers, models, and paths remain untranslated in localized output.
+- Command reference explains `--apply-docs`, `--save-proposal`, `--review`, `--yes`, `--diff`, and `apply --run`.
+- Existing-project workflow documents the recommended `--apply-docs` path and save/apply separation.
+- Troubleshooting explains why normal provider mode does not write final docs.
+- Release smoke guidance uses a temporary copy or disposable branch of `nika-erp`, not the main checkout.

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

@@ -0,0 +1,49 @@
+# Execution Plan - Quiver v55 Analyze Project Doc Apply UX
+
+## Sequential Order
+
+1. `slice-01-cli-proposal-contract`
+2. `slice-02-save-proposal-flow`
+3. `slice-03-noninteractive-apply-engine`
+4. `slice-04-interactive-apply-ux`
+5. `slice-05-apply-saved-proposal`
+6. `slice-06-i18n-docs-release-smoke`
+
+## Parallelization Rules
+
+- `slice-01` must land first because it freezes the CLI and artifact contracts.
+- `slice-02` must wait for proposal artifact schema and paths.
+- `slice-03` must wait for saved proposal support so every apply can persist proposal artifacts first.
+- `slice-04` must wait for the non-interactive apply engine so the selector only orchestrates tested actions.
+- `slice-05` can start after `slice-03`; it must not duplicate apply/write logic.
+- `slice-06` closes documentation, i18n, command matrix, and release smoke after behavior is stable.
+
+## Critical Boundaries
+
+- CLI parse boundary: `slice-01`
+- Proposal artifact boundary: `slice-01`, `slice-02`
+- Write boundary: `slice-03`
+- Human UX boundary: `slice-04`
+- Saved-run trust boundary: `slice-05`
+- Release readiness boundary: `slice-06`
+
+## Rollback
+
+- Revert `slice-04` to remove interactive UX while keeping non-interactive save/apply behavior.
+- Revert `slice-05` if saved proposal application has stale-detection issues.
+- Revert `slice-03` to remove docs applying while retaining proposal save artifacts.
+- Preserve existing `--review` behavior throughout as fallback.
+
+## Required Validation
+
+```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
+```

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.