From a77d72ac7e254f4edd5b7ddb174e029eb4d31b30 Mon Sep 17 00:00:00 2001 From: "github-actions[bot]" <41898282+github-actions[bot]@users.noreply.github.com> Date: Mon, 8 Jun 2026 16:41:46 +0000 Subject: [PATCH 01/10] docs(product): sync product docs --- docs/product/.product-docs-sync-ledger.json | 19 +++++++++++++++++++ docs/product/raw/pr-review-verdict.md | 10 +++++++++- 2 files changed, 28 insertions(+), 1 deletion(-) diff --git a/docs/product/.product-docs-sync-ledger.json b/docs/product/.product-docs-sync-ledger.json index 64ffb29a..f851f64b 100644 --- a/docs/product/.product-docs-sync-ledger.json +++ b/docs/product/.product-docs-sync-ledger.json @@ -1883,6 +1883,25 @@ "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" + }, + { + "pr": 228, + "url": "https://github.com/Terry-Mao/AICodingFlow/pull/228", + "title": "修复 review dismiss 误判和换行输出", + "merged_at": "2026-06-03T15:42:07Z", + "merge_commit": "aebdcd3652fd8cfab6bd430d490530d8000b57f4", + "docs_update": "required", + "affected_docs": [ + "docs/product/raw/pr-review-verdict.md" + ], + "source_context": [ + "PR #228", + "product-docs-sync-context.md", + "product-docs-sync-diff.md" + ], + "proposed_patch": "更新 docs/product/raw/pr-review-verdict.md，补充 maintainer dismissal 的肯定语义要求、否定或疑问 intentional 回复的处理方式，以及 GitHub review 发布前对 markdown body/comment 中字面量 \\\\n 的换行规范化规则。", + "reason": "PR #228 改变了 AI PR Review 的长期用户可见行为：维护者 dismissal 识别不再把否定或疑问语境中的 intentional 裸词当作已 dismiss，并且发布 review 前会把 fenced code block 外的字面量 \\\\n 规范化为真实换行。现有产品文档只概括了 dismissed/resolved 去重和 review 输出契约，未覆盖这些精确语义。", + "recorded_at": "2026-06-08T16:41:46Z" } ] } diff --git a/docs/product/raw/pr-review-verdict.md b/docs/product/raw/pr-review-verdict.md index 0eabb05a..ce4a8b70 100644 --- a/docs/product/raw/pr-review-verdict.md +++ b/docs/product/raw/pr-review-verdict.md @@ -91,6 +91,10 @@ comments 是否已被 resolved、是否仍 unresolved、是否收到维护者明 可用于指定发布 review 的 bot login；未配置时默认按 `github-actions[bot]` 识别旧 bot comments。 +维护者 dismissal 必须是明确表示不需要修改、保持现状、预期行为或有意如此的肯定回复。 +含有 `intentional` 等词但表达否定或疑问的回复，例如询问是否有意或说明并非有意，不应被视为 +`maintainer_dismissed`，旧 finding 仍按 unresolved 处理。 + ## 本地 review 入口 本地开发完成但尚未 push 或创建 PR 时，可以使用 `review-pr-local` 或 @@ -141,6 +145,10 @@ review 不生成 spec context。 reviewer 的场景。`recommended_reviewers` 必须是字符串数组，最多包含 1 个 reviewer。 +发布到 GitHub 前，review body 和 inline comment body 中位于 fenced code block 之外的字面量 +`\n` 会规范化为真实换行，保证总结和评论按 Markdown 段落显示。Fenced code block 内的内容保持 +原样，避免改写 suggestion 或代码片段中的字面量。 + `APPROVE` 表示没有阻塞级发现。`REJECT` 表示存在需要修复后再合并的阻塞级发现。 建议和 nit 不应单独导致 `REJECT`。 @@ -211,5 +219,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，PR #227，Issue #115，Issue #151，Issue #152，Issue #225，`specs/issue-51/product.md`， +PR #116，PR #154，PR #155，PR #162，PR #163，PR #227，PR #228，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`。 From 3cf647df3f6bf0258e4706924cfed24902edafbd Mon Sep 17 00:00:00 2001 From: "github-actions[bot]" <41898282+github-actions[bot]@users.noreply.github.com> Date: Mon, 8 Jun 2026 19:11:23 +0000 Subject: [PATCH 02/10] docs(product): sync product docs --- docs/product/.product-docs-sync-ledger.json | 22 +++++++++++++++++++ .../raw/pr-comment-response-workflow.md | 6 ++++- docs/product/raw/pr-review-verdict.md | 7 +++++- 3 files changed, 33 insertions(+), 2 deletions(-) diff --git a/docs/product/.product-docs-sync-ledger.json b/docs/product/.product-docs-sync-ledger.json index f851f64b..38264c40 100644 --- a/docs/product/.product-docs-sync-ledger.json +++ b/docs/product/.product-docs-sync-ledger.json @@ -1902,6 +1902,28 @@ "proposed_patch": "更新 docs/product/raw/pr-review-verdict.md，补充 maintainer dismissal 的肯定语义要求、否定或疑问 intentional 回复的处理方式，以及 GitHub review 发布前对 markdown body/comment 中字面量 \\\\n 的换行规范化规则。", "reason": "PR #228 改变了 AI PR Review 的长期用户可见行为：维护者 dismissal 识别不再把否定或疑问语境中的 intentional 裸词当作已 dismiss，并且发布 review 前会把 fenced code block 外的字面量 \\\\n 规范化为真实换行。现有产品文档只概括了 dismissed/resolved 去重和 review 输出契约，未覆盖这些精确语义。", "recorded_at": "2026-06-08T16:41:46Z" + }, + { + "pr": 231, + "url": "https://github.com/Terry-Mao/AICodingFlow/pull/231", + "title": "fix(review): 使用 GitHub PR diff 快照", + "merged_at": "2026-06-04T11:44:26Z", + "merge_commit": "92d3d134fda7ef2da570fae7ffcb6e262485832e", + "docs_update": "required", + "affected_docs": [ + "docs/product/raw/pr-review-verdict.md", + "docs/product/raw/pr-comment-response-workflow.md" + ], + "source_context": [ + "PR #231", + "product-docs-sync-diff.md", + ".github/scripts/build_pr_diff.py", + ".github/workflows/review-pr.yml", + ".github/workflows/respond-to-pr-comment.yml" + ], + "proposed_patch": "Document that GitHub workflow PR diff snapshots for AI PR Review and /fix now come from the GitHub PR diff API, and that the workflows fail if the PR head or base SHA changes while preparing the diff.", + "reason": "PR #231 changed the authoritative PR diff snapshot behavior for GitHub-hosted review and /fix workflows from a local base/head git diff to the GitHub PR diff API with before-and-after SHA validation. This is long-term workflow and public failure-semantics knowledge that was not explicitly covered by the existing product docs.", + "recorded_at": "2026-06-08T19:11:23Z" } ] } diff --git a/docs/product/raw/pr-comment-response-workflow.md b/docs/product/raw/pr-comment-response-workflow.md index 0a9d3de2..31eb053b 100644 --- a/docs/product/raw/pr-comment-response-workflow.md +++ b/docs/product/raw/pr-comment-response-workflow.md @@ -45,6 +45,10 @@ agent 使用 workflow 在 `pr-worktree/.codex-runtime/handoff/` 提供的稳定 `pr_event.json`、`pr_diff.txt`、可用的 `spec_context.md` 和 `review_comment_ids.json`。 `pr_event.json` 包含 PR title、body 和 metadata；`review_comment_ids.json` 包含当前 inline review comments 的 bodies、resolved/outdated thread state、paths、lines、diff hunks 和 URLs。 +`pr_diff.txt` 来自 GitHub PR diff API，而不是 checkout 后对 base/head SHA 执行本地 +`git diff`。workflow 会在读取 diff 前后校验 PR metadata 中的 head SHA 和 base SHA 仍等于 +context 解析出的快照；如果 head 或 base 在准备 diff 期间变化，本次 `/fix` run 失败而不是 +让 agent 基于不一致的 PR diff 继续修改代码。 当触发请求要求处理所有 inline comments、未解决 comments，或某一类 inline review comments 时，agent 应使用 `review_comment_ids.json` 确定请求范围内的每条 inline review comment， @@ -113,5 +117,5 @@ workflow 文件的修复提交继续使用当前 workflow 的默认写入凭据 `Contents: Read and write` 与 `Workflows: Read and write` 权限。不要把生成出来的一次性 installation token 存成 secret；该 token 是短期凭据，会过期。 -来源：PR #99，PR #120，PR #133，PR #139，PR #142，PR #145，PR #150，Issue #28，Issue #119，Issue #141，Issue #144，Issue #149，`specs/issue-28/product.md`， +来源：PR #99，PR #120，PR #133，PR #139，PR #142，PR #145，PR #150，PR #231，Issue #28，Issue #119，Issue #141，Issue #144，Issue #149，`specs/issue-28/product.md`， `specs/issue-28/tech.md`。 diff --git a/docs/product/raw/pr-review-verdict.md b/docs/product/raw/pr-review-verdict.md index ce4a8b70..ce00f2ed 100644 --- a/docs/product/raw/pr-review-verdict.md +++ b/docs/product/raw/pr-review-verdict.md @@ -33,6 +33,11 @@ review comment 也不是该入口。 closed PR、draft PR 或来自 fork 的 PR 会被跳过，不会运行 agent、发布 review 或上传 review artifact。 +GitHub workflow 运行 AI PR Review 时，`pr_diff.txt` 来自 GitHub PR diff API，而不是 +checkout 后对 base/head SHA 执行本地 `git diff`。workflow 会在读取 diff 前后校验 PR +metadata 中的 head SHA 和 base SHA 仍等于触发时解析出的快照；如果 head 或 base 在准备 +review diff 期间变化，本次 review run 失败而不是基于不一致的 diff 继续发布评审。 + ## Comment 与手动触发的 PR 关联 当 AI PR Review 由 PR comment 或 `workflow_dispatch` 触发，且目标 PR 的 head @@ -219,5 +224,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，PR #227，PR #228，Issue #115，Issue #151，Issue #152，Issue #225，`specs/issue-51/product.md`， +PR #116，PR #154，PR #155，PR #162，PR #163，PR #227，PR #228，PR #231，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`。 From f1ac2703f0880140003d035d042cdac8e7e26e56 Mon Sep 17 00:00:00 2001 From: "github-actions[bot]" <41898282+github-actions[bot]@users.noreply.github.com> Date: Mon, 8 Jun 2026 21:29:18 +0000 Subject: [PATCH 03/10] docs(product): sync product docs --- docs/product/.product-docs-sync-ledger.json | 17 +++++++++++++++++ 1 file changed, 17 insertions(+) diff --git a/docs/product/.product-docs-sync-ledger.json b/docs/product/.product-docs-sync-ledger.json index 38264c40..0ba83fb3 100644 --- a/docs/product/.product-docs-sync-ledger.json +++ b/docs/product/.product-docs-sync-ledger.json @@ -1924,6 +1924,23 @@ "proposed_patch": "Document that GitHub workflow PR diff snapshots for AI PR Review and /fix now come from the GitHub PR diff API, and that the workflows fail if the PR head or base SHA changes while preparing the diff.", "reason": "PR #231 changed the authoritative PR diff snapshot behavior for GitHub-hosted review and /fix workflows from a local base/head git diff to the GitHub PR diff API with before-and-after SHA validation. This is long-term workflow and public failure-semantics knowledge that was not explicitly covered by the existing product docs.", "recorded_at": "2026-06-08T19:11:23Z" + }, + { + "pr": 234, + "url": "https://github.com/Terry-Mao/AICodingFlow/pull/234", + "title": "Compile product wiki", + "merged_at": "2026-06-05T07:50:42Z", + "merge_commit": "b862396fe00034dabbdf0b8db6419cdbd91dd483", + "docs_update": "not-needed", + "affected_docs": [], + "source_context": [ + "PR #234", + "docs/product/raw/", + "docs/product/wiki/" + ], + "proposed_patch": "No product docs patch is needed because the merged PR updated only the generated wiki query layer from existing raw sources.", + "reason": "PR #234 only compiled existing authoritative docs/product/raw/ content into docs/product/wiki/. It did not change implementation behavior, specs, raw product docs, or any long-term product rule that is not already represented by the existing product documentation.", + "recorded_at": "2026-06-08T21:29:18Z" } ] } From e9d7a20a82e3556e181f07e947959cae6242bf5c Mon Sep 17 00:00:00 2001 From: "github-actions[bot]" <41898282+github-actions[bot]@users.noreply.github.com> Date: Mon, 8 Jun 2026 23:05:57 +0000 Subject: [PATCH 04/10] docs(product): sync product docs --- docs/product/.product-docs-sync-ledger.json | 19 +++++++++++++++++++ 1 file changed, 19 insertions(+) diff --git a/docs/product/.product-docs-sync-ledger.json b/docs/product/.product-docs-sync-ledger.json index 0ba83fb3..d067f711 100644 --- a/docs/product/.product-docs-sync-ledger.json +++ b/docs/product/.product-docs-sync-ledger.json @@ -1941,6 +1941,25 @@ "proposed_patch": "No product docs patch is needed because the merged PR updated only the generated wiki query layer from existing raw sources.", "reason": "PR #234 only compiled existing authoritative docs/product/raw/ content into docs/product/wiki/. It did not change implementation behavior, specs, raw product docs, or any long-term product rule that is not already represented by the existing product documentation.", "recorded_at": "2026-06-08T21:29:18Z" + }, + { + "pr": 238, + "url": "https://github.com/Terry-Mao/AICodingFlow/pull/238", + "title": "Compile product wiki", + "merged_at": "2026-06-06T11:17:02Z", + "merge_commit": "3f3250161df1490bf03bdc2048d8e48a3c172c71", + "docs_update": "not-needed", + "affected_docs": [], + "source_context": [ + "PR #238", + "docs/product/raw/product-wiki-compile-workflow.md", + "docs/product/raw/agent-directory-layout.md", + "docs/product/raw/product-change-reports.md", + "docs/product/raw/project-installer.md" + ], + "proposed_patch": "No docs/product changes needed; the merged PR is a compiled wiki refresh from existing authoritative raw product docs.", + "reason": "PR #238 only updates compiled Product LLM Wiki pages under docs/product/wiki/ from existing docs/product/raw/ sources. The authoritative long-term product facts are already covered by raw docs, so no additional product docs patch is warranted.", + "recorded_at": "2026-06-08T23:05:57Z" } ] } From 1d376a897de81f7b5fb2fa1a6624a7f4febce3bb Mon Sep 17 00:00:00 2001 From: "github-actions[bot]" <41898282+github-actions[bot]@users.noreply.github.com> Date: Tue, 9 Jun 2026 01:32:57 +0000 Subject: [PATCH 05/10] docs(product): sync product docs --- docs/product/.product-docs-sync-ledger.json | 17 +++++++++++++++++ 1 file changed, 17 insertions(+) diff --git a/docs/product/.product-docs-sync-ledger.json b/docs/product/.product-docs-sync-ledger.json index d067f711..3d392800 100644 --- a/docs/product/.product-docs-sync-ledger.json +++ b/docs/product/.product-docs-sync-ledger.json @@ -1960,6 +1960,23 @@ "proposed_patch": "No docs/product changes needed; the merged PR is a compiled wiki refresh from existing authoritative raw product docs.", "reason": "PR #238 only updates compiled Product LLM Wiki pages under docs/product/wiki/ from existing docs/product/raw/ sources. The authoritative long-term product facts are already covered by raw docs, so no additional product docs patch is warranted.", "recorded_at": "2026-06-08T23:05:57Z" + }, + { + "pr": 242, + "url": "https://github.com/Terry-Mao/AICodingFlow/pull/242", + "title": "Compile product wiki", + "merged_at": "2026-06-07T16:50:48Z", + "merge_commit": "ee0b64e28748798fc7ecc7f9ea295deba043aeb9", + "docs_update": "not-needed", + "affected_docs": [], + "source_context": [ + "PR #242", + "product-docs-sync-context.md", + "product-docs-sync-diff.md" + ], + "proposed_patch": "无需文档补丁；现有 raw product docs 仍是权威来源，本次合并只是基于这些来源更新派生 wiki。", + "reason": "PR #242 仅编译并刷新 docs/product/wiki/ 查询层，变更文件全部位于 compiled wiki。它没有修改实现、spec 或 docs/product/raw/ 权威来源，也没有引入新的长期产品行为或规则。", + "recorded_at": "2026-06-09T01:32:57Z" } ] } From 8fff3a413fbfbf93cd138960bf6bc78b5553c7e2 Mon Sep 17 00:00:00 2001 From: "github-actions[bot]" <41898282+github-actions[bot]@users.noreply.github.com> Date: Tue, 9 Jun 2026 05:54:08 +0000 Subject: [PATCH 06/10] docs(product): sync product docs --- docs/product/.product-docs-sync-ledger.json | 17 +++++++++++++++++ 1 file changed, 17 insertions(+) diff --git a/docs/product/.product-docs-sync-ledger.json b/docs/product/.product-docs-sync-ledger.json index 3d392800..e78f0d04 100644 --- a/docs/product/.product-docs-sync-ledger.json +++ b/docs/product/.product-docs-sync-ledger.json @@ -1977,6 +1977,23 @@ "proposed_patch": "无需文档补丁；现有 raw product docs 仍是权威来源，本次合并只是基于这些来源更新派生 wiki。", "reason": "PR #242 仅编译并刷新 docs/product/wiki/ 查询层，变更文件全部位于 compiled wiki。它没有修改实现、spec 或 docs/product/raw/ 权威来源，也没有引入新的长期产品行为或规则。", "recorded_at": "2026-06-09T01:32:57Z" + }, + { + "pr": 245, + "url": "https://github.com/Terry-Mao/AICodingFlow/pull/245", + "title": "refactor(workflows): extract shared script helpers", + "merged_at": "2026-06-08T05:36:00Z", + "merge_commit": "308e9f4630cd6a1b2f959d5d0ad22b73fd39ff88", + "docs_update": "not-needed", + "affected_docs": [], + "source_context": [ + "PR #245", + "Issue #243", + "docs/product/raw/product-docs-sync-workflow.md" + ], + "proposed_patch": "No product docs patch is needed because the change is internal workflow script structure and regression coverage only.", + "reason": "PR #245 is a workflow script refactor that extracts shared helper modules and moves existing context, GitHub API, ledger, metadata, and artifact I/O logic behind reusable Python helpers. The merged diff does not introduce a new product workflow, lifecycle, permission model, configuration contract, or user-visible behavior that is not already covered by the existing product docs sync workflow documentation.", + "recorded_at": "2026-06-09T05:54:08Z" } ] } From 3b07144e3cbd93216e56d51a8ccda98e5a7e6f26 Mon Sep 17 00:00:00 2001 From: "github-actions[bot]" <41898282+github-actions[bot]@users.noreply.github.com> Date: Tue, 9 Jun 2026 10:29:47 +0000 Subject: [PATCH 07/10] docs(product): sync product docs --- docs/product/.product-docs-sync-ledger.json | 23 ++++++++++ docs/product/raw/agent-directory-layout.md | 7 +-- docs/product/raw/pr-review-verdict.md | 48 ++++++++++++--------- 3 files changed, 54 insertions(+), 24 deletions(-) diff --git a/docs/product/.product-docs-sync-ledger.json b/docs/product/.product-docs-sync-ledger.json index e78f0d04..f55661d0 100644 --- a/docs/product/.product-docs-sync-ledger.json +++ b/docs/product/.product-docs-sync-ledger.json @@ -1994,6 +1994,29 @@ "proposed_patch": "No product docs patch is needed because the change is internal workflow script structure and regression coverage only.", "reason": "PR #245 is a workflow script refactor that extracts shared helper modules and moves existing context, GitHub API, ledger, metadata, and artifact I/O logic behind reusable Python helpers. The merged diff does not introduce a new product workflow, lifecycle, permission model, configuration contract, or user-visible behavior that is not already covered by the existing product docs sync workflow documentation.", "recorded_at": "2026-06-09T05:54:08Z" + }, + { + "pr": 246, + "url": "https://github.com/Terry-Mao/AICodingFlow/pull/246", + "title": "refactor(review): extract shared review contracts", + "merged_at": "2026-06-08T07:51:51Z", + "merge_commit": "23678670f7c14c6c6165488b6a7652c70785e578", + "docs_update": "required", + "affected_docs": [ + "docs/product/raw/agent-directory-layout.md", + "docs/product/raw/pr-review-verdict.md" + ], + "source_context": [ + "PR #246", + ".agents/contracts/review.md", + ".agents/contracts/review.schema.json", + ".agents/skills/review-pr-local/SKILL.md", + ".agents/skills/review-spec-local/SKILL.md", + ".github/scripts/prepare_local_review_inputs.py" + ], + "proposed_patch": "Updated authoritative raw product docs to describe `.agents/contracts/`, shared review contract/schema ownership, core review entrypoints with repo companion guidance, and temporary-directory local review snapshot/output paths.", + "reason": "PR #246 changed long-term AI PR Review behavior by introducing a shared review contract and moving local review snapshots/output to system temporary-directory paths. Existing authoritative raw product docs still described repo-root local snapshots and did not document `.agents/contracts/` as a shared workflow/skill contract area.", + "recorded_at": "2026-06-09T10:29:47Z" } ] } diff --git a/docs/product/raw/agent-directory-layout.md b/docs/product/raw/agent-directory-layout.md index dbc64008..9ace518f 100644 --- a/docs/product/raw/agent-directory-layout.md +++ b/docs/product/raw/agent-directory-layout.md @@ -14,8 +14,9 @@ AICodingFlow 使用根目录 `AGENTS.md` 作为共享仓库级 agent guidance， - `.codex/skills -> ../.agents/skills` - `.cursor/rules/agents.mdc` 是 Cursor 专用规则文件。 -`.agents/skills/` 存放可复用 workflow skills；Cursor 规则通过 `.cursor/rules/agents.mdc` -暴露给 Cursor。 +`.agents/skills/` 存放可复用 workflow skills。`.agents/contracts/` 存放 skills 与 +workflows 共享的稳定 artifact schema、validator contract 和 workflow/skill 边界合同。 +Cursor 规则通过 `.cursor/rules/agents.mdc` 暴露给 Cursor。 该布局的产品目标是让 Claude、Codex 和 Cursor 使用同一组仓库规则与 workflow skills，而不是为每个工具维护独立配置副本。 @@ -43,4 +44,4 @@ AICodingFlow 产品行为、workflow、边界、状态和规则问题。查询 目录 junction 只适合作为无法使用真实 symlink 的本地 fallback。它们不是 tracked symlink 路径的默认设置方式，因为可能让 working tree 与 Git index 表现不一致。 -来源：PR #159，Issue #156；PR #161；PR #175；PR #204，Issue #202。 +来源：PR #159，Issue #156；PR #161；PR #175；PR #204，Issue #202；PR #246。 diff --git a/docs/product/raw/pr-review-verdict.md b/docs/product/raw/pr-review-verdict.md index ce00f2ed..f843e1d7 100644 --- a/docs/product/raw/pr-review-verdict.md +++ b/docs/product/raw/pr-review-verdict.md @@ -54,15 +54,19 @@ checks / statuses 视图中。AICodingFlow 参考 `CI` workflow 不再在测试 ## Review skill 选择 -AI PR Review 会先按 changed files 判断 PR 类型，再选择仓库本地 review companion -skill： +AI PR Review 会先按 changed files 判断 PR 类型，再选择核心 review skill： -- spec-only PR 使用 `review-spec-repo`。 -- 其他 code PR 使用 `review-pr-repo`。 +- spec-only PR 主入口使用 `review-spec`。 +- 其他 code PR 主入口使用 `review-pr`。 + +Review workspace 会复制 `.agents/skills/` 与 `.agents/contracts/`。其中 +`.agents/contracts/review.md` 是共享 review contract，定义 snapshot 信任边界、 +`PR_DIFF_V1` 行定位、`review.json` 结构、severity labels、suggestion blocks、校验规则和 +GitHub/API 边界。Review skills 可以补充评审重点，但不得覆盖该合同。 `review-pr-repo` 和 `review-spec-repo` 是 AICodingFlow 仓库对核心 -`review-pr` / `review-spec` 工作流的仓库本地包装器，用于补充本仓库的评审偏好， -不改变核心输出契约。 +`review-pr` / `review-spec` 工作流的 companion guidance，用于补充本仓库的评审偏好， +不作为主入口，也不改变共享输出契约。 Code PR review 会在基础 `review-pr` 评审之外应用 `security-review-pr` 补充安全检查； spec-only PR review 会在基础 `review-spec` 评审之外应用 `security-review-spec` @@ -104,16 +108,16 @@ comments。 本地开发完成但尚未 push 或创建 PR 时，可以使用 `review-pr-local` 或 `review-spec-local` 在当前分支运行与 GitHub review workflow 一致的评审流程。 -两个本地 skill 会先准备根目录快照，再分别委托给 `review-pr-repo` 或 -`review-spec-repo`。 +两个本地 skill 会先准备 review 快照，再分别委托给 `review-pr` 或 `review-spec`； +核心 skill 会按需读取对应的 `review-pr-repo` 或 `review-spec-repo` companion guidance。 -本地 review 输入与输出固定在仓库根目录： +本地 review 输入与输出位于准备脚本创建的系统临时目录。准备命令会打印实际使用的路径： -- `pr_description.txt` -- `pr_diff.txt` -- `spec_context.md`，仅 code review 需要且存在可用 spec context 时生成 -- `.local_review_baseline.status` -- `review.json` +- `pr_description_path` +- `pr_diff_path` +- `spec_context_path`，仅 code review 需要且存在可用 spec context 时非空 +- `baseline_status_path` +- `review_path` 准备 `pr_description.txt` 时，本地 review 优先读取当前分支关联的 GitHub PR metadata。 如果无法获取关联 PR，则回退到基于本地仓库状态构造的 PR metadata。`pr_diff.txt` 不使用 @@ -121,14 +125,13 @@ GitHub PR diff，始终基于当前 worktree 相对选定 base 的完整状态 GitHub PR 且用户未显式传入 base 时，选定 base 使用该 PR metadata 中的真实 base SHA。 本地 review 准备阶段支持 worktree 中已有 staged、unstaged 和未跟踪文件改动。准备脚本会 -删除旧的 review 快照，并基于当前 worktree 相对选定 base 的完整状态生成 `pr_diff.txt`； -未被 Git ignore 的未跟踪文件会纳入 diff，根目录 review 快照文件和 -`.local_review_baseline.status` 不会纳入 diff。 +基于当前 worktree 相对选定 base 的完整状态生成 `pr_diff.txt`。未被 Git ignore 的未跟踪文件 +会纳入 diff；系统临时目录中的 review 快照、baseline status 和 review output 不会纳入 diff。 -`.local_review_baseline.status` 记录准备阶段完成后的业务文件 dirty 状态，并被 Git ignore。 -review 阶段只能写入受控 review 输出文件，不得修改源码、workflow、测试、spec 或 skill -文件；校验会允许 baseline 中已存在的业务文件状态继续存在，但会拒绝新增业务文件改动、 -业务文件状态变化、staged 输出、非 review 快照文件变更，以及 review 输出被意外删除。 +`baseline_status_path` 记录准备阶段完成后的仓库文件状态。review 阶段只能写入打印的 +`review_path`，不得修改源码、workflow、测试、spec 或 skill 文件；校验会允许 baseline 中 +已存在的文件状态继续存在，但会拒绝新增文件改动、文件状态变化、staged 输出、非 review +输出文件变更，以及 review 输出被意外删除。 本地 review 的 base 可以显式传入；显式 base 拥有最高优先级，并会同步反映在 `pr_description.txt` 的 base metadata 中。未显式传入 base 时，已有 GitHub PR 的当前分支优先 @@ -157,6 +160,9 @@ reviewer。 `APPROVE` 表示没有阻塞级发现。`REJECT` 表示存在需要修复后再合并的阻塞级发现。 建议和 nit 不应单独导致 `REJECT`。 +`.agents/contracts/review.schema.json` 提供共享 JSON schema。Workflow 会在 agent 退出后校验 +`review.json`；本地 review 应使用打印的 `pr_diff_path` 与 `review_path` 执行同一类校验。 + ## PR 作者与类型 作者身份按 GitHub PR 的 `author_association` 判断： From 1e7038d8541d66fd78c8884a0e9dbfac1c9897ee Mon Sep 17 00:00:00 2001 From: "github-actions[bot]" <41898282+github-actions[bot]@users.noreply.github.com> Date: Tue, 9 Jun 2026 13:35:02 +0000 Subject: [PATCH 08/10] docs(product): sync product docs --- docs/product/.product-docs-sync-ledger.json | 16 ++++++++++++++++ 1 file changed, 16 insertions(+) diff --git a/docs/product/.product-docs-sync-ledger.json b/docs/product/.product-docs-sync-ledger.json index f55661d0..d2f943f0 100644 --- a/docs/product/.product-docs-sync-ledger.json +++ b/docs/product/.product-docs-sync-ledger.json @@ -2017,6 +2017,22 @@ "proposed_patch": "Updated authoritative raw product docs to describe `.agents/contracts/`, shared review contract/schema ownership, core review entrypoints with repo companion guidance, and temporary-directory local review snapshot/output paths.", "reason": "PR #246 changed long-term AI PR Review behavior by introducing a shared review contract and moving local review snapshots/output to system temporary-directory paths. Existing authoritative raw product docs still described repo-root local snapshots and did not document `.agents/contracts/` as a shared workflow/skill contract area.", "recorded_at": "2026-06-09T10:29:47Z" + }, + { + "pr": 248, + "url": "https://github.com/Terry-Mao/AICodingFlow/pull/248", + "title": "Compile product wiki", + "merged_at": "2026-06-08T08:43:43Z", + "merge_commit": "8262de9d0f930fa080f511333d014a89499a3e97", + "docs_update": "not-needed", + "affected_docs": [], + "source_context": [ + "PR #248", + "docs/product/wiki/log.md" + ], + "proposed_patch": "No product docs patch is needed; the change is a generated wiki compile log entry and belongs outside authoritative long-term product docs.", + "reason": "PR #248 only updated the generated Product LLM Wiki compile log under docs/product/wiki/log.md. It did not change authoritative raw product knowledge, specs, workflows, permissions, lifecycle rules, APIs, configuration semantics, or user-visible product behavior.", + "recorded_at": "2026-06-09T13:35:02Z" } ] } From f26ee05fb67c36cbb551df8abfe31cec069b7994 Mon Sep 17 00:00:00 2001 From: "github-actions[bot]" <41898282+github-actions[bot]@users.noreply.github.com> Date: Tue, 9 Jun 2026 16:23:59 +0000 Subject: [PATCH 09/10] docs(product): sync product docs --- docs/product/.product-docs-sync-ledger.json | 20 ++++++++++++++++++++ 1 file changed, 20 insertions(+) diff --git a/docs/product/.product-docs-sync-ledger.json b/docs/product/.product-docs-sync-ledger.json index d2f943f0..011d9413 100644 --- a/docs/product/.product-docs-sync-ledger.json +++ b/docs/product/.product-docs-sync-ledger.json @@ -2033,6 +2033,26 @@ "proposed_patch": "No product docs patch is needed; the change is a generated wiki compile log entry and belongs outside authoritative long-term product docs.", "reason": "PR #248 only updated the generated Product LLM Wiki compile log under docs/product/wiki/log.md. It did not change authoritative raw product knowledge, specs, workflows, permissions, lifecycle rules, APIs, configuration semantics, or user-visible product behavior.", "recorded_at": "2026-06-09T13:35:02Z" + }, + { + "pr": 247, + "url": "https://github.com/Terry-Mao/AICodingFlow/pull/247", + "title": "refactor(workflows): move handoff files to temp dir", + "merged_at": "2026-06-08T09:03:00Z", + "merge_commit": "343d5788c14437076bfc8342be5f62bc4bf32e81", + "docs_update": "not-needed", + "affected_docs": [], + "source_context": [ + "PR #247", + "product-docs-sync-context.json", + "product-docs-sync-diff.md", + "docs/product/raw/implementation-workflow.md", + "docs/product/raw/pr-comment-response-workflow.md", + "docs/product/raw/spec-workflow.md" + ], + "proposed_patch": "无需补丁；合并 PR 已包含并落地所需的 docs/product/raw 更新。", + "reason": "PR #247 改变了 spec、implementation 和 PR comment response workflow 的 handoff 路径与提交排除契约，但该 PR 已同步更新对应的长期产品文档。现有 docs/product/raw/implementation-workflow.md、docs/product/raw/pr-comment-response-workflow.md 和 docs/product/raw/spec-workflow.md 已覆盖合并后的 .codex-runtime/handoff 行为、metadata 边界和 spec handoff 限制。", + "recorded_at": "2026-06-09T16:23:59Z" } ] } From 97670f70461b88fb230805e2f7de3e5fb4b02b29 Mon Sep 17 00:00:00 2001 From: "github-actions[bot]" <41898282+github-actions[bot]@users.noreply.github.com> Date: Tue, 9 Jun 2026 18:08:41 +0000 Subject: [PATCH 10/10] docs(product): sync product docs --- docs/product/.product-docs-sync-ledger.json | 19 +++++++++++++++++++ docs/product/raw/product-change-reports.md | 14 +++++++++++++- 2 files changed, 32 insertions(+), 1 deletion(-) diff --git a/docs/product/.product-docs-sync-ledger.json b/docs/product/.product-docs-sync-ledger.json index 011d9413..fcdb5f1c 100644 --- a/docs/product/.product-docs-sync-ledger.json +++ b/docs/product/.product-docs-sync-ledger.json @@ -2053,6 +2053,25 @@ "proposed_patch": "无需补丁；合并 PR 已包含并落地所需的 docs/product/raw 更新。", "reason": "PR #247 改变了 spec、implementation 和 PR comment response workflow 的 handoff 路径与提交排除契约，但该 PR 已同步更新对应的长期产品文档。现有 docs/product/raw/implementation-workflow.md、docs/product/raw/pr-comment-response-workflow.md 和 docs/product/raw/spec-workflow.md 已覆盖合并后的 .codex-runtime/handoff 行为、metadata 边界和 spec handoff 限制。", "recorded_at": "2026-06-09T16:23:59Z" + }, + { + "pr": 249, + "url": "https://github.com/Terry-Mao/AICodingFlow/pull/249", + "title": "fix: validate product report spec links", + "merged_at": "2026-06-08T09:21:22Z", + "merge_commit": "4190d0ff50bed980a9376aa2b5ab8ad00b4d002b", + "docs_update": "required", + "affected_docs": [ + "docs/product/raw/product-change-reports.md" + ], + "source_context": [ + "PR #249", + "Issue #239", + "specs/issue-239/product.md" + ], + "proposed_patch": "更新 docs/product/raw/product-change-reports.md 的来源引用和校验行为章节，补充 spec source reference 的合法链接格式、非法目标类型和状态校验拒绝规则。", + "reason": "PR #249 改变了 product change report 的长期来源引用契约和状态校验行为：spec 引用必须使用从 docs/updates/ 出发的仓库相对 Markdown 链接，并且错误 spec source reference 会被拒绝。现有产品文档只记录了 commit ID 和 related issue URL 校验，未覆盖该已合并行为。", + "recorded_at": "2026-06-09T18:08:41Z" } ] } diff --git a/docs/product/raw/product-change-reports.md b/docs/product/raw/product-change-reports.md index 8a92c410..e53743ae 100644 --- a/docs/product/raw/product-change-reports.md +++ b/docs/product/raw/product-change-reports.md @@ -66,6 +66,13 @@ spec。生成的报告不得包含 commit ID。 当条目引用 related issue 时，必须使用 linked issue metadata 提供的 GitHub issue URL。仅写 issue 编号不足以构成 related issue 引用。 +当条目引用 spec 时，必须使用从 `docs/updates/` 报告文件出发的仓库相对 Markdown 链接， +目标只能是当前仓库中已提交的 `specs/issue-*/product.md` 或 `specs/issue-*/tech.md` 文件。 +例如，`docs/updates/auto-update-*.md` 中的合法引用是 +`[Product spec](../../specs/issue-239/product.md)` 或 +`[Tech spec](../../specs/issue-239/tech.md)`。外部 URL、裸 `specs/...` 路径、目录链接、 +不存在的文件，或非 `product.md` / `tech.md` 目标都不是合法 spec source reference。 + ## 校验行为 报告状态校验会拒绝暴露 commit-like SHA token 的生成报告。对于已 linked 的 @@ -75,4 +82,9 @@ issue URL，校验也会拒绝该报告。 即使 PR 编号与 linked issue 编号相同，PR 引用仍然有效。在这种情况下，类似 `PR #87` 的来源引用不会被当作 related issue 引用处理。 -来源：PR #165，https://github.com/Terry-Mao/AICodingFlow/pull/165；PR #168，https://github.com/Terry-Mao/AICodingFlow/pull/168；PR #171，https://github.com/Terry-Mao/AICodingFlow/pull/171；PR #173，https://github.com/Terry-Mao/AICodingFlow/pull/173；PR #181，https://github.com/Terry-Mao/AICodingFlow/pull/181 +报告状态校验会拒绝错误 spec source reference，包括 spec-like Markdown 链接指向外部 URL、 +仓库外路径、缺失文件、目录或非 `product.md` / `tech.md` 文件，以及用裸 +`specs/issue-*/product.md` 或 `specs/issue-*/tech.md` 文本表达的 spec 引用。 +不包含 spec 引用的有效报告仍按既有规则处理。 + +来源：PR #165，https://github.com/Terry-Mao/AICodingFlow/pull/165；PR #168，https://github.com/Terry-Mao/AICodingFlow/pull/168；PR #171，https://github.com/Terry-Mao/AICodingFlow/pull/171；PR #173，https://github.com/Terry-Mao/AICodingFlow/pull/173；PR #181，https://github.com/Terry-Mao/AICodingFlow/pull/181；PR #249，https://github.com/Terry-Mao/AICodingFlow/pull/249；Issue #239，https://github.com/Terry-Mao/AICodingFlow/issues/239；`specs/issue-239/product.md`