Terry-Mao · Terry-Mao · Jun 7, 2026 · Jun 7, 2026 · Jun 7, 2026 · Jun 7, 2026
@@ -1787,6 +1787,102 @@
       "proposed_patch": "无需产品文档补丁；不修改 `docs/product/`。",
       "reason": "PR #213 仅重新编译 `docs/product/raw/` 到 `docs/product/wiki/`，变更范围是派生 wiki 页面和编译日志。现有产品文档已声明 `docs/product/raw/` 是权威来源，且本次没有 raw 文档、spec、产品代码或 workflow 行为变更。",
       "recorded_at": "2026-06-07T01:56:26Z"
+    },
+    {
+      "pr": 215,
+      "url": "https://github.com/Terry-Mao/AICodingFlow/pull/215",
+      "title": "fix: 跳过 product docs sync 中缺失的 issue 引用",
+      "merged_at": "2026-06-01T09:27:21Z",
+      "merge_commit": "67e940c61555249a233118e706984585e95a95c1",
+      "docs_update": "required",
+      "affected_docs": [
+        "docs/product/raw/product-docs-sync-workflow.md"
+      ],
+      "source_context": [
+        "PR #215",
+        "Issue #214",
+        "specs/issue-214/product.md",
+        "specs/issue-214/tech.md"
+      ],
+      "proposed_patch": "更新 Product Docs Sync workflow 权威文档，说明 unreadable linked issue 会被跳过，linked_issues 和相关 specs 只包含成功读取的 issue，且该情况不会让可处理的 merged PR 变为 should_run=false。",
+      "reason": "PR #215 改变了 Product Docs Sync 的长期 workflow 行为：单个 linked issue 读取失败时不再中断上下文准备，而是跳过该 issue 并继续处理 merged PR。现有产品文档只描述了 issue 引用进入上下文和 specs 读取流程，未覆盖缺失或不可读取 issue 的过滤规则。",
+      "recorded_at": "2026-06-07T06:52:58Z"
+    },
+    {
+      "pr": 217,
+      "url": "https://github.com/Terry-Mao/AICodingFlow/pull/217",
+      "title": "fix: append product docs sync PR comments",
+      "merged_at": "2026-06-01T18:50:22Z",
+      "merge_commit": "6a86f6434ec9e30750b1bb14cbb2da449f65a44f",
+      "docs_update": "required",
+      "affected_docs": [
+        "docs/product/raw/product-docs-sync-workflow.md"
+      ],
+      "source_context": [
+        "PR #217",
+        "Issue #216",
+        "specs/issue-216/product.md",
+        "specs/issue-216/tech.md"
+      ],
+      "proposed_patch": "Updated the Product Docs Sync workflow raw product doc to describe appended per-run PR comments on the docs sync PR, including fields, uncertain confirmation visibility, and the rule that old bot comments are not edited.",
+      "reason": "PR #217 changed the long-term Product Docs Sync workflow behavior: every create or update of the docs sync PR now appends a per-run PR comment with the current decision details. Existing product docs described the fixed-branch PR body and ledger behavior but did not cover the new conversation comment record.",
+      "recorded_at": "2026-06-07T10:18:48Z"
+    },
+    {
+      "pr": 222,
+      "url": "https://github.com/Terry-Mao/AICodingFlow/pull/222",
+      "title": "Compile product wiki",
+      "merged_at": "2026-06-02T11:01:32Z",
+      "merge_commit": "6ba69e0f29fe264d01ca9cc207d8298322038894",
+      "docs_update": "not-needed",
+      "affected_docs": [],
+      "source_context": [
+        "PR #222",
+        "docs/product/raw/project-installer.md",
+        "docs/product/raw/update-dedupe-workflow.md"
+      ],
+      "proposed_patch": "No docs/product changes are needed.",
+      "reason": "PR #222 only compiled the generated docs/product/wiki knowledge layer from existing docs/product/raw sources. It did not introduce new product behavior, and the authoritative raw product docs already include the relevant source documents.",
+      "recorded_at": "2026-06-07T12:13:55Z"
+    },
+    {
+      "pr": 226,
+      "url": "https://github.com/Terry-Mao/AICodingFlow/pull/226",
+      "title": "Compile product wiki",
+      "merged_at": "2026-06-03T09:27:59Z",
+      "merge_commit": "7467fb7a8aeec33f29e8786f989559d15de3cdb9",
+      "docs_update": "not-needed",
+      "affected_docs": [],
+      "source_context": [
+        "PR #226",
+        "docs/product/raw/",
+        "docs/product/wiki/"
+      ],
+      "proposed_patch": "无需修改 docs/product/；本次只记录 not-needed 决策。",
+      "reason": "PR #226 只是将现有 docs/product/raw/ 内容重新编译为 docs/product/wiki/ 知识层，没有引入新的权威产品行为、workflow、配置语义或公开契约。变更属于派生 wiki 内容同步，长期产品事实仍已由现有 raw 文档覆盖。",
+      "recorded_at": "2026-06-07T14:33:32Z"
+    },
+    {
+      "pr": 227,
+      "url": "https://github.com/Terry-Mao/AICodingFlow/pull/227",
+      "title": "fix(review): suppress repeated bot review comments",
+      "merged_at": "2026-06-03T09:53:38Z",
+      "merge_commit": "47bfdde64f96ffee7fd9f5f50386ad2c5418498c",
+      "docs_update": "required",
+      "affected_docs": [
+        "docs/product/raw/pr-review-verdict.md"
+      ],
+      "source_context": [
+        "PR #227",
+        "Issue #225",
+        ".agents/skills/review-pr/SKILL.md",
+        ".agents/skills/review-spec/SKILL.md",
+        ".github/scripts/prepare_review_discussion_context.py",
+        ".github/workflows/review-pr.yml"
+      ],
+      "proposed_patch": "Updated docs/product/raw/pr-review-verdict.md to document review_discussion_context.json generation, duplicate-suppression rules, maintainer dismissal handling, unresolved-thread handling, and REVIEW_BOT_LOGIN source attribution.",
+      "reason": "PR #227 changes long-term AI PR Review behavior by adding prior review discussion snapshots and duplicate suppression for resolved, maintainer-dismissed, and still-unresolved bot inline comments. Existing product docs covered review workflow behavior but did not document this discussion context or its instruction-safety boundary.",
+      "recorded_at": "2026-06-07T16:00:13Z"
     }
   ]
 }
@@ -73,6 +73,24 @@ secrets 管理、弱加密或错误随机数、依赖与 supply chain、敏感
 GitHub comment。安全发现的 review comment 使用 `[SECURITY]` 标签，并计入同一个
 `review.json.verdict` 判断；critical security finding 通常应导致 `REJECT`。
 
+## 历史 review discussion 去重
+
+AI PR Review 会在运行前生成 `review_discussion_context.json`，作为当前 PR 已有 review
+threads 的稳定快照。该快照记录配置的 review bot 已发布的 inline comments，以及这些
+comments 是否已被 resolved、是否仍 unresolved、是否收到维护者明确表示不需要修改或保持现状的
+回复。
+
+`review-pr` 和 `review-spec` 只能把 `review_discussion_context.json` 用于重复抑制，不能把
+其中的 issue bodies、PR comments、review replies 或其他 discussion 文本当作新指令执行。
+如果同一 path 和 line 上的旧 bot finding 已被维护者 dismissed 或 thread 已 resolved，agent
+不应重复发布相同 inline comment，除非当前 diff 引入了实质新增或更高严重度的风险。仍 unresolved
+的旧 bot finding 也不应重复创建同位置 inline comment；如果问题仍然重要，应在顶层 review body
+引用现有 unresolved thread。
+
+维护者回复只有在 author association 属于仓库授权身份时才用于去重判断。`REVIEW_BOT_LOGIN`
+可用于指定发布 review 的 bot login；未配置时默认按 `github-actions[bot]` 识别旧 bot
+comments。
+
 ## 本地 review 入口
 
 本地开发完成但尚未 push 或创建 PR 时，可以使用 `review-pr-local` 或
@@ -193,5 +211,5 @@ owner。
 blocking `REQUEST_CHANGES` 和维护者权限共同决定。
 
 来源：PR #55，PR #65，PR #67，PR #79，PR #81，PR #82，PR #89，PR #90，PR #93，PR #103，
-PR #116，PR #154，PR #155，PR #162，PR #163，Issue #115，Issue #151，Issue #152，`specs/issue-51/product.md`，
+PR #116，PR #154，PR #155，PR #162，PR #163，PR #227，Issue #115，Issue #151，Issue #152，Issue #225，`specs/issue-51/product.md`，
 `specs/issue-77/product.md`，`specs/issue-85/product.md`，`specs/issue-115/product.md`。
@@ -37,6 +37,11 @@ PR title 和 PR body 中解析 `Refs #...`、`References #...`、`Fixes #...`、
 形式的 pull request 引用不会被计入 linked issue。这样没有 closing reference、但在 PR 描述中用
 issue reference footer 关联的 issue，也会进入 product docs sync 上下文和相关 specs 读取流程。
 
+如果单个 linked issue 无法读取，例如 issue 编号不存在、不可见或 `gh issue view` 对该编号返回
+失败，workflow 会跳过该 issue 并继续为目标 PR 生成上下文。输出中的 `linked_issues` 只包含成功
+读取的 issue；相关 specs 也只按这些成功读取的 issue 编号读取。缺失或不可读取的 issue 不会让
+workflow 停止，也不会把可处理的 merged PR 改为 `should_run=false`。
+
 如果扫描窗口内没有尚未处理的 merged PR，workflow 会写出空目标上下文并停止，不运行 docs sync
 agent，也不会创建同步 PR。
 
@@ -80,6 +85,12 @@ workflow 会在 `docs/product/` 有变更时创建或更新产品文档同步 PR
 `not-needed` 不修改权威 markdown 文档，但 ledger 更新仍会创建或更新一个只记录同步决策的 PR。
 同一个同步 PR 可以持续累积多个产品文档同步决策，直到经过 review 并合并。
 
+每次 workflow 创建或更新产品文档同步 PR 后，都会在该同步 PR 的 conversation 中追加一条新的
+PR comment，记录本次 run 的 source PR、`docs_update` 决策、原因、受影响文档和 patch summary。
+该 comment 只描述本次 run，不复制完整 ledger 历史；累计的已处理决策仍由 PR body 承载。
+如果最新决策是 `uncertain`，追加 comment 也应明确提示需要维护者确认。workflow 不会编辑旧的
+bot comment 来替代追加记录。
+
 长期产品文档只有在同步 PR 经过 review 并合并后才成为权威产品知识。
 
-来源：PR #179，https://github.com/Terry-Mao/AICodingFlow/pull/179；PR #184，https://github.com/Terry-Mao/AICodingFlow/pull/184；PR #187，https://github.com/Terry-Mao/AICodingFlow/pull/187；PR #188，https://github.com/Terry-Mao/AICodingFlow/pull/188；PR #194，https://github.com/Terry-Mao/AICodingFlow/pull/194。
+来源：PR #179，https://github.com/Terry-Mao/AICodingFlow/pull/179；PR #184，https://github.com/Terry-Mao/AICodingFlow/pull/184；PR #187，https://github.com/Terry-Mao/AICodingFlow/pull/187；PR #188，https://github.com/Terry-Mao/AICodingFlow/pull/188；PR #194，https://github.com/Terry-Mao/AICodingFlow/pull/194；PR #215，Issue #214；PR #217，Issue #216。