M2: Freeze selector input contracts and planning gates #30

New issue

Closed

opened 2026-09-05 21:46:49 +00:00 by creatidy · 0 comments

creatidy commented

2026-09-05 21:46:49 +00:00

(Migrated from github.com)

Summary

M2 outcome: select --explain produces trusted, deterministic recommendations and simulations for the owner's actual models. Before any selector implementation, this planning gate freezes the minimum contracts and decision boundaries so M2 can proceed in small, deterministic slices.

This is a documentation + architecture-contract task. It intentionally does not implement scarcity scoring, capability ratings, model selection, select CLI, simulation, blackout execution, reset-credit handling code, an Artificial Analysis client, a provider health client or compound workflow execution.

Contracts to freeze

TaskRequirement: task level (L0–L5, not a capability score), per-dimension capability minima on a frozen ordinal scale with explicit unknown representation, typed hard constraints, single-place profile expansion.
Model catalog entry: stable provider/model/variant identity separate from display name, quota bucket, aliases and model class; hard properties; context/output allowances; ratings with provenance, confidence, rationale and reviewable human override; capacity bindings. Initial models only: GPT-5.6 Luna, GPT-5.6 Sol, GLM-5.3, GLM-5.3-Flash.
Capacity applicability (critical M2 gate): M1 proved one provider may expose multiple independent/shared capacity buckets. M2 requires a provider-independent capacity scope concept — (provider, scope_id) — with model catalog entries binding to one or more scopes. The v2 window_id is diagnostic and must never be parsed for scope semantics, so the first M2 implementation prerequisite is a new normalized capacity-contract version adding an explicit semantic scope_id (conceptual shape only; no schema v3 implementation in the planning PR).
Scarcity aggregation boundary invariants (no final formula or thresholds yet).
Deterministic evidence/policy precedence: hard user policy > direct capacity > provider-native failure > official public status (advisory) > external benchmarks.
Replenishment contract: reset credits are replenishment opportunities, not current capacity; minimal safe ReplenishmentState.
Artificial Analysis boundary: offline/periodic catalog evidence only, never called during select().
HydraFusion positioning update (now a GitHub Copilot CLI Research Preview).
Bounded compound-workflow ExecutionBudget contract (finite values, no unlimited sentinel).
Staged M2 implementation sequence (M2a–M2e).

Non-scope

No production selector code; no numeric model ratings; no profile minima calibration; no model-policy.json content change unless documents cannot stay consistent otherwise; no reopening of M1 beyond correcting one stale roadmap wording (D-018 bounded auth-recovery exception).

Exit criteria

A future agent can answer unambiguously: what a TaskRequirement is, the capability scale, unknown-capability representation, hard-constraint vocabulary, catalog entry fields, how a model identifies constraining capacity scopes, why parsing window_id is forbidden, the first M2 implementation prerequisite, evidence/policy precedence, reset-credit semantics, the AA boundary, the HydraFusion distinction, the compound-recommendation budget, the M2a–M2e slices, and which questions remain deliberately unresolved.

Decisions recorded as D-020/D-021/D-022 in docs/decisions.md. Human remains the merge gate.

## Summary M2 outcome: `select --explain` produces trusted, deterministic recommendations and simulations for the owner's actual models. Before any selector implementation, this planning gate freezes the minimum contracts and decision boundaries so M2 can proceed in small, deterministic slices. This is a documentation + architecture-contract task. It intentionally does **not** implement scarcity scoring, capability ratings, model selection, `select` CLI, simulation, blackout execution, reset-credit handling code, an Artificial Analysis client, a provider health client or compound workflow execution. ## Contracts to freeze 1. TaskRequirement: task level (L0–L5, not a capability score), per-dimension capability minima on a frozen ordinal scale with explicit unknown representation, typed hard constraints, single-place profile expansion. 2. Model catalog entry: stable provider/model/variant identity separate from display name, quota bucket, aliases and model class; hard properties; context/output allowances; ratings with provenance, confidence, rationale and reviewable human override; capacity bindings. Initial models only: GPT-5.6 Luna, GPT-5.6 Sol, GLM-5.3, GLM-5.3-Flash. 3. **Capacity applicability (critical M2 gate):** M1 proved one provider may expose multiple independent/shared capacity buckets. M2 requires a provider-independent `capacity scope` concept — `(provider, scope_id)` — with model catalog entries binding to one or more scopes. The v2 `window_id` is diagnostic and must never be parsed for scope semantics, so the first M2 implementation prerequisite is a new normalized capacity-contract version adding an explicit semantic `scope_id` (conceptual shape only; no schema v3 implementation in the planning PR). 4. Scarcity aggregation boundary invariants (no final formula or thresholds yet). 5. Deterministic evidence/policy precedence: hard user policy > direct capacity > provider-native failure > official public status (advisory) > external benchmarks. 6. Replenishment contract: reset credits are replenishment opportunities, not current capacity; minimal safe `ReplenishmentState`. 7. Artificial Analysis boundary: offline/periodic catalog evidence only, never called during `select()`. 8. HydraFusion positioning update (now a GitHub Copilot CLI Research Preview). 9. Bounded compound-workflow `ExecutionBudget` contract (finite values, no unlimited sentinel). 10. Staged M2 implementation sequence (M2a–M2e). ## Non-scope - No production selector code; no numeric model ratings; no profile minima calibration; no `model-policy.json` content change unless documents cannot stay consistent otherwise; no reopening of M1 beyond correcting one stale roadmap wording (D-018 bounded auth-recovery exception). ## Exit criteria A future agent can answer unambiguously: what a TaskRequirement is, the capability scale, unknown-capability representation, hard-constraint vocabulary, catalog entry fields, how a model identifies constraining capacity scopes, why parsing `window_id` is forbidden, the first M2 implementation prerequisite, evidence/policy precedence, reset-credit semantics, the AA boundary, the HydraFusion distinction, the compound-recommendation budget, the M2a–M2e slices, and which questions remain deliberately unresolved. Decisions recorded as D-020/D-021/D-022 in `docs/decisions.md`. Human remains the merge gate.