docs: integrate issue tracking and development lessons

2026-09-23 03:01:37 +00:00
parent 2fdb6e548e ccf515c3b1
commit 7bbd7a407f
17 changed files with 343 additions and 3 deletions
@@ -11,10 +11,10 @@
 .doc/
  README.md              ← 本文件（总地图）
  status/                ← 模块/功能完成度 SSOT
-  audit/                 ← 问题发现与分析
+  audit/                 ← 问题发现与分析、ISSUES.md 问题/修复台账
  remediation/           ← 整改方案与发布缺口
  archive/               ← 历史（只增不删）
-  ops/                   ← 活协作（任务、交接、调研）
+  ops/                   ← 活协作（任务、交接、调研；lessons/ 开发经验）
  system-design/         ← 模块架构深读
  adr/                   ← 架构决策
  backlog/               ← 产品 backlog（非阻塞）
@@ -40,6 +40,8 @@
 | 当前在做什么 | [ops/CURRENT.md](ops/CURRENT.md) |
 | 模块完成度 | [status/FEATURE-MATRIX.md](status/FEATURE-MATRIX.md) |
 | 发布 blocker | [remediation/gap-matrix.md](remediation/gap-matrix.md) |
+| 问题历史、修复经过 | [问题台账](audit/ISSUES.md) · [闭环规范](ops/2026-09-23-issue-learning-workflow.md) |
+| 开发注意事项与经验检索 | [经验索引](ops/lessons/INDEX.md) |
 | 审计/问题分析 | [audit/INDEX.md](audit/INDEX.md) |
 | 整改方案 | [remediation/INDEX.md](remediation/INDEX.md) |
 | 历史归档 | [archive/README.md](archive/README.md) |
@@ -68,6 +70,6 @@ audit（问题）→ remediation（方案）→ ops/short-term（任务）
  → test-reports（验收）→ archive（关闭证据）
 ```

-状态字段：`planned | in_progress | blocked | done | cancelled`
+任务状态字段：`planned | in_progress | blocked | done | cancelled`。问题以 issue_state、经验以 lesson_state 独立记录，取值与转换见 [闭环规范](ops/2026-09-23-issue-learning-workflow.md)；研究任务完成不关闭待修问题。

 会话结束不等于任务完成；只有 done/cancelled 任务归档。CURRENT 保留最多 3 项焦点及活跃/阻塞/待集成/待清理事项，完成认领和长证据迁入 [历史快照](archive/ops/2026-09-21-current-history.md)。移动文档同步修复相对链接，保留证据与来源。规范生命周期另用 proposed/approved/active/deprecated；工具能力另用 manual/enforced。
@@ -0,0 +1,27 @@
+# 历史问题补录：可选职责与正文哈希
+
+补录日期：2026-09-23；owner：Codex；登记任务：[issue-learning-2026-09-23](../ops/short-term/2026-09-23-issue-learning.md)。这是两个问题的登记主记录，原审计、修复任务及验收报告继续作为事实证据；没有重新运行产品测试或读取业务数据。`evidence_basis=historical`，当前运行状态未复测，源码复核基线为 `2fdb6e548e3784771f27e6a9e79b9c364f76c566`。
+
+## nullable-duty
+
+- issue_id：`ISSUE-20260923-nullable-duty`；issue_state：`resolved`；severity：high；recurrence_count：0（指登记后重开次数，非历史发生总数）。
+- 发现/修复日期：2026-09-17；原处理 owner：Cursor；补录 owner：Codex；原任务：`fix/docgov-optional-duty-null-fk`。
+- 现象与已证实根因：[原审计](2026-09-17-docgov-optional-duty-null-fk.md)。可选 reviewer 缺席合法返回 0，但创建路径直接写入可空 FK；heal 路径已有空值映射，创建路径漏改。底层 FK 又被错误分型掩盖。
+- 同类范围：可选职责的创建/heal 写入边界。历史报告验证 reviewer/approver 为 NULL；不能由此推断所有 FK、全职责模式和全部授权边界均已验证。
+- 修复思路：保留可选职责语义，在 SQL 边界将缺席值映射 NULL，并改善错误分型；通过强制配置 reviewer 绕过错误会改变业务契约。未发现其他尝试的实测记录，不虚构失败实验。
+- 修复经过/提交：[原任务](../archive/ops/2026-09-17-docgov-optional-duty-null-fk.md)，历史合并 `e488d10`；本次只核对原文记录，不把短 SHA 当当前制品身份。
+- 验证与关闭范围：[原报告](../test-reports/2026-09-17-docgov-optional-duty-null-fk-test-report.md) 记录单测、PG 集成、真实任务 API 启动与 DB NULL；证明账本创建通过，不证明真实 UI 或 PI 全流程完成。历史 deployment=passed（dev，来源为原报告），当前运行未复测。
+- 本次复核：当前源码 `internal/docgov/engine.go` 创建路径仍调用 `nullIfZero`；这是源码检查，未重跑 PG。
+- 经验：[LESSON-20260923-nullable-duty](../ops/lessons/2026-09-23-nullable-duty.md)。后续触发：职责模型或任一持久化入口变化时复核，异常复发重开。独立的 flushSync 警告不在本条关闭范围。
+
+## content-hash
+
+- issue_id：`ISSUE-20260923-content-hash`；issue_state：`resolved`；severity：critical；recurrence_count：0（登记后）。
+- 发现/修复日期：2026-09-14；原处理：Cursor 修复、Antigravity UI 验收；补录 owner：Codex。
+- 现象与因果链：[原审计](2026-09-14-project143-controlled-content-404.md)。文件存在却被报 404；规范化去掉有硬换行语义的双空格，bootstrap 只改账本哈希未同步文件；并发 hydration 与无效轮询更新放大故障。
+- 同类范围：旧文档 bootstrap、规范化、账本/文件投影、错误映射与刷新竞态。历史扫描范围见原审计，不扩大为所有数据无问题。
+- 修复思路/选择：[整改方案](../remediation/2026-09-14-controlled-content-canonical-hash-remediation.md)。保持文本语义、原子投影和结构化错误；历史原文件与旧 head 先保全再显式 migration_repair。静默覆盖原文件会丢失语义，不能用于“对齐哈希”。这不是本轮数据操作授权。
+- 修复经过：[原审计关闭结果](2026-09-14-project143-controlled-content-404.md#关闭结果) 与 [最终报告](../test-reports/2026-09-14-controlled-content-ui-acceptance.md)；后续水合/缓存修复合入 `d0e8f60`、`36e4bc3`。报告保留早期失败及无效运行，只有 clean-run3 / full-chain-final 属最终有效证据。
+- 验证与关闭范围：原报告记录旧项目真实页面、全链路主阶段和重启恢复 PASS；历史 deployment=passed（dev）。不据此宣告当前 production_ready 或当前制品无回归。
+- 本次复核：`internal/docrevision/canonicalize.go` 已委托 doccontent；`canonicalize_golden_test.go` 包含硬换行和封装一致性测试。本次未执行这些测试。
+- 经验：[LESSON-20260923-content-hash](../ops/lessons/2026-09-23-content-hash.md)。后续触发：canonicalizer、bootstrap、投影或水合修改时复核；复发追加时间线并重开。
@@ -0,0 +1,10 @@
+# 问题与修复台账
+
+维护规则：[问题记录与开发经验闭环](../ops/2026-09-23-issue-learning-workflow.md)。每个问题一个稳定 ID；主记录是事实与状态来源，本表为可检索投影。新发现及时登记，修复后保留记录；发布 blocker 仍见 [gap-matrix](../remediation/gap-matrix.md)。
+
+更新：2026-09-23。本轮为初始建库，仅补录两个历史案例；下列历史 resolved 不表示本日运行回归通过。
+
+| issue_id | 模块 / 检索词 | 问题 | 严重度 | issue_state | owner | 证据日期 / 范围 | 唯一主记录 | 经验 |
+|---|---|---|---|---|---|---|---|---|
+| ISSUE-20260923-nullable-duty | docgov / nullable / 23503 / reviewer_id | 可选职责空值写 0 导致 FK 失败 | high | resolved | Codex（历史补录） | 2026-09-17；历史 PG / API 冒烟；当前未复测 | [主记录](2026-09-23-historical-issue-records.md#nullable-duty) | [LESSON-20260923-nullable-duty](../ops/lessons/2026-09-23-nullable-duty.md) |
+| ISSUE-20260923-content-hash | docrevision / canonicalize / hard-break / 404 | 规范化破坏 Markdown 语义并造成正文哈希漂移 | critical | resolved | Codex（历史补录） | 2026-09-14；历史真实 UI / 重启；当前未复测 | [主记录](2026-09-23-historical-issue-records.md#content-hash) | [LESSON-20260923-content-hash](../ops/lessons/2026-09-23-content-hash.md) |
@@ -33,3 +33,9 @@ CURRENT 是带时间的活跃协调快照；Git/机器状态用于核验实际
 修订 ID：`systemic-issue-analysis-2026-09-23-r1`；owner：`Codex`；state：`active`（已通过 `958dd44fee8bbea8d19129457fc0ad749fdebdbe` 合入 dev）；工具能力：`manual`。用户明确要求将“由个案追查同类根因、潜在问题，研究并提出方案”加入规范，授权与验证见 [任务记录](./short-term/2026-09-23-systemic-issue-analysis.md)。

 核心行为唯一来源为 [AGENTS 分析要求](../../AGENTS.md#bug-与系统问题的分析要求)，验证范围由 [验证契约](./2026-09-21-validation-contract.md#问题修复的回归范围) 定义，[分析模板](./templates/audit-note.md) 承载证据。客户端继续引用统一入口。生效提交为 `958dd44fee8bbea8d19129457fc0ad749fdebdbe`，候选验证与受控集成收据见任务记录；不新增业务实施或环境操作授权。
+
+## 问题记录与经验复用局部修订
+
+修订 ID：`issue-learning-2026-09-23-r1`；owner：Codex；state：`approved`（待受控合入 dev 后 active）；执行能力：`manual`。用户要求同时管理出现的问题、修复记录和思路，并及时总结为开发注意事项，授权与验证见 [任务](short-term/2026-09-23-issue-learning.md)。
+
+[闭环规范](2026-09-23-issue-learning-workflow.md) 为本流程唯一来源；AGENTS 增加按任务触发的读取/更新入口，模板承载证据，问题台账和经验索引提供检索。生效提交为包含本修订的首个受控 dev 集成提交，以任务收据与 Git 父链核实；未合入不能声称全仓生效。此修订不新增产品功能、自动门禁或运行权限。
@@ -0,0 +1,61 @@
+# 问题记录与开发经验闭环
+
+修订：`issue-learning-2026-09-23-r1`；owner：Codex；生效条件见 [规范登记](2026-09-21-policy-registry.md)。执行能力为 `manual`：依靠 Agent 读取、任务记录与审查；本轮没有增加自动检索、CI 阻断或模型训练。
+
+## 入口与职责
+
+| 入口 | 回答的问题 | 权威边界 |
+|---|---|---|
+| [问题台账](../audit/ISSUES.md) | 出现过什么问题，目前处理到哪一步？ | 索引和状态投影；事实、修复经过以链接的唯一问题主记录为准 |
+| 问题主记录 | 为什么发生、考虑过哪些方案、改了什么、如何验证？ | 放 audit，或沿用已有任务/审计中的明确章节；使用 [问题模板](templates/issue-record.md) |
+| [开发经验](lessons/INDEX.md) | 遇到类似工作应先检查什么？ | 按机制提炼的注意事项；使用 [经验模板](templates/development-lesson.md)，不替代现行规范 |
+| CURRENT / FEATURE-MATRIX / gap-matrix | 当前协调 / 能力 / 发布门禁 | 维持原职责；只有对应状态改变才更新 |
+
+修复方案、任务、提交、验收报告通过链接串联，已有材料直接复用。一个 task 可处理多个 issue，一个 issue 可跨分析/实施任务；研究任务 done 不等于问题 resolved。一个 lesson 可覆盖多个同根因 issue。短问题可在任务主文档内记录，无需机械创建一套文件。
+
+## 何时记录、检索和总结
+
+1. **设计、编码、排障或运维前**：按模块、路径、错误码、症状和共用机制检索问题台账及经验索引。先查索引、再读命中条目的来源；核对当前源码/规范是否仍适用。在任务记录填写检索词、命中 ID、采纳的检查；无命中明确记录。简单信息答复不要求建任务或检索整库。
+2. **首次发现问题时**：在当前任务 worktree 建立或补充问题主记录和台账行，记录预期/实际、影响、环境/版本、owner、下一步及证据缺口；尚未定位也可以登记。ID 使用 `ISSUE-YYYYMMDD-<slug>`，日期为登记日；发生日期另列，跨 worktree 以语义 slug 避免抢序号。
+3. **定位、改方案、完成修复或发现验收失败时**：在同一主记录追加时间线和尝试结果；保留被否定假设、失败方案及不适用条件，区分观察、推测和已证实根因。按 [问题分析要求](../../AGENTS.md#bug-与系统问题的分析要求) 检查共用机制和同类入口。
+4. **根因与修复得到验证后、任务收口前**：提炼经验或更新已有同机制经验，并链接回问题。若尚无验证证据，只能建 `candidate`；若没有新增可复用结论，记“不新增经验”及理由，仍保留问题记录。分析-only、未修复或验收失败的问题继续留在台账。
+5. **经验落到开发动作**：写清触发条件、机制、应做检查、错误做法及原因、验证方法、适用边界。优先链接现有测试/约束；需要新增回归、lint、架构门禁或规范时，在当前授权内实施，超出授权则记录 owner/后续任务。仅提出自动化建议不能标为已落实。
+6. **复发或规则变化时**：同一故障未解决的复现追加原 issue；已关闭问题再次出现，重开原 issue 为 `investigating`，递增 `recurrence_count` 并保留原关闭证据。不同根因建立新 issue 并互相链接。复盘为何已有经验/测试未生效：未检索、范围不适用、遗漏入口、检查未执行或实现回退，并更新防护。模块/接口/规范变化时复核命中经验；确认过时标 `superseded` 并链接替代条目，无替代则 `retired`，保留历史。
+
+检索示例（在任务工作区执行，替换为本任务关键词）：
+
+```bash
+rg -n -i 'docgov|nullable|23503|职责' .doc/audit/ISSUES.md .doc/ops/lessons
+```
+
+owner 在上述里程碑及时更新，最迟在会话交接前保存事实和未完成项；不依赖定时服务。经验不会自动改变模型参数，作用是让后续 Agent 能检索、有证据地复用，并逐步把重复风险转换为可执行检查。
+
+## 问题状态与关闭条件
+
+问题的 `issue_state` 与任务 `status` 分开；台账保留当前投影，主记录保留变迁历史。
+
+| issue_state | 含义 / 转移要求 |
+|---|---|
+| open | 已登记，等待定位 |
+| investigating | 正在复现、验证假设和范围 |
+| fixing | 修复方案明确且已获实施授权 |
+| verifying | 修复待验收，或必要证据尚缺 |
+| resolved | 约定范围的修复、必要环境验收均有证据，经验已总结或有不新增理由 |
+| deferred | 暂缓处理；保留风险、责任人、复查触发和授权/决策依据，不冒充修复 |
+| duplicate | 指向唯一主 issue，保留原报告和去重理由 |
+
+定位失败可保留 investigating；临时止血不代表 resolved，必须标清剩余根治项。验证失败回到 investigating/fixing，不能覆盖失败记录。关闭至少能追溯：根因、同类范围、修复提交或获授权的处理动作、原例/变体/正常行为验收及缺项、实际部署状态、lesson 或不新增理由。业务改动待部署时不能把目标环境问题关闭；无需部署写 not_required。
+
+**历史补录**：发生日、修复日和补录日分开。只按旧报告已证明的范围记录 `resolved`，同时标 `evidence_basis=historical` 和当前运行未复测；缺乏关闭证据用 `verifying` 并说明原因，不从旧任务 done 推导修复完成。历史条目不能用于宣布当前系统就绪。本轮仅补录两个有来源案例，不代表穷尽全部历史问题。
+
+## 经验质量与维护
+
+`lesson_state`：`candidate | validated | superseded | retired`。validated 表示注意事项有可核对的因果证据且已复核适用边界，不表示所有模块或当前线上均测试通过。需记录 reviewer、last_reviewed、reviewed_revision、来源 issue、证据日期、关键词、关联测试、适用/不适用范围及仍缺的防护。
+
+同机制优先更新已有 lesson，保留修订记录；新机制才新增 `LESSON-YYYYMMDD-<slug>`。将通用经验升级成强制规范时，只在对应规范的唯一来源修改并登记生效条件，经验条目保留理由与链接。经验与现行规范冲突时先按有效规范执行，登记冲突与复核项；历史经验不能授予数据修复、部署或扩大范围的权限。
+
+## 并发、验收与敏感信息
+
+所有写入沿用 [worktree 操作规范](2026-09-21-agent-worktree-workflow.md)。问题/经验索引使用各自 `path:` 短租约；当前 `agentctl docs apply` 仅覆盖 CURRENT/FEATURE-MATRIX，不宣称新索引有行级 CAS。写入前读最新内容、只改自己的条目；从旧 dev 分出的工作区在集成前合并最新 dev 并处理索引冲突，保留他人条目。索引和主记录在同一逻辑提交同步，避免状态分叉。
+
+文档验收包括链接/锚点、ID 唯一、主记录与索引状态一致、来源及日期、入口/模板可达和情景检查。运行回归按 [验证契约](2026-09-21-validation-contract.md)；未运行、缺项与历史证据单独标明。只保留足够判断的脱敏证据，业务正文、凭证和个人数据不复制进经验库。
@@ -12,6 +12,7 @@

 | owner | task | branch | worktree | mutex | status |
 |---|---|---|---|---|---|
+| Codex | issue-learning-2026-09-23 | feature/issue-learning-2026-09-23 | .worktrees/issue-learning-2026-09-23 | issue-learning-docs | in_progress |
 | Codex | systemic-issue-analysis-2026-09-23 | feature/systemic-issue-analysis-2026-09-23 | .worktrees/systemic-issue-analysis-2026-09-23 | systemic-issue-analysis-docs | done |
 | Codex | modular-contract-standard-2026-09-22 | feature/modular-contract-standard-2026-09-22 | .worktrees/modular-contract-standard-2026-09-22 | modular-contract-docs | done |
 | Codex | herdr-orchestration-v12 | feature/herdr-orchestration-v12 | .worktrees/herdr-orchestration-v12 | herdr-policy+scripts | done |
@@ -0,0 +1,31 @@
+---
+lesson_id: LESSON-20260923-content-hash
+lesson_state: validated
+owner: Codex
+reviewer: Codex (source review)
+last_reviewed: 2026-09-23
+reviewed_revision: 2fdb6e548e3784771f27e6a9e79b9c364f76c566
+source_issues: [ISSUE-20260923-content-hash]
+keywords: [docrevision, doccontent, canonicalize, hash, bootstrap, hard-break, hydration, '404']
+---
+
+# 文本规范化必须保持语义并维护账本与文件一致性
+
+**触发**：修改 Markdown 规范化、哈希、版本 bootstrap、文件投影、正文加载或刷新缓存时。
+
+**机制与来源**：[问题主记录](../../audit/2026-09-23-historical-issue-records.md#content-hash)。去掉行尾双空格破坏硬换行语义；只更新账本哈希使原文件读取失配。统一报 404 和无效轮询更新让数据冲突难以诊断并反复呈现。
+
+**开发检查**：
+
+1. 对规范化定义允许变化和必须保留的语义，保留硬换行等差异样例；哈希一致性依赖相同语义和规范化契约。
+2. 追踪快照、记录哈希与文件投影的写入顺序和失败恢复。旧文档首次 bootstrap 与新文档创建分别覆盖，并发 content/revision 请求和刷新后读取需按实际因果链验证。
+3. 数据修复先按授权保全原文件及旧版本，显式记录修复来源；不能通过静默覆盖或跳过校验来隐藏不一致。
+4. 将不存在、完整性冲突和临时失败按协议区分。检查无变化轮询是否重复触发内容加载；失败反馈应可定位。
+
+**已有防护**：[黄金样例](../../../internal/docrevision/canonicalize_golden_test.go) 含硬换行保持及 doccontent 封装一致性；[历史真实 UI 报告](../../test-reports/2026-09-14-controlled-content-ui-acceptance.md) 覆盖旧文档、刷新和重启。2026-09-23 只核对源码与报告，未重跑；测试存在不等于在未来变更中已执行。
+
+**边界**：哈希不同不自动说明数据丢失，也不自动授权重写。不同文件格式的空白语义不同；不得把 Markdown 规则机械用于其他格式。当前制品和旧数据迁移需要各自证据，新项目 PASS 不代替旧数据验收。
+
+**未完成防护**：没有全仓扫描或新 CI 门禁；未来相关修改按验证契约运行适用用例并记录结果。
+
+**修订**：2026-09-23 从历史问题提炼，核对当前 canonicalize 委托与黄金样例；规范化/投影/缓存契约改变时再审。
@@ -0,0 +1,30 @@
+---
+lesson_id: LESSON-20260923-nullable-duty
+lesson_state: validated
+owner: Codex
+reviewer: Codex (source review)
+last_reviewed: 2026-09-23
+reviewed_revision: 2fdb6e548e3784771f27e6a9e79b9c364f76c566
+source_issues: [ISSUE-20260923-nullable-duty]
+keywords: [docgov, nullable, SQL, FK, reviewer_id, '23503', heal]
+---
+
+# 可选职责在所有持久化入口保持同一空值语义
+
+**触发**：修改可选成员/职责、SQL 写入、创建/heal/import/upsert 等路径时；检查范围以实际共享字段和表写者为准。
+
+**机制与来源**：[问题主记录](../../audit/2026-09-23-historical-issue-records.md#nullable-duty)。内存 0 表示缺席，但数据库可空 FK 需要 NULL；一个入口已有转换不能证明另一个入口也有。原审计中错误被通用 INTERNAL_ERROR 掩盖，说明还需检查错误分型。
+
+**开发检查**：
+
+1. 从字段契约确定缺席、有值但非法、合法值三种语义；沿现有表写者列出所有写入口，检查转换一致性。
+2. 保持可选职责业务规则；让 SQL 边界处理缺席值，不能靠强制填 reviewer 掩盖实现错误。合法角色与非法 ID 仍按原有鉴权/FK 处理。
+3. 对缺席、合法、非法值及相关创建/修复入口安排真实 PG 验证；mock 不会证明 FK/NULL 行为。保持正常职责模式的回归。
+
+**已有防护**：[engine](../../../internal/docgov/engine.go) 创建路径使用 `nullIfZero`；[历史报告](../../test-reports/2026-09-17-docgov-optional-duty-null-fk-test-report.md) 记录 `TestDocGov_CreateOrGetDocument_OptionalDutiesNullFK`、分型单测与 API/DB 冒烟。2026-09-23 仅复核源码及旧报告，未重跑测试；未据此证明真实 UI、所有写路径或当前部署。
+
+**边界**：只适用于明确以 0 表示未设置且列允许 NULL 的字段；不能对所有数值或必填关系统一转 NULL。授权资格判定仍遵循现行规范。
+
+**未完成防护**：跨所有相关入口的自动覆盖不由本条保证；后续变更任务按实际影响补证。没有新增 CI 门禁。
+
+**修订**：2026-09-23 从历史 FK 案例提炼，并核对当前创建路径；接口/表写者变化或同因复发时再审。
@@ -0,0 +1,10 @@
+# 开发经验与注意事项
+
+先按本任务模块、路径、症状和机制检索，再读命中条目的适用条件与来源。执行步骤与维护要求见 [闭环规范](../2026-09-23-issue-learning-workflow.md)；事实入口见 [问题台账](../../audit/ISSUES.md)。这些是仓库可共享的外部经验，不依赖单个聊天会话或某个客户端私有记忆。
+
+| lesson_id | 触发条件 / 关键词 | 注意事项 | lesson_state | 主记录 / 最近复核 |
+|---|---|---|---|---|
+| LESSON-20260923-nullable-duty | docgov、SQL、nullable、23503、可选职责、创建/heal | 检查所有写入口的缺席值语义；用真实 PG 验证 NULL/FK | validated | [可选职责持久化](2026-09-23-nullable-duty.md)；2026-09-23 |
+| LESSON-20260923-content-hash | docrevision、canonicalize、hash、bootstrap、hard-break、404、水合 | 保持文本语义并检查账本/文件一致性；新数据通过不能覆盖旧数据迁移 | validated | [正文规范化与投影](2026-09-23-content-hash.md)；2026-09-23 |
+
+validated 的证据范围见各条目；本日复核为历史材料和源码阅读，未重跑产品回归。后续按机制补充，过时条目标 superseded/retired 并保留替代链接。
@@ -0,0 +1,73 @@
+---
+title: 问题修复记录与开发经验闭环
+task_id: issue-learning-2026-09-23
+status: in_progress
+created: 2026-09-23
+updated: 2026-09-23
+owner: Codex
+task_type: implementation
+task_tier: small
+policy_revision: agent-governance-2026-09-21-r1 + systemic-issue-analysis-2026-09-23-r1 @ 2fdb6e548e3784771f27e6a9e79b9c364f76c566
+branch: feature/issue-learning-2026-09-23
+worktree: .worktrees/issue-learning-2026-09-23
+base_dev_sha: 2fdb6e548e3784771f27e6a9e79b9c364f76c566
+write_scope: [AGENTS.md, PROJECT.md, .doc/README.md, .doc/audit/ISSUES.md, .doc/audit/2026-09-23-historical-issue-records.md, .doc/ops/lessons, .doc/ops/2026-09-23-issue-learning-workflow.md, .doc/ops/2026-09-21-policy-registry.md, .doc/ops/templates, .doc/ops/short-term/2026-09-23-issue-learning.md, .doc/ops/CURRENT.md]
+allowed_environments: []
+mutex: agentctl path leases; git:index for commits
+review_state: approved
+integration_state: pending
+deployment: not_required
+cleanup: pending
+cleanup_owner: owner 退出后的独立维护者
+cleanup_trigger: 本地交付及证据保存完成且 owner 退出后
+remote_sync: not_requested
+---
+
+# 问题修复记录与开发经验闭环
+
+## 用户目标与授权
+
+2026-09-23 本会话用户要求：“除了任务、新功能的设计和实施有 FEATURE-MATRIX 和 CURRENT 来进行管理”，还希望记录“出现的问题、修复记录、修复思路”，及时总结开发注意事项，使 AI 积累经验、减少重复错误。
+
+本轮落实仓库文档机制：问题台账、经验库、模板、Agent 开工/收口入口，完成文档检查及本地受控集成。只改登记范围内的工程规范和文档；不改业务代码、产品提示词、.env、运行环境或用户私有记忆，不 push。旧问题仅补录有来源证据，不扩大为历史全量审计。
+
+## 现状与选择
+
+当前 AGENTS 已有根因/同类分析要求，audit/INDEX 为历史审计目录，CURRENT 为活跃协调，FEATURE-MATRIX 为能力声明；缺少跨任务问题台账和按机制检索的开发经验入口。为保持文档分工，新建 audit/ISSUES 与 ops/lessons；复用现有任务/审计/报告，不再要求每次故障创建全部文档。
+
+问题事实、处理进度、经验成熟度分别用 issue_state、任务 status、lesson_state；记录推测与事实、失败尝试、关闭证据、复发和过时处理。该流程为 manual，不声称 AI 已自动学习或工具已强制执行。
+
+## 检索与来源
+
+检索词：经验、修复、问题、lesson、experience、postmortem、learning。起始工作区无相关经验索引；读取现行规范和相关历史审计/验收。首次补录 nullable-duty 与 content-hash 两类；本次历史问题事实以仓库报告为准，未用私有记忆替代证据。
+
+两条经验分别核对当前 engine 的 nullIfZero、canonicalize 委托和黄金样例存在；历史报告分清 API/PG 冒烟与真实 UI/重启证据。已采用检查：证据日期/范围、旧数据与新数据、未运行不报 PASS、规范入口单一来源。
+
+## 验证计划与结果
+
+纯文档：差异范围和空白；修改/新增文件相对链接与锚点；问题/经验 ID 唯一和互链；索引状态一致；Agent 入口及模板可达。情景自审包括新问题未定位、只分析、修复未部署、暂缓/重复、历史补录、复发、经验过时和无新增经验。不运行产品测试或共享环境操作。
+
+- `python3 /tmp/verify-issue-learning.py 2fdb6e548e3784771f27e6a9e79b9c364f76c566` 执行 git diff 空白/范围、pathlib 相对路径、Markdown 锚点、ID/状态及入口断言，输出：`PASS: 17 documents; 137 relative links/anchors; scope/whitespace; 2 unique issue/lesson pairs and matching states; client/template entrypoints`。临时检查器非产品代码；可按本节检查范围复核。
+- 人工审阅全部新增文档和差异，下面情景均有明确动作；review_state=approved 指本轮 Codex 自审，不是独立审查或未来 Agent 行为实测。
+- 首次临时检查错误地要求每条 Cursor 规则直接含 AGENTS；实际 test-reports-standard 转发统一验证契约。核对原规则后修正检查器，未修改客户端以迎合错误断言。
+
+| 情景 | 文档规定的动作 / 自审结果 |
+|---|---|
+| 新问题未定位 | open/investigating，记录假设/缺口和下一步，通过 |
+| 仅分析完成 | 任务 done 可成立，问题仍保留未解决状态，通过 |
+| 修复未部署 / 验收失败 | verifying 或回 fixing；不能误关闭目标环境问题，通过 |
+| 暂缓 / 重复 | deferred 有 owner/复查与依据；duplicate 链接唯一主 ID，通过 |
+| 历史补录 | 保留旧证据日期和范围，当前未复测；未补录全部历史，通过 |
+| 已关闭问题复发 | 重开原记录，保存旧关闭结果和防护失效原因，通过 |
+| 经验过时 / 冲突 | superseded/retired，保留替代与理由；现行规范优先，通过 |
+| 无新增经验 / 未验证 | 分别写理由或 candidate，不凑条目，通过 |
+
+未运行产品回归、浏览器、PG 或 PI；本轮验证仅为文档与引用源码阅读。证据摘要未复制业务正文、凭证或个人信息。
+
+## 状态与交接
+
+创建基线见 frontmatter。创建前主目录 dev 干净，已核对 worktree 列表和机器登记；唯一未恢复 operation 为其他任务 env:dev，与本轮文档写路径无交集，未操作它。本地缓存 origin/dev 比较为 ahead 14 / behind 245；未 fetch，不能表述为实时远端差异。
+
+本轮使用 writing-for-agents 指导条件读取与单一来源；未启动子 Agent。新增文档采用现有 taxonomy。FEATURE-MATRIX 和 gap-matrix 无相关声明变化，不修改。
+
+cleanup 保留任务及候选 worktree，供 owner 退出后独立维护者复查；所有本轮唯一证据保存本任务。剩余工作为文档验证与受控本地集成；远端未请求同步，运行制品不受影响。
@@ -20,6 +20,10 @@ severity: medium

 用户目标及可核实来源、允许写路径、环境、交付终点、非目标。实质审查须落盘；可作为唯一主文档，无需复制任务链。关联父任务时引用其授权/认领，不另建重复认领。

+## 问题登记与经验检索
+
+涉及具体缺陷时填写 issue_id、issue_state 及 [问题台账](../../audit/ISSUES.md) 链接；已有主记录直接引用。记录检索词、命中经验和适用边界。研究 status=done 不代表 issue_state=resolved；详见 [闭环规范](../2026-09-23-issue-learning-workflow.md)。
+
 ## 现象

 （预期/实际行为、原始案例、触发条件、环境与复现结果）
@@ -58,6 +62,10 @@ Bug/系统问题按 [AGENTS 分析要求](../../../AGENTS.md#bug-与系统问题

 - 

+## 修复经过与经验
+
+修复尝试、被否定方案、提交、部署和验收链接；未实施明确标注。得到验证后关联 lesson，或说明不新增理由；复发时解释已有防护为何失效并更新原记录。
+
 ## 状态与交接

 记录实际命令、被审 SHA、结果与脱敏范围；研究完成指产物有据可审，不代表建议已实施。记录剩余工作、cleanup_owner/保留原因/复查触发，以及本地提交、集成、远端状态。会话结束不强制 done。
@@ -0,0 +1,22 @@
+---
+lesson_id: LESSON-YYYYMMDD-<slug>
+lesson_state: candidate  # candidate | validated | superseded | retired
+owner: <维护者>
+reviewer: <复核者；自审要明确>
+last_reviewed: YYYY-MM-DD
+reviewed_revision: <核对的源码/规范 SHA>
+source_issues: [<issue_id>]
+keywords: [<模块>, <路径或符号>, <症状>, <机制>]
+---
+
+# <能直接指导开发的注意事项>
+
+- 触发条件：何时读本条？
+- 机制与来源：issue/根因/修复和证据日期；假设保留 candidate。
+- 开发检查：具体应该怎样做、应避免的错误及因果理由。
+- 验证方式：原例、同类和正常行为；链接现有测试/规范，区分已执行、仅存在和待补。
+- 适用边界：哪些前提下成立，哪些场景不适用。
+- 防护落实：已落地的测试/门禁/规范，仍需改进的 owner/任务/触发；没有自动化明确写 manual。
+- 修订与失效：复发补充原因；被替代/退役保留理由和替代链接。
+
+细则见 [闭环规范](../2026-09-23-issue-learning-workflow.md)。经验不另建授权或覆盖现行规范。
@@ -0,0 +1,43 @@
+---
+issue_id: ISSUE-YYYYMMDD-<slug>
+issue_state: open  # open | investigating | fixing | verifying | resolved | deferred | duplicate
+severity: medium  # critical | high | medium | low
+owner: <负责定位/跟进者>
+task_ids: [<关联任务 ID>]
+created: YYYY-MM-DD
+occurred_at: <首次发现日期>
+updated: YYYY-MM-DD
+recurrence_count: 0
+evidence_basis: current  # current | historical；均注明版本/日期/环境
+lesson_ids: []
+---
+
+# <问题标题>
+
+按 [闭环规范](../2026-09-23-issue-learning-workflow.md) 维护。已有审计/任务承载这些内容时，在原主记录补字段/章节并索引，不复制正文。授权、worktree 与任务状态链接父任务。
+
+## 事实与证据
+
+预期/实际、触发条件、影响、版本/环境、首次发生与复现方法；证据日期、路径和脱敏范围。无法复现写缺口和下一步。
+
+## 根因与同类范围
+
+区分已证实、假设、已排除；共用机制、因果链、现有防护失效原因；同类入口、检查结果、未覆盖项及理由。
+
+## 修复思路与过程
+
+方案选项、选择理由、修复位置、临时止血局限及根治安排；链接既有方案。
+
+| 日期 | 假设 / 尝试 / 动作 | 实际结果与证据 | 决策 / 下一步 / owner |
+|---|---|---|---|
+| | | | |
+
+失败/未知结果保留，不用后续成功覆盖。追加修复提交、合入和部署证据；多轮尝试分别记录。
+
+## 验收与关闭
+
+原例、同类变体、边界/异常、正常行为，逐项记录真实结果/未运行和证据。记录 resolved 日期和范围；临时止血或研究完成不当作修复完成。deferred 填风险/决策依据/owner/复查触发；duplicate 指向主 ID。
+
+## 经验与复发
+
+lesson 链接，或不新增经验的理由；测试/规范/门禁落实情况和待办 owner。复发保留前次关闭记录、递增次数，解释旧经验/防护为何未生效。
@@ -9,6 +9,12 @@
 - [ ] 验证范围按 [验证契约](../2026-09-21-validation-contract.md)；保存实际命令、SHA、环境、结果和缺项，敏感材料最小化/脱敏。
 - [ ] 本次影响、关联文档、剩余工作/接管条件在主文档或 handoff 中可恢复。

+## 问题与经验
+
+- [ ] 新发现/修复/复发的问题已更新唯一主记录和 [问题台账](../../audit/ISSUES.md)，修复过程、未解决项及 owner 可追溯；研究 done 未误关问题。
+- [ ] 已验证的可复用结论已更新 [开发经验](../lessons/INDEX.md)，或记录不新增理由；未验证结论标 candidate，关联测试/门禁区分已落地与待办。
+- [ ] 本任务采用的经验、适用性和验证结果有记录；复发、过时、冲突经验按 [闭环规范](../2026-09-23-issue-learning-workflow.md) 处理。
+
 ## 认领、集成与环境

 - [ ] CURRENT 增量更新为实际状态；保留活跃/阻塞/待集成/待清理事项，只有已终态且无后续阻塞的认领转历史。
@@ -40,6 +40,14 @@ remote_sync: not_requested  # not_requested | pending | pushed | failed
 - 允许写入、影响模块及依赖：
 - 非目标：

+## 相关问题与经验
+
+- issue_ids / 问题主记录（非问题任务可无）：
+- 开工检索词、命中 lesson_ids、适用性核对及采纳的检查（无命中明确写出）：
+- 收口新增/更新的经验与防护，或不新增理由；未落实项的 owner/触发：
+
+遵循 [闭环规范](../2026-09-23-issue-learning-workflow.md)，问题与经验状态独立于任务完成状态。
+
 ## 步骤与验收

 1. [ ] <步骤> — 验收条件/证据：
@@ -7,6 +7,7 @@
 每会话先读本文件、[PROJECT](./PROJECT.md) 和 [CURRENT](./.doc/ops/CURRENT.md) 活跃摘要。按任务分支补读：

 - 写入成果前：读 [文档地图](./.doc/README.md)、相关任务/方案/handoff；创建、集成、部署、清理前读 [worktree 操作规范](./.doc/ops/2026-09-21-agent-worktree-workflow.md)。
+- 设计、编码、排障或运维前：按模块、症状和机制检索 [问题台账](./.doc/audit/ISSUES.md) 与 [开发经验](./.doc/ops/lessons/INDEX.md)，核对命中条目的适用条件，在任务中记录采纳的检查或无命中。问题发现、修复验证、复发和交接时按 [经验闭环](./.doc/ops/2026-09-23-issue-learning-workflow.md) 更新问题记录、修复经过和经验；未验证结论保留为候选。
 - 编码前：读相关 FEATURE-MATRIX 行、[模块开发标准](./.doc/system-design/2026-09-20-module-development-standards.md)及其接口、事件、表写者约束；依 [验证契约](./.doc/ops/2026-09-21-validation-contract.md) 选择测试。
 - 发布/审计：读 [发布门禁](./.doc/remediation/gap-matrix.md) 和本次范围对应证据；完整发布判断须复核全部发布门禁。
 - 仅使用 Herdr 编排/启动/派发时：读 [角色与备援 SSOT](./.doc/ops/2026-09-13-herdr-agent-roster.md)。会话结束/换人：用 [收口清单](./.doc/ops/templates/session-close-checklist.md)。
@@ -42,6 +42,7 @@
 - 活跃工作/协调快照：[CURRENT](./.doc/ops/CURRENT.md)。
 - 能力声明与剩余条件：[FEATURE-MATRIX](./.doc/status/FEATURE-MATRIX.md)。
 - 发布门禁：[gap-matrix](./.doc/remediation/gap-matrix.md)，以有日期、提交和制品身份的证据作判断；项目入口不缓存“无 blocker”或当前 schema。
+- 问题与修复：[问题台账](./.doc/audit/ISSUES.md)；开发注意事项：[经验库](./.doc/ops/lessons/INDEX.md)，记录与复用遵循 [闭环规范](./.doc/ops/2026-09-23-issue-learning-workflow.md)。
 - 问题与方案：[audit](./.doc/audit/INDEX.md)、[remediation](./.doc/remediation/INDEX.md)。
 - 规范状态与生效版本：[规范登记](./.doc/ops/2026-09-21-policy-registry.md)。