Learn From History Audit

Learn From History

把历史学习当成一个可观测改进环，而不是经验摘抄：固定输入，分层下钻证据，定位最窄变更面，为每项建议同时声明预测收益与回归风险，再由后续历史验证。

默认审计当前项目最近 7 个自然日期（含今天），不跨项目。默认只报告；用户已明确要求应用建议或提交时，按其授权范围完成，不重复确认。报告和 decision manifest 本身不扩大编辑、回滚或发布权限。

本流程采用 Agentic Harness Engineering 的三层可观测思想，并适配为有人确认的项目审计：

1. 组件可观测：每个失败模式只归属一个首选变更面；
2. 经验可观测：最终概览可下钻到 unit finding，再到固定 snapshot 的原始 thread；
3. 决策可观测：每个变更建议都是带收益预测、回归风险和验收条件的可证伪契约。

事实源

• 运行编排与 unit prompt：scripts/run_history.py
• 提取逻辑：scripts/extract_daily.py
• run 与 decision manifest 校验：scripts/validate_run.py
• unit 报告格式：references/analysis-template.md
• 跨轮决策账本：spec/reviews/history-learn-YYYY-MM-DD.json

extract_range.py 仅保留手工范围导出的兼容用途，不是主路径。

流程

0. 核对当前仓库的入口、产物位置与授权

先读根指引和 docs/standards/documentation.md。本仓库的维护入口是本文件及相邻 scripts/；其他安装目录中的旧副本不能替代受版本控制的实现。显式保留本轮用户要求的日期、项目、更新范围与提交授权，交接后从原始请求核对，不让压缩摘要重新解释权限。

本仓库按 DOC-HISTORY-001 / DOC-LINK-001 禁止重建 spec/reviews/，因此使用临时报告模式：报告与变更/验收记录写到本次 run 目录，稳定结论更新对应事实源；完整过程不进入仓库。该模式执行步骤 1–4、6 和已授权的编辑，使用 run validator 验证输入覆盖；步骤 5 和步骤 7 的持久 decision ledger 分支不适用，不声称通过 decision ledger 校验或形成跨轮因果归因。完成后按步骤 9 的临时模式清理输入。后文的 spec/reviews/ 账本协议仅用于明确允许该目录的仓库，不能借技能恢复已废弃目录。

1. 创建 snapshot run

从环境中的 Working directory 取得项目根，显式传入 --cwd：

python3 .claude/skills/learn-from-history/scripts/run_history.py \
  --days 7 \
  --cwd <工作目录>

只有用户明确要求跨项目时才使用 --all：

python3 .claude/skills/learn-from-history/scripts/run_history.py --days 7 --all

脚本创建权限为 0700 的唯一目录：

/tmp/learn-from-history/<run_id>/
  manifest.json
  snapshot/threads.db
  extracted/<day>/*.txt
  prompts/unit-NNN.txt
  summaries/

它通过 SQLite backup 固定本次审计的数据边界，提取物权限为 0600。manifest.json 是本次运行的唯一输入清单，记录 snapshot digest、repository_root、日期、thread、消息数、输入 digest、降级统计和分析单元。

完成标准：命令 exit 0，manifest status=ready 或 status=empty。任一日期失败时命令必须 exit 非零；不得分析部分成功结果。empty 时报告近期无记录并结束。

2. 检查 manifest

Read manifest.json，核对：

• project_filter 或 all_projects 与用户范围一致；
• window.active_days、totals.thread_count、totals.message_count；
• totals.truncations 与 totals.parse_failures；
• 每个 unit 的输入、消息数、prompt、summary 和 sidecar 路径。

再试读窗口两端及不同消息格式的 thread：有消息计数却只有空白正文、工具调用消失或系统提醒被当成用户原话时，先检查提取器与持久化协议。parse_failures=0 不单独证明内容完整。格式契约以 peri-acp-types/src/store.rs 和 messages/ 为准；修改提取器须用 legacy/V1 的真实 SQLite 往返、工具配对与损坏输入回归验证，不只测 JSON helper。修复后从同一 snapshot 补提取，记录旧/新 manifest 与 extractor digest，重审变化的输入；不得沿用旧 digest 或旧行号宣称完成。

本流程按 thread 的 updated_at 日期归档完整 thread，不按消息切断因果链。报告中写清该语义。

不要扫描 run 目录猜测输入，也不要读取其他 run 的同名文件。

3. 执行分析单元

每个 unit 的完整任务已经写入 prompts/unit-NNN.txt。派发 general-purpose agent 时，把该 prompt 文件内容作为任务；子 agent 自己直接 Read/Write，不得再次调用 Agent，不得修改仓库。

调度规则：

• 1 个 unit：同步执行；
• 2 个以上独立 unit：可后台并行，无固定并发上限；
• unit 较多时：分批启动，当前批次全部收到终态后再启动下一批；
• agent 失败时优先 resume 原 child thread，不创建重复任务；
• background 的 started/completed 通知不是通过证据，不轮询未完成结果。

单元按 thread 文件大小和数量规划，不机械按天切分；大日期可拆成多个 unit，小日期可合并。每个 agent 必须同时写：

• summaries/unit-NNN.md：thread 结果和跨 thread finding；
• summaries/unit-NNN.json：status=analyzed、输入 digest、覆盖数、finding 契约和降级复核。

优先比较相同或相近意图中的成功/失败轨迹，找出分歧点；它比单独阅读失败更能区分能力缺口、随机执行偏差和 harness 缺陷。每条 finding 的证据与反证必须写成：

extracted/<day>/<thread>.txt :: <可定位摘录或事件>

原始 thread 是证据层，不是默认阅读入口；先读 unit finding，主张不足时再下钻。输入中有 [TRUNCATED ...] 或 [MESSAGE_PARSE_FAILED] 时，必须人工评估该 thread 是否仍足够支撑 finding，并在 degraded_inputs_reviewed 登记；证据不足则写入 blocked，不得外推。

4. 机器校验经验层

所有 unit 终态后运行：

python3 .claude/skills/learn-from-history/scripts/validate_run.py \
  /tmp/learn-from-history/<run_id>

validator 检查：

• summary 非空且不是 null；
• sidecar unit ID、status=analyzed、thread 数和消息数；
• 输入文件集合与 manifest 完全相等，digest 未变化；
• 降级输入已显式复核，没有 blocked 输入或 extraction failure；
• finding 含 classification、failure pattern、root cause、可下钻 evidence/counterevidence、带分母 frequency、impact、confidence、fact source；
• finding 已选择 target surface，解释归属，并声明 predicted fixes、risk regressions 与 acceptance。

完成标准：命令 exit 0 且 validation.json 为 passed；其 attestation 记录本次实际读取的 manifest digest 与完整 sidecar {unit_id, path, sha256} 集合，供同日 decision ledger 复写并在后续审计中三方核对。失败 unit 优先 resume；校验通过前不得汇总或宣称完成。

5. 归因上轮决策

在汇总新建议前，按日期读取当前项目 spec/reviews/ 中相关的 history-learn-*.json。只处理 status=implemented、含实施验证，且未被任何更新账本给出经保留的 validation.json、manifest digest 和 unit sidecar 共同证明的 keep | revert 终局 verdict 的变更；自报或已丢失 run 证据的终局不生效，improve 与 inconclusive 保持待观察。

对每个 prior change：

1. 将 predicted_fixes 与本轮观察到的改善逐项对照；
2. 主动检查 risk_regressions，并从旧有成功模式中选择至少一个 preserved-success probe；
3. 区分“改动后发生”与“由改动导致”；没有同类对照、明确分歧点或独立验收时，不声称因果；
4. 给出 keep | improve | revert | inconclusive | not_implemented verdict；
5. revert 只是建议，仍需用户确认，且必须说明恢复范围与保留哪些有效部分。

历史窗口未覆盖实施前基线、相关场景未再次出现、运行环境或模型改变时，verdict 必须是 inconclusive，不能用“未再出现失败”冒充修复成功。

6. 聚合、去重与组件归属

只读取当前 manifest 列出的 unit summary/sidecar。每条 finding 先分类：

• rule_gap：真实稳定规则缺口；
• active_issue_covered：已有 active issue，禁止复制事故叙事；
• skill_gap：现有 skill 缺指引或触发失败；
• execution_deviation：规则已覆盖但未遵循；
• external_blocker：环境、权限、provider 或平台阻塞。

再读取当前项目根路由和 finding 所需的最小事实源：

• 根 CLAUDE.md：判断项目哲学与路由，不复制工程细则或事故叙事；
• docs/standards/ 与测试 canonical standard：稳定规则；
• 对应模块 CLAUDE.md：模块入口和专属不变量；
• spec/issues/：active change、事故验收和具体产品风险；
• spec/global/problems.md：历史索引；
• DiscoverSkillsTool：当前 skill catalog。

按最窄有效层选择一个首选 target surface：

不要默认把所有教训塞进 prompt、规则或本 skill。论文消融显示组件收益不相加，重复约束会增加冗余检查；若多个候选面表达同一防线，只保留执行力最强且副作用最小的一层，其他层仅在有独立证据时补充。

只有多次证据、影响明确且存在事实源缺口时才建议新稳定规则；单次事件默认不制度化。若可观测，记录消息数、重复工具调用、错误重试或耗时等效率代理，但不能以“更短”替代任务正确性。