Skip to content

docs(agents): document how to verify a "superseded" closure claim #1906

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
seonghobae merged 3 commits into from
Sep 5, 2026
Merged

docs(agents): document how to verify a "superseded" closure claim #1906

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
8f840e4
docs(agents): document how to verify a "superseded" closure claim
seonghobae Sep 5, 2026
d652a5c
Merge remote-tracking branch 'origin/main' into docs/verify-supersess…
seonghobae Sep 5, 2026
daf8f8e
docs(agents): correct the closure-verification commands after cross-m…
seonghobae Sep 5, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
33 changes: 33 additions & 0 deletions AGENTS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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 <dir> "<prompt>"` 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...<head>`. Two-dot (`origin/main <head>`) 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 "<string>"
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:<path>` 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 <commit> 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/<owner>/<repo>/pulls/<n> -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.
7 changes: 7 additions & 0 deletions CLAUDE.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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...<head>`) — 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
Expand Down
Loading