docs(rfc): link the steward team intake to the shared-authority alignment RFC - #4529
Conversation
…ment RFC The intake section pointed at the runner-layering and visible-launcher contracts, which describe how multi-agent mechanics are layered and how panes start. The contract that actually governs a team request is Shared Goal Alignment and Governed Amendment, whose authority and storage boundary is owned by the pluggable state-provider RFC, so the section was linking to neighbours instead of to the rule that constrains it. The section now states that relationship in the terms those contracts define: - a plan is a staffing act on the shared work graph, and its lanes are per-Agent frontiers over that one graph, which is why the apply routes through the canonical Todo owner and why the intake must not add a second graph, frontier or leader Agent; - intent and staffing are different acts: the plan's objective, acceptance and stop condition live inside `shared_goal_intent_v0` and may not change the Goal's objective, non-goals, acceptance, permissions or stop conditions. A request that refines acceptance is a `shared_acceptance` amendment and a request for new permission is `protected_authority`, both committed only by `GoalAmendmentAuthority` with policy, independent verification and a compare-and-set receipt, never by a team preview; - `peer_v1` is equal execution rank rather than commit authority, so confirming a preview does not make the steward a leader over the lanes or give it priority on shared resources; - the authoritative per-lane readback after a plan lands is the `shared_goal_alignment_v0` projection for that Agent, which the apply receipt does not yet publish. Two gaps are named instead of implied as done, both verified against the code: `add_goal_todo` takes no canonical intent revision, so a materialized lane Todo is not traceable to the intent revision it was meant to advance; and the intake reserves no work and takes no lease or fence, so a lane's first turn competes through the ordinary quota path. The layering rules stay recorded beside this as secondary context. Verified: examples/docs-governance-smoke.py ok (the new relative links resolve); tests/test_steward_team_plan_preview.py and tests/test_steward_team_plan_apply.py 16 passed. Documentation only, both language editions, no behavior change. Signed-off-by: huangruiteng <14976749+huangruiteng@users.noreply.github.com>
huangruiteng
left a comment
huangruiteng
left a comment
There was a problem hiding this comment.
Approval conclusion (author-owned PR; GitHub blocks formal self-approval)
一、变更内容
- 中英两版「管家团队入端口径」小节里与 multi-agent 的联动段落重写：主锚点从"分层最小化契约 + 可见 launcher"改为
共享目标对齐与受治理修订（其权威与存储边界由
共享控制面权威与可插拔状态提供方 拥有），并按该 RFC 自己的词汇写清四点：- 计划是共享工作图上的配人动作，lane 就是同一张图上的 per-Agent frontier，因此落地只走 canonical Todo owner，且不得引入第二张图/第二个 frontier/leader Agent；
- 改意图与配人是两件事：计划的 objective/acceptance/stop condition 只在
shared_goal_intent_v0之内，不得改动 Goal 的 objective、non-goals、acceptance、权限或终止条件；细化验收属shared_acceptance修订，要新权限属protected_authority，两者只由GoalAmendmentAuthority（策略校验 + 独立验证 + CAS 回执）提交，绝不由团队预览提交； peer_v1是平等执行位阶而非提交权威：确认预览不会让管家成为 lane 之上的 leader，也不给共享资源优先权；- 每条 lane 的权威回读是该 Agent 的
shared_goal_alignment_v0投影（loopx shared-goal-alignment可读），而 apply 回执还没投影这份状态。
- 同时把两处缺口如实点名（都对着代码核过）：
add_goal_todo不接受规范意图修订，因此建出的 lane Todo 尚不可追溯到它本应推进的意图修订；入端口径不预留工作、不取租约/fence，lane 首个 turn 仍走普通配额竞争。 - 分层最小化 / 可见 launcher 两条仍是次级上下文保留（前者保证 intake 不拥有 runner/pane/vision 预算，后者按身份相连而非互相调用）。
二、依据与一致性
- 依据是该 RFC 的 §3（状态分区：
shared_goal_intent_v0、共享工作图、per-Agent frontier）、§4.2（修订类别表：lane_route/shared_work_graph/shared_acceptance/protected_authority）与其对peer_v1的定义（平等执行位阶，不等于可越权）。 - 与仓库现有产品面一致：
loopx shared-goal-alignment --goal-id ... --agent-id ...实际可用（本 lane 亲测返回shared_goal_alignment_v0，含 source_basis、frontier_counts、unclaimed_eligible_work），所以"回读用对齐投影"不是纸面建议。 - 与"文档必须与代码一致"的仓库规则一致：新点的两个缺口都是我本次读代码确认过的事实（
add_goal_todo签名无 revision 参数），不是推测。 - 本次只改文档、双语同步，无行为/权限/默认值变化。
三、验证
examples/docs-governance-smoke.py：ok（新增两条相对链接可解析）。tests/test_steward_team_plan_preview.py、tests/test_steward_team_plan_apply.py：16 passed。loopx canary premerge --from-git-diff：merge_gate_passed=true、self_merge_allowed=true、manual_holds=0、failures 0、public boundary ok。
四、风险与残余缺口
- 这是概念锚点的纠正：先前把 intake 挂在"分层/launcher"上并不算错，但没有落到真正约束它的共享权威与修订契约上；本次把约束写清后，"什么请求属于预览、什么请求必须走修订"有了可判定的边界。
- 仍未做且已成文：lane Todo 的意图修订可追溯性（需要 Todo owner 侧的一次显式契约扩展，属于可测的有界改动）；claim/lease 预留；把 per-Agent 对齐投影纳入 apply 回读；以及此前记录的
team_plan_context生产接线、Chat 侧落地路径、多 lane 前端确认面。
五、结论
批准以 admin squash 合并（self_merge_allowed=true）。纯文档、双语同步、可回滚；它修正的是"相关 RFC 指错对象"这一具体缺陷，并把与 shared authority 的联动写到可判定、可验证的粒度。
English verdict: Approved for an admin squash merge. Documentation-only in both language editions: the intake is now anchored to the shared-goal alignment and governed-amendment contract (and its authority/state-provider sibling) instead of the runner-layering and launcher contracts, with the staffing-vs-amendment boundary, the peer_v1 authority rule, the alignment-projection readback, and two code-verified gaps recorded. Docs governance smoke and 16 focused tests pass, and the canary premerge gate is green.
huangruiteng
left a comment
huangruiteng
left a comment
There was a problem hiding this comment.
Approval conclusion (author-owned PR; GitHub blocks formal self-approval)
动机
上一节把入端口径连到了 runner 分层契约（multi_agent_three_layer_minimality_contract_v0）和 pane launcher（multi_agent_visible_launcher_v0），但这两个都不是"约束团队请求"的那条规则：前者讲多 agent 机制怎么分层，后者讲可见 pane 怎么起。真正管住"一次团队请求可以改变 Goal 的什么"的，是共享目标对齐与受治理修订契约，以及拥有其权威/存储边界的 shared-authority 契约。所以原文指向的是邻居，而不是规则本身——这个缺口是真实的，代价也不只是措辞：照着邻居读，实现者可能以为"细化验收条件"或"取得新权限"是团队预览该做的事，而按 owning 契约那属于 GoalAmendmentAuthority（策略校验 + 独立验证 + CAS 回执）。
改动思路
改写没有新开一节或新造文档，而是就地重写原来的 relationship 小节，并把"入端口径到底受谁约束"讲成四条有层次的规则：计划是共享工作图上的配人动作（所以走 canonical Todo owner）、改意图与配人是两件事（shared_acceptance / protected_authority 归 GoalAmendmentAuthority）、peer_v1 是平等执行位阶而非提交权威、每条 lane 的权威回读是对齐投影。原来的分层规则被保留为"同时成立"的一段而不是删除。
两个细节我特别认可：
- 它把 lane 层的
capability_not_granted/audience_not_authorized与意图层的 fail-closed 规则显式对应起来，说明这不是新增权威，而是同一条规则在另一层的表述。 - 它如实点名两处仍缺的缺口（lane Todo 还没携带它要推进的规范意图修订；入端口径不预留工作、不取租约或 fence），没有把"契约已引用"讲成"能力已完成"。
具体改动
两版 RFC 同步把 ### Relationship to the multi-agent contracts 改为 ### Relationship to the multi-agent and shared-authority contracts（英文 551 行），新增四条规则、两处缺口声明，并保留三层最小性与 launcher 的连接说明；+95/-39，全部是 Markdown。
我按 head 12f1b42c、base 856dc9a3 逐条核对：两版链接都能解析（英文指向 ./shared-goal-alignment-and-governed-amendment-v0.md，中文指向对应的 .zh-CN.md，与本文档既有的链接约定一致）；shared_goal_intent_v0、shared_acceptance、protected_authority、GoalAmendmentAuthority、shared_goal_alignment_v0 在对齐契约里都存在且含义与文中一致；peer_v1 那句在契约里就是"equal execution rank, not universal authority"；文中给的 loopx shared-goal-alignment --goal-id <goal> --agent-id <agent> 确实存在，我跑了一次只读调用，输出里 source_basis.revision_basis、frontier_basis、claim 计数与 unclaimed_eligible_work 都对得上文中的"规范修订、frontier basis、claim 与租约事实、可领取的未认领工作"；两处缺口也属实——apply 建 Todo 时没有任何意图修订参数，governed_transition_proposal.py 里也没有 lease/reserve/fence 调用。测试侧：tests/control_plane/test_shared_goal_alignment.py + _cli.py 37 passed，examples/docs-governance-smoke.py ok，git diff --check 干净。
一个 P3（非阻塞，已记入 findings）：这次改写丢掉了旧稿中一条可执行的指引。旧文在 launcher 那条里写着"launcher 自身的规则对入端口径同样成立：不得成为 leader agent、隐藏调度器、晋升权威或第二真源；需要可见 pane、pane 内 A2A tick 或晋升证据的计划，必须把它声明为受支持的 action kind，而不是塞进预览里"。新文保留了身份连接与"不拥有 runner/pane/vision 预算/证据回路"，也新增了"不得引入第二张图、第二个 frontier 或 leader Agent"，但那份枚举与"声明为受支持 action kind"这句没有被带过来。强制面没有丢（校验器仍要求每条 lane 的首个 Todo 的 action_kind 是本机支持的 advancement action kind，文中 502/525/530 行也仍这么写），所以这是文档完整性问题而非规则缺口：读者少了一条"这种需求该写在哪里"的指引。在两版各补回一句即可。
对主干的风险
风险极低且完全可回滚：diff 全部是 Markdown，没有一行可执行代码变化。文档治理 smoke 通过，两版同步更新，链接各自指向对应语言且都能解析，没有重命名或废弃任何 id。
唯一需要留意的是上面那条 P3：删掉的那句是"在哪里表达 pane / 晋升需求"的指引，读者可能少一条线索；但它不改变任何强制规则，blast radius 限于文档完整性。反过来说，这次改写最大的收益是堵住了一个更危险的误读——把"细化验收 / 取新权限"当成团队预览能做的事。
我的整体评价
这是一次方向正确、克制且信息密度更高的文档修复：它纠正了"指向邻居而非规则"的实质问题，用四条分层规则把入端口径的权威边界说清楚，并把两处未完成的缺口如实写在文档里而不是留给读者猜。链接、id、命令、缺口我都逐条对着 owning 契约与代码核过，验证证据与结论一致。
建议把旧稿里"声明为受支持 action kind / launcher 排除项同样适用"这句补回两版（P3），不构成合并阻塞。
English verdict: APPROVE (exact head 12f1b42)
1 participant
Problem
The steward team-intake section linked the intake to the runner-layering contract
(
multi_agent_three_layer_minimality_contract_v0) and the pane launcher(
multi_agent_visible_launcher_v0). Those describe how multi-agent mechanics are layered and howvisible panes start; neither is the contract that governs a team request. The governing contract is
Shared Goal Alignment and Governed Amendment,
whose authority and storage boundary is owned by
Shared Control-Plane Authority and Pluggable State Providers.
So the section pointed at neighbours of the rule that actually constrains the intake.
What changed
Both language editions now state the relationship in the alignment contract's own terms:
work-graph work that preserves canonical intent, which is why the apply routes through the
canonical Todo owner; the lanes are per-Agent frontiers over that one graph, so the intake must not
add a second graph, a second frontier, or a leader Agent.
live inside
shared_goal_intent_v0and may not change the Goal's objective, non-goals, acceptance,permissions or stop conditions. A request that refines acceptance is a
shared_acceptanceamendment and one that needs new permission is
protected_authority; both are committed only byGoalAmendmentAuthoritywith policy check, independent verification and a compare-and-set receipt,never by a team preview. That is the intent-layer form of the fail-closed rule the typed gaps
already express at the lane layer.
peer_v1is equal execution rank, not commit authority, so confirming a preview does not makethe steward a leader over the lanes or give it priority on shared resources.
(
loopx shared-goal-alignment --goal-id <goal> --agent-id <agent>), which the apply receipt doesnot yet publish.
Two gaps are named rather than implied as done, both checked against the code:
add_goal_todotakes no canonical intent revision, so a materialized lane Todo is not traceable tothe intent revision it was meant to advance; and the intake reserves no work and takes no lease or
fence, so a lane's first turn competes through the ordinary quota path. The layering rules remain
recorded beside this as secondary context.
Changed surfaces
docs/architecture/rfcs/harness-selection-dsh-pi-v0.md,docs/architecture/rfcs/harness-selection-dsh-pi-v0.zh-CN.md(one subsection each).Validation
examples/docs-governance-smoke.py: ok; the two new relative links resolve.tests/test_steward_team_plan_preview.py,tests/test_steward_team_plan_apply.py: 16 passed.loopx canary premerge --from-git-diff:merge_gate_passed=true,self_merge_allowed=true,manual_holds=0, failures 0, public boundary ok.Boundaries
Documentation only, both language editions, no runtime behavior, no authority and no default change.
The two named gaps are recorded as open work for the intake rather than as delivered behavior.