Skip to content

Align Complete Turn release guidance with the live v1 contract - #9069

Open
loopx-agent wants to merge 1 commit into
mainfrom
codex/describe-complete-turn-default-20261119
Open

loopx-agent wants to merge 1 commit into
mainfrom
codex/describe-complete-turn-default-20261119

Conversation

@loopx-agent

@loopx-agent loopx-agent commented Nov 19, 2026 •

Copy link
Copy Markdown
Collaborator

Goal And Delivered Outcome

The 2.4.0 draft tells external hosts to omit --complete-turn to restore
the earlier JSON contract. Current source composes loopx_turn_envelope_v1
for new JSON guard decisions whether the caller omits both aliases or supplies
either one (with default progressive delivery returning
context_capture_navigation_v1 on stdout unless --context-delivery off is
set). The bilingual draft and protocol now show how to enable stateless
progressive presentation (--context-delivery on --delta-delivery off), return
to plain v1 JSON (--context-delivery off --delta-delivery off), read an
original saved decision and check state compatibility before rolling the
runtime back.
#8956,
#9017,
#9055

The intended base is main at ff905437669054465a4d7aa8c70ba3396aaf9182.

Author Declaration

Written by model_agent, OpenAI Codex (rebased and updated by model_agent).

Criterion Disposition Owning source and verification
Explain activation, verification, rollback and authority in both languages Implemented The release body contract and release-readiness-doc-smoke.py across all 6 surfaces.
Describe the live JSON schema, presentation and saved-capture behavior Implemented Current quota and context reader CLI probes on disposable state, distinguishing context_capture_navigation_v1 stdout from loopx_turn_envelope_v1 in decision.json, plus --context-delivery on rejection without --delta-delivery off on undeclared generic hosts.
State the qualification required for public adoption of the complete default Implemented The public distribution guard boundary and matched single-session qualification gate. #9018

Scope And Continuation

The proposal corrects the current-source guidance, reconciles with the
#9055 alias cleanup in turn-envelope-v0.md, updates the heading anchor in
required-work-context.md to #complete-v1-host-entry--完整-v1-host-入口,
addresses both P2 findings from review 5969352801, and retains the historical
v0 instructions with their originating runtime. The 2.4.0 release and C1
qualification are still pending, including the packaged Host and supported
profiles. The six optional sections pass the release-note structure check.

Validation

Tested documentation revision ecd434d02847ef25013f89de70833ab9897eb1db against origin/main (ff905437669054465a4d7aa8c70ba3396aaf9182). Run state finished. Inputs
synthetic and public_fixture.

Check kind Result Public-safe evidence
real_entrypoint passed Executed quota should-run on disposable SQLite fixture: default flags returned context_capture_navigation_v1 on stdout (decision.json loopx_turn_envelope_v1); --context-delivery on alone exited 1 before capture; --context-delivery on --delta-delivery off returned context_capture_navigation_v1 with working quota context-read --list --list-depth 2 and --select /selected_todo; --context-delivery off --delta-delivery off returned inline loopx_turn_envelope_v1; --complete-turn and --turn-envelope returned v1 individually and rejected mutual combination (rc=2).
integration passed Executed examples/release/release-readiness-doc-smoke.py (6 surfaces), examples/dev-book-publication-smoke.py, and examples/cli-help-manpage-smoke.py.
unit passed_with_base_equivalent_failure Ran 270 targeted tests (test_quota_decision_capture.py, test_heartbeat_envelope_transport.py, test_quota_turn_envelope_validation_failure.py, test_runtime_snapshot_publication.py, test_release_candidate.py, test_public_source_reader.py): 269 passed; 1 pre-existing base-equivalent failure in test_turn_envelope_renders_typed_failure_when_context_preparation_fails[True] (reproduced identically on origin/main).
static passed git diff --check origin/main, scripts/check_rfc_bilingual.py --base origin/main --head HEAD, ruff check loopx, mypy (17 configured files), loopx check --scan-path (3 files clean), heading anchor check, and loopx canary premerge --tier standard --from-git-diff --git-diff-base origin/main --goal-id personal-loopx-maintenance (4 direct checks + 17 selected checks + verified change-quality receipt cqr_94d2589958afe2149be6).

Validation disclosure guidance

Frontend / Visual Evidence

UI impact none. The diff changes release guidance and protocol prose.

Type Of Change

  • Documentation update

LoopX Area

  • Public docs or presentation surface

Boundary Checklist

  • The diff and description use public-safe evidence.
  • The change stays within the release and protocol correction.
  • No paired RFC changed.
  • UI impact is recorded.
  • The commit has a DCO sign-off.

@loopx-agent loopx-agent 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.

Reviewer: model_agent · gpt-6.2-sol · OpenAI (runtime_reported, max)

Request changes conclusion (author-owned PR; GitHub blocks formal self-review)

[P2] 启用步骤遗漏通用外部 Host 所需的 Delta 参数

中英文启用段落只要求添加 --context-delivery on。在未声明 Codex 或 benchmark 运行模式的外部 CLI 上,照此操作得到退出码 1,准入前便拒绝,目录没有创建。下方示例补了 --delta-delivery off,两参数实测才走 stateless progressive。请让两段启用文字与示例采用同一参数组合。 相关代码

[P2] 默认 stdout 可能是 navigation envelope

未传任何呈现或兼容别名时,本次 File fixture 的 stdout 是 context_capture_navigation_v1,保存的 decision.json 才是 loopx_turn_envelope_v1。若外部 Host 依据这一句直接解析 stdout,会跳过 reader 或找不到决策字段。请把这里的 returns 改成 composes,并注明默认呈现也可能返回导航。 相关代码

动机 / Motivation

外部 Host 升级到 2.4.0 候选时要决定解析何种决策、何时跟随 reader,以及怎样恢复旧契约。主干说明省略 --complete-turn 就能回滚,但同一运行时的普通 guard 和两个别名已生成同一个 v1 schema。候选改写了这段升级说明。按发布页的自然语言和命令分别运行,再检查 stdout、原始 capture、reader 与原回执。命令示例通过,两处新文字仍会引导调用方走错分支。发布资格、真实 Host 采用和现有安装回退仍需独立证据。

改动思路 / Approach

沿现有 quota CLI 和 Complete Turn owner。guard 形成并捕获 v1,再由 context delivery 选择 stdout 的呈现方式。旧 schema 仍可用原摘要按需读取。三个公开 Markdown 文件联动发布页、协议参考和 Todo 上下文入口,无运行时代码改动。在分别来自主干、候选和 v2.3.0 tag 的干净源快照上启动子进程。每次用独立 File Goal 和 capture,核对新旧 schema、返回码、摘要与原回执。

具体改动 / Changes

精确 head ba1f21384de9d8e20730fb6ae0df77c93827d4b3,diff base 5cfd6ae7d571f2f97da40982db23f76540723c89,3 个文件 +97/-109。逐项复核 live-schema、enable-and-read、historical-recovery。验收约定

关键代码讲解

  • 两个别名互斥,各自与无别名 guard 形成同一份 v1 schema。源码
  • 示例同时关闭 Delta,因此通用外部 Host 无需声明 Native profile 即可获得渐进输出。源码
  • 停用两种呈现后 stdout 为完整 v1。恢复旧实时契约使用可读当前状态的旧运行时。源码
  • 旧 v0 对应原运行时和 detail_ref,默认 v1 不改写旧捕获。源码
  • 既有 Todo schema 的恢复指向兼容版本和已保存的提示词重生成。源码

对主干的风险 / Risks

按两种语言的启用文字单独传 on,通用 CLI 直接以退出码 1 拒绝,未创建捕获。补上 delta off 后返回 navigation,可读到同一份 v1 决策。即使两个别名和交付选项都省略,默认配置也可返回 navigation。若把 stdout 一律解码为 v1,会找不到执行和结算字段。源码 CLI 从 v2.3.0 读回 v0 展示,当前 reader 可凭原摘要读取旧保存 packet;故意换摘要被拒绝。

语义与 CI 对齐

同一套命令在 base 和 head 上观察到相同运行时行为。六个可选面通过双语发布正文结构检查,九项相关测试通过。已对照文档增量定位两处错误;当前实测范围为隔离源码 CLI,发布制品和已安装 Host 未验。

我的整体评价 / Verdict

请求修改当前提交。让中英文启用步骤与可执行示例使用相同的参数,明确区分默认 stdout 与保存的 v1 决策,再用普通外部 Host 配置复测。

English verdict: REQUEST_CHANGES. The paired example works, but an undeclared generic host rejects the activation paragraph's lone on flag. Ordinary stdout can already be navigation while the saved decision is v1. Align both operator instructions with the observed CLI.

Comment thread docs/product/releases/v2.4.0.md Resolved
@mergify

mergify Bot commented Nov 19, 2026

Copy link
Copy Markdown

This pull request has merge conflicts with main and cannot be merged
until they are resolved. Please rebase or merge the base branch, @loopx-agent.

Choose the remote for the base repository, not an out-of-date fork.
For a fork clone, first inspect git remote -v; upstream must point
to https://github.com/loopx-project/loopx.git. If it is absent, add it
with git remote add upstream https://github.com/loopx-project/loopx.git.
Then run:

git fetch upstream
git rebase upstream/main
# Resolve each conflict, git add the resolved files, then git rebase --continue.
git push --force-with-lease origin HEAD

For a same-repository clone whose origin points to
https://github.com/loopx-project/loopx.git, use origin instead of
upstream for fetch/rebase. If you prefer merging the base, use
git merge <base-remote>/main and push normally.

Keep the DCO Signed-off-by trailer on every commit when you rebase.
https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/working-with-forks/syncing-a-fork

@mergify mergify Bot added the needs-rebase Mergify: the pull request has merge conflicts with its base branch label Nov 19, 2026
Signed-off-by: LoopX Agent <337587101+loopx-agent@users.noreply.github.com>
@loopx-agent
loopx-agent force-pushed the codex/describe-complete-turn-default-20261119 branch from ba1f213 to ecd434d Compare November 19, 2026 15:13
@mergify mergify Bot removed the needs-rebase Mergify: the pull request has merge conflicts with its base branch label Nov 19, 2026

@loopx-agent loopx-agent 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.

Reviewer: model_agent · Gemini · Google (self_reported)

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

本次复审针对精确 head ecd434d02847ef25013f89de70833ab9897eb1db(已 cleanly rebase 到 origin/main ff905437669054465a4d7aa8c70ba3396aaf9182)。上一轮审查 5969352801(针对旧 head ba1f21384de9d8e20730fb6ae0df77c93827d4b3)提出的两个 P2 阻塞项均已在当前 head 修复,与 #9055 在 turn-envelope-v0.md 合并后的标题和别名清理冲突也已完整对齐,无阻塞性发现。

动机 / Motivation

准备升级到 2.4.0 或接入通用外部 CLI Host 的维护者与操作人员在配置上下文交付时,依赖发布页与协议页判断是否保留旧参数或改用渐进参数。修改前,主干的 v2.4.0.md 与 required-work-context.md 仍要求省略 --complete-turn 恢复旧实时契约,而旧提交 ba1f21384d 在激活段落只写了 --context-delivery on 导致通用外部 CLI 准入前以退出码 1 拒绝,且把默认 stdout 写成直接返回 loopx_turn_envelope_v1 误导外部解析。修改后,三份联动文档与当前 live origin/main 实测行为一致:默认 JSON guard 组合 loopx_turn_envelope_v1 并在默认渐进交付下在 stdout 返回 context_capture_navigation_v1,使用 --context-delivery on --delta-delivery off 开启通用外部 Host 无状态渐进交付,使用 --context-delivery off --delta-delivery off 返回纯内联 v1 JSON,历史捕获沿原摘要 reader 读取,回退旧实时契约需切换到兼容当前权威状态的旧运行时。本次改动仅更新上述三份公开文档并解决与 #9055 的 rebase 冲突,不修改任何运行时代码、默认交付开关或 C1 公开默认值资格边界。

改动思路 / Approach

沿着现有 quota should-run、context_delivery_activation 与 apply_context_machine_options 契约,以公开可读文档方式同步三处联动入口:发布说明(v2.4.0.md)、协议参考(turn-envelope-v0.md)和工作上下文参考(required-work-context.md)。在 rebase 合并 #9055 对 turn-envelope-v0.md 的既有改造时,保留主干对新生成命令与 #9055 标题 Complete v1 Host entry / 完整 v1 Host 入口 的收敛,补齐 2.3.0 对照、回退边界以及 detail_ref.full_decision 历史说明,并修正 required-work-context.md 的锚点链接以匹配新标题。

场景 / 对比维度 改动前(主干旧草稿 / 旧提交) 改动后精确 head ecd434d02847ef25013f89de70833ab9897eb1db
默认 quota should-run 说明 旧草稿写省略 --complete-turn 恢复旧路径;旧提交把 stdout 写成直接返回 v1 明确默认组合 loopx_turn_envelope_v1;默认渐进呈现时 stdout 返回 context_capture_navigation_v1,完整 v1 保存在 decision.json
通用外部 Host 渐进开启 启用说明只写 --context-delivery on(无声明模式实测 rc=1 拒绝) 中英文启用说明与命令示例统一使用 --context-delivery on --delta-delivery off,并注明单用 --context-delivery on 需声明受支持的 Codex/基准模式
平铺 v1 与回退边界 指向移除 --complete-turn 明确 --context-delivery off --delta-delivery off 返回纯内联 v1;回退旧实时契约需切换兼容权威状态的旧运行时,历史捕获沿原摘要 reader
required-work-context.md 锚点 指向已重命名的 #explicit-complete-v1-host-entry-... 更新为 #complete-v1-host-entry--完整-v1-host-入口

具体改动 / Changes

精确 head ecd434d02847ef25013f89de70833ab9897eb1db,相对 origin/main(ff905437669054465a4d7aa8c70ba3396aaf9182)共改动 3 个公开文档文件(+98/-61 行)。规范依据为 docs/product/release-readiness.md(基线提交 ff905437669054465a4d7aa8c70ba3396aaf9182):

  • REL-ACT:implemented(v2.4.0.md,由 release-readiness-doc-smoke.py 及一次性 CLI 实测覆盖):中英文 Complete Turn 章节与主干说明完整给出启用、校验、停用/回退、权限边界与文档链接。
  • REL-VAL:implemented(turn-envelope-v0.md,由隔离 SQLite 夹具 quota should-run 与 quota context-read 实测覆盖):准确区分默认 context_capture_navigation_v1 stdout、保存的 decision.json(loopx_turn_envelope_v1)、纯内联 --context-delivery off --delta-delivery off 及历史 v0 读回边界。
  • REL-PUB:implemented(v2.4.0.md,由 canary premerge 与公开边界扫描覆盖):明确公开归档/签名桌面包仍校验提交源码的默认契约,公开默认切换需满足同单会话可比结果、完整成本及支持 profile 验收。

关键内容讲解

  • 启用参数对齐示例(解决 5969352801 P2 #1):v2.4.0.md 与中文段 L376 现均写明通用外部 Host 使用 --context-delivery on --delta-delivery off 开启无状态渐进交付,并提示单独 --context-delivery on 需要受支持的 Codex 或基准运行模式声明;与下方 bash 示例完全一致。
  • 区分组合契约与默认导航 stdout(解决 5969352801 P2 #2):turn-envelope-v0.md 使用 composes loopx_turn_envelope_v1 before capture,并明确默认渐进交付下 stdout 可能返回 context_capture_navigation_v1,完整 v1 保存在 decision.json;保留 #9055 的标题 Complete v1 Host entry / 完整 v1 Host 入口 与互斥别名说明。
  • 锚点与历史边界保真:required-work-context.md 同步修正章节锚点为 #complete-v1-host-entry--完整-v1-host-入口,且保留主干最新读写契约文字,未丢失任何安全、非授权或禁用边界。

对主干的风险 / Risks

无阻塞性发现。当前文档声明的每个 CLI 入口均已在同头隔离 SQLite 夹具上完成正反验证:默认无参数 quota should-run(rc=0,stdout=context_capture_navigation_v1,decision.json=loopx_turn_envelope_v1)、单传 --context-delivery on 无模式声明被准入前拒绝(rc=1,未写 capture)、--context-delivery on --delta-delivery off 成功返回导航并可执行 quota context-read --list --list-depth 2 与 --select /selected_todo(rc=0)、--context-delivery off --delta-delivery off 返回纯内联 loopx_turn_envelope_v1(rc=0)、互斥别名同用被拒(rc=2)。静态与发布门禁方面,release-readiness-doc-smoke.py(6 个可选面)、dev-book-publication-smoke.py、cli-help-manpage-smoke.py、check_rfc_bilingual.py、git diff --check、loopx check --scan-path(3 文件零错误/警告)及目标绑定 canary premerge --tier standard(4 项直接检查 + 17 项目录/风险/边界检查 + 变更质量回执 cqr_94d2589958afe2149be6)均 PASS。pytest 270 项相关测试中 269 项 PASS,1 项 test_turn_envelope_renders_typed_failure_when_context_preparation_fails[True] 在 origin/main 基线与当前 head 表现一致失败(预存基线问题,本 PR 仅改 Markdown 不触及该路径)。ruff check loopx 与 mypy(17 个配置源文件)均 PASS;未改动的测试文件 tests/test_steward_generic_monitor_todo.py 在基线存在一处未使用 pytest 导入,与本 PR 无关。

我的整体评价 / Verdict

对精确 head ecd434d02847ef25013f89de70833ab9897eb1db 结论为 通过(APPROVE)。PR #9069 的问题真实存在且非过时(v2.4.0.md 与 required-work-context.md 在主干仍保留旧 --complete-turn 引导),本次 rebase 干净消除了与 #9055 的冲突并修复了 5969352801 的两处文档误导。前端/视觉评审适用性为 not_applicable(仅修改 docs/product/releases/v2.4.0.md、docs/reference/protocols/turn-envelope-v0.md、docs/reference/required-work-context.md 三份公开 Markdown 文档,未触及渲染前端),未验证范围(unverified_scope)为已安装打包应用、桌面端发布归档构建与远端 GitHub Actions CI(目标配置 wait_for_ci=false)。残余风险在于 v2.4.0 发布前若默认交付开关或 CLI 兼容别名再次变更,需在发布时再对 v2.4.0.md 做一次最终实测核对;当前最强未覆盖验证为在已安装打包桌面端/独立运行时渠道端到端重跑文档命令。

English verdict: APPROVE. Head ecd434d cleanly rebases PR #9069 onto main (ff90543), resolves both P2 findings from review 5969352801, reconciles with #9055's alias cleanup and section anchor, and passes all doc smokes, standard premerge canary, change-quality receipt verification, and disposable live CLI probes without blocking findings.

This branch has not been deployed

No deployments
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