fix(cli): expose refresh authoring limits before writeback - #5653

Reviewer: model_agent; model=gpt-6.1-sol; provider=OpenAI; runtime_reported; reasoning_effort=xhigh

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

Exact reviewed head: 1798a929bcd996a35713601c55f98df20ed096ce. Review policy revision: 18.

动机

维护者或 Agent 在第一次写入进展、补齐检查点和提交证据时，需要从 CLI 帮助找到合法的调用方式。
以前帮助没有说明检查点恢复须先有原 Turn 写回，也没有明确证据 ID 和 Todo 摘要的长度边界；head 让这些规则直接出现在对应命令帮助中，减少无效尝试。
真实 CLI 帮助与现有校验规则一致，首次写回与恢复路径仍通过测试；但新增文本移动了两处 registry 读取行号，登记清单未同步，完整语义检查出现新的失败。
本 PR 不改变写回、恢复、长度校验、权限或默认行为，也不证明长期模型成功率已有提升。
规范基准：docs/reference/protocols/goal-vision-replan-contract-v0.md @ d3a22cd8e65dcb86c3d483b7e75afbc492669280；reuse-current-owner 对应既有恢复/配置 owner、原身份与继承边界，本次代码和真实入口均已核验。完整语义校验另按仓库既有必需检查判断。

改动思路

完整 diff 仅涉及两处已有文件：命令注册模块与现有 ownership 测试。修复点属于既有 CLI 发现入口，未增加操作或改写业务判断。checkpoint-context 的说明准确对应既有 read_checkpoint_context：须已有原 Turn 的提交，首次应直接在 refresh-state 携带 vision；恢复才读取新 context，并复用原身份。

具体改动

register_refresh_state_command 给证据 ID 说明了 ASCII 开头、1–128 字符、后续允许字符、可重复以及不上传文件；--vision-todo-delta 说明每项 80 字符、只保留前 8 项和共享预算。新增测试复用真实 ID normalizer 和 TypeScript authoring contract，没有另建 Python budget owner。我对照不可变 base 做 AST 比较，剔除 argparse 的 help/description 后完全相同；实际运行两个帮助入口，并通过 11 项 authoring/budget 测试和 39 项真实隔离恢复测试，包括首次无提交拒绝、恢复、错误/过期上下文与同 Turn 写回。相邻重构检查认为当前 owner 已足够，未发现值得增加模块的伴随重构。

对主干的风险

[P2 / blocker] 同步 registry I/O 清单。 新帮助文本移动了 handle_refresh_state_command 的两个 load_registry site；登记的 source line 未更新。完整 native semantic suite 为 353 passed / 1 failed。不可变 base d3a22cd8e65dcb86c3d483b7e75afbc492669280 的相同 drift 命令只报 quota 的 line 310→311；head 新增两个 refresh handler metadata mismatch。逐项完整 census 比较确认这是新增回归，不能因 focused tests 通过或存在 baseline 红项而忽略。请运行 python scripts/generate_project_registry_io_manifest.py，逐项审查分类，再执行 python -B examples/semantic-vocabulary-drift-smoke.py；使用 checkout 的测试解释器。不要放宽校验或把旧 quota 问题当作本 PR 根因。
运行时参数、ID admission、检查点/预算 owner 与权限边界仍保持；八组冻结时钟的完整默认 queue/observer 对照也相同。公共边界检查无新增私有路径/日志/凭证。无新增 capability 操作，所以现有 frontend/Lark 不需 companion 配置；不查询或等待 CI。一次误用 python -m loopx 因包无 main 失败，已改用实际 loopx.cli.main 入口，不归因于本 PR。

我的整体评价

方向合理，提示准确且验证了正负路径，当前 exact head 仍有新引入的必需校验失败。请在同一 PR 补齐清单并提供新的精确 head；新版本需重新核验，不沿用此结论。保留失败与未测范围：没有实测长期模型采纳收益，也不声称恢复/模型问题全部解决。当前不批准、不合并。

English verdict: REQUEST_CHANGES - 1798a92; accurate help and 50 CLI/budget/recovery cases pass, but two newly stale refresh registry I/O census sites fail native semantic validation; update the manifest and revalidate.

Reviewer: model_agent; gpt-6.1-sol; OpenAI; runtime_reported; reasoning_effort=xhigh

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

Exact head: b9bc2ec71052e56326c889485c88aa0bde9d07f2; immutable comparison base: e1aa319de8777ef5a1a9b94eebfb343eff2db51d. 全量三文件 +51/-4 已复核；另行核对前次 review 对原 head 1798a929bcd996a35713601c55f98df20ed096ce 的两处 census 定位缺口。

动机

使用 CLI 为一次工作写回愿景、Todo 调整和证据标识的用户与 Agent。
原 help 没有说明 Todo 条目长度和保留数量，证据标识容易被误填为文件路径；checkpoint-context 也容易被当成首次写回前的准备步骤，造成可避免的拒绝或绕路。现在执行命令前即可读到已有限制，并明确首次直接写回、只有已提交写回缺少 checkpoint 时才读取恢复上下文。
真实 CLI help 已呈现这些说明；五类参数解析、证据标识校验和完整 TypeScript authoring 合同与基线一致，真实 checkpoint 恢复及重复回读的原有隔离规则继续通过。
本次只完成既有 CLI 合同的发现说明和随之移位的两处 registry 索引定位；不收紧预算、不新增扣额或恢复权限、不把 help 当成已执行写回，也不宣称整套宿主完成流程全部通过。

改动思路

最强的反对理由是 help 可能复制错误预算，或用一条通过的文字测试掩盖实际写回与恢复缺陷。这里沿用既有 argparse 注册入口，Python 只解释命令，不成为预算或恢复决策 owner。Todo 条目预算来自原 TypeScript vision owner；证据标识来自既有 normalizer；checkpoint-context 原来就读取同 Goal/Agent/Todo/Turn 的已提交写回。没有新 provider、配置开关、CLI 参数或权限服务。

普通任务的最短路径仍是首次直接 refresh-state 写回 vision。已提交写回缺 checkpoint 时，才用原身份读取 fresh context，再按原 receipt 执行恢复。新增说明没有要求额外预读或重新确认。实际 CLI --help 已读回；整模块 AST 只移除 help/description 字符串后与基线一致，五类实际 parser 输入、七类 identifier 和完整实际 TS authoring 合同逐项相同。原始完整帮助、参数与合同捕获保留，未靠筛掉诊断证明等价。

具体改动

关键代码讲解

1. register_refresh_state_command（loopx/cli_commands/project_lifecycle_refresh_state.py:80）在既有三个位置补齐说明：checkpoint-context 是 committed writeback 后恢复；evidence ID 以 ASCII 字母或数字起始，1–128 字符，后续允许既有字符集合，可重复且不上传文件；Todo delta 每项最多80字符、仅前8项保留，同时计入既有整包预算。原 flag、append 动作、required/default 均未改。
2. handle_refresh_state_command（同文件:410）仍调用既有 scoped read provider 和 refresh/settlement owner。帮助文字让两处 load_registry 由606/687移至622/703；生成 manifest 只更新这两处 line，281项中的其他 metadata、schema、顺序、分类和 source policy 全部不变。没有新增 registry read 或改变来源权威。
3. replan_writeback_requirements（progress_observation.py:329）仍是 Python 到实际 TypeScript owner 的桥。新增测试调用这个 owner 来核对80/8，不新增 Python budget。测试没有凭 mock 提供预算后再宣称符合产品合同。
4. normalize_progress_identifier（progress_result.py:12）未改；实际正反例验证合法opaque ID、128边界、129拒绝、leading-dot路径拒绝、空值/非ASCII/空格拒绝。格式合法不意味着文件存在或证据被上传，这一权限边界在 help 中明确。

已接受规格：docs/reference/protocols/goal-vision-replan-contract-v0.md，固定 revision d3a22cd8e65dcb86c3d483b7e75afbc492669280。判据逐项映射：Ownership Boundary implemented，复用 TS 预算/恢复规则与原 Python 展示适配；CLI Budget implemented，原字段和1,800整包预算不变，help解释现有80/8而不改预算；Read basis for checkpoint-only recovery implemented，原committed writeback、fresh scoped context和同Turn约束有真实恢复/隔离/重放证据。前次评审的 reuse-current-owner 要求也满足；本次没有用作者新描述替代该规格，也没有宣称更大 RFC/Goal 完成。

新增31行测试是 help 与实际 owner 的合同检查；18/-2生产变更只有 help/description；另2/-2是源位置修正。前瞻重构检查已做：现有 owner 足够，新 helper/抽象或第二套验证器没有当前消费者价值，未加框架或兼容分支。

对主干的风险

语义与 CI 对齐

先运行当前差异 semantic advisory，再跑全树 semantic smoke。修复前实际失败是两处 refresh registry census metadata mismatch；修复后 full-tree smoke 通过，架构 semantic 家族651项通过、零失败。空 advisory 不是等价证明；完整manifest对照、实际owner合同和整模块AST才共同支持本次判断。更早旧规格基线的 quota locator 漂移已由主干既有修复处理，没有拿它解释或忽略本 PR 的两处错误。

聚焦 authoring/recovery 组实际是89通过、5失败；不可变基线同组84通过、同样5失败（当前多5个 CLI ownership/help 测试）。五个失败均在未触及的 host vision 完成测试：首次 vision 写回成功，随后显式选择下一 Todo 被既有 autonomous_replan delivery frontier guard 拒绝。额外捕获的五份完整 failed settlement packet 在基线与当前版本逐项完全一致，不只比较数量，也没有归一化掉诊断；guard/frontier/host owner 未改。当前真实 checkpoint read/recovery/isolation、File/SQLite provider fencing、stale/actor/Turn和重放负例通过，给改变的边界提供独立证据。五失败仍未修好，本评审不把整个宿主完成流程称为绿色。

Maintainer ratchet 两边 exit1，完整JSON仅 repository_root 不同；三项既有 debt 是 Lark any56/49、quota handler statements96/90、goal_boundary decisions63/60，完整指标、例外、finding保持相同。没有提高上限或缩窄扫描。Focused Ruff、diff/public boundary 和精确范围 change-quality 通过；uv.lock 仅本地未入提交，四条分支提交都有 sign-off，公开路径没有私有状态、原始日志或凭据。Native premerge canary passed：5项 direct、5项 selected 执行，maintainability 作为已归因的继承 advisory 保留，零 manual hold；strict exact-scope CQR 有效。CI 遵循当前 resolved 契约未查询、未等待。

最新主干 3bb268d7c4ca35c972fb1bcaf19837ba3ffeacaa 的 #5662 已查看：只改变 captured-envelope 的可选详情读取，未改本三文件、refresh参数、vision预算或checkpoint恢复owner；其输入默认保持；随后同步了主干 e1aa319 的 #5585，把 checkpoint source/evaluate 合并为同一 TS resolve，并在此新基线/精确 head 重跑实际 CLI/Node 合同与全组恢复验证。两处 refresh census 修复保留，checkpoint 自己的137行源定位沿用新主干。再后的主干56043933a07fa5d5b0dbecc1dca58aae1c6fc67f只改8项文档，未改本次 owner/consumer/spec，复用证据仍成立。没有新增 caller-facing 能力或配置，既有 apps/packages/frontend/Lark 消费路径未需要新的入口或编辑器，本次不宣称安装发行或 UI 验收。公开首次页面没有变化。再后主干5d0e21468cdea17283f7940d406a9f8ce331ded7（#5664）删除两个未用的 Python Todo transition adapter。两个 Python adapter 函数全树调用搜索零引用（原 TS 协议常量及其 TS 消费者仍保留）；现存 next-action/resume 函数 AST 与测试基线一致，refresh、checkpoint、vision、host settlement 和 frontier 相关 owner 字节也一致。因此这项清理不使当前 help/恢复证据失效。

主要剩余风险是未来 help 与 owner 漂移，以及现有 host guard 测试的预期欠账；前者由 owner agreement 和 native census 检查捕获，后者作为独立限制保留。语义分类复用现有 typed owner，没有 substring denylist 或域特定义务。帮助是说明，现有校验/receipt才是机器约束；描述权限不能授予恢复、扣额或上传权限。回滚只需撤回三文件，无 state/schema 迁移。

我的整体评价

这项 CLI 发现说明与 census 修复的有界目标已达到，delivery verdict 为 goal_achieved，仅指本次 slice。long_horizon preserved：执行决策、持久状态、同身份恢复和重放规则未变，五个既有 guard 失败如实保留；user_experience improved：真实命令帮助在写入前说明输入边界和最短合法路径，没有新增导航/确认负担。没有测量模型成功率、吞吐或长期 soak，测试数量不代表更大 Goal 完成。

全 PR 和前次 review-to-head 增量分别复核；结论基于当前651项语义、真实CLI/Node合同对照、真实隔离恢复正反例和本地 gate。用户已明确授权自合并；published exact-head review、远端读回、approval closeout 和 readiness仍分别验证，不由作者声明或 APPROVE 自动授予权限。

English verdict: APPROVE - exact head b9bc2ec; existing authoring and scoped recovery contracts are accurately exposed, and both shifted registry census locations are repaired. Actual CLI/Node parity and native semantic validation support this bounded slice. Five inherited host-guard failures and unchanged maintainability debt remain disclosed; CI was not consulted.