create-quiver 0.17.4 → 0.17.6

package/specs/quiver-v57-evidence-budget-recovery-ux/SPEC.md

@@ -0,0 +1,139 @@
+# Quiver v57 - Evidence Budget Recovery UX
+
+**Date:** 2026-06-18
+**Status:** In Progress
+**Source:** User-approved requirement, production review, stricter second-pass review, and execution plan for recoverable `ai analyze-project` evidence validation failures.
+
+## Problem
+
+`ai analyze-project --deep --provider codex --model gpt-5.5` can fail safely when the provider cites evidence outside the selected context sample. The current failure is technically correct, but the user must infer whether the fix is increasing `--max-files`, increasing `--max-bytes`, enabling a category such as tests/db, or reducing scope. This creates avoidable friction after an expensive provider run.
+
+The real observed case in `nika-erp` failed with `evidence-not-selected` for paths such as `.env.example`, `eslint.config.mjs`, and `app/test/page.tsx`. A larger budget later succeeded, but Quiver did not calculate or highlight a safe command that would likely recover the run.
+
+## Objective
+
+When provider evidence validation fails because cited evidence was not selected, Quiver must generate a safe, auditable recovery payload and a prominent next command. The recovery must help the user rerun with the right context budget or scope without weakening evidence validation or sending unsafe files.
+
+## Scope
+
+### Included
+
+- Evidence recovery contract for `evidence-not-selected` failures.
+- Secure path normalization and classification.
+- Safety-first classification for missing evidence paths.
+- Deterministic budget recommendation for `--max-files` and `--max-bytes`.
+- Command recommendation that preserves relevant user flags.
+- Human CLI output in English and Spanish.
+- `--json` recovery payload.
+- Validation manifest recovery details.
+- Focused tests, docs, and release smoke with a sanitized nika-erp-style fixture.
+
+### Excluded
+
+- Auto-expanding context and retrying with a larger budget in the same run.
+- Sending or recommending unsafe files such as `.env`, secrets, dependency folders, build outputs, dumps, caches, or binaries.
+- Relaxing provider schema or evidence validation.
+- Modifying product code in the analyzed repository.
+- Generating specs automatically from project analysis.
+- Rewriting the existing sampling engine beyond metadata needed for recovery.
+
+## Requirements
+
+1. On final `evidence-not-selected` failure, Quiver must classify every missing evidence path before recommending any fix.
+2. Classification must be the single source of truth for recovery safety.
+3. Quiver must never recommend increasing budget to include paths excluded for security.
+4. Quiver must never read or send `.env`, secrets, `.git`, `node_modules`, `.next`, caches, dumps, dependency folders, or binaries.
+5. `.env.example` and similar files must be treated as metadata/redacted only unless existing policy explicitly allows safe content.
+6. Quiver must differentiate at least these causes:
+   - `budget_limited`
+   - `security_excluded`
+   - `generated_or_dependency`
+   - `metadata_only`
+   - `missing_file`
+   - `not_discovered`
+   - `outside_scope`
+   - `unknown`
+7. Quiver must calculate recommended budgets from the current selected sample, safe missing evidence, and a safety margin.
+8. Quiver must never recommend a budget lower than the one used by the failed command.
+9. Quiver must enforce caps and suggest scope reduction when a safe recommendation exceeds caps.
+10. Quiver must preserve relevant command flags such as `--deep`, `--provider`, `--model`, `--include-tests`, `--include-db`, `--include-source`, `--scope`, `--lang`, and `--strict`.
+11. Quiver must not preserve transient or contradictory flags in the recommended command when they are not useful for recovery, such as `--json`, `--dry-run`, or obsolete review/apply flags.
+12. Human output must show the recommended fix prominently before long details.
+13. Human output must summarize missing evidence paths and truncate long lists.
+14. Spanish output must be available through existing language selection.
+15. `--json` must expose a stable optional `recovery` object without breaking existing consumers.
+16. Validation manifests must record recovery classification, budget calculation inputs, generated command, and warnings.
+17. If no safe recovery exists, Quiver must say so clearly and recommend inspection with a safe dry-run JSON command.
+18. Recovery must be deterministic for the same validation issues, report, and CLI options.
+
+## Budget Recommendation Contract
+
+Recommended values are calculated only from classified safe evidence:
+
+```text
+safe_missing_bytes = sum(effective_prompt_bytes for safe_to_include missing evidence)
+safety_margin_bytes = max(50000, ceil(safe_missing_bytes * 0.25))
+recommended_max_bytes = round_up_to_50000(current_selected_bytes + safe_missing_bytes + safety_margin_bytes)
+recommended_max_files = max(current_max_files, current_selected_files + safe_missing_file_count + 20)
+```
+
+The final values must never be lower than the original command values. If the recommendation exceeds configured caps, Quiver must not emit an inflated command; it must recommend reducing scope or enabling a more precise category.
+
+## Recovery Output Shape
+
+`--json` and manifests may include:
+
+```json
+{
+  "recovery": {
+    "schema_version": 1,
+    "available": true,
+    "reason": "evidence_not_selected",
+    "recommendation_type": "increase_budget",
+    "command": "npx --yes create-quiver@latest ai analyze-project --deep --max-files 120 --max-bytes 500000 --provider codex --model gpt-5.5",
+    "budget": {
+      "current_max_files": 80,
+      "current_max_bytes": 300000,
+      "recommended_max_files": 120,
+      "recommended_max_bytes": 500000
+    },
+    "evidence_summary": {
+      "safe_to_include": [],
+      "metadata_only": [],
+      "excluded": []
+    },
+    "warnings": []
+  }
+}
+```
+
+The recovery object must be optional and additive.
+
+## Slice Roadmap
+
+| Slice | Title | Status | Dependencies | Parallel Guidance |
+|---|---|---|---|---|
+| slice-01-recovery-contract-security-classifier | Recovery Contract + Security Classifier | completed | none | sequential first |
+| slice-02-budget-command-recommendation | Budget + Command Recommendation | completed | slice-01 | sequential after slice-01 |
+| slice-03-cli-json-i18n-output | CLI + JSON + i18n Output | completed | slice-02 | sequential after slice-02 |
+| slice-04-integration-fixtures-docs-release-smoke | Integration Fixtures + Docs + Release Smoke | completed | slice-03 | final; docs/tests can be parallel inside the slice |
+
+## Production Guardrails
+
+- Provider output remains untrusted until schema and evidence validation pass.
+- Recovery is diagnostic only and must not weaken validation.
+- Recovery must not silently expand budget in the same run.
+- Recovery must not expose secret values or read unsafe content.
+- Failure remains a failure when final provider output is invalid.
+- Manifests must be audit-friendly but redacted.
+
+## Validation Strategy
+
+```bash
+node --test tests/lib/ai-analyze-project-recovery.test.js
+node --test tests/lib/ai-analyze-project-validation.test.js
+node --test tests/commands/ai-analyze-project-provider.test.js
+node --test tests/lib/i18n-catalog.test.js
+node bin/create-quiver.js spec validate specs/quiver-v57-evidence-budget-recovery-ux --strict
+git diff --check
+```

package/specs/quiver-v57-evidence-budget-recovery-ux/STATUS.md

@@ -0,0 +1,20 @@
+# Status - Quiver v57 Evidence Budget Recovery UX
+
+## Current State
+
+- Status: Completed
+- Active slice: none
+- Branch: `feature/QUIVER-57-01-recovery-contract-security-classifier`
+
+## Slice Status
+
+| Slice | Status | Notes |
+|---|---|---|
+| slice-01-recovery-contract-security-classifier | completed | Defines recovery data contract, path safety, classification, and manifest-ready payload base. |
+| slice-02-budget-command-recommendation | completed | Calculates safe budgets, caps, category flags, and one-line rerun commands from the slice-01 classification contract. |
+| slice-03-cli-json-i18n-output | completed | Renders recovery guidance in CLI errors, validation manifests, and English/Spanish messages. |
+| slice-04-integration-fixtures-docs-release-smoke | completed | Adds docs, JSON recovery coverage, troubleshooting guidance, and release evidence. |
+
+## Open Risks
+
+- No critical open risks. Live provider behavior should still be smoke-tested before npm release because external providers can drift.

package/specs/quiver-v57-evidence-budget-recovery-ux/pr.md

@@ -0,0 +1,124 @@
+## Title
+
+Quiver v57 Evidence Budget Recovery UX
+
+## Summary
+
+- Adds safe recovery guidance for `ai analyze-project` evidence validation failures.
+- Classifies missing evidence before recommending budget changes.
+- Calculates safe `--max-files` and `--max-bytes` rerun recommendations from classified evidence.
+- Adds prominent English/Spanish recovery output, JSON recovery errors, validation manifest recovery payloads, docs, and tests.
+
+## PR Policy
+
+- Type: feature.
+- Base: `main`.
+- Scope: Quiver v57 evidence-budget recovery UX.
+- Policy note: this PR groups the full v57 recovery feature because the slices are sequentially dependent and were executed as one approved implementation batch. The PR remains revertable as one feature change.
+- Merge: human merge required.
+
+## Scope
+
+Included:
+
+- Recovery classification for `evidence-not-selected` issues.
+- Safe handling of `.env`, `.env.example`, dependency folders, generated output, binaries, missing files, and paths outside the repo.
+- Budget recommendation and command builder.
+- Human CLI error guidance in English and Spanish.
+- `--json` error payload with optional `recovery`.
+- Validation manifest recovery payload.
+- Public docs and troubleshooting guidance.
+
+Excluded:
+
+- Auto-expanding context and retrying with a larger budget in the same run.
+- Relaxing provider schema or evidence validation.
+- Reading or sending unsafe files.
+- Product-code changes in analyzed repositories.
+
+## Files
+
+- `src/create-quiver/lib/ai/analyze-project-recovery.js`
+- `src/create-quiver/commands/ai.js`
+- `src/create-quiver/lib/ai/analyze-project-validation.js`
+- `src/create-quiver/lib/i18n/messages/en.js`
+- `src/create-quiver/lib/i18n/messages/es.js`
+- `tests/lib/ai-analyze-project-recovery.test.js`
+- `tests/commands/ai-analyze-project-provider.test.js`
+- `docs/TROUBLESHOOTING.md`
+- `docs/reference/commands.md`
+- `docs/workflows/existing-project.md`
+- `docs/workflows/existing-project-ai-quiver-setup.md`
+- `specs/quiver-v57-evidence-budget-recovery-ux/**`
+
+## How to Test (DETAILED - REQUIRED)
+
+### Required Environment
+
+- Node.js compatible with the repo.
+- npm dependencies installed.
+- GitHub CLI only needed for PR creation, not runtime tests.
+
+### Worktree Access
+
+From the repository root:
+
+```bash
+git status --short --branch
+```
+
+Expected branch:
+
+```text
+feature/QUIVER-57-01-recovery-contract-security-classifier
+```
+
+### Run the Project
+
+No dev server is required. This is a CLI/runtime validation change.
+
+### Use Cases
+
+1. Provider cites a test file outside the selected sample.
+   - Quiver fails validation.
+   - Quiver shows a recommended command that includes `--include-tests`.
+   - No docs are written.
+
+2. Provider cites `.env.example`.
+   - Quiver treats it as metadata-only/redacted.
+   - Quiver does not recommend including its raw content.
+
+3. Provider cites unsafe files.
+   - Quiver classifies them as excluded.
+   - Quiver does not recommend increasing budget for them.
+
+4. `--json` is used on final evidence validation failure.
+   - Quiver prints a parseable JSON error payload with optional `recovery`.
+   - Exit behavior remains failure.
+
+### Technical Verification
+
+```bash
+node --test tests/lib/ai-analyze-project-recovery.test.js tests/commands/ai-analyze-project-provider.test.js tests/lib/ai-analyze-project-validation.test.js tests/lib/i18n-catalog.test.js
+npm run docs:check
+node bin/create-quiver.js spec validate specs/quiver-v57-evidence-budget-recovery-ux --strict
+git diff --check
+```
+
+## Evidence
+
+- PASS `node --test tests/lib/ai-analyze-project-recovery.test.js tests/commands/ai-analyze-project-provider.test.js tests/lib/ai-analyze-project-validation.test.js tests/lib/i18n-catalog.test.js`
+- PASS `npm run docs:check`
+- PASS `node bin/create-quiver.js spec validate specs/quiver-v57-evidence-budget-recovery-ux --strict`
+- PASS `git diff --check`
+
+## Rollback
+
+Revert this PR. The feature is additive around failed `ai analyze-project` evidence validation. Existing validation remains strict, and runtime doc writes remain blocked when provider output is invalid.
+
+## Risks / Notes
+
+- Live provider behavior can still drift; run a smoke with a real provider before npm release.
+- The recovery command is diagnostic guidance only. It does not auto-expand context in the same run.
+- The validation manifest gains an optional `recovery` field; existing consumers should remain compatible.
+

package/specs/quiver-v57-evidence-budget-recovery-ux/slices/slice-01-recovery-contract-security-classifier/CLOSURE_BRIEF.md

@@ -0,0 +1,22 @@
+# CLOSURE_BRIEF - slice-01 Recovery Contract + Security Classifier
+
+## Summary
+
+Implemented the recovery classification contract for final `evidence-not-selected` failures.
+
+## Delivered
+
+- Added `src/create-quiver/lib/ai/analyze-project-recovery.js`.
+- Added deterministic evidence path normalization and classification helpers.
+- Classified safe, metadata-only, security-excluded, generated/dependency, missing, outside-scope, and unknown evidence.
+- Reused existing safety/path policies for env files, unsafe segments, file URLs, absolute paths, and traversal paths.
+- Added focused unit tests for safe, metadata-only, unsafe, missing, binary, generated, traversal, and issue aggregation cases.
+
+## Validation
+
+- PASS `node --test tests/lib/ai-analyze-project-recovery.test.js`
+- PASS `node bin/create-quiver.js spec validate specs/quiver-v57-evidence-budget-recovery-ux --strict`
+
+## Notes
+
+- This slice does not calculate budgets, render CLI output, or alter provider validation. Those remain assigned to later slices.

package/specs/quiver-v57-evidence-budget-recovery-ux/slices/slice-01-recovery-contract-security-classifier/EXECUTION_BRIEF.md

@@ -0,0 +1,58 @@
+# EXECUTION_BRIEF - slice-01 Recovery Contract + Security Classifier
+
+## Objective
+
+Implement the recovery contract and secure evidence path classifier for final `evidence-not-selected` failures.
+
+## Context
+
+`ai analyze-project` can fail when the provider cites paths outside the selected sample. This slice must not change CLI output or budget recommendation yet. It creates the safe classification layer that later slices will consume.
+
+## Scope
+
+- Add recovery data contract helpers.
+- Normalize and validate evidence paths as repo-relative paths.
+- Classify missing evidence paths without reading unsafe content.
+- Reuse or mirror existing analyze-project exclusion rules.
+- Detect safe, metadata-only, security-excluded, generated/dependency, missing, outside-scope, and unknown paths.
+- Produce deterministic, manifest-ready classification output.
+- Add focused unit tests.
+
+## Acceptance Criteria
+
+- Unsafe paths are never marked safe to include.
+- `.env`, `.git`, `node_modules`, `.next`, caches, dumps, and binaries are classified as excluded.
+- `.env.example` is classified as metadata-only/redacted, not content-safe.
+- Missing paths are classified without throwing.
+- Absolute paths, traversal paths, and paths outside the repo are rejected or classified as outside-scope.
+- Classification output is deterministic.
+- Unit tests cover safe, metadata-only, unsafe, missing, binary, generated, and traversal cases.
+
+## Expected Files
+
+- `src/create-quiver/lib/ai/analyze-project-recovery.js`
+- `tests/lib/ai-analyze-project-recovery.test.js`
+- `specs/quiver-v57-evidence-budget-recovery-ux/**`
+
+## Validation
+
+```bash
+node --test tests/lib/ai-analyze-project-recovery.test.js
+node bin/create-quiver.js spec validate specs/quiver-v57-evidence-budget-recovery-ux --strict
+git diff --check
+```
+
+## Completion Checklist
+
+- Recovery module exists and exports classifier helpers.
+- Unsafe paths are covered by tests.
+- Metadata-only env templates are covered by tests.
+- Missing, generated, dependency, binary, traversal, and budget-omitted paths are covered by tests.
+- Slice closure brief records validation evidence.
+
+## Constraints
+
+- Do not alter provider schema validation.
+- Do not alter CLI rendering in this slice.
+- Do not calculate final recommended budgets in this slice.
+- Do not read unsafe files to classify them.

package/specs/quiver-v57-evidence-budget-recovery-ux/slices/slice-01-recovery-contract-security-classifier/pr.md

@@ -0,0 +1,12 @@
+# PR - slice-01 Recovery Contract + Security Classifier
+
+## Summary
+
+- Adds a recovery classification module for `ai analyze-project` evidence validation failures.
+- Ensures unsafe paths are excluded before later slices calculate recovery budgets.
+- Adds tests for metadata-only env templates, unsafe paths, binary files, missing files, and deterministic issue aggregation.
+
+## Validation
+
+- PASS `node --test tests/lib/ai-analyze-project-recovery.test.js`
+- PASS `node bin/create-quiver.js spec validate specs/quiver-v57-evidence-budget-recovery-ux --strict`

package/specs/quiver-v57-evidence-budget-recovery-ux/slices/slice-01-recovery-contract-security-classifier/slice.json

@@ -0,0 +1,60 @@
+{
+  "slice_id": "slice-01-recovery-contract-security-classifier",
+  "ticket": "QUIVER-57-01",
+  "type": "feature",
+  "title": "Recovery Contract + Security Classifier",
+  "objective": "Implement safe evidence recovery classification for analyze-project evidence-not-selected failures.",
+  "description": "Defines the deterministic, security-first classifier used to decide whether evidence paths from provider validation failures are safe to recommend, metadata-only, missing, generated, or excluded.",
+  "git": {
+    "branch_type": "feature",
+    "base_branch": "main",
+    "branch_slug": "v57-recovery-contract-security-classifier",
+    "branch_name": "feature/QUIVER-57-01-recovery-contract-security-classifier"
+  },
+  "files": [
+    "src/create-quiver/lib/ai/analyze-project-recovery.js",
+    "tests/lib/ai-analyze-project-recovery.test.js",
+    "specs/quiver-v57-evidence-budget-recovery-ux/**"
+  ],
+  "allowed_write_paths": [
+    "src/create-quiver/lib/ai/analyze-project-recovery.js",
+    "tests/lib/ai-analyze-project-recovery.test.js",
+    "specs/quiver-v57-evidence-budget-recovery-ux/**"
+  ],
+  "depends_on": [],
+  "parallel_safe": "never",
+  "parallel_safe_reason": "This slice defines the security and classification contract consumed by every later slice.",
+  "must": [
+    "Normalize evidence paths as repo-relative paths.",
+    "Never read unsafe file contents for classification.",
+    "Classify safe, metadata-only, security-excluded, generated/dependency, missing, outside-scope, and unknown evidence.",
+    "Keep output deterministic and manifest-ready.",
+    "Add focused unit tests."
+  ],
+  "not_included": [
+    "Budget recommendation.",
+    "Recommended command builder.",
+    "CLI output changes.",
+    "JSON output integration.",
+    "i18n rendering."
+  ],
+  "acceptance": [
+    "Unsafe paths are never marked safe to include.",
+    ".env.example is metadata-only/redacted.",
+    "Missing and traversal paths do not throw.",
+    "Generated/dependency paths are excluded.",
+    "Binary files are excluded.",
+    "Classification output is deterministic."
+  ],
+  "tests": [
+    "node --test tests/lib/ai-analyze-project-recovery.test.js",
+    "node bin/create-quiver.js spec validate specs/quiver-v57-evidence-budget-recovery-ux --strict",
+    "git diff --check"
+  ],
+  "estimated_hours": 4,
+  "actual_hours": 4,
+  "status": "completed",
+  "blocked_reason": null,
+  "started_at": "2026-06-18T00:00:00.000Z",
+  "completed_at": "2026-06-18T00:00:00.000Z"
+}

package/specs/quiver-v57-evidence-budget-recovery-ux/slices/slice-02-budget-command-recommendation/CLOSURE_BRIEF.md

@@ -0,0 +1,9 @@
+# CLOSURE_BRIEF - slice-02 Budget + Command Recommendation
+
+## Summary
+
+Implemented budget and rerun command recommendation from the recovery classification contract.
+
+## Validation
+
+- PASS `node --test tests/lib/ai-analyze-project-recovery.test.js`

package/specs/quiver-v57-evidence-budget-recovery-ux/slices/slice-02-budget-command-recommendation/EXECUTION_BRIEF.md

@@ -0,0 +1,54 @@
+# EXECUTION_BRIEF - slice-02 Budget + Command Recommendation
+
+## Objective
+
+Calculate safe budget recommendations and a rerun command from the slice-01 recovery classification output.
+
+## Context
+
+This slice consumes classification data only. It must not decide path safety or read raw evidence paths directly.
+
+## Scope
+
+- Calculate `recommended_max_files` and `recommended_max_bytes`.
+- Preserve original budgets and never lower them.
+- Apply caps and return `scope_required` when recommendations exceed caps.
+- Prefer enabling category flags when appropriate.
+- Build a one-line portable command preserving relevant flags.
+- Add unit tests for budget math and command preservation.
+
+## Acceptance Criteria
+
+- Recommendations only use safe-to-include evidence.
+- Unsafe and metadata-only evidence do not increase budget.
+- Existing budget values are never reduced.
+- Caps prevent runaway recommendations.
+- Recommended command preserves `--deep`, provider/model, scope/category/lang/strict flags.
+- Transient flags such as `--json` and `--dry-run` are not preserved.
+
+## Expected Files
+
+- `src/create-quiver/lib/ai/analyze-project-recovery.js`
+- `tests/lib/ai-analyze-project-recovery.test.js`
+- `specs/quiver-v57-evidence-budget-recovery-ux/**`
+
+## Validation
+
+```bash
+node --test tests/lib/ai-analyze-project-recovery.test.js
+node bin/create-quiver.js spec validate specs/quiver-v57-evidence-budget-recovery-ux --strict
+git diff --check
+```
+
+## Completion Checklist
+
+- Budget formula is implemented from classification output only.
+- Caps are enforced and tested.
+- Command builder preserves relevant flags and drops transient flags.
+- Unsafe and metadata-only evidence do not increase budgets.
+- Slice closure brief records validation evidence.
+
+## Constraints
+
+- Do not alter CLI rendering in this slice.
+- Do not recalculate security.

package/specs/quiver-v57-evidence-budget-recovery-ux/slices/slice-02-budget-command-recommendation/pr.md

@@ -0,0 +1,12 @@
+# PR - slice-02 Budget + Command Recommendation
+
+## Summary
+
+- Adds budget calculation for safe missing evidence.
+- Adds recovery caps and `scope_required` fallback.
+- Adds one-line command builder that preserves relevant flags and drops transient flags.
+- Keeps unsafe and metadata-only evidence out of budget expansion.
+
+## Validation
+
+- PASS `node --test tests/lib/ai-analyze-project-recovery.test.js`

package/specs/quiver-v57-evidence-budget-recovery-ux/slices/slice-02-budget-command-recommendation/slice.json

@@ -0,0 +1,60 @@
+{
+  "slice_id": "slice-02-budget-command-recommendation",
+  "ticket": "QUIVER-57-02",
+  "type": "feature",
+  "title": "Budget + Command Recommendation",
+  "objective": "Generate safe rerun budget and command recommendations from recovery classification.",
+  "description": "Adds safe recovery budget calculation, caps, category flag hints, and a rerun command builder based only on classified evidence.",
+  "git": {
+    "branch_type": "feature",
+    "base_branch": "main",
+    "branch_slug": "v57-budget-command-recommendation",
+    "branch_name": "feature/QUIVER-57-02-v57-budget-command-recommendation"
+  },
+  "files": [
+    "src/create-quiver/lib/ai/analyze-project-recovery.js",
+    "tests/lib/ai-analyze-project-recovery.test.js",
+    "specs/quiver-v57-evidence-budget-recovery-ux/**"
+  ],
+  "allowed_write_paths": [
+    "src/create-quiver/lib/ai/analyze-project-recovery.js",
+    "tests/lib/ai-analyze-project-recovery.test.js",
+    "specs/quiver-v57-evidence-budget-recovery-ux/**"
+  ],
+  "depends_on": ["slice-01-recovery-contract-security-classifier"],
+  "parallel_safe": "never",
+  "parallel_safe_reason": "Consumes the finalized recovery classification contract.",
+  "must": [
+    "Calculate recommended max files and max bytes from recovery classification output only.",
+    "Never recommend budgets lower than the user's current effective budgets.",
+    "Apply caps so recovery cannot suggest runaway context expansion.",
+    "Preserve relevant analyze-project flags in the suggested command.",
+    "Drop transient or unsafe flags from the suggested command.",
+    "Ensure unsafe, generated, dependency, and metadata-only evidence does not increase recommended budgets."
+  ],
+  "not_included": [
+    "CLI rendering changes.",
+    "Security classification recalculation.",
+    "Automatic retry with expanded budgets.",
+    "Provider schema changes.",
+    "Relaxing evidence validation."
+  ],
+  "acceptance": [
+    "Recommendations are calculated only from safe evidence paths.",
+    "Unsafe and metadata-only evidence never increases the recommended budget.",
+    "Existing user budgets are not reduced.",
+    "Caps prevent unbounded max-files or max-bytes suggestions.",
+    "The suggested command preserves deep, provider, model, scope, category, language, and strict flags when applicable.",
+    "The suggested command omits transient output and execution flags."
+  ],
+  "actual_hours": 4,
+  "tests": [
+    "node --test tests/lib/ai-analyze-project-recovery.test.js",
+    "node bin/create-quiver.js spec validate specs/quiver-v57-evidence-budget-recovery-ux --strict",
+    "git diff --check"
+  ],
+  "estimated_hours": 4,
+  "status": "completed",
+  "started_at": "2026-06-18T00:00:00.000Z",
+  "completed_at": "2026-06-18T00:00:00.000Z"
+}

package/specs/quiver-v57-evidence-budget-recovery-ux/slices/slice-03-cli-json-i18n-output/CLOSURE_BRIEF.md

@@ -0,0 +1,10 @@
+# CLOSURE_BRIEF - slice-03 CLI + JSON + i18n Output
+
+## Summary
+
+Integrated recovery guidance into final analyze-project evidence validation failures.
+
+## Validation
+
+- PASS `node --test tests/commands/ai-analyze-project-provider.test.js`
+- PASS `node --test tests/lib/i18n-catalog.test.js`

package/specs/quiver-v57-evidence-budget-recovery-ux/slices/slice-03-cli-json-i18n-output/EXECUTION_BRIEF.md

@@ -0,0 +1,58 @@
+# EXECUTION_BRIEF - slice-03 CLI + JSON + i18n Output
+
+## Objective
+
+Render the recovery payload in human CLI output, JSON output, validation manifests, and English/Spanish messages.
+
+## Context
+
+This slice consumes the recovery payload from slice 02. It must not recalculate path safety or budget recommendations.
+
+## Scope
+
+- Integrate recovery payload into final `evidence-not-selected` failure handling.
+- Print prominent recommended fix before long issue details.
+- Add optional `recovery` object to `--json`.
+- Persist recovery payload in validation manifest.
+- Add English and Spanish messages.
+- Add focused command and i18n tests.
+
+## Acceptance Criteria
+
+- Human output highlights the recommended command or safe fallback.
+- Long missing evidence lists are grouped and truncated.
+- `--json` remains valid and backward-compatible.
+- Spanish output renders recovery guidance when `--lang es` is active.
+- Exit code remains non-zero for invalid final provider output.
+
+## Expected Files
+
+- `src/create-quiver/commands/ai.js`
+- `src/create-quiver/lib/ai/analyze-project-validation.js`
+- `src/create-quiver/lib/i18n/messages/en.js`
+- `src/create-quiver/lib/i18n/messages/es.js`
+- `tests/commands/ai-analyze-project-provider.test.js`
+- `tests/lib/i18n-catalog.test.js`
+- `specs/quiver-v57-evidence-budget-recovery-ux/**`
+
+## Validation
+
+```bash
+node --test tests/commands/ai-analyze-project-provider.test.js
+node --test tests/lib/i18n-catalog.test.js
+node bin/create-quiver.js spec validate specs/quiver-v57-evidence-budget-recovery-ux --strict
+git diff --check
+```
+
+## Completion Checklist
+
+- CLI output renders recovery guidance prominently.
+- JSON output includes optional recovery payload.
+- Validation manifest persists recovery payload.
+- English and Spanish copy are covered by tests.
+- Slice closure brief records validation evidence.
+
+## Constraints
+
+- Do not weaken validation.
+- Do not auto-apply recovery.

package/specs/quiver-v57-evidence-budget-recovery-ux/slices/slice-03-cli-json-i18n-output/pr.md

@@ -0,0 +1,13 @@
+# PR - slice-03 CLI + JSON + i18n Output
+
+## Summary
+
+- Adds prominent recovery guidance to final `evidence-not-selected` failures.
+- Adds optional recovery payload to validation manifests and thrown errors.
+- Adds English and Spanish recovery copy.
+- Covers Spanish recovery command output in provider command tests.
+
+## Validation
+
+- PASS `node --test tests/commands/ai-analyze-project-provider.test.js`
+- PASS `node --test tests/lib/i18n-catalog.test.js`