Context
Operator named this friction twice across recent sessions: there is no canonical ADR governing model-stats as substrate — capability tiers, context-window limits, sunset triggers, model-name promotion/demotion across families (Claude / Gemini / GPT).
Current state: model identity / capability framing lives in scattered fragments — AGENTS.md Identity section, individual skill substrate, in-memory feedback files, ad-hoc commit messages. Empirically observable drift surface: "Claude 3.5 Sonnet / Gemini 1.5 Pro" training-data-anchor regressions caught session-after-session (see memory: feedback_training_data_anchor_drift.md).
Empirical anchor
Discussion #11598 OQ on missing model-stats substrate. V-B-A this turn confirmed: zero ADR in learn/agentos/decisions/** governs model-stats lifecycle.
Friction
- Agents regress to training-data anchors for "current Claude/Gemini/GPT" framing without local-substrate correction.
- No canonical doc for: capability tiers across families, context-window cap, sunset trigger conditions, model-name promotion mechanism, swarm-routing policy when one family's bandwidth tier shifts.
- Specialization signals (e.g.,
research_swarm_model_velocity_specialization.md — Gemini turn velocity vs Opus depth) live in private memory rather than substrate.
Scope
Author ADR governing the Model-Stats substrate:
- Identity layer — canonical model names (
claude-opus-4-7, claude-sonnet-4-6, gemini-3-1-pro, etc.); rotation discipline as models graduate
- Capability layer — context-window, parallel tool calls, harness compatibility
- Specialization layer — empirical observations (bandwidth vs depth) when V-B-A'd; honest "we don't know yet" when not
- Sunset/promotion triggers — what conditions cause model-name promotion / demotion in canonical substrate
- Swarm-routing implications — when bandwidth-tier shifts at provider side, how does routing policy adapt
Acceptance criteria (stub)
Contract Ledger
Backfilled 2026-05-19 per @neo-gpt PR #11606 Cycle 4 review. The 4-layer architecture (see ADR 0012 §2.1) commits to the following surface-level contracts:
| Target Surface |
Source of Authority |
Proposed Behavior |
Fallback |
Docs |
Evidence |
learn/agentos/decisions/0012-model-stats-framework.md |
This ticket + operator clarification 2026-05-19 (rename-vs-split) |
Capability dimensions, sunset/promotion triggers, registry-update discipline, anti-patterns |
N/A (ADR; rare update) |
ADR self-documents |
PR diff |
learn/agentos/IdentitySchema.md Capability Fields section |
ADR 0012 §2.2 |
Extends AgentIdentity graph node with capability properties (contextWindowInput/Output, parallelToolCalls, thoughtBudget, hosting, family, tier, releaseDate, pricing, license, benchmarkSnapshot, sunsetTriggers, swarmRole) |
N/A (schema extension; rare update) |
IdentitySchema.md self-documents |
PR diff |
learn/agentos/ModelStats.md |
ADR 0012 §2.5 registry-update discipline |
Per-model live registry; authoritative-source-cite per row; rename in-place for minor version bumps, split for major capability-class changes |
Mark rows V-B-A-pending when source unclear |
ModelStats.md §provisioning |
PR diff + cited sources per row |
ai/graph/identityRoots.mjs |
ModelStats.md (registry mirror) |
All 3 cloud AgentIdentity entries carry capability fields; values mirror ModelStats.md verbatim |
seedAgentIdentities.mjs re-run is idempotent (createdAt preserved) |
identityRoots.mjs header comment |
PR diff + node --check ai/graph/identityRoots.mjs pass |
Source-authority hierarchy per ADR 0012 §2.5 (priority order):
- Provider's own model card / API docs (e.g.,
platform.claude.com/docs/..., developers.openai.com/..., deepmind.google/models/model-cards/...)
- Provider's release announcements (e.g.,
openai.com/index/introducing-gpt-5-5/)
- Upstream bug-tracker issues for implementation discrepancies (e.g.,
openai/codex#19319)
- Independent benchmark sites (e.g., LMArena, LLMCheck)
- Commentary / blog aggregators (last resort; tag V-B-A-pending when used)
Cross-refs
- Refs #11598 META — friction item NOT previously captured as ticket (operator-correction 2026-05-18 ~22:40Z: "tickets have to be created. otherwise lost knowledge")
- See also: feedback memory
feedback_training_data_anchor_drift.md, research_swarm_model_velocity_specialization.md (private substrate — promote to shared substrate via this ADR)
Priority
Team to triage. Filed per operator-direction that knowledge-substrate creation is independent of prioritization.
Context
Operator named this friction twice across recent sessions: there is no canonical ADR governing model-stats as substrate — capability tiers, context-window limits, sunset triggers, model-name promotion/demotion across families (Claude / Gemini / GPT).
Current state: model identity / capability framing lives in scattered fragments —
AGENTS.mdIdentity section, individual skill substrate, in-memory feedback files, ad-hoc commit messages. Empirically observable drift surface: "Claude 3.5 Sonnet / Gemini 1.5 Pro" training-data-anchor regressions caught session-after-session (see memory:feedback_training_data_anchor_drift.md).Empirical anchor
Discussion #11598 OQ on missing model-stats substrate. V-B-A this turn confirmed: zero ADR in
learn/agentos/decisions/**governs model-stats lifecycle.Friction
research_swarm_model_velocity_specialization.md— Gemini turn velocity vs Opus depth) live in private memory rather than substrate.Scope
Author ADR governing the Model-Stats substrate:
claude-opus-4-7,claude-sonnet-4-6,gemini-3-1-pro, etc.); rotation discipline as models graduateAcceptance criteria (stub)
learn/agentos/decisions/00XX-model-stats.mdper ADR-at-Graduation workflow (ADR 0005)AGENTS.md, skills, and private memoryContract Ledger
Backfilled 2026-05-19 per @neo-gpt PR #11606 Cycle 4 review. The 4-layer architecture (see ADR 0012 §2.1) commits to the following surface-level contracts:
learn/agentos/decisions/0012-model-stats-framework.mdlearn/agentos/IdentitySchema.mdCapability Fields sectionAgentIdentitygraph node with capability properties (contextWindowInput/Output, parallelToolCalls, thoughtBudget, hosting, family, tier, releaseDate, pricing, license, benchmarkSnapshot, sunsetTriggers, swarmRole)learn/agentos/ModelStats.mdai/graph/identityRoots.mjsseedAgentIdentities.mjsre-run is idempotent (createdAtpreserved)node --check ai/graph/identityRoots.mjspassSource-authority hierarchy per ADR 0012 §2.5 (priority order):
platform.claude.com/docs/...,developers.openai.com/...,deepmind.google/models/model-cards/...)openai.com/index/introducing-gpt-5-5/)openai/codex#19319)Cross-refs
feedback_training_data_anchor_drift.md,research_swarm_model_velocity_specialization.md(private substrate — promote to shared substrate via this ADR)Priority
Team to triage. Filed per operator-direction that knowledge-substrate creation is independent of prioritization.