create-quiver 0.17.2 → 0.17.3

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

@@ -0,0 +1,141 @@
+## Title
+
+QUIVER-55-04 - Interactive Analyze Project Apply UX
+
+## Summary
+
+Implements the fourth v55 slice for `ai analyze-project`: plain TTY `--apply-docs` now shows an explained selector after provider validation instead of forcing users into a large editor buffer.
+
+The selector supports:
+
+- Apply documentation.
+- View bounded diff, then choose again.
+- Save proposal artifacts only.
+- Edit proposal through the existing review flow.
+- Cancel without final docs writes.
+
+## PR Policy
+
+- One slice, one commit, one PR.
+- Runtime UX change, so this must be an individual PR.
+- Human merge required after CI passes.
+
+## Scope
+
+Included:
+
+- Interactive selector module for `--apply-docs`.
+- Safe routing from selector actions into existing save/apply/review flows.
+- Dynamic recommendation based on clean creates vs dirty/update targets.
+- Bounded terminal diff with full diff artifact saved under `.quiver/runs`.
+- English and Spanish selector copy with option descriptions.
+- Tests for apply, save, edit, cancel, view-diff second decision, no-TTY guard, and selector recommendation.
+- Slice status, evidence, and closure updates.
+
+Excluded:
+
+- `ai analyze-project apply --run <run-id>`.
+- Release smoke docs.
+- Product repo code changes.
+
+## Files
+
+- `src/create-quiver/commands/ai.js`
+- `src/create-quiver/lib/ai/analyze-project-interactive.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`
+- `specs/quiver-v55-analyze-project-doc-apply-ux/**`
+
+## How to Test (DETAILED - REQUIRED)
+
+### Required Environment
+
+- Node/npm environment for this repo.
+- No live provider credentials required for automated tests.
+
+### Worktree Access
+
+```bash
+git checkout feature/QUIVER-55-04-v55-interactive-apply-ux
+```
+
+### Run the Project
+
+No dev server is required. This is CLI behavior.
+
+### Use Cases
+
+1. Interactive apply selector:
+
+```bash
+node --test tests/commands/ai-analyze-project-review.test.js
+```
+
+Expected: selector paths for apply, save, edit, cancel, view diff, no-TTY, and Spanish copy pass.
+
+2. UX helper behavior:
+
+```bash
+node --test tests/lib/cli-ux.test.js
+```
+
+Expected: selector recommendations and bounded diff formatting pass.
+
+3. Contract regressions:
+
+```bash
+node --test tests/commands/ai-analyze-project.test.js
+node --test tests/commands/cli-contract.test.js
+node --test tests/commands/ux-flags.test.js
+node --test tests/lib/i18n-catalog.test.js
+```
+
+Expected: CLI contracts, help, UX flags, and i18n catalog remain valid.
+
+### Technical Verification
+
+```bash
+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
+```
+
+Expected: all pass.
+
+## Evidence
+
+Executed locally:
+
+```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.
+
+## Rollback
+
+Revert this PR. `--apply-docs --yes`, `--save-proposal`, and `--review` remain available from earlier slices if this selector UX must be removed.
+
+## Risks / Notes
+
+- `--apply-docs` without `--yes` now runs the provider in interactive TTY mode before showing the selector.
+- no-TTY and CI usage still require `--yes`; otherwise the command fails before provider execution.
+- `apply --run <run-id>` remains intentionally deferred to slice-05.

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

@@ -0,0 +1,72 @@
+{
+  "slice_id": "slice-04-interactive-apply-ux",
+  "ticket": "QUIVER-55-04",
+  "type": "ux",
+  "title": "Interactive Apply UX",
+  "objective": "Add the explained TTY selector for --apply-docs while delegating all writes to the tested apply engine.",
+  "description": "Implements the human selector with option descriptions, dynamic recommendation, diff flow, save/edit/cancel actions, and bounded terminal output.",
+  "git": {
+    "branch_type": "feature",
+    "base_branch": "main",
+    "branch_slug": "v55-interactive-apply-ux",
+    "branch_name": "feature/QUIVER-55-04-v55-interactive-apply-ux"
+  },
+  "files": [
+    "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",
+    "specs/quiver-v55-analyze-project-doc-apply-ux/**"
+  ],
+  "expected_read_paths": [
+    "src/create-quiver/lib/cli/ux.js",
+    "src/create-quiver/lib/ai/analyze-project-review.js",
+    "src/create-quiver/lib/ai/analyze-project-apply.js"
+  ],
+  "allowed_write_paths": [
+    "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",
+    "specs/quiver-v55-analyze-project-doc-apply-ux/**"
+  ],
+  "depends_on": [
+    "slice-03-noninteractive-apply-engine"
+  ],
+  "parallel_safe": "never",
+  "parallel_safe_reason": "Selector behavior depends on the completed apply engine contract.",
+  "must": [
+    "Show option descriptions.",
+    "Use dynamic recommendation.",
+    "Keep terminal diff bounded.",
+    "Route write actions through apply engine."
+  ],
+  "not_included": [
+    "Apply saved run.",
+    "Release smoke docs."
+  ],
+  "acceptance": [
+    "TTY --apply-docs shows explained selector.",
+    "no-TTY --apply-docs without --yes fails actionably.",
+    "Cancel writes no final docs.",
+    "View diff requires a second decision."
+  ],
+  "tests": [
+    "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"
+  ],
+  "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-05-apply-saved-proposal/CLOSURE_BRIEF.md

@@ -0,0 +1,42 @@
+# CLOSURE_BRIEF - slice-05 apply saved proposal
+
+## Summary
+
+Completed. `ai analyze-project apply --run <run-id>` now loads a saved analyze-project doc proposal from `.quiver/runs/<run-id>/proposal/`, revalidates the manifest and proposal JSON, and applies it through the same safe apply engine without executing a provider or requiring provider/model flags.
+
+## Behavior Delivered
+
+- Explicit run ids are validated as safe single path segments before artifact access.
+- Missing or invalid saved proposal manifests fail before docs writes.
+- Saved proposal JSON is reparsed through the doc proposal schema and allowed-path checks.
+- Saved proposal manifest doc paths must match the proposal target docs.
+- Manual proposal content edits are accepted only after revalidation and recorded as `saved-proposal-edited` in the write manifest.
+- Dirty target docs block by default and can be applied only with `--allow-dirty-docs`.
+- Stale target docs block before any final docs write.
+- `--run latest` is resolved only in an interactive terminal, and is rejected with `--yes` or `--json`.
+- Apply-run reports set `provider_execution: skipped` and do not call provider/model resolution.
+
+## Required Evidence
+
+- Apply saved run success test passes.
+- Invalid run id test passes.
+- Stale/dirty blocking tests pass.
+- No-provider-execution test passes.
+- Manual proposal edit audit test passes.
+
+## Validation
+
+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.

package/specs/quiver-v55-analyze-project-doc-apply-ux/slices/slice-05-apply-saved-proposal/EXECUTION_BRIEF.md

@@ -0,0 +1,61 @@
+# EXECUTION_BRIEF - slice-05 apply saved proposal
+
+## Context
+
+Saving a proposal is only useful if users can later apply it without re-running the provider. This flow has a higher trust boundary because proposal artifacts may be stale or manually edited.
+
+## Objective
+
+Implement `ai analyze-project apply --run <run-id>` to apply saved proposals without provider execution.
+
+## Scope
+
+- Resolve and validate run id.
+- Load proposal manifest and normalized JSON.
+- Revalidate proposal schema and allowed paths.
+- Recalculate target doc hashes.
+- Detect stale/dirty docs before writing.
+- Apply through the same apply engine from slice-03.
+- Support `--yes`, `--strict`, `--allow-dirty-docs`, and `--json` where safe.
+- Optionally support `--run latest` only in TTY and never with `--yes`.
+
+## Acceptance Criteria
+
+- `apply --run <run-id>` does not execute provider and does not require provider/model.
+- Invalid or missing run id fails with actionable guidance.
+- Missing/invalid proposal manifest fails without docs writes.
+- Stale or dirty docs block non-interactive apply unless explicitly allowed.
+- Manual proposal edits are accepted only after full revalidation and recorded as edited.
+- `--run latest --yes` is rejected.
+
+## 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-proposal.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-proposal.test.js
+node bin/create-quiver.js spec validate specs/quiver-v55-analyze-project-doc-apply-ux --strict
+git diff --check
+```
+
+## Completion Checklist
+
+- Saved proposal apply path never executes provider.
+- Proposal manifest and normalized JSON are revalidated before writes.
+- Stale/dirty target docs behavior is tested.
+- Edited proposal audit metadata is recorded.
+- Slice closure brief updated with evidence.
+
+## Constraints
+
+- Do not execute provider in `apply --run`.
+- Do not trust saved artifacts without revalidation.
+- Do not allow ambiguous `latest` in automation.

package/specs/quiver-v55-analyze-project-doc-apply-ux/slices/slice-05-apply-saved-proposal/pr.md

@@ -0,0 +1,129 @@
+## Title
+
+QUIVER-55-05 - Apply Saved Analyze Project Proposals
+
+## Summary
+
+Implements the fifth v55 slice for `ai analyze-project`: saved documentation proposals can now be applied by run id without executing a provider.
+
+`ai analyze-project apply --run <run-id>` now loads `.quiver/runs/<run-id>/proposal/manifest.json`, revalidates the saved proposal JSON, checks dirty/stale target docs, and delegates final writes to the existing safe apply engine.
+
+## PR Policy
+
+- One slice, one commit, one PR.
+- Runtime CLI behavior change, so this must be an individual PR.
+- Human merge required after CI passes.
+
+## Scope
+
+Included:
+
+- `ai analyze-project apply --run <run-id>` runtime implementation.
+- Safe run id validation before artifact access.
+- Saved proposal manifest and JSON revalidation.
+- Dirty/stale doc blocking using the original saved proposal hashes.
+- Manual proposal edit detection and write-manifest audit events.
+- `--run latest` guardrails for interactive-only usage.
+- Apply-run post-write validation without requiring the original provider analysis payload.
+- Tests for success, missing artifacts, dirty/stale blocking, no-provider execution, and manual proposal edits.
+- Slice status, evidence, closure, and PR docs.
+
+Excluded:
+
+- Fresh provider prompt/schema changes.
+- Product repo code changes in analyzed projects.
+- Release smoke docs for npm publishing.
+
+## Files
+
+- `src/create-quiver/commands/ai.js`
+- `src/create-quiver/index.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`
+- `tests/commands/ai-analyze-project-review.test.js`
+- `tests/commands/ai-analyze-project.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/npm environment for this repo.
+- No live provider credentials required for automated tests.
+
+### Worktree Access
+
+```bash
+git checkout feature/QUIVER-55-05-v55-apply-saved-proposal
+```
+
+### Run the Project
+
+No dev server is required. This is CLI behavior.
+
+### Use Cases
+
+1. Apply a saved proposal by run id:
+
+```bash
+node --test tests/commands/ai-analyze-project-review.test.js
+```
+
+Expected: saved proposal apply writes docs without provider execution, blocks dirty/stale targets, and records manual proposal edits.
+
+2. Validate saved proposal artifact helpers:
+
+```bash
+node --test tests/lib/ai-analyze-project-proposal.test.js
+```
+
+Expected: run id validation, saved proposal loading, manifest validation, and edit detection pass.
+
+3. Validate CLI contract:
+
+```bash
+node --test tests/commands/ai-analyze-project.test.js
+```
+
+Expected: `apply --run` no longer hits the old stub, missing artifacts fail actionably, and unsafe `latest` combinations are rejected.
+
+### Technical Verification
+
+```bash
+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
+```
+
+Expected: all pass.
+
+## Evidence
+
+Executed locally:
+
+```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.
+
+## Rollback
+
+Revert this PR. Fresh `--save-proposal`, `--apply-docs`, `--apply-docs --yes`, and `--review` behavior from earlier slices remain available.
+
+## Risks / Notes
+
+- `apply --run <run-id>` now writes docs when the saved proposal is valid and current target hashes match.
+- Stale docs always block; `--allow-dirty-docs` only bypasses the dirty-doc guard.
+- `--run latest` is intentionally not available for `--yes` or `--json` automation.

package/specs/quiver-v55-analyze-project-doc-apply-ux/slices/slice-05-apply-saved-proposal/slice.json

@@ -0,0 +1,67 @@
+{
+  "slice_id": "slice-05-apply-saved-proposal",
+  "ticket": "QUIVER-55-05",
+  "type": "feature",
+  "title": "Apply Saved Proposal",
+  "objective": "Apply saved analyze-project doc proposals by run id without provider execution.",
+  "description": "Adds ai analyze-project apply --run <run-id>, revalidates saved artifacts against current repo state, detects stale/dirty docs, and delegates writes to the apply engine.",
+  "git": {
+    "branch_type": "feature",
+    "base_branch": "main",
+    "branch_slug": "v55-apply-saved-proposal",
+    "branch_name": "feature/QUIVER-55-05-v55-apply-saved-proposal"
+  },
+  "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-proposal.test.js",
+    "specs/quiver-v55-analyze-project-doc-apply-ux/**"
+  ],
+  "expected_read_paths": [
+    "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-docs.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-proposal.test.js",
+    "specs/quiver-v55-analyze-project-doc-apply-ux/**"
+  ],
+  "depends_on": [
+    "slice-02-save-proposal-flow",
+    "slice-03-noninteractive-apply-engine"
+  ],
+  "parallel_safe": "never",
+  "parallel_safe_reason": "Saved-run apply crosses a trust boundary and must reuse completed apply engine behavior.",
+  "must": [
+    "Never run provider.",
+    "Revalidate saved proposal and manifest.",
+    "Detect stale/dirty target docs.",
+    "Reject --run latest --yes."
+  ],
+  "not_included": [
+    "Interactive fresh analysis selector.",
+    "Docs release smoke."
+  ],
+  "acceptance": [
+    "Explicit run id applies valid saved proposal.",
+    "Invalid run id fails actionably.",
+    "Stale saved proposal blocks unsafe writes.",
+    "Provider/model are not required."
+  ],
+  "tests": [
+    "node --test tests/commands/ai-analyze-project-review.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"
+  ],
+  "estimated_hours": 5,
+  "status": "completed",
+  "completed_at": "2026-06-12T15:00:00.000Z",
+  "blocked_reason": null
+}

package/specs/quiver-v55-analyze-project-doc-apply-ux/slices/slice-06-i18n-docs-release-smoke/CLOSURE_BRIEF.md

@@ -0,0 +1,38 @@
+# CLOSURE_BRIEF - slice-06 i18n docs release smoke
+
+## Summary
+
+Completed. The final v55 slice updates the user-facing docs, command matrix, troubleshooting guidance, and EN/ES coverage so the completed analyze-project doc apply workflow is discoverable and safe to smoke before release.
+
+## Behavior Delivered
+
+- `docs/reference/commands.md` now describes the recommended `--save-proposal`, `--apply-docs`, and `apply --run <run-id>` flows.
+- `docs/CLI_UX_GUIDE.md` documents the TTY selector, automation path, saved proposal path, and advanced `--review` mode.
+- `docs/workflows/existing-project.md` now recommends `--apply-docs` for existing projects and explains save/apply separation.
+- `docs/TROUBLESHOOTING.md` explains why normal provider mode does not write final docs and how to apply a proposal safely.
+- Release smoke guidance uses a temporary copy of `nika-erp` and explicitly avoids mutating the main checkout.
+- Spanish help coverage now asserts the new analyze-project flags are localized while commands, flags, and paths stay untranslated.
+
+## Required Evidence
+
+- i18n tests pass.
+- docs checks pass.
+- spec validation passes.
+- release smoke guidance is documented.
+
+## Validation
+
+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.

package/specs/quiver-v55-analyze-project-doc-apply-ux/slices/slice-06-i18n-docs-release-smoke/EXECUTION_BRIEF.md

@@ -0,0 +1,64 @@
+# EXECUTION_BRIEF - slice-06 i18n docs release smoke
+
+## Context
+
+The feature is only useful if users can discover the simpler apply flow and understand it in English and Spanish. Release confidence also needs a documented real-project smoke that avoids mutating the user's main `nika-erp` checkout.
+
+## Objective
+
+Complete i18n coverage, user documentation, command matrix/help alignment, and release smoke guidance.
+
+## Scope
+
+- Add/verify EN and ES messages for all new flows.
+- Ensure commands, flags, and paths remain untranslated.
+- Update:
+  - `docs/reference/commands.md`;
+  - `docs/CLI_UX_GUIDE.md`;
+  - `docs/workflows/existing-project.md`;
+  - `docs/TROUBLESHOOTING.md`.
+- Update i18n/UX command matrix if applicable.
+- Document release smoke against temporary copy/disposable branch of `nika-erp`.
+- Validate docs and spec.
+
+## Acceptance Criteria
+
+- English and Spanish outputs are covered by tests.
+- Command docs explain `--apply-docs`, `--save-proposal`, `--review`, `--yes`, `--diff`, and `apply --run`.
+- Troubleshooting explains why normal provider mode does not write final docs.
+- Release smoke commands avoid modifying the main `nika-erp` checkout.
+- Docs checks and spec validation pass.
+
+## Expected Files To Modify
+
+- `src/create-quiver/lib/i18n/messages/en.js`
+- `src/create-quiver/lib/i18n/messages/es.js`
+- `docs/reference/commands.md`
+- `docs/CLI_UX_GUIDE.md`
+- `docs/workflows/existing-project.md`
+- `docs/TROUBLESHOOTING.md`
+- `specs/quiver-v55-analyze-project-doc-apply-ux/**`
+- relevant tests
+
+## Validation Required
+
+```bash
+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
+```
+
+## Completion Checklist
+
+- English and Spanish copy tests pass.
+- Command reference and troubleshooting docs updated.
+- Existing-project workflow documents recommended path.
+- Release smoke evidence is recorded without mutating the main `nika-erp` checkout.
+- Slice closure brief updated with evidence.
+
+## Constraints
+
+- Do not run live provider smoke as CI.
+- Do not mutate the main `nika-erp` checkout during smoke.
+- Do not translate commands, flags, or paths.