create-quiver 0.17.1 → 0.17.3

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

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

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

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

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

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

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.