create-quiver 0.17.1 → 0.17.3

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.

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

@@ -0,0 +1,123 @@
+## Title
+
+QUIVER-55-06 - i18n Docs And Release Smoke Guidance
+
+## Summary
+
+Completes the final v55 slice for `ai analyze-project` doc apply UX.
+
+This PR updates user-facing docs, troubleshooting, command reference, EN/ES help coverage, and release smoke guidance so users can discover the simple apply flow without being forced into the advanced editor review path.
+
+## PR Policy
+
+- One slice, one commit, one PR.
+- Docs/test release-readiness slice.
+- Human merge required after CI passes.
+
+## Scope
+
+Included:
+
+- Command reference updates for `--apply-docs`, `--save-proposal`, `--review`, `--yes`, `--diff`, and `apply --run`.
+- Existing-project workflow updates for the recommended `--apply-docs` path.
+- CLI UX guide updates for selector behavior, automation, saved proposals, and advanced `--review`.
+- Troubleshooting entry explaining why normal provider mode does not write final docs.
+- Safe release smoke guidance against a temporary copy or disposable branch of `nika-erp`.
+- Spanish help coverage for new analyze-project flags while preserving commands/flags untranslated.
+- Spec status, evidence, and closure updates.
+
+Excluded:
+
+- Runtime apply implementation changes.
+- Live provider CI gate.
+- Mutating the main `nika-erp` checkout.
+
+## Files
+
+- `docs/reference/commands.md`
+- `docs/CLI_UX_GUIDE.md`
+- `docs/workflows/existing-project.md`
+- `docs/TROUBLESHOOTING.md`
+- `tests/commands/cli-contract.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.
+
+### Worktree Access
+
+```bash
+git checkout feature/QUIVER-55-06-v55-i18n-docs-release-smoke
+```
+
+### Run the Project
+
+No dev server is required. This is CLI/docs behavior.
+
+### Use Cases
+
+1. Spanish help preserves command syntax:
+
+```bash
+node --test tests/commands/cli-contract.test.js
+```
+
+Expected: `ai analyze-project apply --run <run-id>` and new flags remain exact while Spanish descriptions are localized.
+
+2. i18n catalog coverage:
+
+```bash
+node --test tests/lib/i18n-catalog.test.js
+```
+
+Expected: EN/ES catalogs are complete and command snippets remain exact.
+
+3. Analyze-project apply UX regression coverage:
+
+```bash
+node --test tests/commands/ai-analyze-project-review.test.js
+```
+
+Expected: apply/save/diff/edit/cancel, Spanish selector copy, and apply-run paths remain covered.
+
+### 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
+```
+
+Expected: all pass.
+
+## Evidence
+
+Executed locally:
+
+```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.
+
+## Rollback
+
+Revert this PR. Runtime behavior from slices 01-05 remains intact; only docs/spec/test coverage from this slice is removed.
+
+## Risks / Notes
+
+- Live provider smoke remains release evidence only, not a CI gate.
+- Release smoke guidance intentionally uses a temporary copy or disposable branch for `nika-erp`.
+- `--review` remains documented as advanced JSON edit mode, not the default apply path.

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

@@ -0,0 +1,76 @@
+{
+  "slice_id": "slice-06-i18n-docs-release-smoke",
+  "ticket": "QUIVER-55-06",
+  "type": "docs-release",
+  "title": "i18n, Docs, Release Smoke",
+  "objective": "Complete bilingual UX coverage, documentation, command matrix alignment, and real-project release smoke guidance.",
+  "description": "Adds EN/ES copy coverage, updates user-facing docs, keeps generated command docs aligned, and documents safe nika-erp smoke using a temporary copy or disposable branch.",
+  "git": {
+    "branch_type": "feature",
+    "base_branch": "main",
+    "branch_slug": "v55-i18n-docs-release-smoke",
+    "branch_name": "feature/QUIVER-55-06-v55-i18n-docs-release-smoke"
+  },
+  "files": [
+    "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",
+    "tests/commands/**",
+    "tests/lib/**",
+    "specs/quiver-v55-analyze-project-doc-apply-ux/**"
+  ],
+  "expected_read_paths": [
+    "docs/reference/commands.md",
+    "docs/CLI_UX_GUIDE.md",
+    "docs/workflows/existing-project.md",
+    "docs/TROUBLESHOOTING.md",
+    "src/create-quiver/lib/i18n/messages/en.js",
+    "src/create-quiver/lib/i18n/messages/es.js"
+  ],
+  "allowed_write_paths": [
+    "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",
+    "tests/commands/**",
+    "tests/lib/**",
+    "specs/quiver-v55-analyze-project-doc-apply-ux/**"
+  ],
+  "depends_on": [
+    "slice-04-interactive-apply-ux",
+    "slice-05-apply-saved-proposal"
+  ],
+  "parallel_safe": "never",
+  "parallel_safe_reason": "Docs and i18n must reflect final behavior from earlier slices.",
+  "must": [
+    "Cover English and Spanish output.",
+    "Update docs and command matrix.",
+    "Document release smoke against a temporary copy or disposable branch.",
+    "Keep commands, flags, and paths untranslated."
+  ],
+  "not_included": [
+    "Runtime apply implementation.",
+    "Live provider CI gate."
+  ],
+  "acceptance": [
+    "EN/ES tests pass.",
+    "docs:check passes.",
+    "schema:slice:check passes.",
+    "Spec validation passes."
+  ],
+  "tests": [
+    "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"
+  ],
+  "estimated_hours": 4,
+  "status": "completed",
+  "completed_at": "2026-06-12T16:56:48.000Z",
+  "blocked_reason": null
+}