[Feature]: 长程目标下新增 reportable 触发点「阶段性完工/进入 replan」，即使有剩余 todo 也能引导 agent 发周报

[huangruiteng]

背景

periodic-report 目前的 reportable trigger kinds（capabilities/periodic_report/triggers.py）都是「结果型/事件型」：

• manual / cadence_due：手动或日历驱动
• material_blocker / material_decision / material_recovery：异常与决策
• primary_goal_outcome / vision_closed：主目标交付或目标关闭

对于长程目标（例如金融深研这种有大量剩余 todo、可持续数周甚至数月的工作），agent 需要在「阶段性完工 / 进入 replan / 完成一个有边界的批次」等工作节点发周报，而不是等目标关闭（vision_closed）或主目标交付（primary_goal_outcome）。当前这些节点没有可报告的 trigger kind：

• vision_closed 只在目标终态关闭时触发，长程目标可能几周都不会关闭；
• primary_goal_outcome 只在有最终交付结果时触发；
• cadence_due 是纯日历驱动，无法表达「这个节点发生了有意义的推进」；
• todo_completed 是非报告类 kind（静默），且是单条 todo 粒度，不是「批次/段」级别。

诉求

1. 新增一个 reportable trigger kind，例如 bounded_segment_milestone（别名：advancement_batch_completed / milestone_checkpoint），语义为：agent 完成一个有边界的阶段/批次，并进入 replan 或继续长程推进，即使仍有剩余 todo 也应触发周报。

2. facts 建议字段（与现有 kinds 一致的白名单 + 严格校验）：

   • segment_ref（必填，段标识，如 week-2026-W34 / segment-2026-08-24）
   • transition（如 replan_entered / segment_completed / vision_checkpoint）
   • delivered_count（本段交付数）
   • remaining_todo_count（剩余 todo 数，明确「还有剩余 todo 也照样触发」）
   • durable_writeback（布尔，是否已写回控制面）
   • material 判定建议：transition 为 segment_completed 或 replan_entered 且 durable_writeback=True 即视为 material。

3. 触发优先级：建议介于 cadence_due(10) 与 material_decision(50) 之间（如 30–40），避免压过手动/异常触发，又高于纯日历。

4. 报告映射：复用现有 milestone 类报告（如 milestone_update），renderer 沿用 weekly 预设的 html + markdown 双渲染。

5. 可选增强：trigger_policy 增加「聚合阈值」能力——当非报告类 todo_completed 在窗口内累计达到 N 条、或控制面进入 replan 时，自动晋升为 reportable 的 bounded_segment_milestone，让周报既可以在工作节点上被 agent 主动申报，也可以被策略自动兜底。

为什么这对长程目标重要

长程工作（如持续数周的深研/交易准备）最缺的不是「目标关闭时的总结」，而是阶段边界上的定期回顾：做了什么、证据链推进到哪、剩余 todo 还剩什么、下一段计划。现有 trigger 语义把「可报告」绑定在终态或异常上，导致长程目标要么等关闭、要么靠纯日历，丢失了「进入 replan 这个关键节点」本身的信息。新增 bounded_segment_milestone 可以把控制面已有的 replan/段边界事件自然映射为周报触发点。

[huangruiteng]

Implemented and validated in #3527, which merged to main. Closing this request as completed.

[huangruiteng]

更正：#3527 完成的是第一阶段——新增 bounded_segment_milestone、严格 facts 校验、优先级/weekly preset 接入、文档与测试。原 issue 第 5 项“根据窗口内 todo_completed 累积或进入 replan 自动晋升为 reportable trigger”的增强尚未完成。

因此此前“已全部完成”的结论过早；后续应继续以本 issue 跟踪剩余阶段。此回复仅纠正完成范围，不执行 issue 状态或元数据变更。

[huangruiteng]

Follow-up：provider-neutral post-writeback capability hook

PR #3554 完成了 periodic-report 的 capability-side runtime producer：它能从 durable public-safe rollout events 生成 typed trigger decision，但目前只有显式 CLI caller，没有修改 LoopX 执行循环 core，也不会在 Todo 完成、replan 或 durable writeback 后自动运行。

这意味着本 issue 的 trigger / aggregation producer 阶段可视为已推进，但“让 LoopX bot 自动发周报”的 core 接线仍未完成。建议后续独立 PR 落下面这个最小 contract：

1. Core-owned typed hook registry：control-plane 提供 provider-neutral 的 post-writeback hook contract；capability 注册关心的 durable event kinds，不允许 core 反向 import periodic_report，也不接受任意 shell command 作为扩展接口。
2. 明确调用边界：只在 primary durable writeback 成功并取得 event receipt 后，由 orchestrator boundary dispatch；不要把 capability invocation 塞进底层 append_rollout_event_once。
3. 最小公开输入：hook 只收到 public-safe event identity、goal/agent/todo identity、state/version 与必要的 bounded projection；不得获得 raw task、日志、轨迹、凭据或隐式写权限。
4. Typed intent 输出：hook 返回有 schema、idempotency key、budget、failure policy 和 requested write scope 的 intent。periodic-report hook 可返回 trigger-evaluation intent，后续仍复用现有 compose-run → renderer → authorized sink 边界。
5. 隔离与监督：primary writeback 不因可选 capability 失败而回滚；失败需可观察、可重试、去重，多个 hook 的顺序/预算/故障隔离必须由 core contract 决定。
6. 真实闭环验证：覆盖 disabled capability 零调用、成功 writeback exactly-once、失败/重复 writeback 不误触发、hook failure 不污染主事务、无外部写权限，以及 fake scheduler 下 completion/replan 自动产生 report intent 的 E2E。

完成标准不是“存在一个可手动调用的 producer”，而是：core 在合法 writeback 后通过通用 hook contract 自动产生 periodic-report intent，同时保持 capability-owned policy、core-owned lifecycle 与 sink-owned external effects 三者权威分离。

关联：#3527 的架构讨论、PR #3554 的 producer 前置件。

[huangruiteng]

#3551 is now a concrete vertical example of the core-hook direction discussed here, implemented as a read-time interaction projection hook:

1. The CLI composition root registers repository_change_window.repository_delivery; quota/core orchestration does not import the capability.
2. Core owns a typed loopx_capability_hook_registration_v0 contract with one invocation, bounded result bytes, declared projection slots/read scope, mandatory failure isolation, and an empty write scope.
3. Registration is admitted by the TypeScript boundary before the provider runs. The capability then returns a path-free status candidate; TypeScript validates it and is the sole owner of the repository_delivery_gate_v0 mapping.
4. Only an installed, fully verified provider may project commit/push admission. External/legacy diagnostics, drift, malformed output, producer exceptions, or slot conflicts fail closed or remain not-applicable without blocking the primary quota decision.
5. The real closure test is quota should-run in a repository with the installed reference_guard: the hook projects prepare/validate separately from commit/push, includes next_eligible_at when blocked, and grants neither Git effects nor remote-write authority.

This also clarifies the phase boundary for the proposal in this issue: the above contract is intentionally phase=interaction_projection, not a post-writeback callback. The post-writeback form should reuse the provider-neutral registry/supervision shape, but add a separate registration/result schema whose input is the successful primary durable receipt and whose output is a typed idempotent intent. It should not inherit write authority from this read hook.

PR: #3570

[huangruiteng]

Follow-up：provider-neutral post-writeback capability hook

PR #3554 完成了 periodic-report 的 capability-side runtime producer：它能从 durable public-safe rollout events 生成 typed trigger decision，但目前只有显式 CLI caller，没有修改 LoopX 执行循环 core，也不会在 Todo 完成、replan 或 durable writeback 后自动运行。

这意味着本 issue 的 trigger / aggregation producer 阶段可视为已推进，但“让 LoopX bot 自动发周报”的 core 接线仍未完成。建议后续独立 PR 落下面这个最小 contract：

1. Core-owned typed hook registry：control-plane 提供 provider-neutral 的 post-writeback hook contract；capability 注册关心的 durable event kinds，不允许 core 反向 import periodic_report，也不接受任意 shell command 作为扩展接口。
2. 明确调用边界：只在 primary durable writeback 成功并取得 event receipt 后，由 orchestrator boundary dispatch；不要把 capability invocation 塞进底层 append_rollout_event_once。
3. 最小公开输入：hook 只收到 public-safe event identity、goal/agent/todo identity、state/version 与必要的 bounded projection；不得获得 raw task、日志、轨迹、凭据或隐式写权限。
4. Typed intent 输出：hook 返回有 schema、idempotency key、budget、failure policy 和 requested write scope 的 intent。periodic-report hook 可返回 trigger-evaluation intent，后续仍复用现有 compose-run → renderer → authorized sink 边界。
5. 隔离与监督：primary writeback 不因可选 capability 失败而回滚；失败需可观察、可重试、去重，多个 hook 的顺序/预算/故障隔离必须由 core contract 决定。
6. 真实闭环验证：覆盖 disabled capability 零调用、成功 writeback exactly-once、失败/重复 writeback 不误触发、hook failure 不污染主事务、无外部写权限，以及 fake scheduler 下 completion/replan 自动产生 report intent 的 E2E。

完成标准不是“存在一个可手动调用的 producer”，而是：core 在合法 writeback 后通过通用 hook contract 自动产生 periodic-report intent，同时保持 capability-owned policy、core-owned lifecycle 与 sink-owned external effects 三者权威分离。

关联：#3527 的架构讨论、PR #3554 的 producer 前置件。

@cmyk-labs FYI