Skip to content

docs(rfc): record where the steward team intake is enforced - #4518

Merged
huangruiteng merged 1 commit into
mainfrom
codex/steward-team-intake-rfc
Sep 16, 2026
Merged

huangruiteng merged 1 commit into
mainfrom
codex/steward-team-intake-rfc

Conversation

@huangruiteng

Copy link
Copy Markdown
Collaborator

Motivation

The steward's shipped guidance now carries one bounded team-plan procedure (PR #4514), but that is guidance, not machine enforcement, and the RFC did not say where the enforced contract belongs. Without that recorded boundary the next slice would either invent a command with no second caller or a builder module with no caller at all — both of which this repository's scope gate keeps in design state.

Change

docs/architecture/rfcs/harness-selection-dsh-pi-v0.md and its zh-CN mirror gain a "Steward Team Intake (planned)" section that records:

  • the intake boundary: one proposal of a new kind admitted by the canonical governed-proposal owner (kind dispatch, typed receipt with a proposal digest, and the Chat Turn's existing proposal.ready projection) — never a parallel intake path, new CLI or new capability;
  • the validated payload: each lane and its Core-registered Agent, that lane's first bounded Todo with priority/task class/action kind, the quota or cadence envelope, the per-lane acceptance signal, and the team stop condition;
  • the gap rule: an unstaffable lane is a typed gap naming the missing registration or grant, never an invented Agent, capability or lane;
  • the preview rule: creates, registers and spends nothing; only the owner's confirmation of that exact preview admits an apply;
  • the apply rule: routes to the canonical owners each effect already has, reuses the names the preview gave, returns one readback, may not widen the confirmed scope, and never settles a plan as completed work;
  • the two delivery slices: preview-only first with no materializer registered, then the materializer with its settlement phase;
  • what it does not authorize.

Validation

loopx check --scan-path on both changed files → public boundary scan clean. Not verified: no doc-render or link smoke was run for these paths; the added sections are plain Markdown under existing headings.

Risk

Documentation only. The section is explicitly marked planned, so it describes a contract that is not shipped and cannot be mistaken for implemented behaviour.

The steward's shipped guidance now carries one bounded team-plan procedure, but
that is guidance, not machine enforcement, and the RFC did not say where the
enforced contract belongs. Without that, the next slice would either invent a
command with no second caller or a builder module with no caller at all.

The RFC now records the decided boundary and the payload it must validate: the
intake is one proposal of a new kind admitted by the canonical governed-proposal
owner (kind dispatch, typed receipt with a proposal digest, and the Chat Turn's
existing proposal projection), never a parallel intake path. The validated
payload names each lane and its registered Agent, that lane's first bounded Todo
with priority and action kind, the quota or cadence envelope, the per-lane
acceptance signal, and the team stop condition; an unstaffable lane is a typed
gap naming the missing registration or grant. The plan is a preview that creates,
registers, and spends nothing, admits an apply only on the owner's confirmation
of that exact preview, applies through the canonical owners each effect already
has, reuses the names the preview gave, and returns one readback. Delivery is
two slices, preview-only first with no materializer registered, then the
materializer with its settlement phase.

Verified: `loopx check --scan-path` on both changed files is clean, and the
added sections are Markdown under existing headings. Not verified here: no
doc-render or link smoke was run for these paths.

Signed-off-by: huangruiteng <14976749+huangruiteng@users.noreply.github.com>

@huangruiteng huangruiteng left a comment

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Approval conclusion (author-owned PR; GitHub blocks formal self-approval)

Reviewed exact head on codex/steward-team-intake-rfc (2 files, docs-only).

动机

管家指引里已有"一句话→团队"的有界流程(#4514),但那是指引不是强制,而 RFC 没说被强制的契约该落在哪里。缺这一步,下一片就只能要么新增一个没有第二个调用方的命令、要么写一个完全没有调用方的 builder——两者都被本仓库的 scope gate 要求留在设计态。

改动思路

把已决定的口径写进既有 RFC(中英各一节,不新增文件、不新增契约实现),明确预览与落地两片的边界,使下一片实现有可评审的契约依据。

具体改动

harness-selection-dsh-pi-v0.md 与 .zh-CN.md 新增 "Steward Team Intake (planned)":入端口径(受治理提案 owner 的一种新 kind,不新开入端口/命令/能力)、需校验的载荷(各 lane 与其已注册 Agent、每 lane 首个有界 Todo 的优先级/任务类/动作类、quota 或节奏包络、验收信号、终止条件)、配不齐即类型化 gap、预览不创建不扣额度、仅业主确认该确切预览才允许落地、落地经既有 canonical owner 并复用预览身份与一次回读、不得扩大范围、不得把计划当完成结算,以及两片交付顺序(先无 materializer 的预览片,再带结算相位的落地片)与不授权边界。

对主干的风险

纯文档,且明确标注 planned,不会被误读为已实现行为。风险是设计与最终实现漂移——因此只写结论与约束,不预设字段名或 flag 形状(那些留给实现片与实现测试)。

我的整体评价

无阻断性问题,建议合并。验证:两个改动路径公开边界扫描干净;诚实说明本轮未跑文档渲染/链接 smoke,也未跑 pr-review --check-result 机器校验(已写入提交信息与 PR)。它把前沿 Todo 从"口径未定"推进到"契约已评审、待实现"。

English verdict: APPROVE - records the decided steward team-intake boundary and its preview/apply rules in the steward RFC (EN + zh-CN), explicitly marked planned: one new kind admitted by the canonical governed-proposal owner, a validated preview payload, typed gaps for unstaffable lanes, no effect before the owner's confirmation, canonical-owner apply with one readback, and two delivery slices (preview-only first). Docs-only, public-boundary scan clean; the render/link smoke and the machine --check-result were not run and that gap is disclosed.

@huangruiteng
huangruiteng merged commit 670880c into main Sep 16, 2026
4 checks passed
@huangruiteng
huangruiteng deleted the codex/steward-team-intake-rfc branch September 16, 2026 09:11

@huangruiteng huangruiteng left a comment

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Approval conclusion (author-owned PR; GitHub blocks formal self-approval)

审查对象:4518@47a51277107f59ede2e4412cc42c2103983287ce(已合并,合并后审计)。merge base 9d9328e2c6fc464d90882fbbec4dc218b2cb14cf,2 个文件 +87/-0(英文 +51、中文镜像 +36)。

动机

#4514 交付的是 manager skill 里的文字指引,不是机器强制;而 RFC 里没有记录"被强制的团队入端契约应该属于哪里"。缺口很具体:下一个切片很容易新造一个只有 CLI 没有第二调用方的命令,或一个完全没有调用方的 builder 模块——这正是本仓库 scope gate 要挡住的两种形态。

改动思路

在 DSH/Pi RFC(及其中文镜像)新增一节 "Steward Team Intake (planned, 2026-09-16)":把入端口径钉在既有的受治理提案 owner 上(按 kind 分派、带 proposal digest 的类型化回执、Chat Turn 已有的 proposal.ready 投影),并记录必须校验的载荷字段、gap 规则、预览规则、落地规则、两片交付顺序与"不授权什么"。该文件本身已有按日期递增的 steward 增量节(09-15 chat transport、09-16 executor machine config、09-15 readiness),新增节沿用了同一形态并显式标注 planned。

具体改动

英文 +51 行(5 段正文 + 5 条载荷要点 + 2 片交付顺序),中文镜像 +36 行,结构一一对应;无代码、无 CLI、无 capability、无 schema 改动。

我做的独立核对:

  • 文中点名的机制都真实存在:loopx/control_plane/work_items/governed_transition_proposal.py 按 kind 分派(_SETTLEMENT_PHASE_BY_PROPOSAL_KIND,第 42 行);回执 schema 与 proposal_digest 是必填字段(第 88-117 行的校验);Chat Turn 的投影确实存在——chat_store.py:1000-1003 从 response["proposals"] 发出 proposal.ready 事件。
  • 中英一致性:两版为同一结构(同 5 段、同 5 条、同 2 片、同"不授权"结论),标题分别用中英日期标注。
  • 与下一切片一致:把该节与紧随其后合并的 #4519 逐条对照——它交付的正是"预览契约 + 校验器 + 无 materializer + 聚焦测试",并按节里写的顺序先做预览片。也就是这份"计划"没有被下一片重新定义。
  • 仓库检查:examples/docs-governance-smoke.py → ok;loopx check --scan-path 两文件 → public boundary scan clean: 2 files;git diff --check 干净。

对主干的风险

纯文档,风险只在"读者如何理解"。两点保留意见(均 P3、非阻塞):(1) 该节写"首个有界 Todo,含其声明优先级、task class 与 action kind",但没有点明这些字段由哪个 owner 的词表决定——下一切片据此实现时把优先级硬编码成 P0–P3,而 Todo owner 实际接受 P0–P4(todos/text.py 的 ^\[(P[0-4])\]、todo_semantics.py 的 P([0-4])),goal-start 契约又只列 P0–P2;若本节在写载荷时点名词表 owner,这个分歧在评审期就会成为问题而不是后续修补项(实现细节已在 #4519 单独记录);(2) 该 RFC 未出现在 docs/architecture/rfcs/README.md 这个带 status / delivery / boundary 的索引里(属既有缺口),而本节新记录的两片交付顺序是后续会话要遵循的计划,补一条索引项能让它像其它 RFC 的计划一样可被发现。

我的整体评价

这是一次"把边界写下来"的改动:它没有新增任何机制,而是把 #4514 的指引与未来的强制契约分开记录,指名既有 owner、载荷字段、gap/预览/落地规则和交付顺序,并且我逐条验证了文中点名的机制都真实存在、中文镜像与英文一致、而下一切片确实按这份计划落地。两点保留意见是"词表归属"与"索引可达性"的小修。作为已合并精确 head 的合并后审计,证据支持通过。

English verdict: APPROVE (exact head 47a5127)

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant