From 98f92a6cc3b84fcf7fd7bed29b6e175ef75e62a1 Mon Sep 17 00:00:00 2001 From: cyfung1031 <44498510+cyfung1031@users.noreply.github.com> Date: Sat, 22 Aug 2026 07:16:43 +0900 Subject: [PATCH 1/4] =?UTF-8?q?=F0=9F=93=84=20bind=20agent=20reviews=20to?= =?UTF-8?q?=20live=20PR=20revisions?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- AGENTS.md | 2 +- docs/DOC-MAINTENANCE.md | 3 +++ docs/develop.md | 23 +++++++++++++++++++++++ 3 files changed, 27 insertions(+), 1 deletion(-) diff --git a/AGENTS.md b/AGENTS.md index 64ed8efcd..23303a209 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -15,7 +15,7 @@ duplicating its rules. | build or modify a page, dialog, or block | [`docs/design.md`](docs/design.md) — Core Constraints apply to every UI change | | add or change localized content | [`docs/translation.md`](docs/translation.md) + matching `docs/references/terminology-.md` when present | | add, edit, reorganize, or review tracked contributor Markdown (`AGENTS.md`, `docs/*`, `.github/*.md`, package/source-local READMEs) | [`docs/DOC-MAINTENANCE.md`](docs/DOC-MAINTENANCE.md) — if you can't grep it on this branch, don't claim it | -| open or update a pull request | [`docs/pull-request.md`](docs/pull-request.md) | +| create or update a pull request or publish its branch | [`docs/develop.md#publication-preflight-and-head-binding`](docs/develop.md#publication-preflight-and-head-binding) + [`docs/pull-request.md`](docs/pull-request.md) | | manually confirm a feature works | [`docs/verification.md`](docs/verification.md) — drive a throwaway session against the built extension, not the committed suite | For tasks matching multiple rows, read every applicable owner before that work; do not front-load unrelated diff --git a/docs/DOC-MAINTENANCE.md b/docs/DOC-MAINTENANCE.md index 758ae6314..8e1552cc8 100644 --- a/docs/DOC-MAINTENANCE.md +++ b/docs/DOC-MAINTENANCE.md @@ -115,6 +115,9 @@ places, or they drift apart. To discover the current full set rather than relyin - [ ] No content that only exists on a feature branch is presented as current `main` — removed, or explicitly marked "planned (branch `X`)". - [ ] No fact is duplicated across docs; the owning doc holds it, the others link to it. +- [ ] New sections are inserted at owner-appropriate boundaries. Preserve existing logical blocks and their + adjacent explanations; after insertion, recheck the surrounding order and links. Do not split a code block + from its following explanation unless that boundary change is intentional and documented. ## Checklist 2 — Fact-check (when a doc states something concrete) diff --git a/docs/develop.md b/docs/develop.md index 5696ca0c7..335ffb40e 100644 --- a/docs/develop.md +++ b/docs/develop.md @@ -180,4 +180,27 @@ Work from a feature branch or fork and open PRs against `main`. Chinese PR title Use `.github/pull_request_template.md` as the starting point. It is intentionally lightweight for human-authored PRs; agents should preserve its checklist and expand `Description / 描述` only when useful. The detailed structure is defined in [`pull-request.md`](./pull-request.md). Keep exact commands and results in `验证`, describe UI evidence when the change is visual, and do not claim checks or evidence that did not happen. +### Publication preflight and head binding + +Before creating or updating a pull request, or pushing its branch, bind the revision being reviewed to the +current remote state: + +1. Confirm the worktree is clean, the branch is named, and `HEAD` is not detached with + `git status --short --branch`, `git symbolic-ref --short HEAD`, and `git rev-parse HEAD`. +2. Fetch the current base and relevant head refs before choosing the parent or diff. For a new pull request, + fetch `origin/main` and branch from that ref. For an existing pull request, read its live metadata and record + the repository, base branch, head branch, and head SHA before fetching the relevant head ref. If the target + pull request or head repository cannot be identified, stop and label the evidence local-only; do not call it + final pull-request evidence. +3. Compare the local SHA used for review with the live branch/PR head using `git rev-parse HEAD`, + `git ls-remote refs/heads/` when a remote head exists, and the live pull-request + metadata. A local `HEAD` or tracking ref is not evidence of the pull-request head. If any bound identity + differs, stop, rebind the worktree and diff, and rerun the review against the new head before continuing. +4. Re-read the remote head immediately before pushing. Push normally only when the expected head is unchanged; + never force-push or overwrite remote commits that were not part of the bound review. After pushing, verify + that the remote ref equals the published SHA. +5. Before reporting review or verification results, or changing pull-request metadata, re-read the live pull + request and bind every claim to its returned head SHA. If code or decision-relevant description changed after + a check, rerun the affected checks and review; do not relabel evidence from an older SHA as final evidence. + **Review policy**: review **all** modified files (including `.md`/`.json`); PR description is context only — judge from the diff. Verify every code path touched. From fb82e4338c271da2c48c316d2041de1d12f2b771 Mon Sep 17 00:00:00 2001 From: cyfung1031 <44498510+cyfung1031@users.noreply.github.com> Date: Sat, 22 Aug 2026 07:21:16 +0900 Subject: [PATCH 2/4] =?UTF-8?q?=F0=9F=93=84=20require=20final-diff=20scope?= =?UTF-8?q?=20evidence?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/develop.md | 3 +++ docs/pull-request.md | 16 ++++++++++++++++ 2 files changed, 19 insertions(+) diff --git a/docs/develop.md b/docs/develop.md index 335ffb40e..606a806ca 100644 --- a/docs/develop.md +++ b/docs/develop.md @@ -202,5 +202,8 @@ current remote state: 5. Before reporting review or verification results, or changing pull-request metadata, re-read the live pull request and bind every claim to its returned head SHA. If code or decision-relevant description changed after a check, rerun the affected checks and review; do not relabel evidence from an older SHA as final evidence. + For PR-body scope claims, apply the final-diff rule in + [`pull-request.md#scope-claims-and-final-diff-evidence`](./pull-request.md#scope-claims-and-final-diff-evidence); + intention or an earlier local check is insufficient. **Review policy**: review **all** modified files (including `.md`/`.json`); PR description is context only — judge from the diff. Verify every code path touched. diff --git a/docs/pull-request.md b/docs/pull-request.md index 870222532..18ab865e5 100644 --- a/docs/pull-request.md +++ b/docs/pull-request.md @@ -91,6 +91,22 @@ An agent must not present a change as review-ready when a material acceptance co Verification claims bind to a revision or clearly identified worktree. If code, configuration, generated artifacts, or a decision-relevant description changes after a check, rerun every affected check before claiming readiness. A final commit SHA is sufficient identity for ordinary GitHub work; a cryptographic evidence ledger is not required by default. +### Scope claims and final-diff evidence + +Claims that a pull request includes only a named scope or excludes another change are evidence-bearing. Before +writing or retaining one: + +1. Bind the live pull request base and head SHAs. +2. Inspect `git diff ...`, including changed paths and patch content, against the stated + inclusion or exclusion set. Branch ancestry, commit intention, and an earlier local checkout do not prove + the claim. +3. Record the exact base/head pair and the check in `验证`. If no observable diff can prove the claim, omit it or + label it unverified. + +Any new commit, force-push, rebase, base change, conflict resolution, or scope-claim edit invalidates earlier +scope evidence. Recompute the final diff and re-read the live pull request before publishing or reporting the +claim. + ## Evidence triggered by changed contract Activate only the rows touched by the actual change; mixed changes use their union. From 4659061381d5ba7803ac8fc8b478a02e88b68e00 Mon Sep 17 00:00:00 2001 From: cyfung1031 <44498510+cyfung1031@users.noreply.github.com> Date: Sat, 22 Aug 2026 07:28:03 +0900 Subject: [PATCH 3/4] =?UTF-8?q?=F0=9F=93=84=20broaden=20revision=20binding?= =?UTF-8?q?=20trigger?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- AGENTS.md | 3 +-- docs/develop.md | 40 ++++++++++++++++++++-------------------- 2 files changed, 21 insertions(+), 22 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 23303a209..929d15163 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -10,12 +10,11 @@ duplicating its rules. | Before you… | Read | | --- | --- | | write code | [`docs/develop.md`](docs/develop.md) | -| review code or a pull request | [`docs/develop.md`](docs/develop.md) + [`docs/pull-request.md`](docs/pull-request.md) for PR-body rules | +| review or report a branch/PR, or create/update a PR or publish its branch | [`docs/develop.md#revision-scope-and-publication-binding`](docs/develop.md#revision-scope-and-publication-binding) + [`docs/pull-request.md`](docs/pull-request.md) | | change a process/message/service/persistence boundary or add a subsystem | [`docs/architecture.md`](docs/architecture.md) + the relevant `docs/references/architecture-*.md` | | build or modify a page, dialog, or block | [`docs/design.md`](docs/design.md) — Core Constraints apply to every UI change | | add or change localized content | [`docs/translation.md`](docs/translation.md) + matching `docs/references/terminology-.md` when present | | add, edit, reorganize, or review tracked contributor Markdown (`AGENTS.md`, `docs/*`, `.github/*.md`, package/source-local READMEs) | [`docs/DOC-MAINTENANCE.md`](docs/DOC-MAINTENANCE.md) — if you can't grep it on this branch, don't claim it | -| create or update a pull request or publish its branch | [`docs/develop.md#publication-preflight-and-head-binding`](docs/develop.md#publication-preflight-and-head-binding) + [`docs/pull-request.md`](docs/pull-request.md) | | manually confirm a feature works | [`docs/verification.md`](docs/verification.md) — drive a throwaway session against the built extension, not the committed suite | For tasks matching multiple rows, read every applicable owner before that work; do not front-load unrelated diff --git a/docs/develop.md b/docs/develop.md index 606a806ca..04c4d5181 100644 --- a/docs/develop.md +++ b/docs/develop.md @@ -180,30 +180,30 @@ Work from a feature branch or fork and open PRs against `main`. Chinese PR title Use `.github/pull_request_template.md` as the starting point. It is intentionally lightweight for human-authored PRs; agents should preserve its checklist and expand `Description / 描述` only when useful. The detailed structure is defined in [`pull-request.md`](./pull-request.md). Keep exact commands and results in `验证`, describe UI evidence when the change is visual, and do not claim checks or evidence that did not happen. -### Publication preflight and head binding +### Revision, Scope, and Publication Binding -Before creating or updating a pull request, or pushing its branch, bind the revision being reviewed to the -current remote state: +Before reviewing or reporting a branch or pull request, or creating/updating a pull request or pushing its +branch, bind the artifact, revision, and scope to the current remote state: -1. Confirm the worktree is clean, the branch is named, and `HEAD` is not detached with - `git status --short --branch`, `git symbolic-ref --short HEAD`, and `git rev-parse HEAD`. +1. Identify the target. For a live pull request, read its metadata and record its repository, base branch, head + branch, and head SHA. If only a local branch or commit is available, record its SHA and label all results + local-only; do not call them final pull-request evidence. 2. Fetch the current base and relevant head refs before choosing the parent or diff. For a new pull request, - fetch `origin/main` and branch from that ref. For an existing pull request, read its live metadata and record - the repository, base branch, head branch, and head SHA before fetching the relevant head ref. If the target - pull request or head repository cannot be identified, stop and label the evidence local-only; do not call it - final pull-request evidence. -3. Compare the local SHA used for review with the live branch/PR head using `git rev-parse HEAD`, + fetch `origin/main` and branch from that ref. For an existing pull request, fetch the recorded head repository + and branch. +3. Compare the local SHA used for review or publication with the live branch/PR head using `git rev-parse HEAD`, `git ls-remote refs/heads/` when a remote head exists, and the live pull-request - metadata. A local `HEAD` or tracking ref is not evidence of the pull-request head. If any bound identity - differs, stop, rebind the worktree and diff, and rerun the review against the new head before continuing. -4. Re-read the remote head immediately before pushing. Push normally only when the expected head is unchanged; - never force-push or overwrite remote commits that were not part of the bound review. After pushing, verify - that the remote ref equals the published SHA. -5. Before reporting review or verification results, or changing pull-request metadata, re-read the live pull - request and bind every claim to its returned head SHA. If code or decision-relevant description changed after - a check, rerun the affected checks and review; do not relabel evidence from an older SHA as final evidence. - For PR-body scope claims, apply the final-diff rule in + metadata. A local `HEAD` or tracking ref is not evidence of the pull-request head. If any identity differs, + stop, rebind the worktree and diff, and rerun the review before continuing. +4. For a live pull request, derive review conclusions and inclusion/exclusion claims from the live base-to-head + diff, including changed paths and patch content. Apply the final-diff rule in [`pull-request.md#scope-claims-and-final-diff-evidence`](./pull-request.md#scope-claims-and-final-diff-evidence); - intention or an earlier local check is insufficient. + branch ancestry, intention, and an earlier local check are insufficient. +5. Before publication, require `git status --short --branch`, a named non-detached branch, and `git rev-parse + HEAD`; re-read the remote head immediately before pushing. Push normally only when the expected head is + unchanged, never force-push or overwrite unreviewed remote commits, and verify the remote ref after pushing. +6. Before reporting results or changing pull-request metadata, re-read the live pull request and bind every claim + to its returned head SHA. Any new commit, force-push, rebase, base change, conflict resolution, or scope-claim + edit invalidates earlier evidence; rerun the affected review, checks, and final-diff audit. **Review policy**: review **all** modified files (including `.md`/`.json`); PR description is context only — judge from the diff. Verify every code path touched. From add187bfb0a40abf89b8c4aa166df8843a1ab3d7 Mon Sep 17 00:00:00 2001 From: cyfung1031 <44498510+cyfung1031@users.noreply.github.com> Date: Sat, 22 Aug 2026 07:35:39 +0900 Subject: [PATCH 4/4] =?UTF-8?q?=F0=9F=93=84=20constrain=20authorized=20PR?= =?UTF-8?q?=20rewrites?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/develop.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/docs/develop.md b/docs/develop.md index 04c4d5181..7cd946773 100644 --- a/docs/develop.md +++ b/docs/develop.md @@ -201,7 +201,9 @@ branch, bind the artifact, revision, and scope to the current remote state: branch ancestry, intention, and an earlier local check are insufficient. 5. Before publication, require `git status --short --branch`, a named non-detached branch, and `git rev-parse HEAD`; re-read the remote head immediately before pushing. Push normally only when the expected head is - unchanged, never force-push or overwrite unreviewed remote commits, and verify the remote ref after pushing. + unchanged. Never overwrite an unexpected or unreviewed remote commit. If the user explicitly authorizes a + rewrite, bind the current remote head, use a lease-protected force update against that exact SHA, and verify + the remote ref after pushing. 6. Before reporting results or changing pull-request metadata, re-read the live pull request and bind every claim to its returned head SHA. Any new commit, force-push, rebase, base change, conflict resolution, or scope-claim edit invalidates earlier evidence; rerun the affected review, checks, and final-diff audit.