docs(rfc): activate goal capabilities with lightweight composition - #4826
Conversation
huangruiteng
left a comment
There was a problem hiding this comment.
Request changes
评审对象:1a6b15c633a8032431434af484b2170988f7f4e4
动机
这个 RFC 解决的问题是真实且值得做的:LoopX 已有 catalog、readiness、Agent-context hooks、external-evidence、Decision Context、Explore 和 reward memory,但缺少一个 Goal 级的 durable adoption/composition 视图,新 Agent 仍需从散落投影和 prose 中重新推导“为什么选、怎么组合、何时降级/退役”。本 PR 也正确强调 ready、executed、admitted、decision-changing 与 domain-eligible 不能混为一谈,并把默认关闭、fail-open、无隐式安装/授权、feature-off parity 和 Goal-by-Goal rollback 写进了提案。
但当前 exact head 还没有兑现它最关键的承诺——“组合现有 owner,而不创建第二套 source of truth”。阻塞点不是文档格式,而是 normative receipt ownership:Section 1/5 声称 portfolio 拥有 use/effect receipts,随后 capability_use_receipt_v1 又直接存 provider/model/connector revision、coverage、source family、failure、parent disposition 和 decision effects;这些事实分别已有 capability effect、#4813 external-evidence admission/retirement、Decision Context 与 reward-memory attribution owner。
改动思路
整体正向流是合理的:Goal gap 投影候选,goal_capability_adoption_v1 记录 candidate/trial/adopted/degraded/retired,capability_composition_plan_v1 冻结 revision/budget/authority references,三个 Agent-context hook 在 plan/delegate/result 边界共享 composition identity,原 provider/domain owner 执行并产出自己的 receipt,portfolio 再据此提出下一次 lifecycle review。配置、权限、Todo、provider 和原始 evidence 都不应被复制。
问题出在最后一步的 owner 被扩大了。当前 schema 把“portfolio 观察到 owner receipt 并据此改变 adoption lifecycle”写成“portfolio 自己拥有一份通用 use/effect receipt”。对 external evidence,这与 #4813 的 receipt + parent admission + retirement 重叠;对 reward memory,它与 application/outcome/attribution 分离重叠;对普通非证据 capability,adopted | ignored | refuted 和 decision_effects[] 又不是通用、domain-neutral 的结果词汇。owner receipt 一旦纠正、撤销或退役,两套记录没有定义谁覆盖谁。
最小修复不需要推翻本 RFC:把这个 generic record 改成 portfolio observation/index,只保存不可变 owner receipt/admission/outcome refs、lineage digest 和 portfolio-local review trigger;effect、evidence admission、decision effect/utility 仍由原 owner 持有。portfolio 自己只为 adoption/composition/lifecycle transition 写 receipt,并明确 adopted 仅表示 capability-adoption policy,不等于证据被 parent admit、效果成功或获得 authority。
具体改动
- 新增英中双语 Goal-scoped Capability Portfolio RFC,并在 RFC index 中明确 Proposal 状态。
- 提出 catalog reference、Goal adoption、composition plan 与 use/effect receipt 四个 schema,以及 M0–M5 的 inspect、trial、Goal owner、three-hook composition、effect qualification 和产品入口计划。
- 明确 external-evidence connector lifecycle、Goal authority provider、revision drift、replay、privacy/default-off/rollback 与 CLI/frontend/Lark 共用 projection 的边界。
关键内容讲解
- Section 1–4 对“为什么需要 portfolio”以及 catalog/readiness 不等于 execution/coverage/admission 的拆分是准确的;#4813 也被正确标注为 M1 prerequisite,而非整个 portfolio 的完成证明。
goal_capability_adoption_v1与capability_composition_plan_v1有清晰的 Goal gap、exact revision、budget、authority reference 和 canonical digest,适合作为 portfolio 自己的状态。- 阻塞发生在 Section 5 的 ownership 与
capability_use_receipt_v1:前者说 portfolio “只引用”外部 receipt,后者却复制同一批事实并把 evidence-specific disposition 设为 generic Core vocabulary。 - M0 计划先交付“四个 schema”,而 storage profile 到 M2 前仍未决定;因此这个矛盾不能留到实现后处理,否则会从文档问题变成持久化迁移与跨 surface reconciliation 问题。
对主干的风险
P1:不要让 portfolio 成为第二个 effect/admission/decision receipt authority
当前 obligation 是:portfolio 只组织 capability adoption/composition,并引用现有 owner truth。触发问题的改动是 Section 5 让 portfolio 拥有 capability_use_receipt_v1,而该 record 又复制 exact provider/model/connector revision、coverage、source families、typed failures、parent_disposition 与 decision_effects。可观察后果是 owner receipt 被修正/retire 后,portfolio 仍可能显示旧的 adopted/coverage/effect;或者 generic Core 需要解释 evidence-only 的 refuted 语义。
最小修复:将它重命名/重定义为 owner-receipt-backed observation/index;明确 immutable source refs、source owner/revision 和冲突时的唯一权威;把 parent disposition/decision effects 保留在 Decision Context、external-evidence 或 capability outcome owner;portfolio 只记录自己的 lifecycle decision receipt。同步更新 Section 1/5、M0 和 acceptance,加入一个 external-evidence 与一个 non-evidence capability 的“owner receipt correction/retirement 后仍只有一份 truth”示例。新 head 请重跑 uv run --extra test python examples/docs-governance-smoke.py 和 git diff --check <base>...HEAD。
本地验证方面,docs-governance-smoke.py 已通过,git diff --check 0ef7ebd749ec97a698a8fc7f2a29844dd368689b...HEAD 也通过;远端 DCO、dependency review、Pages build 与 merge-gate 当前成功。它们证明文档形态健康,但不能消除上述 normative ownership 冲突。
我的整体评价
我支持 Goal-scoped portfolio 这个方向,也认可当前 default-off、no-new-authority、revision binding、three-hook 和跨产品入口的总体骨架。这里不是要求现在决定 storage backend、实现 reducer 或完成 finance/non-finance trial;只要求在 schema 成为 M0 交付物前,把“组合现有事实”与“复制现有事实”的边界修正清楚。
因此 exact head 结论是 REQUEST_CHANGES。修复后复审重点很窄:portfolio 是否仅拥有 adoption/composition/lifecycle transition,是否用 typed immutable refs 消费 capability/domain owner receipt,以及 external-evidence 与 non-evidence 两类示例是否都不需要 generic Core 重述领域判定。
English verdict: REQUEST_CHANGES - exact head 1a6b15c defines a valuable Goal-scoped portfolio, but its generic use/effect receipt duplicates capability, evidence-admission, Decision Context, and utility authority; narrow it to owner-receipt-backed observations and portfolio lifecycle receipts before M0 hardens the schemas.
Signed-off-by: huangruiteng <14976749+huangruiteng@users.noreply.github.com>
Signed-off-by: huangruiteng <14976749+huangruiteng@users.noreply.github.com>
1a6b15c to
d82949a
Compare
|
已按 review 修正,new exact head: 核心收窄:
验证: |
huangruiteng
left a comment
There was a problem hiding this comment.
Approve
评审对象:d82949a2a40f93cfbaef7eb66d6d7cdfb8825e9c
动机
这个 RFC 解决的是一个真实的控制面空缺:LoopX 已经分别拥有 capability catalog、Goal external-capability binding、Todo admission、三个 Agent-context hook、external-evidence、Decision Context、Explore 与 reward memory,但还缺少一个 Goal 级、可跨 Agent 读回的 adoption/composition/lifecycle contract。没有这个层次,新 Agent 只能从分散投影和 prose 重新推导“为什么考虑、为什么选择、何时降级/退役”,并容易把 installed/ready/executed/admitted/decision-changing/domain-eligible 混成一个状态。
本轮复审的关键不是证明 portfolio 已实现,而是判断 proposal 是否把未来 authority 放对位置。上一 head 的 blocker 是 generic capability_use_receipt_v1 复制了 provider/evidence/admission/decision-effect truth,可能在 owner receipt 被纠正或退役后留下第二份真相。新 head 已把目标收窄为:Portfolio 只拥有 adoption、composition 和 lifecycle transition;效果、准入、覆盖、utility、权限与 protected effect 仍由原 owner 持有。
改动思路
完整路径现在是:Goal acceptance gap 投影 catalog candidate → 预览有界 composition → 通过既有 Goal binding 读回 exact operation/provider revision/profile digest → before_delegate 冻结 route/budget/schema/authority refs → 原 capability/provider/delegation/domain owner 产出 receipt → Portfolio 只索引 immutable owner receipt,并据此提出 keep/reconfigure/degrade/retire。
这条路径保持了三个重要边界:
goal.external_capability_bindings继续是 provider enablement 的唯一 owner,Portfolio 不写平行 binding;capability_owner_receipt_observation_v1是 read-only index,不复制 provider/model/connector revision、coverage、source family、cost、failure、parent disposition、decision effect 或 utility;capability_lifecycle_transition_receipt_v1只记录 Portfolio 自己的状态迁移,adopted仅表示 Goal 的 capability-adoption policy 选择,不表示 evidence 已准入、结果成功或获得新权限。
异常路径也闭合:owner correction/retirement 产生新的 owner reference,旧 observation 在读时 supersede;owner readback 与索引冲突时 owner 胜出,stale observation 不能驱动迁移;binding/config/provider revision drift 使 plan 失效;Portfolio 不可用时普通工作 fail-open,但 Todo 本身的 capability requirement 仍由既有 admission 独立阻断。
具体改动
- 新增英中双语 Goal-scoped Capability Portfolio RFC,并在 RFC index 中明确 Draft / Proposal 状态与当前边界。
- 定义
capability_catalog_entry_v1、goal_capability_adoption_v1、capability_composition_plan_v1、capability_owner_receipt_observation_v1与 portfolio-only lifecycle transition receipt 的职责。 - 明确 M0–M5:contract/inspect、external-evidence trial、Goal adoption owner、three-hook composition、effect qualification、CLI/packaged frontend/Lark product journey。
- 明确 default-off、Goal-by-Goal rollout、feature-off parity、no bulk promotion、no destructive registry migration 与 disable-writer/read-only-receipt rollback。
- 增加 external-evidence 与 non-evidence 两类 owner correction/retirement 示例和 acceptance row,覆盖上一轮要求的 single-truth 反例。
关键内容讲解
- Section 5 的 ownership 现在与现有系统一致:Portfolio 组织“选择与复评”,原 owner 负责“发生了什么、是否准入、效果如何”。这避免 TypeScript Portfolio reducer 再造一套 evidence/decision vocabulary。
owner_receipt_ref + owner_receipt_digest + lineage_digest提供可重放的观察身份,但不会把 owner payload 再持久化一遍;公开视图如需 coverage/failure,只能按授权在读时 join,并保留 provenance。- 现有
goal.external_capability_bindings的 preview/apply/readback 事务被明确复用;adopted但 binding stale/missing 的 entry 可以展示、不可运行,消除了 policy selection 与 runtime enablement 的歧义。 - M0 现在交付 adoption/composition/lifecycle schema 与只读 owner projection,不再把通用 effect ledger 作为基础设施固化;M1–M5 各自有真实 host/provider、replay/drift、双垂域与跨产品入口证据门槛。
对主干的风险
当前没有阻塞 finding。上一轮 P1 已被完整修复:generic use/effect receipt 被移除,owner-wins、stale rejection、external/non-evidence correction 示例、M0/acceptance 与中英文镜像均已同步。
剩余风险是 proposal risk,而不是本 PR 隐藏的 shipped behavior:Portfolio storage profile 尚未决定,reducer、真实 provider trial、finance/non-finance uplift、default-off parity 与 CLI/frontend/Lark readback 尚未实现。文档没有把这些未交付项包装成完成;它们分别留在 M1–M5 gate,#4813 也只被称为独立 prerequisite。
验证结果:
uv run --extra test python examples/docs-governance-smoke.py:通过;git diff --check origin/main...HEAD:通过;- public/private boundary scan:通过,无本地绝对路径、凭据、私有组织叙事或 ignored artifact 引用;
- 两个 commit 均有 DCO sign-off;远端 DCO、dependency review、Pages build、changed-path classification 与 merge-gate 成功;
- runtime suites 因 docs-only classifier 跳过,这是预期 skip,不是未解释失败;
- 对照
docs/reference/extensions.md与loopx/extensions/capability_admission.py,RFC 对现有 binding owner、read-only direct invoke 与 governed effect 边界的描述一致。
我的整体评价
这个 exact head 已经从“有价值但会复制 authority 的大提案”收敛成“复用现有 owner、只补 Goal-level organization contract 的可实现提案”。范围虽有 991 行,但内容是一个英中镜像 RFC 加 11 行 index,没有混入 speculative runtime scaffolding;normative sections、milestone gates、open decisions 与 non-normative evidence/history 分层清楚。
Future-facing pass 已应用:最高价值的简化就是删除 generic effect ledger,改为 owner-receipt observation + portfolio lifecycle receipt;本 PR 没有必要顺带引入代码抽象。后续实现仍需按 RFC 的 owner-correction、revision drift、feature-off、真实 provider 与跨 surface acceptance 逐阶段证明,不能用本次文档批准替代。
结论:APPROVE。该结论只适用于 exact head d82949a2a40f93cfbaef7eb66d6d7cdfb8825e9c,不授予 merge authority,也不证明 M0–M5 已交付。
English verdict: APPROVE — exact head d82949a resolves the prior duplicate-authority blocker by keeping effect, admission, coverage, utility, binding, and permission truth with their existing owners while the Goal portfolio owns only adoption, composition, and lifecycle transitions; the docs-only proposal is coherent, explicitly unshipped, and passes its focused governance, integrity, DCO, boundary, and repository checks.
huangruiteng
left a comment
There was a problem hiding this comment.
Request changes conclusion (author-owned PR; GitHub blocks formal self-review)
评审对象:d82949a2a40f93cfbaef7eb66d6d7cdfb8825e9c
动机
这个 RFC 要补的 Goal 级能力组织层是有价值的:catalog、Goal binding、Todo admission、三个 Agent-context hook、external-evidence、Decision Context、Explore 与 reward memory 已分别存在,但目前没有一个跨 Agent 可读回的 adoption/composition/lifecycle contract。上一轮评审指出的主要 authority 缺陷也已经修好:当前 head 删除了通用 effect ledger,改为只索引 immutable owner receipt,并明确 Portfolio 只拥有 adoption、composition 和 lifecycle transition。
本轮复审继续按 RFC 自己声明的目标检查状态词是否保持单一、可实现、跨入口一致。这里发现一个新的规范性不一致:goal_capability_adoption_v1.status 明确定义为 candidate | trial | adopted | degraded | retired,但后续规范段落又把 active 当作 Portfolio/adoption 状态使用。由于同一 RFC 同时定义了 connector lifecycle 的 active,这不是普通措辞差异,而会让实现者无法确定 public projection、迁移和产品入口究竟应使用 adopted 还是 active。
改动思路
正确的整体边界已经基本闭合:Goal gap 投影 candidate → 预览 composition → 通过现有 Goal binding 读回 exact config/provider revision → before_delegate 冻结 route/budget/authority → 原 capability/provider/domain owner 产出 receipt → Portfolio 只索引 owner receipt,并据此提出 keep/reconfigure/degrade/retire。Portfolio 不安装、不授权、不复制 coverage/admission/effect truth,失败时普通工作 fail-open,而 Todo 自身的 required capability 仍由既有 admission 阻断。
需要再收紧的是两个相邻但不同的生命周期:
- Portfolio adoption 使用
candidate/trial/adopted/degraded/retired; - external-evidence connector qualification 使用
candidate/trial/qualified/active/degraded/retired(以该 owner 的最终 typed contract 为准)。
RFC 应在所有 Portfolio public projection、operational contract 和产品入口中只使用 adoption schema 的 canonical 状态;若需要同时展示 connector active,必须标注这是 owner-joined connector fact,而不是 Portfolio adoption status。
具体改动
- 新增英中双语 Goal-scoped Capability Portfolio RFC,并在 RFC index 中标注 Draft / Proposal 与未交付边界。
- 定义 catalog reference、Goal adoption、composition plan、owner-receipt observation 与 Portfolio-only lifecycle transition receipt。
- 复用现有 Goal binding、external-evidence、delegation、Decision Context 与 outcome owner,明确 owner correction/retirement 时 owner wins。
- 给出 M0–M5 的 contract/inspect、connector trial、Goal reducer、three-hook composition、effect qualification 与 CLI/frontend/Lark 产品旅程。
关键内容讲解
goal_capability_adoption_v1是 Portfolio 状态词的唯一规范来源,当前只列出candidate | trial | adopted | degraded | retired。- Connector qualification profile 另有
active阶段,这是 external-evidence/connector owner 的事实,不应被 Portfolio 重新命名或复制。 - Section 5 的 “Portfolio
activeoradopted” 把两个 owner 的词汇放进同一主语;Section 10 又要求 operator 检查active/trial/degraded adoptions,使跨 CLI/frontend/Lark 的 canonicaladoption status无法从 schema 唯一推导。 - 这与 RFC 的验收表直接相关:产品入口被要求显示相同的
adoption status,如果规范保留两套未定义映射,M0 reducer 和 M5 public projection 会各自猜测并产生兼容债务。
对主干的风险
P1:统一 Portfolio adoption 与 connector qualification 的状态词
当前义务是让 typed reducer 与所有公开入口共享同一 adoption state machine。触发问题的文本是:
- Section 5:
Portfolio active or adopted describes selection policy only; - Section 10:
active/trial/degraded adoptions; - 中文镜像对应为“Portfolio 的
active或adopted”和“active/trial/degraded adoption”; - 但 schema 与 M2 milestone 只定义
candidate/trial/adopted/degraded/retired。
可观察风险是:实现者可能在 reducer 增加一个未定义 active,也可能让 CLI 显示 active、frontend 显示 adopted,或把 connector readiness 错投影成 Portfolio adoption。这样会破坏 RFC 已强调的 typed state、owner provenance 和跨 surface 一致性。
最小修复:英中同步把 Portfolio 语境中的 active 改为 canonical adopted;Section 5 明确 connector active 是从 external-evidence owner 读时联结的 qualification fact;Section 10 改为 adopted/trial/degraded adoptions,必要时单独列出 active connectors;并在 acceptance/fixture 中加入一个 adoption=adopted、connector=active 的不同 owner 示例,证明两者不会互相映射。修复后重跑 uv run --extra test python examples/docs-governance-smoke.py 与 git diff --check origin/main...HEAD。
本地验证:docs-governance-smoke.py 通过;git diff --check origin/main...HEAD 通过;远端 18 个有效检查均成功或按 docs-only 分类预期跳过。它们证明文档结构和仓库门禁健康,但不会发现这个跨段状态词冲突。
我的整体评价
上一轮 duplicate-authority blocker 已经被完整修复,owner-receipt observation、owner-wins、stale rejection、Goal binding single owner 与 M0–M5 边界都比旧 head 清晰。本轮只剩一个范围很窄但必须在 schema 固化前解决的 semantic blocker:Portfolio adopted 与 connector active 需要保持两个 owner 的 typed facts,不能在 normative prose 中混为同一个 adoption status。
因此 exact head 结论是 REQUEST_CHANGES。修复范围只涉及英中镜像中的状态词、owner 注释和一个验收示例,不要求增加 runtime 实现或扩大 RFC 范围。Future-facing pass 的重点也正是让未来 reducer/public projection 不必维护 active ↔ adopted 的隐式兼容映射。
English verdict: REQUEST_CHANGES — exact head d82949a resolves the previous duplicate-authority issue, but the normative RFC still uses active as a Portfolio adoption state even though goal_capability_adoption_v1 defines only candidate | trial | adopted | degraded | retired; keep connector active as an owner-joined qualification fact and use canonical adopted across the Portfolio reducer and public projections.
…-portfolio-rfc Signed-off-by: huangruiteng <14976749+huangruiteng@users.noreply.github.com>
Signed-off-by: huangruiteng <14976749+huangruiteng@users.noreply.github.com>
Signed-off-by: huangruiteng <14976749+huangruiteng@users.noreply.github.com>
…al-capability-portfolio-rfc Signed-off-by: huangruiteng <14976749+huangruiteng@users.noreply.github.com>
Signed-off-by: huangruiteng <14976749+huangruiteng@users.noreply.github.com>
Signed-off-by: huangruiteng <14976749+huangruiteng@users.noreply.github.com>
|
已修复本轮 comment,并按 Goal 已启用能力应自动参与、组合按需、Core 最小职责的方向重整 RFC。 当前 exact head:
验证:完整 这是 RFC 修订,不宣称上述 runtime、性能或跨入口旅程已经实现。当前 GitHub 的 DCO、dependency-review 和 Pages build 仍在排队或运行中,尚未得到最终 CI 结果;因此本条是修复与验证进度读回,不替代新 head 的最终 APPROVE,也不执行合并。 English update: The RFC now makes existing scoped enablement sufficient, keeps independent work on lightweight native routes, and separates Portfolio policy from connector qualification and Kernel authority. Local documentation and integrity checks pass; final exact-head CI is still queued or running, so no final approval is asserted. |
Problem and resulting contract
Goal capability enablement should activate supported behavior without a second Portfolio switch, adoption record or per-Turn reminder. The RFC now makes independent work use existing direct routes and introduces a bounded composition only for a real dependency or selection tradeoff. Durable adoption state is optional and records policy that cannot be derived from existing configuration or owner receipts.
adoptedseparate from connector-owneractive, including independently changing owner-status examples and acceptance cases.This is a bilingual RFC and navigation update. It does not implement or qualify the proposed runtime, frontend or Lark behavior. Existing catalog, Goal configuration/binding, effect, evidence and outcome owners remain authoritative.
Validation
uv run --extra test python examples/docs-governance-smoke.py— passed after repairing the baseline external-evidence mirror links.git diff --checkand the complete base-to-head diff check — passed.loopx checkpublic-boundary scan — five changed documentation files clean; unrelated registry-state warnings remain outside this PR.The bounded refactor removes mandatory adoption/DAG work and duplicated descriptor fields instead of adding a planner or storage layer. Runtime and UI qualification remain explicit implementation milestones; no executable surface changes in this PR. Maintainer merge requested after exact-head review.