create-quiver 0.15.0 → 0.15.2

package/specs/quiver-v31-ai-model-catalog-agent-selection/slices/slice-01-model-catalog-alias-normalization/EXECUTION_BRIEF.md

@@ -0,0 +1,53 @@
+# EXECUTION_BRIEF - slice-01 Local model catalog and alias normalization
+
+## Context
+
+Quiver currently stores free-form model labels. Users can accidentally save display names as provider model ids, causing live provider failures.
+
+## Objective
+
+Create Quiver's local model catalog and shared alias normalization helpers.
+
+## Scope
+
+- `src/create-quiver/lib/ai/model-catalog.js`
+- `src/create-quiver/lib/agent-profiles.js`
+- related unit tests
+
+## Acceptance Criteria
+
+- Required Codex, Claude, and Gemini entries exist.
+- Catalog includes version and last updated date.
+- Aliases normalize case-insensitively and tolerate spaces/dashes.
+- `GPT 5.5`, `gpt 5.5`, `Gpt-5.5`, and `gpt-5.5` resolve to `gpt-5.5`.
+- Existing v2 profiles remain readable.
+- Custom models remain allowed.
+
+## Technical Plan Summary
+
+Add pure catalog/model-resolution helpers first. Later slices consume these helpers for prompts, doctor, repair, and live command preflight.
+
+## Suggested Steps
+
+1. Add `model-catalog.js`.
+2. Add helpers for listing providers/models, defaults by role, alias matching, and normalization.
+3. Extend profile building to use normalization where safe.
+4. Add tests for catalog shape and aliases.
+
+## Restrictions
+
+- Do not add prompts.
+- Do not execute provider CLIs.
+- Do not add remote catalog calls.
+
+## Risks
+
+- Catalog entries can become stale.
+- Alias collisions must not silently choose a model.
+
+## Completion Checklist
+
+- [ ] Catalog helpers implemented.
+- [ ] Alias normalization tested.
+- [ ] Legacy profile compatibility tested.
+- [ ] `git diff --check` passes.

package/specs/quiver-v31-ai-model-catalog-agent-selection/slices/slice-01-model-catalog-alias-normalization/slice.json

@@ -0,0 +1,72 @@
+{
+  "slice_id": "slice-01-model-catalog-alias-normalization",
+  "ticket": "QUIVER-31-01",
+  "type": "feature",
+  "title": "Local model catalog and alias normalization",
+  "objective": "Create Quiver's local provider/model catalog and shared model resolution helpers.",
+  "description": "Adds the source of truth for known providers, model ids, display names, aliases, role recommendations, metadata, and normalization.",
+  "git": {
+    "branch_type": "feature",
+    "base_branch": "main",
+    "branch_slug": "v31-model-catalog-alias-normalization",
+    "branch_name": "feature/QUIVER-31-01-v31-model-catalog-alias-normalization"
+  },
+  "files": [
+    "src/create-quiver/lib/ai/model-catalog.js",
+    "src/create-quiver/lib/agent-profiles.js",
+    "tests/lib/model-catalog.test.js",
+    "tests/lib/agent-profiles.test.js"
+  ],
+  "expected_read_paths": [
+    "SPEC.md",
+    "src/create-quiver/lib/ai/providers.js",
+    "src/create-quiver/lib/agent-profiles.js",
+    "tests/lib/ai-providers.test.js",
+    "tests/lib/agent-profiles.test.js"
+  ],
+  "allowed_write_paths": [
+    "src/create-quiver/lib/ai/model-catalog.js",
+    "src/create-quiver/lib/agent-profiles.js",
+    "tests/lib/model-catalog.test.js",
+    "tests/lib/agent-profiles.test.js",
+    "specs/quiver-v31-ai-model-catalog-agent-selection/**"
+  ],
+  "depends_on": [
+    "slice-00-spec-foundation"
+  ],
+  "parallel_safe": "no",
+  "parallel_safe_reason": "Catalog helpers are foundational for later selectors, doctor, repair, and preflight slices.",
+  "must": [
+    "Add a versioned catalog with catalogVersion and lastUpdated.",
+    "Include Codex, Claude, and Gemini models required by the spec.",
+    "Support aliases, role recommendations, cost/quality/stability metadata, and custom entries.",
+    "Normalize aliases case-insensitively and with tolerant spacing/dashes.",
+    "Keep existing v2 agent profiles readable.",
+    "Expose pure helpers that can be unit-tested without a TTY."
+  ],
+  "not_included": [
+    "Interactive prompts.",
+    "Live provider execution.",
+    "Remote catalog API."
+  ],
+  "acceptance": [
+    "All required model entries are available through the catalog.",
+    "`GPT 5.5`, `gpt 5.5`, `Gpt-5.5`, and `gpt-5.5` resolve to `gpt-5.5` for Codex.",
+    "Ambiguous aliases do not silently choose a model.",
+    "Custom models remain allowed with metadata indicating they are not catalog-validated.",
+    "Tests cover catalog shape, defaults, aliases, and legacy profile compatibility."
+  ],
+  "tests": [
+    "node --test tests/lib/model-catalog.test.js tests/lib/agent-profiles.test.js",
+    "git diff --check"
+  ],
+  "validation_hints": [
+    "Test pure functions directly instead of prompt flows.",
+    "Do not call provider CLIs in this slice."
+  ],
+  "estimated_hours": 6,
+  "status": "completed",
+  "blocked_reason": null,
+  "actual_hours": 5,
+  "completed_at": "2026-05-27"
+}

package/specs/quiver-v31-ai-model-catalog-agent-selection/slices/slice-02-interactive-agent-set-selectors/CLOSURE_BRIEF.md

@@ -0,0 +1,36 @@
+# CLOSURE_BRIEF - slice-02 Interactive agent set provider and model selectors
+
+## Summary
+
+Implemented guided provider/model resolution for `ai agent set <role>`.
+The command now supports interactive provider/model selectors when TTY prompts are available, requires explicit `--provider` and `--model` in non-interactive mode, supports existing profile actions, custom model ids, and a write summary before saving.
+
+## Validation Against Acceptance Criteria
+
+- [x] Interactive setup works through injectable selector helpers.
+- [x] No-TTY guardrails fail clearly without hanging.
+- [x] Existing profiles can be updated, extended, switched as default, or canceled before writes.
+- [x] Custom model flow captures technical id and display name.
+- [x] Known catalog selections write technical model ids and human display names.
+
+## Relevant Changes
+
+- Added reusable `promptText` support to CLI selectors.
+- Added provider/model selector resolution to `ai agent set`.
+- Added provider CLI status hints for provider choices.
+- Added role-ordered model choices from the local catalog.
+- Made `ai agent` dispatch async-safe.
+- Added tests for selector helpers, no-TTY behavior, interactive provider/model selection, custom models, and named profile creation.
+
+## Pending
+
+- Live validation and repair remain deferred to later slices.
+
+## Remaining Risks
+
+- Provider install status is best-effort and only detects CLI availability, not whether the selected account can run the chosen model.
+- Interactive prompt rendering itself is covered through injected selectors rather than a real terminal e2e test.
+
+## Future Recommendations
+
+Add richer live provider validation only after the selector flow is stable.

package/specs/quiver-v31-ai-model-catalog-agent-selection/slices/slice-02-interactive-agent-set-selectors/EXECUTION_BRIEF.md

@@ -0,0 +1,56 @@
+# EXECUTION_BRIEF - slice-02 Interactive agent set provider and model selectors
+
+## Context
+
+Agent setup currently requires users to know provider ids and exact model ids. v30 added selector primitives; v31 uses them to guide agent model setup.
+
+## Objective
+
+Make `ai agent set <role>` interactive in TTY mode when provider/model data is missing.
+
+## Scope
+
+- `src/create-quiver/commands/ai.js`
+- `src/create-quiver/lib/cli/selectors.js`
+- `src/create-quiver/lib/agent-profiles.js`
+- related tests
+
+## Acceptance Criteria
+
+- TTY setup shows provider and model selectors.
+- No-TTY/CI without required flags fails clearly.
+- Existing profiles are summarized before changes.
+- Users can update current, create new, change default, or cancel.
+- Custom model flow collects technical id and display name.
+- Cancellation writes no files.
+
+## Technical Plan Summary
+
+Reuse catalog helpers from slice-01 and selector helpers from v30. Keep prompt logic injectable for tests.
+
+## Suggested Steps
+
+1. Add a resolver for interactive agent setup options.
+2. Add provider selector with CLI install status.
+3. Add model selector ordered by role recommendations.
+4. Add summary before writes.
+5. Add no-TTY guardrails.
+6. Add tests for TTY, no-TTY, cancellation, and custom.
+
+## Restrictions
+
+- Do not implement agent doctor/repair here.
+- Do not force live validation.
+- Do not break scripted `--provider --model` usage.
+
+## Risks
+
+- Interactive tests can be brittle if logic is not separated from rendering.
+- Existing profile overwrite must be explicit.
+
+## Completion Checklist
+
+- [ ] TTY flow implemented.
+- [ ] No-TTY safety tested.
+- [ ] Existing profile flow tested.
+- [ ] Custom model flow tested.

package/specs/quiver-v31-ai-model-catalog-agent-selection/slices/slice-02-interactive-agent-set-selectors/slice.json

@@ -0,0 +1,78 @@
+{
+  "slice_id": "slice-02-interactive-agent-set-selectors",
+  "ticket": "QUIVER-31-02",
+  "type": "feature",
+  "title": "Interactive agent set provider and model selectors",
+  "objective": "Make `ai agent set <role>` guide users through provider and model selection in TTY mode.",
+  "description": "Adds a guided setup flow that shows providers, CLI install status, known models ordered by role, custom model input, summaries, cancellation, and no-TTY safeguards.",
+  "git": {
+    "branch_type": "feature",
+    "base_branch": "main",
+    "branch_slug": "v31-interactive-agent-set-selectors",
+    "branch_name": "feature/QUIVER-31-02-v31-interactive-agent-set-selectors"
+  },
+  "files": [
+    "src/create-quiver/commands/ai.js",
+    "src/create-quiver/lib/cli/selectors.js",
+    "src/create-quiver/lib/agent-profiles.js",
+    "tests/commands/ai-agent.test.js",
+    "tests/lib/cli-selectors.test.js"
+  ],
+  "expected_read_paths": [
+    "SPEC.md",
+    "src/create-quiver/lib/ai/model-catalog.js",
+    "src/create-quiver/lib/cli/selectors.js",
+    "src/create-quiver/lib/agent-profiles.js",
+    "tests/commands/ai-agent.test.js"
+  ],
+  "allowed_write_paths": [
+    "src/create-quiver/commands/ai.js",
+    "src/create-quiver/lib/cli/selectors.js",
+    "src/create-quiver/lib/agent-profiles.js",
+    "tests/commands/ai-agent.test.js",
+    "tests/lib/cli-selectors.test.js",
+    "specs/quiver-v31-ai-model-catalog-agent-selection/**"
+  ],
+  "depends_on": [
+    "slice-01-model-catalog-alias-normalization"
+  ],
+  "parallel_safe": "yes",
+  "parallel_safe_reason": "Can run in parallel with ai models list if command-file conflicts are coordinated.",
+  "must": [
+    "Open interactive setup automatically only in TTY when required flags are missing.",
+    "Fail clearly in no-TTY/CI when required flags are missing.",
+    "Show existing profiles before changes.",
+    "Support update current, create new, change default, and cancel.",
+    "Show provider CLI install status.",
+    "Order model choices by the requested role.",
+    "Support custom model id and display name.",
+    "Show a write summary before saving.",
+    "Do not write on cancellation."
+  ],
+  "not_included": [
+    "Agent doctor and repair.",
+    "Live validation execution unless a small reusable hook is needed and remains disabled by default.",
+    "Remote model catalog."
+  ],
+  "acceptance": [
+    "`ai agent set planner` in TTY shows provider/model selectors.",
+    "No-TTY command without flags fails without hanging.",
+    "Known model selection writes technical `model` and human `displayName`.",
+    "Custom selection writes a technical id and a default display name if none is provided.",
+    "Cancellation writes no profile changes.",
+    "Duplicate display names are distinguishable in selectors."
+  ],
+  "tests": [
+    "node --test tests/commands/ai-agent.test.js tests/lib/cli-selectors.test.js",
+    "git diff --check"
+  ],
+  "validation_hints": [
+    "Test prompt logic through injectable selector helpers.",
+    "Do not require a real interactive terminal in unit tests."
+  ],
+  "estimated_hours": 8,
+  "status": "completed",
+  "blocked_reason": null,
+  "actual_hours": 6,
+  "completed_at": "2026-05-27"
+}

package/specs/quiver-v31-ai-model-catalog-agent-selection/slices/slice-03-agent-doctor-repair/CLOSURE_BRIEF.md

@@ -0,0 +1,36 @@
+# CLOSURE_BRIEF - slice-03 Agent profile doctor and repair dry-run
+
+## Summary
+
+Implemented `ai agent doctor` and `ai agent repair --dry-run` for existing agent profile diagnostics and safe repair previews.
+
+## Validation Against Acceptance Criteria
+
+- [x] Doctor checks every configured profile, not only defaults.
+- [x] Severity and exit codes behave correctly; errors set exit code 1.
+- [x] Repair dry-run shows proposed changes only and writes no files.
+- [x] Human and JSON output contracts pass.
+- [x] Unsupported providers are errors.
+- [x] Display aliases in `model` are detected and repairable.
+- [x] Custom unvalidated models are warnings.
+
+## Relevant Changes
+
+- Added pure doctor report and repair-plan builders in `agent-profiles.js`.
+- Added `ai agent doctor` with human and JSON output.
+- Added `ai agent repair --dry-run` with before/after repair previews.
+- Updated help text to expose `ai agent doctor` and `ai agent repair`.
+- Added CLI and library tests for invalid legacy profiles, alias repair, JSON output, and no-write repair behavior.
+
+## Pending
+
+- Write-mode repair remains intentionally unavailable.
+
+## Remaining Risks
+
+- Provider CLI checks are best-effort and do not prove account/model entitlement.
+- Repair currently only normalizes safe catalog alias issues; unsupported providers and custom models still require human action.
+
+## Future Recommendations
+
+Consider write-mode repair only after dry-run behavior is dogfooded.

package/specs/quiver-v31-ai-model-catalog-agent-selection/slices/slice-03-agent-doctor-repair/EXECUTION_BRIEF.md

@@ -0,0 +1,57 @@
+# EXECUTION_BRIEF - slice-03 Agent profile doctor and repair dry-run
+
+## Context
+
+Projects can already have misconfigured profiles. New selectors only help future setup, so existing profiles need diagnostics and safe repair previews.
+
+## Objective
+
+Add `ai agent doctor` and `ai agent repair --dry-run`.
+
+## Scope
+
+- `src/create-quiver/commands/ai.js`
+- `src/create-quiver/lib/agent-profiles.js`
+- `src/create-quiver/lib/ai/model-catalog.js`
+- related tests
+
+## Acceptance Criteria
+
+- Doctor evaluates all profiles and identifies defaults.
+- Findings use `error`, `warning`, and `info`.
+- Unsupported providers are errors.
+- Custom unvalidated models are warnings.
+- Display aliases stored in `model` are detected.
+- Repair dry-run shows before/after changes without writes.
+- Human output uses `Checks` and `Suggested fixes`; JSON is clean.
+
+## Technical Plan Summary
+
+Build profile diagnostics as pure data first, then render human/JSON outputs from that shared report.
+
+## Suggested Steps
+
+1. Add profile issue classifier.
+2. Add doctor report builder.
+3. Add human and JSON renderers.
+4. Add repair proposal builder.
+5. Wire commands.
+6. Add fixture tests for legacy bad profiles.
+
+## Restrictions
+
+- Do not auto-write repairs by default.
+- Do not install provider CLIs.
+- Do not mark catalog models as available without live validation.
+
+## Risks
+
+- Doctor can become noisy if severities are weak.
+- Repair must preserve legitimate custom values.
+
+## Completion Checklist
+
+- [ ] Doctor command implemented.
+- [ ] Repair dry-run implemented.
+- [ ] JSON outputs tested.
+- [ ] Legacy bad-profile fixture tested.

package/specs/quiver-v31-ai-model-catalog-agent-selection/slices/slice-03-agent-doctor-repair/slice.json

@@ -0,0 +1,77 @@
+{
+  "slice_id": "slice-03-agent-doctor-repair",
+  "ticket": "QUIVER-31-03",
+  "type": "feature",
+  "title": "Agent profile doctor and repair dry-run",
+  "objective": "Diagnose existing agent profile issues and preview safe repairs without writing files.",
+  "description": "Adds `ai agent doctor` and `ai agent repair --dry-run` for missing data, unsupported providers, display aliases stored as model ids, custom unvalidated models, duplicate labels, and missing provider CLIs.",
+  "git": {
+    "branch_type": "feature",
+    "base_branch": "main",
+    "branch_slug": "v31-agent-doctor-repair",
+    "branch_name": "feature/QUIVER-31-03-v31-agent-doctor-repair"
+  },
+  "files": [
+    "src/create-quiver/commands/ai.js",
+    "src/create-quiver/lib/agent-profiles.js",
+    "src/create-quiver/lib/ai/model-catalog.js",
+    "tests/commands/ai-agent.test.js",
+    "tests/lib/agent-profiles.test.js"
+  ],
+  "expected_read_paths": [
+    "SPEC.md",
+    "src/create-quiver/lib/agent-profiles.js",
+    "src/create-quiver/lib/ai/model-catalog.js",
+    "src/create-quiver/lib/cli/ux.js",
+    "tests/commands/ai-agent.test.js"
+  ],
+  "allowed_write_paths": [
+    "src/create-quiver/commands/ai.js",
+    "src/create-quiver/lib/agent-profiles.js",
+    "src/create-quiver/lib/ai/model-catalog.js",
+    "tests/commands/ai-agent.test.js",
+    "tests/lib/agent-profiles.test.js",
+    "specs/quiver-v31-ai-model-catalog-agent-selection/**"
+  ],
+  "depends_on": [
+    "slice-01-model-catalog-alias-normalization",
+    "slice-02-interactive-agent-set-selectors"
+  ],
+  "parallel_safe": "no",
+  "parallel_safe_reason": "Doctor and repair depend on catalog issue classification and may share command wiring with selectors.",
+  "must": [
+    "Add human and JSON output for `ai agent doctor`.",
+    "Evaluate every profile, not only defaults.",
+    "Classify findings as error, warning, or info.",
+    "Set exit code 1 when errors exist.",
+    "Add `ai agent repair --dry-run` with before/after proposed changes.",
+    "Prevent repair writes without explicit confirmation or `--yes` if write mode is implemented.",
+    "Use v30 human output hierarchy with Checks and Suggested fixes."
+  ],
+  "not_included": [
+    "Remote validation against provider APIs.",
+    "Automatic destructive profile rewrites.",
+    "Installing provider CLIs."
+  ],
+  "acceptance": [
+    "Doctor reports unsupported providers as errors.",
+    "Doctor reports custom unvalidated models as warnings.",
+    "Doctor detects `model: \"GPT 5.5\"` and suggests repair.",
+    "Repair dry-run shows normalized `model: gpt-5.5` and `displayName: GPT 5.5` without writing.",
+    "`--json` outputs parseable JSON without human prose.",
+    "Human output uses Quiver Doctor-style sections."
+  ],
+  "tests": [
+    "node --test tests/commands/ai-agent.test.js tests/lib/agent-profiles.test.js",
+    "git diff --check"
+  ],
+  "validation_hints": [
+    "Include fixtures for multiple profiles and duplicate display names.",
+    "Include the real bug profile with `model: \"GPT 5.5\"`."
+  ],
+  "estimated_hours": 8,
+  "status": "completed",
+  "blocked_reason": null,
+  "actual_hours": 7,
+  "completed_at": "2026-05-27"
+}

package/specs/quiver-v31-ai-model-catalog-agent-selection/slices/slice-04-shared-preflight-provider-errors/CLOSURE_BRIEF.md

@@ -0,0 +1,35 @@
+# CLOSURE_BRIEF - slice-04 Shared model preflight and provider error extraction
+
+## Summary
+
+Implemented shared model alias resolution and provider error extraction across planner and executor runtime paths.
+
+## Validation Against Acceptance Criteria
+
+- [x] Live commands preflight profile models before provider execution.
+- [x] Legacy profile display aliases block before provider execution with a repair suggestion.
+- [x] CLI `--model` display aliases normalize to technical ids in dry-runs.
+- [x] Provider invalid-model errors are surfaced ahead of secondary MCP/tool noise.
+- [x] Provider error text redacts common secret patterns.
+- [x] Existing successful provider runs keep working.
+
+## Relevant Changes
+
+- Added provider model alias normalization and blocking policy.
+- Added provider error cause extraction for invalid model, auth, missing CLI, timeout, and generic failures.
+- Added provider failure serialization for non-zero provider exits with stderr but no process error.
+- Applied profile-alias blocking to planner, reviewer, repair-plan, execute-slice, and execute-plan flows.
+- Added tests for CLI alias normalization, legacy profile blocking, invalid model extraction, and secret redaction.
+
+## Pending
+
+- None for this slice.
+
+## Remaining Risks
+
+- Provider stderr formats can change; new failures should be added as fixtures.
+- Custom model ids still rely on provider-side validation because Quiver cannot know account entitlement locally.
+
+## Future Recommendations
+
+Track provider stderr patterns as test fixtures when new provider failures are observed.

package/specs/quiver-v31-ai-model-catalog-agent-selection/slices/slice-04-shared-preflight-provider-errors/EXECUTION_BRIEF.md

@@ -0,0 +1,55 @@
+# EXECUTION_BRIEF - slice-04 Shared model preflight and provider error extraction
+
+## Context
+
+The real dogfooding failure surfaced as `provider run failed` even though Codex emitted a useful invalid-model error. Live AI commands need shared preflight and better error extraction.
+
+## Objective
+
+Apply model resolution before live provider execution and surface actionable provider errors.
+
+## Scope
+
+- `src/create-quiver/lib/ai/providers.js`
+- `src/create-quiver/lib/ai/executor.js`
+- `src/create-quiver/lib/ai/execution-plan.js`
+- `src/create-quiver/commands/ai.js`
+- related tests
+
+## Acceptance Criteria
+
+- Live commands block before provider execution for known bad display aliases.
+- CLI `--model "GPT 5.5"` is normalized or blocked with guidance.
+- Dry-runs show the real command and technical model id.
+- Invalid model errors are prioritized over secondary MCP/tool noise.
+- Secrets are redacted from provider errors.
+
+## Technical Plan Summary
+
+Create one shared provider/model resolution path and one provider-error extraction path, then adopt them across planner, reviewer, executor, and execution-plan flows.
+
+## Suggested Steps
+
+1. Add shared model preflight helper.
+2. Add provider error extractor.
+3. Adopt helper in planner/reviewer commands.
+4. Adopt helper in executor/execution-plan flows.
+5. Add tests with fake provider output.
+
+## Restrictions
+
+- Do not require real provider auth in tests.
+- Do not change provider prompt content except for validation/preflight.
+- Do not remove custom model support.
+
+## Risks
+
+- Over-eager blocking can prevent legitimate custom models.
+- Provider stderr formats can change.
+
+## Completion Checklist
+
+- [ ] Shared preflight implemented.
+- [ ] Provider error extraction implemented.
+- [ ] Planner and executor paths adopted.
+- [ ] Regression test covers `GPT 5.5`.

package/specs/quiver-v31-ai-model-catalog-agent-selection/slices/slice-04-shared-preflight-provider-errors/slice.json

@@ -0,0 +1,84 @@
+{
+  "slice_id": "slice-04-shared-preflight-provider-errors",
+  "ticket": "QUIVER-31-04",
+  "type": "feature",
+  "title": "Shared model preflight and provider error extraction",
+  "objective": "Apply model resolution and useful provider errors before every live AI command.",
+  "description": "Adds shared preflight for profile and CLI model overrides plus provider error extraction that prioritizes invalid model and auth causes over noisy secondary logs.",
+  "git": {
+    "branch_type": "feature",
+    "base_branch": "main",
+    "branch_slug": "v31-shared-preflight-provider-errors",
+    "branch_name": "feature/QUIVER-31-04-v31-shared-preflight-provider-errors"
+  },
+  "files": [
+    "src/create-quiver/lib/ai/providers.js",
+    "src/create-quiver/lib/ai/executor.js",
+    "src/create-quiver/lib/ai/execution-plan.js",
+    "src/create-quiver/commands/ai.js",
+    "tests/lib/ai-providers.test.js",
+    "tests/commands/ai-prepare-context-planner.test.js",
+    "tests/commands/ai-plan.test.js",
+    "tests/commands/ai-execute-slice.test.js"
+  ],
+  "expected_read_paths": [
+    "SPEC.md",
+    "src/create-quiver/lib/ai/providers.js",
+    "src/create-quiver/lib/ai/model-catalog.js",
+    "src/create-quiver/lib/ai/executor.js",
+    "src/create-quiver/commands/ai.js"
+  ],
+  "allowed_write_paths": [
+    "src/create-quiver/lib/ai/providers.js",
+    "src/create-quiver/lib/ai/executor.js",
+    "src/create-quiver/lib/ai/execution-plan.js",
+    "src/create-quiver/commands/ai.js",
+    "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",
+    "specs/quiver-v31-ai-model-catalog-agent-selection/**"
+  ],
+  "depends_on": [
+    "slice-01-model-catalog-alias-normalization",
+    "slice-03-agent-doctor-repair"
+  ],
+  "parallel_safe": "no",
+  "parallel_safe_reason": "Touches shared provider and AI command runtime behavior.",
+  "must": [
+    "Create shared provider/model selection resolution used by live AI commands.",
+    "Apply normalization or blocking to profile models and CLI `--model` overrides.",
+    "Block before provider execution for known display aliases that can be corrected.",
+    "Keep dry-run output truthful with the real command and model args.",
+    "Extract invalid model, auth, missing CLI, timeout, and secondary warning causes.",
+    "Redact secrets in surfaced provider errors.",
+    "Preserve JSON/no-TTY cleanliness."
+  ],
+  "not_included": [
+    "Changing provider CLI install process.",
+    "Guaranteeing account-level access without live validation.",
+    "Changing prompt content unrelated to model selection."
+  ],
+  "acceptance": [
+    "Live AI commands block before provider execution for `model: \"GPT 5.5\"` with Codex.",
+    "CLI override `--model \"GPT 5.5\"` is normalized or blocked with a concrete suggestion.",
+    "Dry-run shows the real command and technical model id.",
+    "Provider stderr with invalid model plus MCP noise reports invalid model as primary cause.",
+    "Existing successful provider runs keep working."
+  ],
+  "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",
+    "git diff --check"
+  ],
+  "validation_hints": [
+    "Use fake provider runners for failure cases.",
+    "Do not require real provider auth in automated tests."
+  ],
+  "estimated_hours": 10,
+  "status": "completed",
+  "blocked_reason": null,
+  "actual_hours": 8,
+  "completed_at": "2026-05-27"
+}