fix(heartbeat): clarify scope-bounded work without tiny-step bias

[huangruiteng]

Summary

Clarify that bounded execution limits scope and budget, not the number of operations or files. The default thin heartbeat previously retained bounded slice but omitted the fuller explanation that related work can be completed together.

• Share compact work-sizing guidance across full/compact/brief/thin and visible-goal prompts. Size work by task, evidence and risk toward a verifiable result; neither a tiny operation nor a large batch is universally required.
• Align ordinary CLI action descriptions and project/self-repair skills. Fine-grained mode retains independent checkpoints, fresh-evidence successor checks and one settlement per coherent effort.
• Keep compatibility mode names, schemas, profile thresholds, permission gates, monitor/recovery limits, scheduler cadence and explicit stop/replan transitions unchanged. This intentionally changes model-facing guidance, not the execution state machine.

Validation

• 217 targeted pytest tests passed: heartbeat prompt support, notification authority, recommendations, fine-grained mode, host-loop activation, guided-start projection and recommendation refinement.
• Heartbeat prompt CLI smoke passed, including all absolute prompt budgets and real generated CLI packets.
• Quota heartbeat-recommendation and interaction-contract state-machine smokes passed.
• Both edited skills passed the skill validator; git diff --check passed.
• Public boundary scan passed (22 scanned files, zero errors). The shared local registry reported three unrelated existing warnings; no registry or runtime state was modified for this change.

The smoke retains absolute character budgets and ordering between prompt sizes, replacing incidental percentage-compression assertions so essential shared instructions are not dropped merely to achieve a ratio. Existing copy assertions were updated to the new wording; added coverage checks compaction, terminal boundaries and fine-mode opt-in isolation.

Scope and limits

The existing heartbeat rule module owns this guidance; no new capability, protocol, budget knob or state ledger is introduced. Sharing the rule removes duplicate semantics without a new abstraction layer. Only public product source, documentation and synthetic tests are included.

No live model behavior qualification was run: these results establish prompt propagation and protocol regression coverage, not measured improvement in agent delivery. No installation, automatic prompt replacement, merge or production action is included.

[liubf21]

详细中文评审

结论：REQUEST_CHANGES。 Reviewed head: 03768b0bffe9093b5fdf339b5fb42818dd682b08。方向和代码归属合理，但默认 CLI 输出突破现有相对增长预算；已在本地独立复现 CI 的五项失败，修复前不建议合并。

动机

旧版 full prompt 已允许相关实现、测试和文档组成一个 bounded batch，但默认 thin prompt 仍主要保留 bounded slice，没有带上如何确定工作规模的解释。模型可能因此把一个操作或一次写回当成停止点。这个 PR 把工作粒度解释为任务、证据、风险、授权和预算内的可验证结果，同时承认一个聚焦修复也可能足够。保持原状不能解决默认入口的信息丢失；只改 thin 又会让不同压缩模式和普通动作描述继续表达不同含义。因此，在现有规则模块共享简短指导、同步相关文案是合理的小范围修复。代码能够证明指导传播，尚不能证明真实模型的交付效果已经改善；PR 正确披露了这个限制。

改动思路

入口仍是 heartbeat-prompt → build_heartbeat_prompt → 已有 task-body renderer；权威输入仍来自执行 profile、goal boundary 和 quota/interaction contract。新常量放在既有 heartbeat/rules.py，没有新 capability、provider、状态存储或第二套执行决策。默认 thin、full/compact/brief，以及共用 _render_goal_task_body 的 Goal host 都消费这条规则。workflow_skill_install.py 的现有源解析与安装路径以及运行提示中的 skill routing 使两个修改后的 skill 属于真实指令面，不能只按文档审查。

正向路径：eligible goal 经过 quota guard 获得执行义务，renderer 提供按范围推进的指导，完成后沿既有验证、持久写回、refresh/spend 路径结算。fine mode 则额外追加 checkpoint 规则，完成当前 Todo 后先读 fresh evidence，再决定 successor；本次未改变该条件分支。负向路径：should_run=false、monitor quiet/no-spend、recovery-only 和 terminal no-follow-up 的限制仍由既有 quota/host 合同承担；工作规模指导不覆盖这些停止条件。

复用扫描覆盖 pre-change a5b43072ada7fb3fc0073098bc2faa9250f9e9f3 与本次 head 的 builder、task_body、rules、start_contract、recommendation、primary_action、interaction_contract 和 workflow skill 安装路径。邻接 #4125 同时调整共享 heartbeat 文案的语言策略，合并顺序需要重跑 prompt 测试；#4140 的 delivery readback 是不同边界，本 PR 也没有因此获得自动更新或真实调度送达证明。

具体改动

完整 diff 为 17 文件、+122/-71：7 个产品 Python 文件、2 个 skill、2 篇文档、4 个 pytest 文件和2 个现有 smoke。没有新增文件或抽象层。

关键代码讲解

1. heartbeat/rules.py::SCOPE_BOUNDED_WORK_RULE 与 heartbeat/task_body.py 的各 renderer：统一“操作/文件数不决定停止点”的指导，并保留预算、授权、停止与重规划约束。full 中的验证要求改为与变更风险相称；compact 同时压缩了引导文字；thin 直接追加新规则，是输出增长问题的一个来源。
2. heartbeat/builder.py::FINE_GRAINED_TURN_RULE、build_heartbeat_prompt：把 small checkpoint 改为 independently verifiable checkpoint，强调拆分独立决策；追加规则仍受规范化后的 fine granularity 控制，guard/spend 命令构建不变。
3. goals/start_contract.py::build_goal_start_prompt：只改 fine 分支的 Todo/工作描述，保留禁止预写 successor、fresh-evidence 检查、方向变化 replan 和一次结算。用相同合成输入比较，普通 start prompt 在 base/head 间逐字相同。
4. quota/heartbeat_recommendation.py::_default_rule、_post_handoff_observation_rule：修改 spend/reason 文案，保留兼容模式名和分支次序。work_items/primary_action.py::resolve_canonical_primary_action 与 interaction_contract.py::protocol_action_packet_fields 同步普通 bounded-delivery fallback 动作文字，没有增加新的执行授权。
5. 两个 skill 与两篇文档同步当前指导；prompt smoke 保留绝对预算和尺寸排序、移除百分比压缩要求；新增 pytest 证明四种尺寸包含共享规则、Goal host 保留 terminal/settlement 约束，fine 测试保留 opt-in 与 successor 检查。新增测试偏指令传播覆盖，不能替代全局 CLI 相对预算检查或真实模型行为验证。

对主干的风险

[P2，阻塞合并] 默认输出增长超过仓库的 CLI budget contract。

触发点是默认 thin heartbeat 和普通 quota should-run 的 Markdown 输出。heartbeat/task_body.py:688 加入新规则，quota/heartbeat_recommendation.py:619-620 延长默认 spend policy 后，现有真实 CLI differential 失败：

• surface/heartbeat_prompt_thin/{small,crowded,multi_agent}/markdown：UTF-8 bytes 增长 99，允许 64。
• surface/quota_should_run/{small,multi_agent}/markdown：chars 增长 41，允许 32。

CI checks 日志 与本地结果一致。独立复现命令：

python examples/control_plane/cli-output-base-head-differential-smoke.py \
  --base-ref 34b7d02db20e5ab9eabca71e3e71e7f77f5108ad \
  --main-ref 34b7d02db20e5ab9eabca71e3e71e7f77f5108ad

这些失败发生在绝对 prompt budget 仍通过时，所以调整 heartbeat-prompt-smoke.py 的压缩比例断言不能解决它。最小修复是在现有规则和默认 spend-policy 文案中压缩冗余，保留工作规模、停止、授权和结算语义，再运行 cli-output-budget-regression-smoke.py 及 heartbeat smoke。不要仅提高通用 allowance 或刷新预期来消除失败。该问题是输出预算回归，不是已证实的越权或错误结算。

验证结果：

• 本地 147 pytest tests passed：prompt support、recommendation rules/refinement、fine-grained mode、host-loop activation、notification rule。
• heartbeat-prompt-smoke.py、quota heartbeat recommendation state-machine smoke、interaction-contract state-machine smoke 均通过；后两者实际使用了本地 TypeScript runtime。
• 额外 8 组 base/head × prompt-size/fine-mode 配对比较通过：guard/spend 命令、fine 规则启用和 successor fresh-evidence 边界一致；普通 start prompt 逐字相同。通用 sizing 文案本身是已披露的默认变化，因此没有将整段 prompt 冒称为字节级兼容。
• git diff --check 通过；完整 diff 未见新增私有路径、凭证、raw evidence 或内部组织上下文。CI 日志另显示 Ruff 与 mypy 通过。
• CLI base/head differential 失败，五项；未声称全量 suite、真实模型效果或安装后自动调度送达已验证。

审查 lenses：未新增字符串状态分类或第二套状态权威；新指导对实现、研究等目标通用；默认变化已在文档和重命名测试披露；must_attempt_work 的强制执行与工作规模指导仍有区分；没有新增 actor/authority 协议名。fine 的启用条件仍独立，两个共享 skill 的变更也没有无条件加入 fine checkpoint 义务。

我的整体评价

问题成立，现有 heartbeat 规则模块是合适的归属，17 个文件主要是在同步同一个模型可见语义，不属于过度架构。future-facing refactor pass 已考虑 rule ownership 与 fallback 文案：共享 sizing 常量已经完成有价值的有限整理；无需为了两个相同 fallback 字符串新增通用层。

本次明确阻塞是可复现的 CLI 输出预算回归。压缩两个受影响输出并使必需检查通过后，适合重新审查；真实模型是否减少过早停止仍是未验证效果，不能从模板断言推导。此结论仅覆盖以上 exact head，不包含安装、自动替换 prompt 或合并授权。

[liubf21]

English verdict: REQUEST_CHANGES at 03768b0bffe9093b5fdf339b5fb42818dd682b08. The guidance change is cohesive and reuses the existing heartbeat rule owner, but real CLI output exceeds the existing base/head growth contract: three thin-prompt Markdown fixtures grow by 99 UTF-8 bytes (64 allowed), and two quota Markdown fixtures grow by 41 characters (32 allowed). Independently reproduced all five failures against 34b7d02db20e5ab9eabca71e3e71e7f77f5108ad, matching CI. Compress the shared prompt/default spend-policy text without weakening authority, stop, or settlement instructions, then rerun the budget and heartbeat smokes. Validation: 147 focused pytest tests, three relevant smokes, eight paired base/head fine-mode checks, and diff hygiene passed. No new state-machine defect was established; live model delivery improvement remains unverified.

[huangruiteng]

Addressed the CI failures in 03f6b4083.

• Kept the scope-bounded guidance. Narrowed the default spend-policy wording without changing its meaning.
• Intentionally raised only the thin-prompt UTF-8 growth allowance to 192 bytes for bilingual lifecycle guidance. Character, line, absolute-output budgets and all other surfaces remain unchanged. Added negative coverage proving those boundaries still reject excess growth.
• Updated two stale managed-host assertions to the current equivalent Goal-continuation wording; the no-successor-to-continue and closure checks remain.

Validation: 92 focused pytest checks, heartbeat-prompt-smoke.py, and the full real-CLI absolute plus base/head budget regression passed. No live model behavior qualification or installed automation mutation is claimed. Hosted CI is rerunning.

Product judgment: scope/budget should bound authorized work, not impose an arbitrary operation count. The narrowly disclosed byte adjustment is preferable to deleting lifecycle guidance merely to satisfy an ASCII-oriented growth allowance. The automation installation/update lifecycle is being handled separately; this PR does not silently replace users' installed prompts.