docs/models: prefer newest per series (Opus 4.8), add GPT-5.6 IDs, fix Ralph free-model wording - #1469
Merged
tamirdresher merged 4 commits intoJul 13, 2026
Conversation
…5.6 IDs, fix Ralph free-model wording Follow-up to bradygaster#1444 (merged), addressing tamirdresher's three explicit requests in bradygaster#1444 (comment) (refs bradygaster#1080, bradygaster#1183). Item 1 — Prefer newest model per series (fallback ordering): - packages/squad-sdk/src/config/models.ts: DEFAULT_FALLBACK_CHAINS.standard now leads with claude-sonnet-5 (was claude-sonnet-4.6). - packages/squad-sdk/src/runtime/constants.ts: MODELS.FALLBACK_CHAINS.standard same reorder. Premium chains already led with claude-opus-4.8 post-bradygaster#1444. - model-selection-reference.md, SKILL.md files: examples now show claude-opus-4.8 first in Premium, claude-sonnet-5 first in Standard. Item 2 — Add GPT-5.6 model IDs (gpt-5.6-sol, gpt-5.6-terra, gpt-5.6-luna): - Added to MODEL_CATALOG in models.ts (tier: standard, githubCategory: powerful — mirrors gpt-5.5 sibling entry). - Added to DEFAULT_FALLBACK_CHAINS.standard and MODELS.FALLBACK_CHAINS.standard (after claude-sonnet-4.6, before gpt-5.4). - Reachability: CLI-observed as Standard-tier reachable models (2026-07-13). - NOTE: gpt-5.6 entries in DOCS_NAME_TO_ID (cli/commands/models.ts) are deferred until draft PR bradygaster#1445 merges (that file is in bradygaster#1445's diff). - Updated Valid Models in all model-selection-reference.md + SKILL.md copies. Item 3 — Ralph circuit-breaker free-model wording: - .squad-templates/ralph-circuit-breaker.md: replaced multiplier table (0x / "Free — unlimited") with usage-based framing (lightweight category — lowest-cost, still billed). Updated preferredModel example to claude-sonnet-5. - Synced to all 3 template targets via sync-templates.mjs. NOTE: MODELS.DEFAULT (claude-sonnet-4.6) is intentionally left unchanged. That global default is out of scope for this PR — can be a separate decision. TDD: test/catalog-refresh.test.ts — wrote failing tests first (8 RED), then implemented changes. Final result: 16/16 tests GREEN. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
primetimetank21
requested review from
bradygaster and
tamirdresher
as code owners
July 13, 2026 05:41
Contributor
🛫 PR Readiness Check
PR Scope: 📦🔧 Mixed (product + infrastructure)
|
| Status | Check | Details |
|---|---|---|
| ❌ | Single commit | 4 commits — consider squashing before review |
| ✅ | Not in draft | Ready for review |
| ✅ | Branch up to date | Up to date with dev |
| ❌ | Copilot review | No Copilot review yet — it may still be processing |
| ✅ | Changeset present | Changeset file found |
| ✅ | Scope clean | |
| ✅ | No merge conflicts | No merge conflicts |
| ✅ | Copilot threads resolved | 1 active Copilot thread(s) resolved (3 outdated skipped) |
| ❌ | CI passing | 7 check(s) still running |
Files Changed (19 files, +238 −129)
| File | +/− |
|---|---|
.changeset/models-gpt56-fallback-ordering.md |
+15 −0 |
.copilot/skills/model-selection/SKILL.md |
+9 −9 |
.squad-templates/model-selection-reference.md |
+9 −9 |
.squad-templates/ralph-circuit-breaker.md |
+18 −15 |
.squad/skills/model-selection/SKILL.md |
+3 −3 |
packages/squad-cli/templates/model-selection-reference.md |
+9 −9 |
packages/squad-cli/templates/ralph-circuit-breaker.md |
+18 −15 |
packages/squad-cli/templates/skills/model-selection/SKILL.md |
+3 −3 |
packages/squad-sdk/src/config/models.ts |
+35 −3 |
packages/squad-sdk/src/runtime/constants.ts |
+6 −5 |
packages/squad-sdk/templates/model-selection-reference.md |
+9 −9 |
packages/squad-sdk/templates/ralph-circuit-breaker.md |
+18 −15 |
packages/squad-sdk/templates/skills/model-selection/SKILL.md |
+3 −3 |
templates/model-selection-reference.md |
+9 −9 |
templates/ralph-circuit-breaker.md |
+18 −15 |
test/agents.test.ts |
+5 −1 |
test/catalog-refresh.test.ts |
+47 −4 |
test/compat-v041.test.ts |
+2 −1 |
test/models.test.ts |
+2 −1 |
Total: +238 −129
This check runs automatically on every push. Fix any ❌ items and push again.
See CONTRIBUTING.md and PR Requirements for details.
Contributor
|
Contributor
🟠 Impact Analysis — PR #1469Risk tier: 🟠 HIGH 📊 Summary
🎯 Risk Factors
📦 Modules Affectedcopilot-config (1 file)
root (3 files)
squad-cli (3 files)
squad-sdk (5 files)
squad-state (1 file)
templates (2 files)
tests (4 files)
This report is generated automatically for every PR. See #733 for details. |
Contributor
There was a problem hiding this comment.
Pull request overview
Updates Squad’s model catalog, fallback-chain ordering, and related documentation/templates so examples and selection guidance prefer the newest model per series (notably Opus 4.8 / Sonnet 5), adds GPT‑5.6 variant IDs, and revises Ralph circuit-breaker wording to avoid “free model” language under usage-based billing.
Changes:
- Added
gpt-5.6-sol,gpt-5.6-terra,gpt-5.6-lunato the SDK model catalog and standard fallback chains. - Reordered standard fallback chains to prefer
claude-sonnet-5first (while keepingMODELS.DEFAULTunchanged). - Updated model-selection docs/skills and Ralph circuit-breaker templates to reflect new model preferences and updated billing language; added/extended catalog refresh invariants tests.
Reviewed changes
Copilot reviewed 15 out of 15 changed files in this pull request and generated 4 comments.
Show a summary per file
| File | Description |
|---|---|
packages/squad-sdk/src/config/models.ts |
Adds GPT‑5.6 model catalog entries and reorders DEFAULT_FALLBACK_CHAINS.standard. |
packages/squad-sdk/src/runtime/constants.ts |
Reorders MODELS.FALLBACK_CHAINS.standard to prefer newest models first and includes GPT‑5.6 variants. |
test/catalog-refresh.test.ts |
Extends catalog invariants to include GPT‑5.6 and adds ordering assertions for chain heads. |
.squad-templates/ralph-circuit-breaker.md |
Reframes fallback guidance away from “free” language; updates preferred model examples. |
.squad-templates/model-selection-reference.md |
Updates vision/default references and fallback chain examples / valid model lists. |
.squad/skills/model-selection/SKILL.md |
Updates model-selection skill guidance for newest models and standard fallback ordering. |
.copilot/skills/model-selection/SKILL.md |
Updates Copilot skill guidance for newest models and standard fallback ordering. |
templates/ralph-circuit-breaker.md |
Synced copy of Ralph circuit-breaker template updates. |
templates/model-selection-reference.md |
Synced copy of model-selection reference updates. |
packages/squad-cli/templates/ralph-circuit-breaker.md |
Synced CLI template copy updates for Ralph circuit breaker. |
packages/squad-cli/templates/model-selection-reference.md |
Synced CLI template copy updates for model-selection reference. |
packages/squad-cli/templates/skills/model-selection/SKILL.md |
Synced CLI skill template updates for model-selection guidance. |
packages/squad-sdk/templates/ralph-circuit-breaker.md |
Synced SDK template copy updates for Ralph circuit breaker. |
packages/squad-sdk/templates/model-selection-reference.md |
Synced SDK template copy updates for model-selection reference. |
packages/squad-sdk/templates/skills/model-selection/SKILL.md |
Synced SDK skill template updates for model-selection guidance. |
…geset Address Copilot review comments on PR bradygaster#1469: - 3 doc/skill files had abbreviated Standard fallback chain (omitting gpt-5.6-terra, gpt-5.6-luna, gemini-2.5-pro). Now matches the full SDK runtime chain exactly: claude-sonnet-5 → claude-sonnet-4.6 → gpt-5.6-sol → gpt-5.6-terra → gpt-5.6-luna → gpt-5.4 → gpt-5.3-codex → claude-sonnet-4.5 → gemini-2.5-pro → (omit model param) Files: .squad-templates/model-selection-reference.md, .copilot/skills/model-selection/SKILL.md (manual), .squad/skills/model-selection/SKILL.md (sync canonical) Synced to all 3 template targets + 2 skill package targets. - Premium chain confirmed correct (claude-opus-4.8 first) — no change needed. - Add .changeset/models-gpt56-fallback-ordering.md (@bradygaster/squad-sdk patch) to satisfy Changelog Gate CI check. 16/16 catalog-refresh tests remain GREEN. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Three test files hard-coded the old fallback chain head (claude-sonnet-4.6) that was intentionally reordered in the parent commit (newest-per-series first, tamirdresher PR bradygaster#1444 follow-up). The tests remain logically correct — they now assert the NEW intended behavior. - test/compat-v041.test.ts: standard[0] → 'claude-sonnet-5' - test/models.test.ts: standard[0] → 'claude-sonnet-5' - test/agents.test.ts: standard fallback chain toEqual updated (reordered + added gpt-5.6-sol/terra/luna) Inline comment added to each noting the deliberate reorder. Pre-existing failures (cli-packaging-smoke, init-scaffolding) are EBUSY file-lock errors unrelated to these changes — confirmed on baseline. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
… API Live API (canonical) returns: sol=powerful, terra=versatile, luna=lightweight. Original seed incorrectly set all three to 'powerful' (mirroring gpt-5.5). Tier (standard) and fallback-chain membership are unchanged; only githubCategory (the cost-policy billing axis) is corrected. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
tamirdresher
approved these changes
Jul 13, 2026
tamirdresher
left a comment
tamirdresher
left a comment
Collaborator
There was a problem hiding this comment.
Validated against the live Copilot CLI catalog and current implementation: all three requested follow-ups are delivered, synchronized templates and runtime chains agree, targeted tests and CI are green. The luna tier/category nuance and deferred friendly-name mapping can be tracked separately and are not blockers.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
docs/models: prefer newest per series (Opus 4.8), add GPT-5.6 IDs, fix Ralph free-model wording
Context
Follow-up PR explicitly requested by @tamirdresher when he merged #1444.
Tamir's three requests, addressed below.
Relationship to #1445
Independent of the cost-policy PR #1445 — the two touch different files, so they can merge in either order without conflict. The only sequenced item is the deferred
DOCS_NAME_TO_IDaddition for the three GPT-5.6 IDs: that map lives inpackages/squad-cli/src/cli/commands/models.ts, which #1445 owns, so it should land in a small follow-up after #1445 merges. This PR itself is self-contained and ready to merge independently.Item 1 — Prefer the NEWEST model per series in examples and fallback chains
Code changes:
packages/squad-sdk/src/config/models.tsDEFAULT_FALLBACK_CHAINS.standard[0]→claude-sonnet-5(wasclaude-sonnet-4.6)packages/squad-sdk/src/runtime/constants.tsMODELS.FALLBACK_CHAINS.standard[0]→claude-sonnet-5(same reorder)Premium chains already led with
claude-opus-4.8after #1444 ✅Doc/template changes: all
model-selection-reference.mdandmodel-selectionSKILL files updated so that:claude-opus-4.8 → claude-opus-4.7 → claude-opus-4.6 → ...claude-sonnet-5 → claude-sonnet-4.6 → gpt-5.6-sol → ...claude-opus-4.8(newest vision-capable model)MODELS.DEFAULTremainsclaude-sonnet-4.6. Changing the global default is higher-impact and should be a conscious, separate decision — it is explicitly out of scope here.Item 2 — Add GPT-5.6 model IDs (gpt-5.6-sol, gpt-5.6-terra, gpt-5.6-luna)
Reachability validation basis: GPT-5.6 variants (sol, terra, luna) observed as Standard-tier picker-reachable models via the Copilot CLI catalog on 2026-07-13. Consistent with gpt-5.5, which is already in the seed.
Code changes:
packages/squad-sdk/src/config/models.tsMODEL_CATALOGentries:gpt-5.6-sol,gpt-5.6-terra,gpt-5.6-luna—tier: 'standard',githubCategory: 'powerful'(mirrorsgpt-5.5sibling)packages/squad-sdk/src/config/models.tsDEFAULT_FALLBACK_CHAINS.standard(afterclaude-sonnet-4.6, beforegpt-5.4)packages/squad-sdk/src/runtime/constants.tsMODELS.FALLBACK_CHAINS.standard(same position)Template changes: all Valid Models lists in
model-selection-reference.mdandmodel-selectionSKILL files updated to includegpt-5.6-sol,gpt-5.6-terra,gpt-5.6-lunaunder Standard.DOCS_NAME_TO_IDmap inpackages/squad-cli/src/cli/commands/models.tsis in draft PR #1445's diff. To avoid conflicts, gpt-5.6 entries to that map are deferred until #1445 merges (see "Relationship to #1445" above).Item 3 — Ralph circuit-breaker: replace "free models" wording
Changes to
.squad-templates/ralph-circuit-breaker.md(synced to all 3 template targets):0x/"Free — unlimited"languagepreferredModelexampleclaude-sonnet-4.6→claude-sonnet-5"(all free-tier)"→"(lightweight-category — lowest cost, still billed)"Tests
TDD approach: wrote failing tests first, then implemented.
New tests added to
test/catalog-refresh.test.ts:config/runtime premium chain[0] is claude-opus-4.8(ordering invariant)config/runtime standard chain[0] is claude-sonnet-5(ordering invariant) ← was failing REDMODEL_CATALOG contains gpt-5.6-sol/terra/luna(membership) ← was failing REDgpt-5.6-sol appears in config/runtime standard fallback chain← was failing REDFiles changed
Source (TDD-gated):
packages/squad-sdk/src/config/models.tspackages/squad-sdk/src/runtime/constants.tstest/catalog-refresh.test.tsCanonical templates (sync sources):
.squad-templates/ralph-circuit-breaker.md.squad-templates/model-selection-reference.md.squad/skills/model-selection/SKILL.md.copilot/skills/model-selection/SKILL.mdSynced copies (generated via
sync-templates.mjs --sync+sync-skill-templates.mjs):templates/ralph-circuit-breaker.mdtemplates/model-selection-reference.mdpackages/squad-cli/templates/ralph-circuit-breaker.mdpackages/squad-cli/templates/model-selection-reference.mdpackages/squad-cli/templates/skills/model-selection/SKILL.mdpackages/squad-sdk/templates/ralph-circuit-breaker.mdpackages/squad-sdk/templates/model-selection-reference.mdpackages/squad-sdk/templates/skills/model-selection/SKILL.mdRefs
Closes follow-up from: #1444 (comment)
Refs: #1080, #1183
Branch stacks on:
upstream/dev(includes merged #1444)