From 08fe5be8e5d2fdfa6986209c9cbe457851e6c94b Mon Sep 17 00:00:00 2001 From: song Date: Mon, 12 Oct 2026 21:04:39 +0800 Subject: [PATCH] docs(amendment): map the first complete governed work-item transaction Signed-off-by: song --- ...oal-alignment-and-governed-amendment-v0.md | 131 ++++++++++++++++++ ...ignment-and-governed-amendment-v0.zh-CN.md | 102 ++++++++++++++ 2 files changed, 233 insertions(+) diff --git a/docs/architecture/rfcs/shared-goal-alignment-and-governed-amendment-v0.md b/docs/architecture/rfcs/shared-goal-alignment-and-governed-amendment-v0.md index b197461400..e8ac2bc9b4 100644 --- a/docs/architecture/rfcs/shared-goal-alignment-and-governed-amendment-v0.md +++ b/docs/architecture/rfcs/shared-goal-alignment-and-governed-amendment-v0.md @@ -745,6 +745,137 @@ lane/proposal/stale-basis negatives and later qualifies the supported commit path. This RFC retains Stage 3–5 implementation and promotion ownership; manager readiness cannot silently mark those stages done. +### 9.2 Proposed first commit transaction: one policy-bound work item + +This is the concrete transaction mapping required by §9.1, for review before +runtime implementation. It is not a shipped commit API, a new authority +profile, or approval to activate one. Stage 1/2 remain proposal-only. The first +Stage 3 operation adds **one unclaimed Agent Todo from an owner-preauthorized +fixed template**, inside `shared_work_graph`. It does not edit acceptance, +permissions, existing Todo meaning, dependencies or another Agent's work. +Ordinary Todo creation remains with its existing writer; the amendment path is +used only when an admitted proposal must record a shared Goal revision and +exact replan settlement under this policy. + +A fixed template is a deliberately narrow first policy, not a classifier for +arbitrary intent-preserving prose. The owner chooses its bounded purpose and +complete authority-relevant Todo fields once. The proposer selects its id and +supplies only operation/causal identities; it cannot supply replacement text, +write scopes, capabilities, recipients, claim/lease state, approval outcomes, +validation results or a different template revision. Additional amendment +operations require their own reviewed policy; this choice does not broaden any +existing Agent permission or oblige owners to preauthor every ordinary Todo. + +#### Root intent, policy and lifetime + +The full canonical envelope in §3.1 must exist before this operation is +available: objective, non-goals, acceptance, permission/write boundaries, stop +and terminal conditions, immutable root intent, policy, Goal revision and +intent digest. The source Goal lifecycle owns its exact `goal_instance_id`; +provider identity, Todo digest, state-event sequence and the existing acceptance +contract cannot substitute for it. Initialization is an explicit trusted-owner +operation on that exact Goal, not an Agent field update or an automatic import +from Markdown. Existing legacy goals stay on their existing path until the +lifecycle owner admits an explicit migration; do not mint an unrelated id in +the amendment module. + +Keep intent and its amendment receipts in the **existing canonical Goal +projection and atomic journal**, not a new file/store beside it. Reuse the +source/lifetime owner's admission and retirement fence so a Goal recreation +cannot race a commit. A pre-commit identity read alone is insufficient. The +current generic registry path rejects the lifecycle-only `source_session_v1` +profile; this proposal does not waive that gate or grant all business effects. +A selected profile must qualify this named owner before it can commit. + +The policy identifies the permitted operation, fixed templates and revisions, +eligible registered proposers, bounded creation scope/capacity, and its explicit +out-of-policy disposition. Missing policy means unavailable, not an implicit +allow. For this deterministic class, exact template/authority checks may be the +configured automatic rule; classes requiring an independent verifier retain +§4's separate actor and exact proposal-digest requirements. Policy membership +never replaces current runtime permission, capability, lease or stop checks. +Root intent cannot be amended by this operation. Initialization and retirement +must be retryable through their existing lifecycle owners; a lost response must +not create another root or reactivate a retired one. + +#### Transaction and readback ownership + +| Boundary | Existing owner to reuse | Required implementation and observable result | +| --- | --- | --- | +| Intent and policy authoring | Goal lifecycle plus the canonical Goal authority; `acceptance_authority.ts` supplies a transaction pattern, not full-intent semantics | Owner-authored complete root/policy, exact source lifetime and provider revision; no inferred root from an acceptance document or team receipt | +| Proposal | `goal_amendment_proposal.ts` / `.py`, existing durable admission journal | Bind the actual intent revision/digest, template revision and complete work basis. Historical Stage 2 source-only proposals remain readable but cannot be silently upgraded into commit-ready proposals | +| Current source and actor | Current Goal source/lifetime and canonical writer fences | Same Goal instance, current registered proposer and supported profile must remain admitted through the commit boundary; stale source, recreation or unsupported owner refuses | +| Work-item planning | `todo_create.ts::planCoordinationTodoCreate` and the existing Todo domain normalizer | Plan an active, unclaimed Agent record from the fixed template. Reuse role, scope, duplicate and record rules; do not call the standalone create transaction and then separately update the Goal | +| In-flight work | Complete canonical Todo/lease snapshot and existing lease owner | This operation leaves every existing Todo and lease unchanged. Record the applicable `unaffected` disposition and exact observed basis; a stale basis conflicts. An operation needing cancellation/fence rotation is outside this policy and must not relabel its impact as unaffected | +| Canonical effect | `prepareCoordinationProjectionCommit`, existing `AuthorityStore` CAS and `CoordinationCommandReceipt` recovery | One accepted transaction publishes the new Todo, Goal revision/basis change, amendment event and immutable receipt, with the same operation/proposal identity. No intermediate Todo-only or revision-only state may become authoritative | +| Replan settlement | Existing autonomous-replan semantic observation and acknowledgement owner | The canonical receipt binds the exact obligation and committed outcome. The owning reader must validate and consume that evidence; an unchecked string, ordinary acknowledgement or new side ledger cannot settle it | +| Peers and projections | Shared alignment, Agent Vision/frontier and existing projection delivery owners | Expose the new Goal basis and whether each peer has adopted it. Preserve current work only under its explicit compatible disposition; new semantic writes based on the old revision reject or rebase | +| Operator result | Existing Goal/Agent interaction, proposal detail and readback; CLI and packaged frontend share the same typed result | Distinguish submitted, canonically committed, historical replay and pending replan/peer adoption. A stored receipt is not a claim, lease or current execution grant | + +The amendment owner must compose the existing **planner**, not nest a separate +Todo commit inside a second transaction. A duplicate/equivalent existing Todo +must follow the existing semantic-duplicate rules without inventing another +Goal advancement. Operation replay returns its original historical result; +changed operation content conflicts. The current authority projection is read +separately so a replay cannot restamp old evidence as the latest Goal state. + +The atomic unit includes the canonical amendment and its exact settlement +fact. Replan history, UI projection delivery and peer adoption are separate +owner readbacks, not fictitious cross-store writes inside the provider CAS. +If a reader cannot yet consume the committed evidence, report that pending +boundary and keep the affected continuation held. Recover delivery using the +same receipt/operation; never reapply the Todo or write an independent success +ACK to make the projection green. The implementing change must show the actual +consumer path before claiming Stage 3 replan settlement complete. + +A provider exception after dispatch is ambiguous until the original receipt is +read. Retain the operation identity and fence; do not generate a replacement +id or infer no effect from a timeout. For a request-derived proposal, all of +§5.1's reservation, commit/abort ordering and request-side linkage are also +required. A profile missing those capabilities must refuse request-derived +commit while preserving proposal admission and unrelated work. It must not +strip source context and relabel the request as a direct Goal proposal. + +#### One implementation package and decisive acceptance + +Deliver the following as one useful stage package rather than independent +serializer, registry or receipt-only PRs. The first supported local profile +must execute the actual owning backend and packaged interaction; simulated +providers do not qualify the transaction. + +1. An owner can inspect the full root/policy, explicitly authorize the bounded + template operation and read it back through the same Goal lifetime. A regular + Agent cannot initialize, replace or widen it. Off/legacy behavior is unchanged. +2. A registered proposer creates an in-envelope proposal, sees its exact current + basis, commits the template work item without a per-proposal human approval, + and reads the newly created unclaimed Todo plus its immutable amendment receipt. +3. Exercise incorrect/missing lifetime, unsupported profile, stale Goal/provider + revision, edited template/proposal, unregistered actor, protected fields, + stopped Goal and incompatible lease impact. Each rejects without partial + mutation; unrelated Goal/Agent work retains its existing path. +4. Lose responses before and after the actual provider commit and restart the + caller. The same operation yields zero or one canonical transaction and one + original outcome, with independent Todo, Goal-basis and receipt readback. + A stale concurrent proposal rebases; an already committed replay remains + historical. No generic retry creates a second work item. +5. Complete exact-obligation settlement and have two peers read the new basis: + one continues compatible leased work, the other adopts the new unclaimed work + through ordinary claim/lease admission. Prove stale semantic writes cannot + proceed, and that adoption is observed rather than inferred from message send. +6. In the packaged Goal/Agent journey, inspect unavailable/stale states, correct + the proposal, reload after a lost response and read both the committed result + and any remaining adoption hold. CLI reads the same owner state. Lark remains + separately unqualified until its actual interaction is tested. If shared + PostgreSQL authority code is changed, run its isolated real-server suite; + File/SQLite fixtures do not stand in for it. + +Revert before activation by removing the unconsumed candidate. After a root or +amendment has been committed, keep its historical readers and fences: disabling +the entrypoint cannot delete intent, roll back committed work or permit old +writers. Use the original owners' forward reconciliation/retirement procedures. +This package is a prerequisite for the broader Stage 4/5 and manager acceptance, +not evidence that those milestones or G1's two real cycles have completed. + ### Steward execution integration (2026-09-16) [Roadmap](loopx-overall-roadmap-v0.md) R1 repairs team-plan source-basis preconditions; R4 supplies the product continuation for Stage 3–5. The current team receipt `intent_basis` only reuses `source_basis_digest`, a source-facts summary that does not cover the full objective/non-goals/acceptance/permissions/stop envelope. It may be absent and is not a CAS precondition. Do not claim full canonical intent binding. diff --git a/docs/architecture/rfcs/shared-goal-alignment-and-governed-amendment-v0.zh-CN.md b/docs/architecture/rfcs/shared-goal-alignment-and-governed-amendment-v0.zh-CN.md index e037d9ad4b..93990b18b1 100644 --- a/docs/architecture/rfcs/shared-goal-alignment-and-governed-amendment-v0.zh-CN.md +++ b/docs/architecture/rfcs/shared-goal-alignment-and-governed-amendment-v0.zh-CN.md @@ -622,6 +622,108 @@ proposal/admission 与提交不可用边界，无关工作继续。验收后， 随后验证已支持 commit 路径。本文保留 Stage 3–5 的实现与晋级责任；管家就绪不能 悄悄把这些阶段标为完成。 +### 9.2 首个 commit 事务提案：一个受 policy 约束的工作项 + +这是 §9.1 要求在 runtime 实现前评审的具体事务映射，不是已交付 commit API、新 +权限 profile 或激活批准。Stage 1/2 仍只接纳 proposal。首个 Stage 3 操作属于 +`shared_work_graph`：从 **owner 预授权的固定 template 创建一个未认领 Agent Todo**。 +不编辑 acceptance、权限、既有 Todo 语义、依赖或其他 Agent 的工作。普通 Todo 创建 +仍使用原 writer；只有 admitted proposal 需要在该 policy 下记录共享 Goal revision +及精确 replan settlement 时，才使用 amendment 路径。 + +固定 template 是有意收窄的首个 policy，不是任意自然语言是否保持 intent 的分类器。 +owner 一次性选择其有界用途及完整 authority-relevant Todo 字段。proposer 只选择 id +并提供 operation/causal identity，不能替换正文、write scope、capability、recipient、 +claim/lease、审批结果、验证结果或 template revision。其他 amendment 操作需要各自 +经过评审的 policy；此选择不扩大 Agent 现有权限，也不要求 owner 为所有普通 Todo +预写 template。 + +#### 根意图、policy 与生命周期 + +操作可用前必须存在 §3.1 的完整 canonical envelope：objective、non-goals、acceptance、 +permission/write boundary、stop/terminal condition、不可变 root intent、policy、 +Goal revision 和 intent digest。source Goal lifecycle 拥有准确的 `goal_instance_id`； +provider identity、Todo digest、state-event sequence 或既有 acceptance contract 都 +不能代替它。初始化是该准确 Goal 上显式的 trusted-owner 操作，不是 Agent 字段更新， +也不是从 Markdown 自动导入。legacy Goal 保留原路径，直到 lifecycle owner 接纳明确 +迁移；amendment 模块不能另造一个无关 id。 + +intent 和 amendment receipt 保存在**既有 canonical Goal projection 与原子 journal**， +不在旁边新建文件/store。复用 source/lifetime owner 的 admission 与 retirement fence， +使 Goal recreation 不能与 commit 竞态；提交前读一次 identity 不足以保证这一点。 +当前 generic registry 路径拒绝仅生命周期用途的 `source_session_v1` profile；本提案不 +豁免该门，也不授予所有 business effect。选定 profile 必须先验证这个明确 owner， +才可 commit。 + +policy 标明允许的操作、固定 template 与 revision、合格 registered proposer、有界 +创建范围/容量及显式 out-of-policy disposition。缺失 policy 表示不可用，不能隐式放行。 +该确定性 class 可按配置采用准确 template/authority 校验自动决定；需要独立 verifier +的 class 仍遵循 §4 的独立 actor 与准确 proposal digest。policy membership 不替代当前 +runtime permission、capability、lease 或 stop 校验。本操作不能修改 root intent。 +初始化和 retirement 必须通过既有 lifecycle owner 可重试；丢响应不能新建第二个 root， +也不能重新激活已退役 root。 + +#### 事务与读回归属 + +| 边界 | 复用的既有 owner | 必须实现的行为与可观察结果 | +| --- | --- | --- | +| intent/policy 编写 | Goal lifecycle 与 canonical Goal authority；`acceptance_authority.ts` 仅提供事务模式，不是完整 intent 语义 | owner 编写完整 root/policy，绑定准确 source lifetime/provider revision，不能从 acceptance document 或 team receipt 推断 root | +| proposal | `goal_amendment_proposal.ts` / `.py` 与已有 durable admission journal | 绑定真实 intent revision/digest、template revision 和完整 work basis；历史 Stage 2 source-only proposal 可读，但不能静默升级为可 commit | +| 当前 source/actor | 当前 Goal source/lifetime 与 canonical writer fence | 同 Goal instance、当前 registered proposer 和支持的 profile 必须保持 admitted 直到提交边界；stale source、recreation 或 unsupported owner 拒绝 | +| 工作项 planning | `todo_create.ts::planCoordinationTodoCreate` 与既有 Todo domain normalizer | 从固定 template 规划 active、未认领 Agent record，复用 role/scope/duplicate/record 规则；不能先调用独立 create 事务再单独更新 Goal | +| 在途工作 | 完整 canonical Todo/lease snapshot 与既有 lease owner | 既有 Todo/lease 一律不变，记录适用的 `unaffected` disposition 与准确观察 basis；stale basis 冲突。需要取消/fence rotation 的操作不属于该 policy，不能伪装成 unaffected | +| canonical effect | `prepareCoordinationProjectionCommit`、既有 `AuthorityStore` CAS 与 `CoordinationCommandReceipt` recovery | 同一个已接纳事务写入新 Todo、Goal revision/basis 变化、amendment event 和不可变 receipt，共用 operation/proposal identity；不能出现单独 Todo 或单独 revision 成为 authority 的中间状态 | +| replan settlement | 既有 autonomous-replan semantic observation/acknowledgement owner | canonical receipt 绑定准确 obligation 与已提交结果，由 owning reader 验证并消费；未经校验的字符串、普通 ACK 或新旁路账本不能结算 | +| peer/projection | shared alignment、Agent Vision/frontier 与既有 projection delivery owner | 显示新 Goal basis 及各 peer 是否已采纳；仅按明确兼容 disposition 保留在途工作；基于旧 revision 的新 semantic write 拒绝或 rebase | +| 操作者结果 | 既有 Goal/Agent interaction、proposal detail/readback，CLI 与打包前端共用类型化结果 | 区分 submitted、canonical committed、历史 replay 和仍待 replan/peer adoption；receipt 不是 claim、lease 或当前执行 grant | + +amendment owner 必须组合既有 **planner**，不能在第二个事务里嵌套一次独立 Todo +commit。已有相同/等价 Todo 遵循原 semantic-duplicate 规则，不伪造一次 Goal 推进。 +operation replay 返回原历史结果，operation 内容变化则冲突。当前 authority projection +单独读回，不能把 replay 的旧证据重新标成最新 Goal 状态。 + +原子单元包含 canonical amendment 及其准确 settlement fact。replan history、UI +projection delivery 和 peer adoption 是各自 owner 的读回，不是 provider CAS 内虚构的 +跨 store 写入。如果 reader 尚不能消费已提交证据，必须显示该 pending 边界并保持受影响 +continuation 的 hold。用同一 receipt/operation 恢复交付，不能重做 Todo 或独立写成功 ACK +让投影变绿。实现变更只有证明真实 consumer 路径后才能声称 Stage 3 replan settlement +完成。 + +provider dispatch 后的异常在读回原 receipt 前保持 ambiguous。保留 operation identity +和 fence，不能生成替代 id，也不能从 timeout 推断无效果。request-derived proposal 还 +必须满足 §5.1 全部 reservation、commit/abort ordering 与 request-side linkage。 +profile 不支持时必须拒绝 request-derived commit，同时保留 proposal admission 和无关 +工作；不能删除 source context，把它改称直接 Goal proposal。 + +#### 一个实现包与决定性验收 + +以下形成一个有用的阶段实现包，不拆成相互独立的 serializer、registry 或 receipt-only +PR。首个支持的本地 profile 必须执行真实 owning backend 与打包交互；模拟 provider +不能证明事务。 + +1. owner 能检查完整 root/policy，显式授权有界 template 操作，并在同一 Goal lifetime + 读回。普通 Agent 不能初始化、替换或扩大它。off/legacy 行为不变。 +2. registered proposer 生成 in-envelope proposal，看到准确当前 basis，无需逐提案人工 + 审批即可 commit template 工作项，并读回新未认领 Todo 与不可变 amendment receipt。 +3. 覆盖错误/缺失 lifetime、不支持 profile、stale Goal/provider revision、编辑过的 + template/proposal、未注册 actor、protected field、已停止 Goal 及不兼容 lease impact。 + 每项均无部分变更；无关 Goal/Agent 工作保留原路径。 +4. 在真实 provider commit 前后丢响应并重启 caller。同一 operation 只能有零或一个 + canonical transaction 和一个原结果，并分别读回 Todo、Goal basis 与 receipt。 + 过期并发 proposal rebase；已提交 replay 保持历史性质；普通 retry 不能产生第二项工作。 +5. 完成精确 obligation settlement，让两个 peer 读取新 basis：一个继续兼容 leased work， + 另一个经普通 claim/lease admission 接纳新未认领工作。证明 stale semantic write 不能 + 继续，并观察真实 adoption，不能用消息发送代替。 +6. 在打包 Goal/Agent 流程中检查 unavailable/stale 状态、修正 proposal、丢响应后 reload， + 读回已提交结果及剩余 adoption hold；CLI 读取相同 owner 状态。Lark 在实际交互验收前 + 单独未资格。若改动共享 PostgreSQL authority 代码，运行隔离真实 server suite； + File/SQLite fixture 不能代替它。 + +激活前可以移除尚无 consumer 的 candidate 回退。root 或 amendment 已提交后，必须保留 +历史 reader 和 fence；禁用入口不能删除 intent、回滚已提交工作或允许旧 writer。 +继续使用原 owner 的 forward reconciliation/retirement。这个包为更广 Stage 4/5 和 +manager 验收提供前置，不证明这些 milestone 或 G1 两轮真实协作已完成。 + ### 管家执行衔接（2026-09-16） [统一路线](loopx-overall-roadmap-v0.zh-CN.md) R1 修复团队计划的源基线约束，R4 拥有本 RFC Stage 3–5 的产品接续。当前 team-plan receipt 的 `intent_basis` 仅复用 `source_basis_digest`；后者是来源事实摘要，不覆盖完整 objective/non-goals/acceptance/permissions/stop envelope。该字段可缺失且不是 CAS precondition；不得声称计划已绑定完整 canonical intent revision。