create-quiver 0.17.5 → 0.17.6

package/docs/TROUBLESHOOTING.md

@@ -131,6 +131,58 @@ npx --yes create-quiver@latest ai analyze-project apply --run <run-id>
 
 `--review` sigue disponible como modo avanzado si querés editar la propuesta JSON manualmente antes de escribir.
 
+## `ai analyze-project` falla con `evidence-not-selected`
+
+### Síntoma
+
+El comando:
+
+```bash
+npx --yes create-quiver@latest ai analyze-project --deep --provider codex --model gpt-5.5
+```
+
+falla con un mensaje como:
+
+```text
+provider analysis JSON failed evidence validation
+evidence-not-selected
+```
+
+### Explicación
+
+El provider citó una ruta que no estaba dentro de la muestra enviada. Quiver mantiene esa validación porque evita que el modelo afirme cosas usando archivos que no leyó.
+
+En versiones actuales, Quiver clasifica esas rutas antes de sugerir un fix:
+
+- rutas seguras omitidas por presupuesto pueden recomendar `--max-files` o `--max-bytes` mayores;
+- tests omitidos pueden recomendar `--include-tests`;
+- DB/schema omitidos pueden recomendar `--include-db`;
+- `.env`, secretos, `.git`, `.quiver`, dependencias, caches, dumps, binarios y outputs generados no se recomiendan;
+- `.env.example` se trata como metadata/redacted, no como contenido seguro completo.
+
+### Qué hacer
+
+Usá el comando exacto que Quiver imprime debajo de `Recommended fix` o `Solucion recomendada`. Por ejemplo:
+
+```bash
+npx --yes create-quiver@latest ai analyze-project --deep --max-files 120 --max-bytes 500000 --provider codex --model gpt-5.5
+```
+
+Si Quiver no puede recomendar un aumento seguro porque se exceden los caps o la evidencia no debe enviarse, inspeccioná la muestra y acotá el scope:
+
+```bash
+npx --yes create-quiver@latest ai analyze-project --deep --dry-run --json
+npx --yes create-quiver@latest ai analyze-project --deep --scope apps/web --provider codex --model gpt-5.5
+```
+
+La auditoría queda en:
+
+```text
+.quiver/runs/run-.../validation/analyze-project-validation.json
+```
+
+Ese manifest incluye `recovery`, con clasificación de rutas, presupuesto calculado, comando sugerido y warnings.
+
 ## `ai analyze-project` no completa `docs/CONTEXTO.md` ni crea `docs/ARCHITECTURE.md`
 
 ### Síntoma

package/docs/reference/commands.md

@@ -226,6 +226,7 @@ Garantías del flujo con proveedor:
 - Si el proveedor devuelve JSON con drift seguro como `notes`, `claim` usado como `name` faltante, o `confidence` en paths no permitidos, Quiver lo repara, registra el repair y revalida.
 - Si el JSON sigue inválido pero el error es retryable, Quiver hace 1 retry por defecto, con cap duro de 2 retries.
 - Si el JSON final es inválido, Quiver falla sin escribir docs finales y deja manifests de validación/retry/repair en `.quiver/runs`.
+- Si el proveedor cita evidencia fuera de la muestra seleccionada, Quiver clasifica esas rutas, no recomienda incluir secretos ni binarios, y muestra una `Recommended fix` / `Solucion recomendada` con un comando seguro cuando corresponde.
 - El modo provider normal aplica docs finales por defecto después de validar la propuesta, crear proposal artifacts, snapshot, write manifest y validación post-write.
 - `--apply-docs` en TTY muestra opciones explicadas para aplicar, ver diff, guardar propuesta, editar propuesta o cancelar.
 - `--apply-docs --yes` aplica en automatización después de validar propuesta, paths permitidos, hashes, snapshot y post-write.
@@ -260,6 +261,7 @@ Evidencia esperada:
 - `package-lock.json` aparece en `detected.lockfiles` y en omitidos con `sampling:lockfile-metadata`, no en contenido enviado al provider.
 - El modo provider escribe artifacts auditados en `.quiver/runs`, redactados y con tamaño controlado, y aplica docs finales validados por defecto.
 - Si el provider devuelve drift no reparable, el comando falla con path/tipo/causa probable y próximo comando seguro, sin escribir docs finales.
+- Si el error es `evidence-not-selected`, el validation manifest incluye un bloque `recovery` con clasificación de rutas, presupuesto calculado, warnings y comando recomendado. Por ejemplo, si el provider citó tests omitidos, Quiver puede sugerir `--include-tests`; si faltó presupuesto seguro, puede sugerir `--max-files` y `--max-bytes` mayores. Si la evidencia es `.env`, dependencias, caches, dumps o binarios, no la recomienda.
 - `--save-proposal` debe crear `.quiver/runs/<run-id>/proposal/*` sin modificar docs finales.
 - `--apply-docs` debe mostrar selector explicado en TTY o requerir `--yes` en automatización.
 - `apply --run <run-id>` debe aplicar la propuesta guardada sin volver a ejecutar proveedor.
@@ -283,6 +285,7 @@ Rollback de release:
 | `npx --yes create-quiver@latest ai analyze-project --deep --apply-docs --yes --provider codex --model gpt-5.5` | Aplica docs validados en modo automatizado, con snapshots y validación post-write. |
 | `npx --yes create-quiver@latest ai analyze-project apply --run <run-id>` | Aplica una propuesta guardada sin ejecutar proveedor ni requerir `--provider` o `--model`. |
 | `npx --yes create-quiver@latest ai analyze-project --scope apps/web --max-files 80 --max-bytes 300000 --include-tests --dry-run` | Acota el análisis por workspace/ruta y presupuesto de muestra. |
+| `npx --yes create-quiver@latest ai analyze-project --deep --max-files 120 --max-bytes 500000 --provider codex --model gpt-5.5` | Ejemplo de rerun cuando Quiver recomienda ampliar una muestra segura después de `evidence-not-selected`. Usá el comando exacto que imprime el error. |
 | `npx --yes create-quiver@latest ai prepare-context --dry-run` | Previsualiza actualizaciones documentales de contexto para IA. |
 | `npx --yes create-quiver@latest ai prepare-context` | Escribe actualizaciones documentales de contexto para IA. |
 | `npx --yes create-quiver@latest ai prepare-context --with-planner --dry-run` | Previsualiza una propuesta docs-only generada por el planner sin escribir archivos. |

package/docs/workflows/existing-project-ai-quiver-setup.md

@@ -108,7 +108,6 @@ Archivos que puede crear o actualizar:
 ```bash
 npx --yes create-quiver@latest ai analyze-project \
   --deep \
-  --review \
   --provider codex \
   --model gpt-5.5
 ```

package/docs/workflows/existing-project.md

@@ -98,6 +98,7 @@ Qué hace:
 - muestra loader en TTY y progreso lineal en no-TTY;
 - si hay drift seguro de schema, como `notes` extra, `claim` usado como `name` faltante o `confidence` donde no está permitido, lo repara de forma auditada;
 - si el error es retryable, hace un retry acotado con feedback compacto;
+- si el provider cita evidencia fuera de la muestra, clasifica esas rutas y muestra una solución recomendada con `--include-tests`, `--include-db`, `--max-files` o `--max-bytes` solo cuando sea seguro;
 - si la propuesta final no es válida, falla sin escribir docs finales.
 
 Si preferís separar generación y aplicación:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-quiver",
-  "version": "0.17.5",
+  "version": "0.17.6",
   "private": false,
   "description": "Quiver CLI for scaffolding projects from the packaged template",
   "license": "MIT",

package/specs/quiver-v43-cli-i18n-audit-release-readiness/command-language-mode-matrix.json

@@ -610,6 +610,7 @@
     { "command": "ai analyze-project --deep --review", "profile": "ai-analyze-project", "critical": "pass" },
     { "command": "ai analyze-project --deep --provider codex --model gpt-5.5", "profile": "ai-analyze-project", "critical": "pass" },
     { "command": "ai analyze-project --deep --save-proposal --provider codex --model gpt-5.5", "profile": "ai-analyze-project", "critical": "pass" },
+    { "command": "ai analyze-project --deep --max-files 120 --max-bytes 500000 --provider codex --model gpt-5.5", "profile": "ai-analyze-project", "critical": "pass" },
     { "command": "ai analyze-project --deep --apply-docs --provider codex --model gpt-5.5", "profile": "ai-analyze-project", "critical": "pass" },
     { "command": "ai analyze-project --deep --apply-docs --yes --provider codex --model gpt-5.5", "profile": "ai-analyze-project", "critical": "pass" },
     { "command": "ai analyze-project apply --run <run-id>", "profile": "ai-analyze-project", "critical": "pass" },

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

@@ -0,0 +1,27 @@
+# Evidence Report - Quiver v57 Evidence Budget Recovery UX
+
+## Validation Log
+
+- 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`
+- Completed slice: `slice-01-recovery-contract-security-classifier`
+- Completed slice: `slice-02-budget-command-recommendation`
+- PASS `node --test tests/commands/ai-analyze-project-provider.test.js`
+- PASS `node --test tests/lib/i18n-catalog.test.js`
+- Completed slice: `slice-03-cli-json-i18n-output`
+- PASS `npm run docs:check`
+- Completed slice: `slice-04-integration-fixtures-docs-release-smoke`
+- 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 `node bin/create-quiver.js spec validate specs/quiver-v57-evidence-budget-recovery-ux --strict`
+- PASS `git diff --check`
+
+## Required Evidence Before Completion
+
+- Focused recovery unit tests. Completed for slice 01.
+- Budget and command recovery tests. Completed for slice 02.
+- Validation manifest compatibility tests. Completed for slice 03.
+- CLI output tests for English and Spanish. Completed for slice 03.
+- JSON recovery payload tests. Completed for slice 04 through `runAnalyzeProject --json` error payload coverage.
+- Sanitized nika-erp-style smoke. Covered by provider command fixture that reproduces omitted test evidence and metadata-only `.env.example` without private repo content.
+- Spec validation. Completed.
+- `git diff --check`. Completed.

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

@@ -0,0 +1,41 @@
+# Execution Plan - Quiver v57 Evidence Budget Recovery UX
+
+## Order
+
+1. `slice-01-recovery-contract-security-classifier`
+2. `slice-02-budget-command-recommendation`
+3. `slice-03-cli-json-i18n-output`
+4. `slice-04-integration-fixtures-docs-release-smoke`
+
+## Parallelism
+
+- Slice 01 is sequential and blocks everything else.
+- Slice 02 is sequential after Slice 01 because it consumes the classification contract.
+- Slice 03 is sequential after Slice 02 because it renders the recovery payload and must not recalculate safety or budget.
+- Slice 04 is final. Inside Slice 04, docs, release notes, and integration fixture work can be done in parallel once Slice 03 is complete.
+
+## PR Strategy
+
+- PR 1: Slice 01.
+- PR 2: Slice 02.
+- PR 3: Slice 03.
+- PR 4: Slice 04.
+
+## Validation Gates
+
+Each PR must run its focused tests plus:
+
+```bash
+git diff --check
+node bin/create-quiver.js spec validate specs/quiver-v57-evidence-budget-recovery-ux --strict
+```
+
+## Blocking Rule
+
+Do not start a later slice unless the previous slice has:
+
+- stable data contracts;
+- focused tests;
+- updated handoff status;
+- no unresolved safety ambiguity.
+

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`