diff --git a/AGENTS.md b/AGENTS.md index 64ed8efcd..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 | -| open or update a pull request | [`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..7cd946773 100644 --- a/docs/develop.md +++ b/docs/develop.md @@ -180,4 +180,32 @@ 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. +### Revision, Scope, and Publication Binding + +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. 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, 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 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); + 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 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. + **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.