create-quiver 0.15.0 → 0.15.2

package/docs/reference/commands.md

@@ -2,6 +2,25 @@
 
 Usá `npx --yes create-quiver@latest --help` para ver la lista viva de comandos soportados por la versión instalada.
 
+## npx vs instalación local
+
+Quiver está pensado para ejecutarse principalmente con `npx`:
+
+```bash
+npx --yes create-quiver@latest <comando>
+```
+
+En ese modo npm descarga o reutiliza el CLI desde su caché y no lo instala en `node_modules`. Eso es normal: `create-quiver` es una herramienta de workflow, no una dependencia runtime de la app.
+
+Instalalo como dependencia de desarrollo solo si querés fijar una versión para el equipo:
+
+```bash
+npm install --save-dev create-quiver
+npx create-quiver <comando>
+```
+
+Más detalle: [Instalación y uso con npx](../getting-started/installation.md).
+
 ## Configuración inicial
 
 | Comando | Para qué sirve |
@@ -26,16 +45,29 @@ Usá `npx --yes create-quiver@latest --help` para ver la lista viva de comandos
 | `npx --yes create-quiver@latest ai prepare-context --with-planner --dry-run` | Previsualiza una propuesta docs-only generada por el planner sin escribir archivos. |
 | `npx --yes create-quiver@latest ai prepare-context --with-planner --print-prompt` | Imprime el prompt exacto para ejecutar el planner en otro entorno. |
 | `npx --yes create-quiver@latest ai prepare-context --with-planner --review --interactive` | Ejecuta planner, abre revisión humana y pide confirmación antes de escribir docs permitidos. |
-| `npx --yes create-quiver@latest ai agent set <role> --provider <provider> --model "<label>"` | Guarda un perfil de agente sin secretos. |
+| `npx --yes create-quiver@latest ai models list` | Lista proveedores y modelos conocidos por Quiver sin afirmar disponibilidad en la cuenta. |
+| `npx --yes create-quiver@latest ai models list --provider codex` | Filtra el catálogo local por proveedor. |
+| `npx --yes create-quiver@latest ai models list --json` | Emite el catálogo local en JSON parseable. |
+| `npx --yes create-quiver@latest ai agent set <role>` | En TTY, guía la selección de proveedor, modelo conocido por Quiver o modelo custom. |
+| `npx --yes create-quiver@latest ai agent set <role> --provider <provider> --model <model-id>` | Guarda un perfil de agente sin secretos en modo script/no-TTY. |
+| `npx --yes create-quiver@latest ai agent set planner --provider codex --model gpt-5.5 --dry-run` | Previsualiza la escritura del perfil sin modificar `.quiver/agents/profiles.json`. |
+| `npx --yes create-quiver@latest ai agent doctor` | Diagnostica perfiles de agentes, alias visuales, proveedores faltantes y modelos custom no validados. |
+| `npx --yes create-quiver@latest ai agent doctor --json` | Emite el diagnóstico de perfiles como JSON parseable. |
+| `npx --yes create-quiver@latest ai agent repair --dry-run` | Previsualiza reparaciones seguras de perfiles, como normalizar `model: "GPT 5.5"` a `model: "gpt-5.5"` y `displayName: "GPT 5.5"`. |
 | `npx --yes create-quiver@latest ai run create --input <file>` | Inicia una ejecución persistente de IA. |
 | `npx --yes create-quiver@latest ai status` | Muestra el estado de la ejecución actual. |
 | `npx --yes create-quiver@latest ai plan --phase acceptance --input <file>` | Genera criterios de aceptación. |
 | `npx --yes create-quiver@latest ai plan --phase acceptance --review --interactive --input <file>` | Permite revisar y confirmar el borrador del planner antes de guardarlo. |
-| `npx --yes create-quiver@latest ai revise --phase acceptance --input <file>` | Crea una nueva versión de criterios. |
-| `npx --yes create-quiver@latest ai approve --phase acceptance --version <n>` | Aprueba criterios. |
+| `npx --yes create-quiver@latest ai revise --phase acceptance --input <feedback.md>` | Crea una nueva versión de criterios desde feedback; `--input` sin valor o archivos inexistentes fallan antes del proveedor. |
+| `npx --yes create-quiver@latest ai approve --phase acceptance` | En TTY lista drafts y recomienda el current/latest; en CI/no-TTY exige `--version <n>`. |
+| `npx --yes create-quiver@latest ai approve --phase acceptance --version <n>` | Aprueba criterios en modo explícito/script-safe. |
 | `npx --yes create-quiver@latest ai plan --phase technical-plan` | Genera plan técnico. |
-| `npx --yes create-quiver@latest ai review-plan` | Revisa el plan técnico. |
-| `npx --yes create-quiver@latest ai approve --phase technical-plan --version <n>` | Aprueba el plan técnico revisado. |
+| `npx --yes create-quiver@latest ai revise --phase technical-plan --input <feedback.md>` | Crea una nueva versión del plan técnico desde feedback. |
+| `npx --yes create-quiver@latest ai review-plan` | Revisa el plan técnico y guarda recomendación `approve`, `approve-with-risk` o `revise`. |
+| `npx --yes create-quiver@latest ai repair-plan` | Repara un plan técnico aprobado legacy que no cumple el contrato `spec.slices[]`, creando un nuevo draft. |
+| `npx --yes create-quiver@latest ai approve --phase technical-plan` | En TTY lista drafts con datos de review; `revise` bloquea aprobación y `approve-with-risk` muestra riesgos. |
+| `npx --yes create-quiver@latest ai approve --phase technical-plan --version <n>` | Aprueba el plan técnico revisado en modo explícito/script-safe. |
+| `npx --yes create-quiver@latest ai approvals` | Muestra approvals run-scoped/globales, candidatos actuales, versión recomendada y próximo comando. |
 
 ## Specs y slices
 
@@ -76,6 +108,7 @@ Usá `npx --yes create-quiver@latest --help` para ver la lista viva de comandos
 | `--methodology wdd-sdd` | Declara la metodología soportada por comandos interactivos o automatizados. |
 | `--no-color` | Desactiva colores ANSI en salida humana. |
 | `--provider codex\|claude\|gemini` | Selecciona CLI local de proveedor. |
+| `--model <model-id>` | Selecciona el identificador técnico del modelo para `ai agent set` o ejecución de proveedor. Quiver normaliza alias conocidos, pero no garantiza acceso en la cuenta del proveedor. |
 | `--commit` | Permite que Quiver commitee trabajo validado del slice. |
 | `--mode manual` | Imprime prompts para asignación manual de ejecutores. |
 | `--mode delegated` | Usa ejecución delegada con worktrees temporales cuando es seguro. |
@@ -90,6 +123,7 @@ Usá `npx --yes create-quiver@latest --help` para ver la lista viva de comandos
 | `ai plan` | sí | sí | sí |
 | `spec create` | sí | sí | sí |
 | `ai pr` | no | sí | sí |
+| `ai approve` | no | no | no |
 | `flow`, `next`, `graph` | no | no | no |
 | `ai inspect`, `ai export`, `ai specs list`, `ai slices list`, `ai trace report` | no | no | no |
 

package/package.json

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

package/specs/quiver-v31-ai-model-catalog-agent-selection/EVIDENCE_REPORT.md

@@ -0,0 +1,185 @@
+# Evidence Report - Quiver v31 AI Model Catalog and Agent Selection
+
+## Summary
+
+This report starts with documentation-only evidence for `slice-00`. Product implementation evidence must be appended by each later slice.
+
+## slice-00 - Spec foundation
+
+### Completed
+
+- Created v31 spec package with `SPEC.md`, `STATUS.md`, `EXECUTION_PLAN.md`, `EVIDENCE_REPORT.md`, and `pr.md`.
+- Created 8 slice folders with `slice.json`, `EXECUTION_BRIEF.md`, and `CLOSURE_BRIEF.md`.
+- Synchronized `README_FOR_AI.md` and `ROADMAP.md` to mark v31 as planned work.
+
+### Validation
+
+- `find specs/quiver-v31-ai-model-catalog-agent-selection -name 'slice.json' -print -exec node -e "JSON.parse(require('fs').readFileSync(process.argv[1], 'utf8')); console.log('ok', process.argv[1])" {} \;` passed for 8 slice files.
+- `node bin/create-quiver.js spec validate specs/quiver-v31-ai-model-catalog-agent-selection` passed and reported 8 slices.
+- `git diff --check` passed.
+
+### Risks Observed During Validation
+
+- The repo is currently ahead of `origin/main` by the local `v0.15.0` release commit from the prior npm publication attempt. This slice does not modify or resolve that release state.
+
+## Later Slices
+
+Each implementation slice must append:
+
+- commands executed;
+- tests or smokes run;
+- files changed;
+- validation result;
+- human and JSON output evidence when applicable;
+- remaining risks;
+- evidence location.
+
+## slice-01 - Local model catalog and alias normalization
+
+### Completed
+
+- Added `src/create-quiver/lib/ai/model-catalog.js` as the local, versioned model catalog source of truth.
+- Added Codex, Claude, and Gemini known model entries with aliases, role recommendations, cost/quality/stability metadata, and custom model support.
+- Added tolerant alias normalization for case, spaces, dashes, and punctuation.
+- Updated agent profile creation to normalize known visual aliases into technical model ids while preserving human `displayName`.
+- Preserved free-form custom model support and added optional profile metadata: `modelSource`, `modelAlias`, `validation_status`, `validated_at`, and `validation_error`.
+
+### Validation
+
+- `node --test tests/lib/model-catalog.test.js tests/lib/agent-profiles.test.js` passed: 10 tests.
+- `git diff --check` passed.
+
+### Risks
+
+- Catalog entries are local and can become stale. Later docs must keep the wording "known by Quiver" and avoid implying account-level availability.
+- Live provider validation and command preflight are intentionally deferred to later slices.
+
+## slice-02 - Interactive agent set provider and model selectors
+
+### Completed
+
+- Added interactive provider/model resolution for `ai agent set <role>`.
+- Added no-TTY/CI safeguards requiring explicit `--provider` and `--model`.
+- Added existing profile actions: update current, create new, change default, and cancel before writes.
+- Added provider CLI status hints in provider choices.
+- Added role-ordered model choices from the local catalog.
+- Added custom model id and display-name capture.
+- Added a write summary before saving profiles selected through prompts.
+- Made `ai agent` dispatch async-safe.
+
+### Validation
+
+- `node --test tests/commands/ai-agent.test.js tests/lib/cli-selectors.test.js tests/lib/model-catalog.test.js tests/lib/agent-profiles.test.js` passed: 30 tests.
+
+### Risks
+
+- Provider status is best-effort CLI detection and does not guarantee account-level model availability.
+- Interactive rendering is validated through injectable prompt helpers; real terminal behavior should be covered by smoke testing in the final slice.
+
+## slice-03 - Agent profile doctor and repair dry-run
+
+### Completed
+
+- Added pure profile diagnostics that evaluate every configured agent profile.
+- Added `ai agent doctor` with human output sections `Checks` and `Suggested fixes`.
+- Added `ai agent doctor --json` with parseable JSON output and no human prose.
+- Added exit code 1 when doctor errors are present.
+- Added `ai agent repair --dry-run` with before/after changes and no writes.
+- Added safe catalog-alias repair for legacy profiles such as `model: "GPT 5.5"`.
+- Added warnings for custom unvalidated models and provider CLI checks.
+- Updated CLI help for `ai agent doctor` and `ai agent repair`.
+
+### Validation
+
+- `node --test tests/commands/ai-agent.test.js tests/lib/agent-profiles.test.js tests/lib/model-catalog.test.js tests/lib/cli-selectors.test.js` passed: 36 tests.
+
+### Risks
+
+- Provider CLI checks are best-effort and do not prove selected model entitlement.
+- Repair write mode is intentionally unavailable until dry-run behavior is dogfooded.
+
+## slice-04 - Shared model preflight and provider error extraction
+
+### Completed
+
+- Added shared provider model alias resolution.
+- Added blocking policy for display aliases read from persisted profiles.
+- Added normalization for CLI `--model` display aliases in dry-run and invocation output.
+- Added provider error cause extraction for invalid model, auth, missing CLI, timeout, and generic failures.
+- Added provider failure serialization for non-zero exits where stderr contains the useful cause.
+- Applied model preflight options to planner, reviewer, repair-plan, execute-slice, and execute-plan runtime paths.
+- Added tests for `GPT 5.5` CLI override normalization, legacy profile blocking before provider execution, invalid model priority over MCP noise, and secret redaction.
+
+### Validation
+
+- `node --test tests/lib/ai-providers.test.js tests/commands/ai-prepare-context-planner.test.js tests/commands/ai-execute-slice.test.js` passed: 35 tests.
+- `node --test tests/lib/ai-providers.test.js tests/commands/ai-prepare-context-planner.test.js tests/commands/ai-plan.test.js tests/commands/ai-review-plan.test.js tests/commands/ai-execute-slice.test.js tests/commands/ai-execute-plan.test.js` passed: 78 tests.
+
+### Risks
+
+- Provider stderr patterns can change; future observed failures should become fixtures.
+- Custom models remain allowed and can only be proven through live provider validation.
+
+## slice-05 - AI models list command
+
+### Completed
+
+- Added `ai models list`.
+- Added `--provider <id>` filtering for catalog providers.
+- Added `--json` clean machine output with `catalogVersion` and `lastUpdated`.
+- Updated CLI help and contract tests.
+- Added human output wording that says models are known by Quiver and avoids claiming availability.
+
+### Validation
+
+- `node --test tests/commands/ai-models.test.js tests/commands/cli-contract.test.js` passed: 11 tests.
+
+### Risks
+
+- The model catalog is local and can become stale until Quiver has a remote/update mechanism.
+
+## slice-06 - Documentation and generated template alignment
+
+### Completed
+
+- Updated `README.md` with concise public-facing model catalog, agent setup, doctor, and repair commands.
+- Updated `docs/reference/commands.md` with interactive and script-safe agent setup, `ai models list`, `ai agent doctor`, and `ai agent repair --dry-run`.
+- Updated `docs/CLI_UX_GUIDE.md` with the profile data contract: `model` is the provider technical id and `displayName` is the human label.
+- Updated generated project templates: `docs/COMMANDS.md.template`, `docs/AI_ONBOARDING_PROMPT.md.template`, and `docs/AI_CONTEXT.md.template`.
+- Updated `README_FOR_AI.md`, `ROADMAP.md`, `STATUS.md`, and the slice closure to reflect completed docs/templates alignment without claiming package publication.
+
+### Validation
+
+- `node bin/create-quiver.js --help` passed and exposed `ai models list`, `ai agent doctor`, and `ai agent repair --dry-run`.
+- `node bin/create-quiver.js ai models list --provider codex` passed and printed "Models are known by Quiver; provider account access is not guaranteed."
+- `node bin/create-quiver.js spec validate specs/quiver-v31-ai-model-catalog-agent-selection` passed with a warning before this evidence section was appended.
+- `git diff --check` passed.
+
+### Risks
+
+- The final release-readiness slice must verify the CLI help contract after docs alignment.
+- The local model catalog can become stale until Quiver has a remote/update mechanism.
+
+## slice-07 - Tests, smokes, package dry-run, and release readiness
+
+### Completed
+
+- Corrected remaining CLI help/flow guidance so `--model` is documented as a technical model id, not a free-form label.
+- Updated contract tests and `smoke:create-quiver` packaged-help assertions for `ai agent doctor`, `ai agent repair --dry-run`, `ai models list`, and `--model <model-id>`.
+- Updated release docs: `CHANGELOG.md`, `README_FOR_AI.md`, `ROADMAP.md`, `STATUS.md`, `pr.md`, and this evidence report.
+
+### Validation
+
+- `node --test tests/commands/cli-contract.test.js tests/commands/flow.test.js tests/commands/ai-agent.test.js tests/lib/agent-profiles.test.js` passed: 44 tests.
+- `node --test tests/**/*.test.js` passed: 482 tests.
+- `npm run smoke:doctor-fixtures` passed: 13 fixture states.
+- `npm run smoke:create-quiver` passed after updating packaged-help expectations.
+- `npm run smoke:guided-workflow` passed.
+- `npm run package:quiver` passed with package smoke.
+- `npm pack --dry-run` passed and generated dry-run tarball details for `create-quiver@0.15.0`.
+
+### Risks
+
+- npm publication was not performed and still requires explicit human approval.
+- Live provider model entitlement was not tested because it depends on provider CLI/account access and may consume tokens.
+- The local model catalog remains manually maintained until Quiver has a remote/update mechanism.

package/specs/quiver-v31-ai-model-catalog-agent-selection/EXECUTION_PLAN.md

@@ -0,0 +1,85 @@
+# Execution Plan - Quiver v31 AI Model Catalog and Agent Selection
+
+## Execution Order
+
+```mermaid
+flowchart TD
+    S00[slice-00: Spec foundation]
+    S01[slice-01: Model catalog and alias normalization]
+    S02[slice-02: Interactive agent set selectors]
+    S03[slice-03: Agent doctor and repair dry-run]
+    S04[slice-04: Shared preflight and provider errors]
+    S05[slice-05: AI models list]
+    S06[slice-06: Docs and templates alignment]
+    S07[slice-07: Tests, smokes, and release readiness]
+
+    S00 --> S01
+    S01 --> S02
+    S01 --> S03
+    S01 --> S04
+    S01 --> S05
+    S02 --> S03
+    S03 --> S04
+    S04 --> S06
+    S05 --> S06
+    S06 --> S07
+```
+
+## Waves
+
+### Wave 0 - Sequential
+
+1. `slice-00-spec-foundation`
+
+This slice must run first. It commits the approved spec, every slice, handoffs, execution plan, PR body, and source-of-truth documentation sync.
+
+### Wave 1 - Sequential Core
+
+1. `slice-01-model-catalog-alias-normalization`
+
+The catalog and model-resolution contract must exist before selectors, doctor, repair, or live command preflight can use it.
+
+### Wave 2 - Parallel after slice-01
+
+- `slice-02-interactive-agent-set-selectors`
+- `slice-05-ai-models-list`
+
+These can run in parallel if their write scopes stay separated.
+
+### Wave 3 - Sequential Diagnostics and Runtime
+
+1. `slice-03-agent-doctor-repair`
+2. `slice-04-shared-preflight-provider-errors`
+
+Doctor/repair should land before command preflight so existing-profile diagnostics and preflight reuse the same issue classification.
+
+### Wave 4 - Sequential Docs
+
+1. `slice-06-docs-templates-alignment`
+
+Docs depend on the final command names and output contracts.
+
+### Wave 5 - Sequential Close
+
+1. `slice-07-tests-smokes-release-readiness`
+
+Final validation is never parallel-safe.
+
+## Parallel Safety Notes
+
+- Do not run any implementation slice before `slice-00`.
+- Do not implement selectors before catalog helpers exist.
+- Do not add live command preflight before doctor/repair issue classification is stable.
+- `slice-02` and `slice-05` may both touch `commands/ai.js`; if conflicts are likely, run `slice-02` first.
+- `slice-07` must close the spec after all other slices.
+
+## Recommended Commit Order
+
+1. `docs: add v31 ai model catalog spec`
+2. `feat: add ai model catalog normalization`
+3. `feat: add interactive agent model selectors`
+4. `feat: add agent profile doctor repair`
+5. `feat: add ai model preflight errors`
+6. `feat: add ai models list`
+7. `docs: document ai model catalog setup`
+8. `docs: close v31 model catalog release readiness`