diff --git a/AGENTS.md b/AGENTS.md index 881e3aabf5..a565e1024c 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -99,3 +99,36 @@ history, never the organization's actual state. conclusions.** Sessions here share a model and tend to share blind spots. A read-only `codex exec -s read-only -C ""` pass has already caught a factual error in this very section that same-family review missed. + +## Verifying a "superseded — closing" claim + +`docs/org-required-workflow-rollout.md` allows retiring a PR "only after verified +complete successor carryover of every unique valid delta; redundancy alone is not +a close instruction." Verify that carryover against the tree, not against how +convincing the closing comment reads. These commands narrow it down; none of +them alone proves succession. + +- Read what the branch actually contributes with a **three-dot** diff: + `git diff --stat origin/main...`. Two-dot (`origin/main `) also + reports changes `main` gained that the branch lacks, which on a stale PR reads + as large phantom deletions by the PR. A long-lived branch's title records what + it was opened for, so it is not evidence of current scope either. +- Look for each claimed-inherited piece by content: `git grep -lF "" + origin/main --` (use `-F`; `git grep` treats the pattern as a regex otherwise). + No output means that exact string is absent from `main` — strong evidence the + delta is missing, but not proof, since a successor may have renamed or + restructured the same behaviour. Conversely a match is not proof of inheritance: + the same name can carry different behaviour. +- `git show origin/main:` tells you whether the path exists on `main` + **now**. A non-zero exit does not mean the content never landed — it may have + landed and later been deleted — and success does not mean the successor kept + the predecessor's changes to it. +- Ancestry is the wrong tool here. `git merge-base --is-ancestor main` + answers "was this commit object merged", not "is this content on `main`". This + repository mixes squash merges with real merge commits, so a squash-carried + delta reports false while a later-reverted one still reports true. +- When the delta is provably absent and no successor accounts for it, reopen + (`gh api repos///pulls/ -X PATCH -f state=open`) and comment the + commands and their output. Missing evidence is not the same as disproven + succession: if the check is merely inconclusive, say so and ask, rather than + reopening or letting the closure stand unexamined. diff --git a/CLAUDE.md b/CLAUDE.md index 550ad5ce80..3620985604 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -127,6 +127,13 @@ repeatable compile command. workflow files (e.g. `test_pr_governance_audit_contract.py`, `test_codeql_pr_workflow_contract.py`, `test_opencode_workflow_shell_syntax.py`, `test_opencode_agent_contract.py`). Editing those files without running the test suite will break CI. +- **A "superseded" closure is a claim to verify, not accept.** See `AGENTS.md`'s "Verifying a + 'superseded — closing' claim" section. Two traps specific to this repo: use a **three-dot** + diff (`git diff --stat origin/main...`) — two-dot reports `main`'s own newer commits as + phantom deletions by a stale PR; and do not use `git merge-base --is-ancestor` as the test, + because this repo mixes squash merges with real merge commits, so it answers a different + question than "is this content on `main`". Narrowing a PR into successors is the same claim and + needs the same evidence. - **100% coverage and 100% docstrings on `scripts/ci/`** are hard gates, not aspirations. New helper code needs matching tests and docstrings. - **Product hourly callers** stay thin. Do not hard-code OriginWeave, aFIPC, naruon, or Keyverse