Project goal-scoped agent task visibility

[huangruiteng]

Summary

• project a compact versioned task_scope on agent-scoped quota decisions
• preserve the same task authority boundary in TurnEnvelope
• document goal-local visibility, claim-before-run, and read-only global inventory semantics

Validation

• 52 focused pytest cases passed
• loopx canary premerge --from-git-diff --tier standard: 18/18 selected checks passed
• CLI output budget and maintainability ratchet passed
• public/private boundary scan passed with 0 findings

Boundaries

• additive projection only; no todo selection or execution rule changes
• no scoring, benchmark runner, permission, production, or destructive-git changes
• no private state, raw benchmark evidence, credentials, local paths, or generated logs

[huangruiteng]

Maintainer self-review

• Changed surfaces: agent-scoped quota projection, TurnEnvelope contract capsule, focused control-plane fixture, and the two canonical interaction/data-contract docs.
• Direct checks: diff hygiene, changed-file Python compile, Ruff, 52 focused pytest cases, and the global-manager command-protocol smoke all passed.
• Risk gate: loopx canary premerge --from-git-diff --tier standard passed 18/18 selected checks after rebasing onto current origin/main; this includes CLI output budget, maintainability ratchet, quota resume behavior, review-packet surfaces, canary runner qualification, and public/private boundary scanning.
• Failures/skips: no final failures, skips, or advisory failures. During development the first shape exceeded CLI and maintainability budgets; it was replaced with one compact versioned enum without raising thresholds.
• Manual holds: none reported by the canary gate. GitHub pytest is still running.
• Boundary review: additive projection only; no todo routing/selection behavior, benchmark scoring or runner semantics, permission boundary, production action, raw evidence, credentials, local paths, or generated logs.
• Coverage rationale: the focused tests prove current-agent, unclaimed, and other-agent lanes plus TurnEnvelope retention; the risk-selected canaries cover the touched quota/CLI/control-plane surfaces and exact output budgets.
• Merge decision: do not merge before GitHub pytest completes and repository review requirements are satisfied.

[huangruiteng]

CI follow-up

GitHub pytest completed successfully in 3m45s. The local 18/18 premerge gate and public-boundary scan remain green. The PR is ready for its linked independent review; author merge remains deferred until that review satisfies repository policy.

[huangruiteng]

Independent review result: approve merge. No blocking findings at exact head 86fde0c40637c6df5d90a45cffd6d9dc29a61755.

Findings

No blocking correctness, authority, compatibility, or boundary issue found.

Non-blocking budget note: the quota hot-path fixture is now 12547/12550 JSON characters. This PR does not raise the threshold and uses one compact enum instead of a wide duplicate object, so I do not consider it a merge blocker. The next quota hot-path addition will need to remove or compact existing output rather than append another field.

Product and architecture judgment

The change closes a real agent-facing ambiguity without changing todo selection. Agent-scoped quota decisions now carry one versioned task_scope; current-agent and eligible unclaimed items remain executable candidates, other-agent claims remain diagnostic, and an unclaimed selection still carries claim_required_before_work=true. The same enum is retained in TurnEnvelope.contract_capsule, so host handoff does not lose the boundary. Cross-goal candidate authority is unchanged; the docs correctly reserve cross-goal visibility for explicit read-only global-manager inventory.

The diff shape is proportionate: 20 net production lines, 18 documentation lines, and 86 focused test lines. The private helper has one caller, but keeping the enum attachment in the agent-scope owner is reasonable and avoids duplicating contract knowledge in quota assembly. I found no safe reduction that would preserve ownership and validation more clearly.

Validation

• GitHub pytest: success.
• 10 passed for the new visibility tests plus adjacent agent-scope regressions.
• Hot-path interface budget smoke: pass, including quota 12547/12550.
• Work-lane contract and agent-scope/work-lane consistency smokes: pass.
• Changed-file py_compile, Ruff, and git diff --check: pass.
• Remote head read back unchanged before verdict.

Merge decision

Approved for merge. This is an additive control-plane contract projection with focused negative boundaries; it does not alter routing, permissions, benchmark behavior, production actions, or persisted state.

[huangruiteng]

Maintainer exact-head review: no blocking findings at 86fde0c40637c6df5d90a45cffd6d9dc29a61755.

Findings

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

Non-blocking constraint: the quota hot-path fixture is 12547/12550 JSON characters. This PR keeps the contract compact and does not raise the threshold, so it is mergeable; the next hot-path addition should compact existing output before adding another field.

Product and architecture judgment

The projection makes visibility explicit without changing todo selection or permission. A registered peer can read ordinary work in the current goal, execute only its own claimed or eligible unclaimed candidate, and must claim an unclaimed selection before work. Other-agent claims remain diagnostic. The versioned task_scope is retained in TurnEnvelope, while cross-goal inventory remains an explicit read-only global-manager surface and cannot enter goal-local execution routing.

The diff is proportionate: one compact enum attached by the existing agent-scope owner, one TurnEnvelope retention field, focused tests, and canonical documentation. This avoids a duplicate wide object and keeps task authority in existing selection code.

Validation

• GitHub pytest: passed on the exact head.
• Independent exact-head review: no blocker.
• 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 maintainability, claim/resume behavior, quota/scheduler/monitor contracts, the tight CLI output budget, 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 after #2548, with exact-head protection. The combined post-merge state has been validated.