diff --git a/docs/product/.product-docs-sync-ledger.json b/docs/product/.product-docs-sync-ledger.json index 8ae51a6..64ffb29 100644 --- a/docs/product/.product-docs-sync-ledger.json +++ b/docs/product/.product-docs-sync-ledger.json @@ -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" } ] } diff --git a/docs/product/raw/pr-review-verdict.md b/docs/product/raw/pr-review-verdict.md index d8eea0f..0eabb05 100644 --- a/docs/product/raw/pr-review-verdict.md +++ b/docs/product/raw/pr-review-verdict.md @@ -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`。 diff --git a/docs/product/raw/product-docs-sync-workflow.md b/docs/product/raw/product-docs-sync-workflow.md index 3980f94..2a8e719 100644 --- a/docs/product/raw/product-docs-sync-workflow.md +++ b/docs/product/raw/product-docs-sync-workflow.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。