diff --git a/docs/product/.product-docs-sync-ledger.json b/docs/product/.product-docs-sync-ledger.json index fcdb5f1..8ae2673 100644 --- a/docs/product/.product-docs-sync-ledger.json +++ b/docs/product/.product-docs-sync-ledger.json @@ -2072,6 +2072,80 @@ "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" + }, + { + "pr": 250, + "url": "https://github.com/Terry-Mao/AICodingFlow/pull/250", + "title": "Update PR review guidance", + "merged_at": "2026-06-08T09:29:38Z", + "merge_commit": "b89a979c5db8a592d9e61fdf1845fb9851f39260", + "docs_update": "required", + "affected_docs": [ + "docs/product/raw/pr-review-verdict.md" + ], + "source_context": [ + "PR #250", + ".agents/skills/review-pr-repo/SKILL.md" + ], + "proposed_patch": "Updated the authoritative PR review product doc with the newly merged repo-local review guidance and added PR #250 to the source references.", + "reason": "PR #250 merged durable repo-local AI PR Review guidance that changes how reviews interpret intra-PR path changes, product wiki/raw source support, and issue-number reference validation. Existing product docs described the companion guidance mechanism but did not capture these current review behavior rules.", + "recorded_at": "2026-06-09T18:39:36Z" + }, + { + "pr": 253, + "url": "https://github.com/Terry-Mao/AICodingFlow/pull/253", + "title": "refactor(install): skip upstream tests by default", + "merged_at": "2026-06-08T09:56:26Z", + "merge_commit": "d7014c75123ec59c236a54918bf5081f43fa32c1", + "docs_update": "not-needed", + "affected_docs": [ + "docs/product/raw/project-installer.md" + ], + "source_context": [ + "PR #253", + "docs/product/raw/project-installer.md", + "install.sh" + ], + "proposed_patch": "No additional product docs patch is needed because `docs/product/raw/project-installer.md` already records that `.github/aicodingflow-tests/` is an upstream-managed test directory and is not installed by default.", + "reason": "PR #253 changed the project installer sync boundary by excluding `.github/aicodingflow-tests/` from default target-repository installs. The merged PR already updated the authoritative product documentation to describe the current default sync scope and the upstream-test-directory boundary.", + "recorded_at": "2026-06-09T20:37:22Z" + }, + { + "pr": 255, + "url": "https://github.com/Terry-Mao/AICodingFlow/pull/255", + "title": "Compile product wiki", + "merged_at": "2026-06-09T08:05:48Z", + "merge_commit": "f858d456621156e389611b2ceb90022f9afcb58f", + "docs_update": "not-needed", + "affected_docs": [], + "source_context": [ + "PR #255", + "docs/product/raw/", + "docs/product/wiki/" + ], + "proposed_patch": "No product docs patch is needed; the PR updates generated wiki summaries and concepts from existing authoritative raw sources.", + "reason": "PR #255 only recompiles derived files under docs/product/wiki/ from existing docs/product/raw/ sources. It does not introduce or change authoritative product behavior, workflow contracts, configuration semantics, or public user-facing rules that require a raw product docs update.", + "recorded_at": "2026-06-09T22:15:43Z" + }, + { + "pr": 254, + "url": "https://github.com/Terry-Mao/AICodingFlow/pull/254", + "title": "feat: 新增 update-triage 自进化流程", + "merged_at": "2026-06-09T10:30:13Z", + "merge_commit": "1bb0263052515fd8d3d99a570ce87c1812eaa4a2", + "docs_update": "required", + "affected_docs": [ + "docs/product/raw/update-triage-workflow.md" + ], + "source_context": [ + "PR #254", + "Issue #134", + "specs/issue-134/product.md", + "specs/issue-134/tech.md" + ], + "proposed_patch": "新增 docs/product/raw/update-triage-workflow.md，记录 update-triage 的触发输入、维护者修正信号学习规则、允许写入范围和固定 PR 行为。", + "reason": "PR #254 新增了可由维护者手动触发的 update-triage 自进化 workflow，并定义了 triage 反馈学习规则、写入边界和 PR 行为。这是长期产品行为变更，现有产品文档只覆盖 issue triage、update-dedupe 和 update-pr-review，未覆盖该新流程。", + "recorded_at": "2026-06-10T00:01:02Z" } ] } diff --git a/docs/product/raw/pr-review-verdict.md b/docs/product/raw/pr-review-verdict.md index f843e1d..225937d 100644 --- a/docs/product/raw/pr-review-verdict.md +++ b/docs/product/raw/pr-review-verdict.md @@ -68,6 +68,13 @@ GitHub/API 边界。Review skills 可以补充评审重点，但不得覆盖该 `review-pr` / `review-spec` 工作流的 companion guidance，用于补充本仓库的评审偏好， 不作为主入口，也不改变共享输出契约。 +Repo-local code review guidance 会约束本仓库的 AI PR Review 如何解释若干稳定场景： +评审引用路径缺失前，应先检查同一 PR diff 是否新增、删除或重命名了相关路径；当 +`docs/product/wiki/` 编译内容改变长期产品或 workflow 事实时，应核对同一 PR 中对应 +`docs/product/raw/` 权威来源是否支持该事实，但不要求仅反映已更新 raw source 的 wiki +recompile 再次修改 raw；解析 `#` 引用的 validator 或报告检查应区分 issue +引用与 PR/source 引用，只在明确的 issue 或 related issue 语境中强制 issue URL 要求。 + Code PR review 会在基础 `review-pr` 评审之外应用 `security-review-pr` 补充安全检查； spec-only PR review 会在基础 `review-spec` 评审之外应用 `security-review-spec` 补充设计层安全检查。安全发现不会生成单独输出，而是合并进同一个 `review.json`。 @@ -230,5 +237,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，PR #231，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，PR #250，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/update-triage-workflow.md b/docs/product/raw/update-triage-workflow.md new file mode 100644 index 0000000..316a58c --- /dev/null +++ b/docs/product/raw/update-triage-workflow.md @@ -0,0 +1,54 @@ +# update-triage 自进化 triage 规则 workflow + +`update-triage` workflow 用于从最近被 issue triage 处理过的 issues 中收集维护者后续修正信号， +并把稳定、重复、仓库特定的 triage 经验沉淀到 repo-local triage companion guidance。它不重新 +分诊单个 issue，不直接修改 GitHub issues，也不改变 core `triage-issue` skill 的输出合同或安全边界。 + +## 触发与输入 + +维护者可以通过 GitHub Actions `Update Triage Guidance` workflow 手动运行该流程。默认运行 +分析最近 7 天内有更新、且能可靠定位 bot triage 时间的 issues；workflow inputs 可以覆盖扫描天数， +指定单个 issue 用于调试，并控制是否推送更新分支。 + +聚合脚本先为每个候选 issue 定位 `triaged_at`：优先使用 bot triage comment marker 的创建时间， +其次使用 bot 添加 `triaged` label 的 timeline event。无法定位可靠 triage 时间的 issue 会被跳过， +避免把 triage 前的维护者动作误学为后续修正。定位后，脚本只收集 `created_at > triaged_at` 的 +维护者 label added / removed、reopened 事件和后续评论。 + +维护者身份优先来自 GitHub 返回的 `OWNER`、`MEMBER` 或 `COLLABORATOR` 关系；必要时可使用可验证 +的组织成员身份作为 fallback。Bot actor 和普通 reporter 评论默认不作为学习信号。`closed-as-duplicate` +或正式 duplicate 关闭信号由 `update-dedupe` 负责，不进入 triage guidance 学习。 + +## 规则学习 + +`update-triage` skill 读取聚合后的 triage feedback JSON，并寻找稳定、重复、可泛化的维护者修正模式。 +默认至少需要两个独立 issues 支持同一模式，才认为证据足够。可学习模式包括维护者反复纠正的 label +分类、area 判断、issue shape heuristic、复现度默认值或同类 follow-up question。 + +证据不足、只有一次性 override、现有 guidance 已覆盖，或全部信号属于 duplicate 学习范围时，流程产出 +`no_change`，不修改 repo-local guidance，也不创建无意义更新 PR。证据存在但无法安全解释时，流程应产出 +`error`，由外层 workflow 停止应用。 + +## 写入边界 + +`update-triage` skill 本身只写临时 `update-triage-output/` 交接目录。需要更新 guidance 时，它输出 +完整 replacement file；外层 runner 负责应用输出、校验写入范围、提交、推送以及创建或更新 PR。 + +持久写入范围仅限： + +- `.agents/skills/triage-issue-repo/SKILL.md` +- `.github/issue-triage/config.json` + +普通 triage heuristic 应写入 `.agents/skills/triage-issue-repo/SKILL.md`。只有稳定模式表明 label +taxonomy 需要新增 label、重命名 label 或澄清 description 时，才允许最小化更新 +`.github/issue-triage/config.json`。流程不得修改 `.agents/skills/triage-issue/SKILL.md`、 +`.agents/skills/dedupe-issue-repo/SKILL.md`、workflow 文件、脚本、测试、README 或产品代码。 + +## PR 行为 + +有 guidance diff 时，runner 使用固定分支 `feat/update-triage` 创建或更新 PR，并在 PR body 中说明 +数据来源窗口或指定 issue、学到的维护者修正模式摘要、更新文件，以及非关闭 issue reference。没有 +guidance diff 时，不创建 PR。若实现或后续维护需要更新 `.github/workflows/update-triage.yml` 这类 +workflow 文件，推送该类文件仍需要外层 workflow 配置具备 workflow 写权限的 token。 + +来源：PR #254，Issue #134，`specs/issue-134/product.md`。