Scope contract health to selected goals

[huangruiteng]

Summary

• emit structured contract error ownership at validation sources using global, goal, and known goals scopes
• derive legacy error lists from the structured diagnostics and project selected-goal status from global plus exact goal-owned failures
• make goal-targeted status consumers (quota, turn, diagnose, review-packet, demo, and auto-research frontier) request a goal-scoped read model
• make implicit ready-score choose only a real registry goal, then re-read scoped status before scoring it
• preserve existing same-goal execution visibility: current-agent claims first, unclaimed work remains selectable, and peer claims remain diagnostic-only

This turns the direction explored in #2074 into a source-owned contract instead of relying on goal-id string prefixes at the quota consumer.

Ownership model

• Global: registry identity ambiguity, registry boundary failures, and public-boundary failures
• Goal: one registry goal entry, active state, or todo contract
• Known goal set: shared state-file and similar findings whose affected goals are explicit
• Broad inventory: unfiltered status continues to expose all goal diagnostics
• Selected goal: execution gates consume only global plus selected-goal diagnostics

Validation

• pytest -q tests/control_plane (463 passed)
• pytest -q tests/control_plane/test_contract_health.py (7 passed, repeated after rebase)
• status-goal-filter-smoke.py
• status-collection-readmodel-smoke.py
• todo-claim-visibility-lanes-smoke.py
• todo-user-gate-scope-smoke.py
• quota-agent-scoped-user-gate-smoke.py
• heartbeat-quota-flow-smoke.py
• loopx-turn-codex-cli-quickstart-smoke.py
• demo-cli-smoke.py
• auto-research-demo-goal-isolation-smoke.py
• loopx canary premerge --from-git-diff after rebasing to current origin/main

The premerge gate passed all direct checks, risk-profile smokes, output budgets, scheduler/quota canaries, and public-boundary checks. It reported the existing control-plane-maintainability-ratchet-smoke.py baseline as advisory_inherited_failure; the failure did not mention any changed file and is non-blocking under the canary contract.

Review notes

• Compatibility string fields remain available, but ownership must come from error_diagnostics.
• Similar goal ids are matched exactly.
• Synthetic health rows such as loopx-contract cannot be selected as the implicit ready-score goal.
• Global failures remain fail closed.
• This changes runtime status/quota behavior and is intentionally left for independent review rather than self-merge.

[huangruiteng]

CI maintainability regressions are fixed at 750d2190 after rebasing onto current origin/main (c788088b).

• goal_status_health_ok is imported through a private alias, so it no longer expands the public loopx.quota compatibility facade.
• quota plan construction and selected-goal health evaluation now live behind one narrow _build_quota_plan_for_goal helper, returning build_quota_should_run to its reviewed statement ceiling without widening either exception.

Validation after rebase:

• maintainability ratchet + focused contract tests: 12 passed
• full tests/control_plane: 477 passed
• Ruff: passed
• loopx canary premerge --from-git-diff: standard tier, 18/18 selected checks passed; public boundary clean, no warnings or manual holds

GitHub pytest is running on the new exact head.

[huangruiteng]

Maintainer exact-head review: no blocking findings at 750d219024824e4fcc5ca1637da96236846a03d8.

Findings

No correctness, compatibility, authority, or public/private-boundary blocker found.

Product and architecture judgment

This change fixes a real control-plane isolation problem at the right ownership layer. Contract failures are classified where they are produced as global, exact goal, or an explicit affected goals set. Broad status inventory still exposes every diagnostic, while selected-goal status and quota consume only global plus selected-goal failures. Registry identity and public-boundary failures remain fail closed.

The implementation size is justified by replacing existing untyped error emission across registry, active-state, status, quota, and ready-score consumers, plus substantial negative coverage. The new contract_health module centralizes one durable rule, and the quota call site uses a narrow helper instead of expanding the hot path. I found no safe reduction that would preserve the source-owned semantics and current validation more clearly.

Validation

• GitHub pytest: passed on the exact head.
• Exact-head control-plane suite before final integration: 477 passed.
• Combined Scope contract health to selected goals #2548 then Project goal-scoped agent task visibility #2549 integration: clean Git merge with no conflict; 479 control-plane tests passed.
• Repository-constrained Ruff scope: passed.
• Combined standard premerge gate: 18/18 selected checks passed, including changed-file compile, maintainability, quota/scheduler/monitor contracts, CLI output budgets, canary qualification, and public/private boundary scanning.
• Failures/skips: an initial combined local run inherited an unrelated editable checkout and failed before the target CLI could load. Pinning imports to the integration worktree made the same test pass, followed by the clean 479-test run. No product failure or skipped validation remains.
• Manual holds: none.

Merge decision

Approved for the user's explicitly authorized maintainer self-merge, with exact-head protection. Merge #2548 before #2549; the combined state has been validated.