create-quiver 0.14.1 → 0.15.1

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

@@ -0,0 +1,98 @@
+## Title
+
+Quiver v31: AI model catalog and guided agent setup
+
+## Summary
+
+- Adds a local Quiver model catalog for Codex, Claude, and Gemini.
+- Separates technical model ids from human display names.
+- Adds guided provider/model selection for agent profiles.
+- Adds diagnostics and repair dry-run for existing profile misconfigurations.
+- Improves live AI command preflight and provider error messages.
+
+## Scope
+
+- Local model catalog and alias normalization.
+- Interactive `ai agent set <role>` provider/model flow.
+- `ai models list`.
+- `ai agent doctor`.
+- `ai agent repair --dry-run`.
+- Shared model preflight for live AI commands.
+- Better invalid-model/provider error extraction.
+- Documentation, templates, tests, smokes, and package readiness.
+
+## Files
+
+Expected areas:
+
+- `src/create-quiver/lib/ai/model-catalog.js`
+- `src/create-quiver/lib/agent-profiles.js`
+- `src/create-quiver/lib/ai/providers.js`
+- `src/create-quiver/lib/cli/selectors.js`
+- `src/create-quiver/commands/ai.js`
+- `docs/**`
+- `README.md`
+- `README_FOR_AI.md`
+- `ROADMAP.md`
+- `tests/**`
+- `specs/quiver-v31-ai-model-catalog-agent-selection/**`
+
+## How to Test (DETAILED - REQUIRED)
+
+### Required Environment
+
+- Node.js and npm.
+- Optional provider CLIs for live validation smoke tests.
+- A terminal that can run both TTY and no-TTY command checks.
+
+### Worktree Access
+
+- One dedicated branch/worktree for `quiver-v31-ai-model-catalog-agent-selection`.
+- One commit per slice.
+
+### Run the Project
+
+This is a CLI framework change. Run command-level tests and smoke commands from the Quiver repo root.
+
+### Use Cases
+
+- Configure a planner interactively with Codex and a known model.
+- Configure an executor with `custom`.
+- Run `ai agent doctor` against legacy profile fixtures.
+- Run `ai agent repair --dry-run` against `model: "GPT 5.5"`.
+- Run `ai models list` and `ai models list --json`.
+- Run `ai prepare-context --with-planner` with a bad display alias and verify Quiver blocks before Codex execution.
+- Verify no-TTY and JSON outputs do not prompt or colorize.
+
+### Technical Verification
+
+- `node --test tests/**/*.test.js`
+- `npm run smoke:create-quiver`
+- `npm run smoke:doctor-fixtures`
+- `npm run smoke:guided-workflow`
+- `npm run package:quiver`
+- `npm pack --dry-run`
+- `git diff --check`
+- `node bin/create-quiver.js spec validate specs/quiver-v31-ai-model-catalog-agent-selection`
+
+## Evidence
+
+- `node --test tests/**/*.test.js` passed: 482 tests.
+- `npm run smoke:create-quiver` passed.
+- `npm run smoke:doctor-fixtures` passed: 13 fixture states.
+- `npm run smoke:guided-workflow` passed.
+- `npm run package:quiver` passed.
+- `npm pack --dry-run` passed.
+- `git diff --check` passed.
+- `node bin/create-quiver.js spec validate specs/quiver-v31-ai-model-catalog-agent-selection` passed.
+
+## Rollback
+
+Revert slice commits in reverse order. Free-form custom model support and non-interactive profile setup must remain available during rollback.
+
+## Risks / Notes
+
+- Catalog models are known by Quiver, not guaranteed available for every account.
+- Live validation can consume tokens and must be opt-in.
+- Provider CLI behavior can change across versions.
+- Existing profiles can contain legitimate custom values and must not be overwritten without explicit confirmation.

package/specs/quiver-v31-ai-model-catalog-agent-selection/slices/slice-00-spec-foundation/CLOSURE_BRIEF.md

@@ -0,0 +1,30 @@
+# CLOSURE_BRIEF - slice-00 Spec foundation and source-of-truth sync
+
+## Summary
+
+Created the approved v31 spec package and synchronized source-of-truth docs to record the planned AI model catalog and guided agent setup work.
+
+## Validation Against Acceptance Criteria
+
+- [x] Spec package exists and validates.
+- [x] Source-of-truth docs mention v31 as planned.
+- [x] No product code was modified.
+- [x] Evidence report updated.
+
+## Relevant Changes
+
+- Added `specs/quiver-v31-ai-model-catalog-agent-selection/**`.
+- Updated `README_FOR_AI.md`.
+- Updated `ROADMAP.md`.
+
+## Pending
+
+- Implement `slice-01-model-catalog-alias-normalization`.
+
+## Remaining Risks
+
+- Local `main` is ahead of `origin/main` by the prior `v0.15.0` release commit. This is unrelated to v31 implementation but should be resolved before the next package release.
+
+## Future Recommendations
+
+Execute implementation slices only after this documentary foundation is committed.

package/specs/quiver-v31-ai-model-catalog-agent-selection/slices/slice-00-spec-foundation/EXECUTION_BRIEF.md

@@ -0,0 +1,51 @@
+# EXECUTION_BRIEF - slice-00 Spec foundation and source-of-truth sync
+
+## Context
+
+The v31 requirements and technical plan were approved to improve AI agent model selection after a real Codex failure caused by `model: "GPT 5.5"` instead of `model: "gpt-5.5"`.
+
+## Objective
+
+Publish the approved v31 spec package and synchronize source-of-truth docs without implementing product code.
+
+## Scope
+
+- `specs/quiver-v31-ai-model-catalog-agent-selection/**`
+- `README_FOR_AI.md`
+- `ROADMAP.md`
+
+## Acceptance Criteria
+
+- The v31 spec package exists and validates.
+- Every slice has `slice.json`, `EXECUTION_BRIEF.md`, and `CLOSURE_BRIEF.md`.
+- Source-of-truth docs mention v31 as planned.
+- No product code is modified.
+
+## Technical Plan Summary
+
+Create the documentation foundation first so later executors can work from bounded slice handoffs.
+
+## Suggested Steps
+
+1. Review this spec package for completeness.
+2. Update `README_FOR_AI.md` and `ROADMAP.md` to mark v31 as planned.
+3. Run spec validation.
+4. Update `EVIDENCE_REPORT.md`, `STATUS.md`, and this closure brief.
+
+## Restrictions
+
+- Do not implement product code.
+- Do not change package version.
+- Do not claim npm publication.
+
+## Risks
+
+- Source-of-truth docs can drift if v31 is not mentioned.
+- The local repo may contain a pending release commit; do not alter it unless explicitly requested.
+
+## Completion Checklist
+
+- [ ] Source-of-truth docs synchronized.
+- [ ] Spec validation passes.
+- [ ] Evidence recorded.
+- [ ] No product code changed.

package/specs/quiver-v31-ai-model-catalog-agent-selection/slices/slice-00-spec-foundation/slice.json

@@ -0,0 +1,62 @@
+{
+  "slice_id": "slice-00-spec-foundation",
+  "ticket": "QUIVER-31-00",
+  "type": "documentation",
+  "title": "Spec foundation and source-of-truth sync",
+  "objective": "Publish the approved v31 spec package and synchronize source-of-truth docs before implementation.",
+  "description": "Creates the spec, execution plan, PR body, evidence report, slice definitions, and handoffs for AI model catalog and guided agent setup.",
+  "git": {
+    "branch_type": "feature",
+    "base_branch": "main",
+    "branch_slug": "v31-ai-model-catalog-agent-selection",
+    "branch_name": "feature/QUIVER-31-v31-ai-model-catalog-agent-selection"
+  },
+  "files": [
+    "README_FOR_AI.md",
+    "ROADMAP.md",
+    "specs/quiver-v31-ai-model-catalog-agent-selection/**"
+  ],
+  "expected_read_paths": [
+    "README_FOR_AI.md",
+    "ROADMAP.md",
+    "specs/quiver-v31-ai-model-catalog-agent-selection/SPEC.md"
+  ],
+  "allowed_write_paths": [
+    "README_FOR_AI.md",
+    "ROADMAP.md",
+    "specs/quiver-v31-ai-model-catalog-agent-selection/**"
+  ],
+  "depends_on": [],
+  "parallel_safe": "no",
+  "parallel_safe_reason": "The documentary foundation must land before every implementation slice.",
+  "must": [
+    "Commit the approved v31 spec package.",
+    "Ensure every slice has slice.json, EXECUTION_BRIEF.md, and CLOSURE_BRIEF.md.",
+    "Mark v31 as planned in source-of-truth docs without claiming implementation or npm publication.",
+    "Run spec validation and diff checks."
+  ],
+  "not_included": [
+    "Implementing product code.",
+    "Publishing npm.",
+    "Changing package version."
+  ],
+  "acceptance": [
+    "The v31 spec package exists and validates.",
+    "Source-of-truth docs mention v31 as planned.",
+    "No product code is modified.",
+    "Evidence report records documentation validation."
+  ],
+  "tests": [
+    "git diff --check",
+    "node bin/create-quiver.js spec validate specs/quiver-v31-ai-model-catalog-agent-selection"
+  ],
+  "validation_hints": [
+    "Confirm README_FOR_AI.md does not say v31 is implemented.",
+    "Confirm ROADMAP.md does not say v31 is shipped."
+  ],
+  "estimated_hours": 2,
+  "status": "completed",
+  "blocked_reason": null,
+  "actual_hours": 2,
+  "completed_at": "2026-05-27"
+}

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

@@ -0,0 +1,32 @@
+# CLOSURE_BRIEF - slice-01 Local model catalog and alias normalization
+
+## Summary
+
+Implemented the local AI model catalog and connected known alias normalization to agent profile creation.
+
+## Validation Against Acceptance Criteria
+
+- [x] Catalog entries added.
+- [x] Alias normalization implemented.
+- [x] Custom models still allowed.
+- [x] Legacy profile compatibility preserved.
+
+## Relevant Changes
+
+- Added `src/create-quiver/lib/ai/model-catalog.js`.
+- Updated `src/create-quiver/lib/agent-profiles.js`.
+- Added `tests/lib/model-catalog.test.js`.
+- Updated `tests/lib/agent-profiles.test.js`.
+
+## Pending
+
+- Interactive setup, doctor/repair, live preflight, models list, and docs remain for later slices.
+
+## Remaining Risks
+
+- Catalog freshness remains a known operational risk until a future remote catalog exists.
+- Live provider availability is not guaranteed by catalog presence.
+
+## Future Recommendations
+
+Keep the catalog as the single source of truth until a remote catalog API exists.

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.