feat(reward-memory): add agent-turn-recall and reward-memory walkthro…

[rootkiller6788]

…ugh (#GH-C71)

Summary

Issue Or Task

• Closes #
• Contributor task ID:

Validation

• python3 -m py_compile loopx/*.py
• loopx check --scan-root .
• Other:

Type of Change

• Bug fix
• New feature
• Breaking change
• Refactoring (no functional changes)
• Documentation update
• Test update

LoopX Area

• Control plane (goals, todos, quota, scheduler, registry, runtime)
• Benchmark boundary (adapters, runners, verifiers, scoring, evidence)
• Capability or extension (providers, adapters, skills)
• Public docs or presentation surface (README, protocols, dashboard)
• Build, packaging, installer, or CI
• Host or runtime integration

Boundary Checklist

• I did not commit .loopx/, .codex/goals/, live ACTIVE_GOAL_STATE.md, credentials, private benchmark traces, verifier output, raw agent sessions, internal document links, or local machine paths.
• I did not duplicate maintainer-owned benchmark work unless a maintainer split out a public issue for it.
• I kept the change scoped to the linked issue/task.

[huangruiteng]

Review PR #3115 — exact head 700f522032243b3e41d3272ff31ffe34fb7f3545

详细中文评审

动机

该 PR 为 Agent Turn Recall ↔ Reward Memory（GH-C71）补充贡献者可见的端到端 walkthrough smoke，证明从 corpus 健康到作用域 recall 的整条管线都已实现、可回归且默认不产生新 authority。Reward Memory 是默认关闭、仅建议、不授予权限的设计契约（Stage 3 opt-in），同时 Agent Turn Situation 必须与用户 prompt 解耦；这些安全边界分散在 loopx.capabilities.agent_turn_recall.core 与 loopx.capabilities.reward_memory 的多个函数中，缺少一条统一的可执行验证路径。本 PR 用单文件示例把 13 个场景串起来，是比分散断言更可维护的贡献者入口。

改动思路

改动集中在新增 examples/agent-turn-recall-reward-memory-walkthrough-smoke.py，不触碰产品代码、不依赖真实 provider（用 FakeProvider 模拟 retrieval）、不读写外部 sink。示例直接调用真实模块 API：build_agent_turn_situation、build_agent_turn_recall_preview、build_reward_memory_* 全族函数与 apply_reward_memory_recall，所有 fixture 均为合成数据。13 个场景按两个大面组织：Reward Memory（架构/registry/health/candidate/review/guard/active record）与 Agent Turn Recall（situation/preview/request/execute/apply/advisory），最后以完整管线收尾；每个载荷都经过 _assert_public_safe，main() 汇总失败并返回非零退出码。

具体改动

关键内容讲解

• FakeProvider 与 _corpus/_binding/_checkpoint/_quota_decision：用可注入的 retrieval 对象覆盖 completed/unavailable 两条路径；corpus 声明 scope、freshness、lifecycle、retrieval、maintenance、privacy 六个关键块；_quota_decision 合成一个不含用户文本的 quota 决策，保证 situation 与 prompt 解耦。
• 场景 1（架构边界）：reward_memory_architecture_v0 必须 status == design_contract、Stage 3 为 implemented_opt_in、confidence_never_increases_authority 出现在 safety invariants、automatic_recall == False。
• 场景 2/3（registry 与 health）：7 个 reference corpora 覆盖 5 个 class，raw_memory_captured 与 registry_persisted 均为 False；health 按 corpus 报告 pipeline 步骤，empty 状态 may_apply_memory == False，retrieval_verified 为 True。
• 场景 4/5/6（candidate 与 guard）：候选必须 raw_content_captured == False 且 candidate_persisted/provider_write_performed == False；review 的 accept/reject/edit/no_write 四种路径状态正确；verified == False 的 checkpoint 会让 accept 退化为 no_write 且保持 guard_blocked——这是最关键的失败闭环。
• 场景 7（active record）：只有 guard 通过的 accepted candidate 能成为 active，且 active 记录带 corpus scope 与可选 expires_at，provider_write_performed == False。
• 场景 8/9（turn situation 与 preview）：situation 不含 user_prompt_included，相同输入指纹一致、不同 turn 的 turn_recall_id 不同；preview 零 provider 调用、guidance 为空、execute_required_for_recall == True、exact_query_exposed == False。
• 场景 10/11（recall request/execute/apply）：request 校验 workspace/project/revision 作用域与 freshness/conflict，错误 project 触发 project_scope_mismatch；执行经 FakeProvider 返回 public packet 与 transient items；apply_memory 是 caller-owned 回调，provider unavailable 时 fail-open 保留 base output（fail_open_preserved_base == True）。
• 场景 12/13（advisory 与端到端）：active 记录 item 只是建议、grants_new_action_authority == False、raw_content_captured == False；完整管线 architecture → registry → health → candidate → review → active → situation → preview → request → execute → apply 的每个载荷都通过 public-safe 检查。

对主干的风险

• 无产品代码改动，git diff --check 干净；CI dependency-review 与 pytest 均为 SUCCESS。
• 示例漂移风险被结构抑制：全部场景调用 exact-head 的真实 capability API 而非硬编码输出；管线行为变化时 smoke 会失败。
• 不新增抽象或调用方：agent_turn_recall 与 reward_memory 均为已上线 capability 模块，本 smoke 只补公开回归路径，不存在“无活跃调用方”的 scope-fit 问题。
• 安全边界验证充分：guard 拒绝写、fail-open、prompt 解耦、raw content 缺席、无外部 sink 均有断言；FORBIDDEN 词表用字符串拼接构造以避免源码误判。
• 该 PR 文件较大（+1010），但内容与 13 个独立场景一一对应，建议按 Reward Memory / Agent Turn Recall 两个面 review；本地已独立运行全部场景通过，合入后可作为这两条 capability 管线的持续回归入口。

我的整体评价

同意合并（APPROVE）。1010 行的 walkthrough smoke 覆盖面与该管线复杂度匹配：它把 Reward Memory 的默认关闭/仅建议/不授权边界、corpus 生命周期、guard 拒绝写、Agent Turn Situation 的 prompt 独立性、recall 的作用域校验与 fail-open 应用全部落到可执行断言，且 13/13 场景在 exact head 700f522032243b3e41d3272ff31ffe34fb7f3545 本地独立运行通过；CI 双检查均绿。无阻塞项；建议后续把该示例加入常规 smoke 清单。

English Verdict

APPROVE — exact head 700f522032243b3e41d3272ff31ffe34fb7f3545.

Key finding: the walkthrough smoke exercises the real agent_turn_recall and reward_memory capability APIs across 13 scenarios (architecture boundary, corpus registry/health, guarded candidate lifecycle, prompt-independent turn situation, scoped recall with fail-open application, advisory-only records, full pipeline); all 13 passed in an independent local run at the exact head, CI dependency-review and pytest are both SUCCESS, and git diff --check is clean. No production code changes and no new abstractions; no blockers found.

Validation: local run of examples/agent-turn-recall-reward-memory-walkthrough-smoke.py (13/13 ok); CI checks 2/2 SUCCESS.

[huangruiteng]

详细中文评审（durable_smoke_value 门槛）

精确评审头： 3115@700f522032243b3e41d3272ff31ffe34fb7f3545

动机

本 PR 是单文件 examples/agent-turn-recall-reward-memory-walkthrough-smoke.py（+1010 行），演示 agent-turn recall 与 reward-memory。按 durable_smoke_value 门槛，例程类 PR 必须证明对仓库/产品的真实、持久价值；本 PR 不满足。

改动思路

13 个 scenario 覆盖 turn recall、reward memory、advisory recall 与完整 pipeline。作为演示自洽，但 reward-memory 已有专门测试与 smoke 覆盖，且文件体积达 1010 行。

具体改动（关键内容讲解）

• existing_coverage_scan：tests/capabilities/test_reward_memory_ingestion.py、examples/reward-memory-evaluation-smoke.py、examples/reward-memory-dogfood-smoke.py 已覆盖 reward memory 关键路径；本 walkthrough 与既有覆盖高度重叠。
• same_author_batch_scan：#3113–#3120 为同一作者 8 个同构 walkthrough 系列，本文件是该系列中体积最大者（1010 行）。
• real_product_or_repo_value_verdict：若 recall 语义确有未覆盖断言，应在 tests/ 补 thin focused test；1010 行 example 重复既有覆盖，对仓库是噪音。

对主干的风险

代码本身无运行时风险。风险在模式：同作者以超大体量同形状 walkthrough 系列占满队列，稀释真实 runtime 改动可见度。

我的整体评价

REQUEST_CHANGES。 修复建议（择一）：(1) 收敛为 thin focused pytest；(2) 与 #3113–#3120 系列合并为一个有差异化价值的 walkthrough。贡献行为警告：按 PR #3134 政策，若同一作者在警告后再提交此类低价值同形状 PR，将禁止该账号继续向本仓库提交 PR（owner 执行屏蔽）。

---

English Verdict

REQUEST_CHANGES — exact head 700f522032243b3e41d3272ff31ffe34fb7f3545.

Under the durable_smoke_value gate, this 1010-line example-only walkthrough duplicates existing reward-memory coverage (test_reward_memory_ingestion.py, reward-memory evaluation/dogfood smokes) and is part of the same author's 8-PR walkthrough series. Consolidate into thin focused tests or one differentiated walkthrough. Contribution warning: further low-value same-shape PRs will lead to the account being blocked from submitting PRs.