LoopSpec Demo：封闭 Loop 最小运行契约

结论

本轮实验把 Loop Engineering 从原则推进到可运行结构：用 LoopSpec 描述一个封闭 loop，用 LoopRun 记录一次 dry-run 的状态、阶段、验证结果、产物和 handoff 边界。

当前结果：

• Loop 数：4。
• ready_for_handoff 数：2。
• completed_dry_run 数：2。
• failed 数：0。
• knowledge gap 数：1。
• ask event 数：1。
• leak marker 数：0。
• missing artifact 数：0。
• stale generated 数：0。
• missing CI gate 数：0。
• projection retry scheduled 数：1。
• projection timeout 数：1。
• projection callback rejected 数：1。
• projection idempotency key 数：3。
• projection lease token 数：1。

这说明在没有企业微信接口时，Framework 不会假装 loop 已完整完成，而是把 Context Gap Collection Loop 停在 ready_for_handoff：ask event 已生成并验证，本地回复解析 contract 已由 --reply-text 固定下来，真实投递、签名校验和消息回调仍等待 WeCom adapter。

同时，Knowledge Maintenance Loop 已经能检查发布链路中的关键生成物：研发进度页、实验报告索引、Loop 报告、vault 索引和维护日志。当前 dry-run 没有发现缺失文件或 stale generated 输出，但语义层面的“内容是否过时”仍保留为人工 review handoff。

PR/Docs Health Loop 已经能检查 GitHub Actions workflow 是否覆盖项目看板、实验索引、Loop 报告、单元测试和 MkDocs strict build。当前本地门禁契约通过，真实 PR checks 和 review comments 仍保留为 GitHub adapter handoff。

Projection Remediation Retry Loop 已经能检查 stale projection 补证 worker 的 retry contract：waiting item 超过 lease 后进入 retry_scheduled，retry delay 到期后重新打开 adapter attempt，并轮换 attempt-level idempotency key；active lease 期间第二个 worker 不能抢占 item，错误 lease token 的 adapter callback 会被拒绝。当前 dry-run 通过，真实 Postgres/OpenSearch worker、持久化队列锁和 adapter callback 仍保留为外部 adapter handoff。

运行命令：

bash python scripts/loop_spec_demo.py --write-report

结果文件：

• vault/90-system/loop-spec-demo.json
• vault/50-outputs/loop-spec-demo-results.json
• vault/50-outputs/loop-spec-demo-analysis.md

LoopSpec 最小字段

当前 LoopSpec 至少描述：

字段	含义
loop_id	loop 标识
goal	目标和完成方向
trigger	触发条件
state_refs	外置状态来源
max_iterations	最大迭代次数
stop_conditions	停止条件
handoff_conditions	交还人工或外部系统条件
phases	discover / plan / act / verify / persist / decide / notify

每个 phase 还要有 objective、actions、verifiers 和 persist_outputs。这保证 loop 不是口号，而是可检查的运行契约。

当前 Demo Loops

Context Gap Collection

text Context Management Eval 发现 knowledge gap -> 读取缺口和 owner -> 生成 ask event -> 验证消息 contract 和泄漏标记 -> 写入 LoopRun 结果和报告 -> 判断真实企微投递尚未完成 -> 通过 docs/project-progress 暴露状态

当前 LoopRun：

指标	值
status	ready_for_handoff
iterations	1
completed_conditions	knowledge_gap_detected, ask_event_drafted, ask_contract_verified, safe_output_verified
handoff_conditions	requires_real_wecom_delivery
ask_event_count	1
leak_marker_count	0

Knowledge Maintenance

text 知识生产型变更发生 -> 检查项目看板、实验索引、Loop 报告和 vault 入口 -> 验证生成物是否同步 -> 写入 LoopRun registry -> 通过 docs/project-progress 暴露状态 -> 语义过时判断交给人工 review

当前 LoopRun：

指标	值
status	completed_dry_run
iterations	1
completed_conditions	project_status_dashboard_up_to_date, experiment_report_index_up_to_date, loop_report_present, required_knowledge_pages_present
handoff_conditions	requires_human_review_for_semantic_staleness
checked_artifact_count	5
missing_artifact_count	0
stale_generated_count	0

PR / Docs Health

text 准备提交或合并 -> 检查 CI workflow 是否覆盖必要门禁 -> 检查生成物 freshness -> 写入 LoopRun registry -> 通过 docs/project-progress 暴露状态 -> 真实 PR checks 和 review comments 等待 GitHub adapter

当前 LoopRun：

指标	值
status	ready_for_handoff
iterations	1
completed_conditions	ci_required_gates_present, generated_outputs_current, local_preflight_contract_verified
handoff_conditions	requires_real_github_pr_ci_status, requires_review_comment_polling
required_ci_gate_count	5
missing_ci_gate_count	0
local_preflight_passed	1

Projection Remediation Retry

text Projection Remediation Eval 发现 waiting item timeout -> 安排 retry_scheduled -> retry delay 到期后重新打开 adapter attempt -> 验证 attempt idempotency key 轮换 -> 验证 active lease 与 callback token guard -> 验证 safe output 不暴露幂等 key、lease token 或原始来源 -> 写入 LoopRun registry -> 真实 worker / 持久化队列 / adapter callback 等待外部接入

当前 LoopRun：

指标	值
status	completed_dry_run
iterations	1
completed_conditions	timeout_retry_scheduled, attempt_idempotency_key_rotated, lease_token_callback_guarded, safe_output_verified
handoff_conditions	requires_live_reindex_worker_adapter, requires_persistent_queue_locking
projection_retry_scheduled_count	1
projection_timeout_count	1
projection_callback_rejected_count	1
projection_idempotency_key_count	3
projection_lease_token_count	1
leak_marker_count	0

得到的 Insight

1. Loop Engineering 在产品里必须落成结构化状态，不应只停留在文档原则。
2. 没有企微接口时，真实状态应该是 ready_for_handoff，不是伪造“已发送”。
3. LoopRun 可以把 context eval、ask event、验证结果、报告和项目看板连接起来。
4. 研用测一体不能只靠人工习惯，至少要把生成物同步、关键入口存在性和报告 freshness 变成可检查的 loop。
5. PR/Docs Health 不能只靠口头约定；CI 必须覆盖生成物 freshness、测试和 MkDocs strict build。
6. Projection Remediation Retry 说明 worker retry、lease 和 callback policy 也应该进入 LoopRun，而不是隐藏在后台任务实现里。
7. 当前 dry-run 只能证明结构、本地门禁、生成物同步和本地 retry/lease/callback contract，不能证明语义不过时、真实 PR review 状态或真实 reindex worker 并发安全；这些判断需要进入后续 adapter / review queue。

下一步

• 企微 adapter 就绪后，把 requires_real_wecom_delivery 替换为真实消息投递、签名校验和回调事件，并复用现有回复解析与 knowledge card review。
• 把 requires_human_review_for_semantic_staleness 设计成可追踪的人工 review queue。
• 接入 GitHub PR adapter，把 requires_real_github_pr_ci_status 替换为真实 PR checks 和 review comments 轮询。
• 接入真实 reindex worker 后，把 requires_live_reindex_worker_adapter 替换为 Postgres/OpenSearch worker、持久化队列、并发锁、retry ledger 和 adapter callback。