create-quiver 0.17.2 → 0.17.4

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

@@ -0,0 +1,61 @@
+# EXECUTION_BRIEF - slice-02 save proposal flow
+
+## Context
+
+Users need a way to keep the generated documentation proposal without applying final docs. This must work in automation and must not require an editor.
+
+## Objective
+
+Implement `--save-proposal` so Quiver persists a validated, normalized proposal and audit summary without writing final documentation.
+
+## Scope
+
+- Build proposal from `buildAnalyzeProjectDocProposal(parsed.analysis)`.
+- Save:
+  - normalized proposal JSON;
+  - compact Markdown summary;
+  - full diff artifact;
+  - manifest with hashes and events.
+- Support `--save-proposal --json`.
+- Do not create snapshots or write final docs.
+- Update run status with proposal artifact metadata.
+
+## Acceptance Criteria
+
+- `--save-proposal` runs provider, validates/repairs JSON, and saves proposal artifacts.
+- Final docs are not modified.
+- no-TTY mode works without prompting.
+- `--json` emits clean machine-readable proposal result.
+- Invalid final JSON does not create usable proposal artifacts.
+- Proposal Markdown summary is compact and does not embed full doc contents by default.
+
+## Expected Files To Modify
+
+- `src/create-quiver/commands/ai.js`
+- `src/create-quiver/lib/ai/analyze-project-proposal.js`
+- `tests/commands/ai-analyze-project-provider.test.js`
+- `tests/lib/ai-analyze-project-proposal.test.js`
+- this slice closure/status/evidence files
+
+## Validation Required
+
+```bash
+node --test tests/commands/ai-analyze-project-provider.test.js
+node --test tests/lib/ai-analyze-project-proposal.test.js
+node bin/create-quiver.js spec validate specs/quiver-v55-analyze-project-doc-apply-ux --strict
+git diff --check
+```
+
+## Completion Checklist
+
+- Save-only proposal flow implemented without final docs writes.
+- Proposal JSON, Markdown, diff, and manifest artifacts covered by tests.
+- `--json` output contract verified.
+- Invalid JSON failure path verified.
+- Slice closure brief updated with evidence.
+
+## Constraints
+
+- Do not write docs final.
+- Do not create snapshots for save-only flows.
+- Do not re-run provider when only formatting artifacts.

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

@@ -0,0 +1,116 @@
+## Title
+
+QUIVER-55-02 - Save Analyze Project Proposal Artifacts
+
+## Summary
+
+Implements the second v55 slice for `ai analyze-project`: `--save-proposal` now persists a validated, normalized documentation proposal without writing final docs.
+
+## PR Policy
+
+- One slice: `slice-02-save-proposal-flow`.
+- Runtime behavior change is limited to save-only proposal artifact persistence.
+- This PR does not implement docs apply, interactive selector UX, or saved proposal apply.
+
+## Scope
+
+Included:
+
+- Build a normalized doc proposal from validated provider analysis.
+- Save proposal JSON, compact Markdown summary, full diff, and manifest under `.quiver/runs/<run-id>/proposal/`.
+- Record proposal metadata in run status.
+- Support `--save-proposal --json`.
+- Keep final docs unchanged.
+- Avoid snapshots in save-only mode.
+- Add command and helper tests for success, JSON output, and invalid provider JSON.
+
+Excluded:
+
+- No `--apply-docs` implementation.
+- No interactive selector.
+- No `ai analyze-project apply --run` implementation.
+- No live provider smoke in CI.
+
+## Files
+
+- `src/create-quiver/commands/ai.js`
+- `src/create-quiver/lib/ai/analyze-project-proposal.js`
+- `tests/commands/ai-analyze-project-provider.test.js`
+- `tests/lib/ai-analyze-project-proposal.test.js`
+- `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 automated tests.
+
+### Worktree Access
+
+```bash
+git checkout feature/QUIVER-55-02-v55-save-proposal-flow
+```
+
+### Run the Project
+
+No dev server is required. This is a CLI save-artifact slice.
+
+### Use Cases
+
+#### Case 1: Save proposal artifacts
+
+```bash
+node --test tests/commands/ai-analyze-project-provider.test.js
+```
+
+Expected: `--save-proposal` test writes proposal artifacts under `.quiver/runs/<run-id>/proposal/` and does not write `docs/CONTEXTO.md`.
+
+#### Case 2: Save proposal JSON output
+
+```bash
+node --test tests/commands/ai-analyze-project-provider.test.js
+```
+
+Expected: `--save-proposal --json` output parses as JSON and points to the saved proposal manifest.
+
+#### Case 3: Invalid provider JSON remains safe
+
+```bash
+node --test tests/commands/ai-analyze-project-provider.test.js
+```
+
+Expected: invalid final provider JSON rejects before proposal artifacts are created.
+
+### Technical Verification
+
+```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
+```
+
+## Evidence
+
+- All technical verification commands passed locally.
+- `slice-02` closure brief records executed evidence.
+- No live provider call was required.
+
+## Rollback
+
+Revert this PR:
+
+```bash
+git revert <merge-commit-sha>
+```
+
+This restores `--save-proposal` to the previously recognized-but-unavailable contract while preserving the earlier slice-01 CLI contract.
+
+## Risks / Notes
+
+- Saved proposals are artifacts only; users still need a later slice to apply them with `apply --run`.
+- The Markdown summary intentionally omits full proposed doc contents; the JSON and diff artifacts hold details.

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

@@ -0,0 +1,69 @@
+{
+  "slice_id": "slice-02-save-proposal-flow",
+  "ticket": "QUIVER-55-02",
+  "type": "feature",
+  "title": "Save Proposal Flow",
+  "objective": "Persist validated analyze-project doc proposals without writing final documentation.",
+  "description": "Implements --save-proposal with normalized JSON, compact Markdown summary, full diff artifact, manifest hashes, run-status metadata, and JSON automation output.",
+  "git": {
+    "branch_type": "feature",
+    "base_branch": "main",
+    "branch_slug": "v55-save-proposal-flow",
+    "branch_name": "feature/QUIVER-55-02-v55-save-proposal-flow"
+  },
+  "files": [
+    "src/create-quiver/commands/ai.js",
+    "src/create-quiver/lib/ai/analyze-project-proposal.js",
+    "tests/commands/ai-analyze-project-provider.test.js",
+    "tests/lib/ai-analyze-project-proposal.test.js",
+    "specs/quiver-v55-analyze-project-doc-apply-ux/**"
+  ],
+  "expected_read_paths": [
+    "src/create-quiver/lib/ai/analyze-project-docs.js",
+    "src/create-quiver/lib/ai/analyze-project-review.js",
+    "src/create-quiver/lib/ai/artifacts.js"
+  ],
+  "allowed_write_paths": [
+    "src/create-quiver/commands/ai.js",
+    "src/create-quiver/lib/ai/analyze-project-proposal.js",
+    "tests/commands/ai-analyze-project-provider.test.js",
+    "tests/lib/ai-analyze-project-proposal.test.js",
+    "specs/quiver-v55-analyze-project-doc-apply-ux/**"
+  ],
+  "depends_on": [
+    "slice-01-cli-proposal-contract"
+  ],
+  "parallel_safe": "never",
+  "parallel_safe_reason": "This slice depends on the artifact contract and feeds the apply engine.",
+  "must": [
+    "Save normalized proposal JSON.",
+    "Save compact Markdown summary.",
+    "Save diff artifact.",
+    "Never write final docs."
+  ],
+  "not_included": [
+    "Apply docs.",
+    "Interactive selector.",
+    "Apply saved run."
+  ],
+  "acceptance": [
+    "--save-proposal writes proposal artifacts.",
+    "--save-proposal --json is parseable.",
+    "Final docs remain unchanged.",
+    "Invalid final JSON does not create usable proposal artifacts."
+  ],
+  "tests": [
+    "node --test tests/commands/ai-analyze-project-provider.test.js",
+    "node --test tests/lib/ai-analyze-project-proposal.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"
+  ],
+  "estimated_hours": 5,
+  "actual_hours": 5,
+  "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-03-noninteractive-apply-engine/CLOSURE_BRIEF.md

@@ -0,0 +1,36 @@
+# CLOSURE_BRIEF - slice-03 non-interactive apply engine
+
+## Summary
+
+Implemented. `ai analyze-project --deep --apply-docs --yes` now runs the provider, builds a validated doc proposal, saves proposal artifacts, blocks unsafe dirty/stale writes, creates a snapshot, writes only approved docs, saves a separate write manifest, runs post-write validation, and supports parseable JSON output.
+
+The interactive `--apply-docs` selector and `apply --run` remain out of scope for later slices.
+
+## Evidence
+
+- Apply success test passes with proposal artifacts, snapshot, write manifest, written docs, and post-write validation.
+- Dirty target docs block `--yes` unless `--allow-dirty-docs` is provided.
+- Stale target hash preflight is covered at the apply engine boundary.
+- Invalid provider doc proposals write no final docs and create no proposal artifacts.
+- `--apply-docs --yes --json` emits a parseable complete result.
+- Existing `--review` tests still pass unchanged.
+
+## Validation
+
+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.

package/specs/quiver-v55-analyze-project-doc-apply-ux/slices/slice-03-noninteractive-apply-engine/EXECUTION_BRIEF.md

@@ -0,0 +1,62 @@
+# EXECUTION_BRIEF - slice-03 non-interactive apply engine
+
+## Context
+
+Automation needs a safe direct apply path. This must not depend on selector UI and must reuse existing write plan, snapshot, and post-write validation behavior.
+
+## Objective
+
+Implement the non-interactive apply engine for `--apply-docs --yes`.
+
+## Scope
+
+- Save proposal artifacts before applying.
+- Build write plan from normalized proposal.
+- Detect dirty/stale target docs.
+- Block dirty docs in `--yes` unless `--allow-dirty-docs` is passed.
+- Create snapshot before writes.
+- Write docs through existing safe write path.
+- Save write manifest.
+- Run post-write validation.
+- Support `--apply-docs --yes --json`.
+
+## Acceptance Criteria
+
+- `--apply-docs --yes` writes only allowed docs when proposal is valid.
+- `--apply-docs --yes` blocks on invalid proposal.
+- `--apply-docs --yes` blocks on dirty docs unless explicitly allowed.
+- Snapshot and write manifest are created before/after writes as appropriate.
+- JSON output includes run id, proposal artifacts, write plan, snapshot, written docs, validation, and artifacts.
+- Existing `--review` behavior remains unchanged.
+
+## Expected Files To Modify
+
+- `src/create-quiver/commands/ai.js`
+- `src/create-quiver/lib/ai/analyze-project-apply.js`
+- `src/create-quiver/lib/ai/analyze-project-proposal.js`
+- `tests/commands/ai-analyze-project-review.test.js`
+- `tests/lib/ai-analyze-project-validation.test.js`
+- this slice closure/status/evidence files
+
+## Validation Required
+
+```bash
+node --test tests/commands/ai-analyze-project-review.test.js
+node --test tests/lib/ai-analyze-project-validation.test.js
+node bin/create-quiver.js spec validate specs/quiver-v55-analyze-project-doc-apply-ux --strict
+git diff --check
+```
+
+## Completion Checklist
+
+- Non-interactive apply engine uses validated proposals only.
+- Dirty/stale docs guardrails covered by tests.
+- Snapshot and write manifest behavior verified.
+- JSON output includes apply artifacts and validation status.
+- Slice closure brief updated with evidence.
+
+## Constraints
+
+- Do not implement selector UI in this slice.
+- Do not allow product code writes.
+- Do not let `--yes` approve anything beyond validated doc updates.

package/specs/quiver-v55-analyze-project-doc-apply-ux/slices/slice-03-noninteractive-apply-engine/pr.md

@@ -0,0 +1,132 @@
+## Title
+
+QUIVER-55-03 - Non-Interactive Analyze Project Apply Engine
+
+## Summary
+
+Implements the third v55 slice for `ai analyze-project`: `--apply-docs --yes` now applies validated documentation proposals through a safe non-interactive write engine.
+
+## PR Policy
+
+- One slice: `slice-03-noninteractive-apply-engine`.
+- Runtime behavior change is limited to the non-interactive `--apply-docs --yes` path.
+- This PR does not implement interactive selector UX or saved proposal application by run id.
+- Human merge is required because this PR changes runtime write behavior.
+
+## Scope
+
+Included:
+
+- Persist proposal artifacts before applying docs.
+- Build the write plan from a normalized validated proposal.
+- Block dirty target docs in `--yes` unless `--allow-dirty-docs` is passed.
+- Block stale target docs when current hashes no longer match the saved proposal manifest.
+- Create snapshots before final doc writes.
+- Write approved docs only through the existing managed-block path.
+- Save `.quiver/runs/<run-id>/writes/analyze-project-doc-writes.json`.
+- Run post-write validation.
+- Support `--apply-docs --yes --json`.
+- Preserve existing `--review` behavior.
+
+Excluded:
+
+- No interactive selector for plain `--apply-docs`.
+- No `ai analyze-project apply --run <run-id>`.
+- No live provider smoke in CI.
+
+## Files
+
+- `src/create-quiver/commands/ai.js`
+- `src/create-quiver/lib/ai/analyze-project-apply.js`
+- `src/create-quiver/lib/ai/analyze-project-proposal.js`
+- `tests/commands/ai-analyze-project-review.test.js`
+- `tests/lib/ai-analyze-project-apply.test.js`
+- `tests/lib/ai-analyze-project-proposal.test.js`
+- `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 automated tests.
+
+### Worktree Access
+
+```bash
+git checkout feature/QUIVER-55-03-v55-noninteractive-apply-engine
+```
+
+### Run the Project
+
+No dev server is required. This is a CLI docs-apply engine slice.
+
+### Use Cases
+
+#### Case 1: Apply valid docs non-interactively
+
+```bash
+node --test tests/commands/ai-analyze-project-review.test.js
+```
+
+Expected: `--apply-docs --yes` writes approved docs, saves proposal artifacts, creates a snapshot, saves the write manifest, and passes post-write validation.
+
+#### Case 2: Automation JSON output
+
+```bash
+node --test tests/commands/ai-analyze-project-review.test.js
+```
+
+Expected: `--apply-docs --yes --json` emits parseable JSON containing run id, proposal artifacts, write plan, snapshot, written docs, post-write validation, and write manifest.
+
+#### Case 3: Dirty docs are blocked by default
+
+```bash
+node --test tests/commands/ai-analyze-project-review.test.js
+```
+
+Expected: existing target docs block `--yes` unless `--allow-dirty-docs` is provided; final docs remain unchanged when blocked.
+
+#### Case 4: Stale docs are blocked
+
+```bash
+node --test tests/lib/ai-analyze-project-apply.test.js
+```
+
+Expected: hash mismatches between proposal manifest and current target docs fail before writing final docs.
+
+### Technical Verification
+
+```bash
+node --test tests/commands/ai-analyze-project-review.test.js tests/lib/ai-analyze-project-apply.test.js tests/lib/ai-analyze-project-proposal.test.js tests/lib/ai-analyze-project-validation.test.js
+node --test tests/commands/ai-analyze-project-provider.test.js tests/commands/ai-analyze-project.test.js tests/commands/cli-contract.test.js tests/commands/ux-flags.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
+```
+
+## Evidence
+
+- All technical verification commands passed locally.
+- Full `npm test` passed locally: 730 tests.
+- `slice-03` closure brief records executed evidence.
+
+## Rollback
+
+Revert this PR:
+
+```bash
+git revert <merge-commit-sha>
+```
+
+This disables non-interactive docs apply while preserving the earlier CLI contract and `--save-proposal` artifacts.
+
+## Risks / Notes
+
+- `--apply-docs` without `--yes` still intentionally blocks until the interactive selector slice lands.
+- Existing docs are treated as dirty targets and require `--allow-dirty-docs` for automation.
+- Saved proposal application remains a later slice.

package/specs/quiver-v55-analyze-project-doc-apply-ux/slices/slice-03-noninteractive-apply-engine/slice.json

@@ -0,0 +1,76 @@
+{
+  "slice_id": "slice-03-noninteractive-apply-engine",
+  "ticket": "QUIVER-55-03",
+  "type": "feature",
+  "title": "Non-Interactive Apply Engine",
+  "objective": "Apply validated analyze-project doc proposals safely through --apply-docs --yes without selector UI.",
+  "description": "Adds the reusable apply engine: proposal persistence, dirty/stale preflight, snapshot, doc writes, write manifest, post-write validation, and JSON output.",
+  "git": {
+    "branch_type": "feature",
+    "base_branch": "main",
+    "branch_slug": "v55-noninteractive-apply-engine",
+    "branch_name": "feature/QUIVER-55-03-v55-noninteractive-apply-engine"
+  },
+  "files": [
+    "src/create-quiver/commands/ai.js",
+    "src/create-quiver/lib/ai/analyze-project-apply.js",
+    "src/create-quiver/lib/ai/analyze-project-proposal.js",
+    "tests/commands/ai-analyze-project-review.test.js",
+    "tests/lib/ai-analyze-project-apply.test.js",
+    "tests/lib/ai-analyze-project-proposal.test.js",
+    "tests/lib/ai-analyze-project-validation.test.js",
+    "specs/quiver-v55-analyze-project-doc-apply-ux/**"
+  ],
+  "expected_read_paths": [
+    "src/create-quiver/lib/ai/analyze-project-docs.js",
+    "src/create-quiver/lib/ai/analyze-project-validation.js",
+    "src/create-quiver/lib/ai/analyze-project-review.js"
+  ],
+  "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-proposal.js",
+    "tests/commands/ai-analyze-project-review.test.js",
+    "tests/lib/ai-analyze-project-apply.test.js",
+    "tests/lib/ai-analyze-project-proposal.test.js",
+    "tests/lib/ai-analyze-project-validation.test.js",
+    "specs/quiver-v55-analyze-project-doc-apply-ux/**"
+  ],
+  "depends_on": [
+    "slice-01-cli-proposal-contract",
+    "slice-02-save-proposal-flow"
+  ],
+  "parallel_safe": "never",
+  "parallel_safe_reason": "This slice owns the docs write boundary and must be reviewed independently.",
+  "must": [
+    "Persist proposal before apply.",
+    "Create snapshot before final doc writes.",
+    "Save write manifest.",
+    "Run post-write validation."
+  ],
+  "not_included": [
+    "Interactive selector.",
+    "Apply saved run.",
+    "Docs release smoke."
+  ],
+  "acceptance": [
+    "--apply-docs --yes writes valid allowed docs.",
+    "Dirty docs block --yes unless --allow-dirty-docs is passed.",
+    "Invalid proposal writes no final docs.",
+    "--apply-docs --yes --json is parseable and complete."
+  ],
+  "tests": [
+    "node --test tests/commands/ai-analyze-project-review.test.js",
+    "node --test tests/lib/ai-analyze-project-apply.test.js",
+    "node --test tests/lib/ai-analyze-project-proposal.test.js",
+    "node --test tests/lib/ai-analyze-project-validation.test.js",
+    "node bin/create-quiver.js spec validate specs/quiver-v55-analyze-project-doc-apply-ux --strict",
+    "git diff --check"
+  ],
+  "estimated_hours": 6,
+  "actual_hours": 6,
+  "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-04-interactive-apply-ux/CLOSURE_BRIEF.md

@@ -0,0 +1,47 @@
+# CLOSURE_BRIEF - slice-04 interactive apply UX
+
+## Summary
+
+Completed. Plain TTY `ai analyze-project --deep --apply-docs` now runs the provider, builds the validated proposal, and shows an explained selector instead of forcing a large editor buffer. The selector routes apply/save/edit/cancel/view-diff actions through the existing safe proposal, review, and apply flows.
+
+## Behavior Delivered
+
+- TTY `--apply-docs` shows compact summary, proposed files, changed/dirty counts, selected context artifact, and option descriptions.
+- Dynamic recommendation puts `Apply documentation` first for clean creates and `View diff` first for dirty/update targets.
+- `View diff` saves the full diff artifact, prints only a bounded terminal preview, and requires a second decision.
+- `Save proposal` writes `.quiver/runs/<run-id>/proposal/*` artifacts only.
+- `Edit proposal` reuses the existing review/editor/confirmation flow.
+- `Cancel` writes no final docs and records `apply-canceled` status.
+- no-TTY or CI `--apply-docs` without `--yes` fails before provider execution with actionable guidance.
+- English and Spanish selector copy are covered.
+
+## Required Evidence
+
+- Apply option test passes.
+- Diff option test passes.
+- Save option test passes.
+- Edit option test passes.
+- Cancel option test passes.
+- no-TTY error test passes.
+
+## Validation
+
+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.

package/specs/quiver-v55-analyze-project-doc-apply-ux/slices/slice-04-interactive-apply-ux/EXECUTION_BRIEF.md

@@ -0,0 +1,70 @@
+# EXECUTION_BRIEF - slice-04 interactive apply UX
+
+## Context
+
+The main user-facing improvement is an explained selector that avoids forcing users into a large editor buffer. This selector must orchestrate already-tested save/apply/edit actions instead of owning write logic.
+
+## Objective
+
+Implement `--apply-docs` TTY selector UX with English/Spanish messages and safe action routing.
+
+## Scope
+
+- Show compact analysis/proposal summary.
+- Show proposed files and action counts.
+- Show repair summary and artifact paths.
+- Render selector options with one-line descriptions.
+- Dynamic recommendation:
+  - Apply documentation when target docs are clean/low-risk;
+  - View diff when docs are existing/dirty/high-risk.
+- Implement actions:
+  - apply;
+  - view diff then apply/save/cancel;
+  - save proposal;
+  - edit proposal via existing `--review` path;
+  - cancel.
+- Truncate human diff and save full diff artifact.
+
+## Acceptance Criteria
+
+- TTY `--apply-docs` shows explained options.
+- no-TTY `--apply-docs` without `--yes` fails with actionable message.
+- Cancel writes no final docs.
+- Save proposal from selector writes artifacts only.
+- Edit proposal reuses editor flow and handles editor failure by returning actionable guidance.
+- View diff does not accidentally apply docs and requires a second decision.
+- `--review` remains backward compatible.
+
+## Expected Files To Modify
+
+- `src/create-quiver/commands/ai.js`
+- `src/create-quiver/lib/ai/analyze-project-interactive.js`
+- `src/create-quiver/lib/ai/analyze-project-apply.js`
+- `src/create-quiver/lib/i18n/messages/en.js`
+- `src/create-quiver/lib/i18n/messages/es.js`
+- `tests/commands/ai-analyze-project-review.test.js`
+- `tests/lib/cli-ux.test.js`
+- this slice closure/status/evidence files
+
+## Validation Required
+
+```bash
+node --test tests/commands/ai-analyze-project-review.test.js
+node --test tests/lib/cli-ux.test.js
+node bin/create-quiver.js spec validate specs/quiver-v55-analyze-project-doc-apply-ux --strict
+git diff --check
+```
+
+## Completion Checklist
+
+- TTY selector presents explained choices in the configured language.
+- no-TTY apply without `--yes` fails with actionable guidance.
+- Diff, save, edit, cancel, and apply paths are tested.
+- Terminal diff output remains bounded.
+- Slice closure brief updated with evidence.
+
+## Constraints
+
+- Do not duplicate write logic inside selector code.
+- Do not make `--interactive` required for `--apply-docs`.
+- Do not print unbounded diffs in terminal.