protocol: findings before citing code, and checks that were kind once
Two rules that look unrelated and are one failure, plus the change that makes
the second enforceable.
1. A FINDING REACHES `main` BEFORE THE CODE THAT CITES IT. A citation resolving
only on a peer branch is dead the moment it merges. Not hypothetical: 495
decoder and 366 port commits sit off `main`, and `port/scripts/boot.gd`
already cites two docs/re pages present on neither its own branch nor main.
2. A CHECK MAY ONLY SOFTEN AGAINST A CONDITION IT CAN TEST -- the Pi agent's
wording, and better than mine, because it is applicable while writing rather
than a call to be vigilant. The mechanical form:
Can this branch tell the difference between "not yet" and "no longer"?
`gitea-protect --verify` printed ⚪ "not a collaborator (yet)" and continued,
so the only instrument checking Write-not-Admin could not report that gate
being REMOVED. `check-citations` reported peer citations instead of failing
them, because under the old topology that was unfixable from the container.
Both were correct AND kind when written; neither recorded that the kindness
had a scope. Nobody edits these into being wrong -- the world moves and the
allowance stays, which is why they survive review. The smell is leniency with
an expiry date nobody set; the fix is the testable-condition rule.
check-citations gains `--for-merge`, which turns the peer class into a failure.
A flag rather than a new default because BOTH readings are still live: mid-work
on a topic branch the peer class really is unfixable noise. What the old code
could not express is where the code is GOING, and that is a condition the caller
can state. Measured on this tree: 19 citations resolve only on a peer branch --
which is the size of the #7-depends-on-#8 edge, not the 2 I had counted in
boot.gd.
The selftest gains that third class, because a flag whose classification is
unexercised is the shape this rule exists to catch. Controlled: emptying
PEER_REFS makes the peer case collapse into "nowhere" and the selftest reports
🔴 BROKEN, rc=2.
⚠️ Pre-existing and NOT from this change: the default run already exits 1 on 4
citations of `export/...` paths. Those are the generated tree, gitignored by
design, and main's copy of the tool fails identically. The CITE regex treats
`export/` as a repo prefix. Reported, not fixed -- it is the port's file and its
call whether the regex or the citations are wrong.
This commit is contained in:
@@ -155,6 +155,40 @@ rule is written here so you know it, not so it depends on you.
|
||||
A PR you cannot describe in a paragraph is an item that was too big. That is the
|
||||
signal to split it, not to write a longer description.
|
||||
|
||||
### 🔴 A finding reaches `main` before the code that cites it
|
||||
|
||||
A citation that resolves only on a peer branch is **dead the moment it merges**.
|
||||
Open the finding's PR first and make it a dependency of the code's.
|
||||
|
||||
This is not hypothetical and it is not small: **495 decoder commits and 366 port
|
||||
commits sit off `main`**, so nearly anything either agent re-proposes will hit
|
||||
it. `port/scripts/boot.gd` already cites two `docs/re/` pages that exist on
|
||||
neither its own branch nor `main`.
|
||||
|
||||
## Checks that were kind once
|
||||
|
||||
Two rules that look unrelated and are the same failure.
|
||||
|
||||
**A check may only soften against a condition it can test.**
|
||||
|
||||
`gitea-protect --verify` printed ⚪ *"not a collaborator (yet)"* and continued
|
||||
without failing — so the one instrument that checks Write-not-Admin could not
|
||||
report that gate being **removed**. `check-citations` reported peer-branch
|
||||
citations rather than failing them, because under the old branch topology that
|
||||
was a state nobody could fix. Both were **correct and kind when written**, and
|
||||
neither recorded that the kindness had a scope.
|
||||
|
||||
The test is mechanical, and you apply it to your own code:
|
||||
|
||||
> **Can this branch tell the difference between *not yet* and *no longer*?**
|
||||
|
||||
If it cannot, it does not get to be lenient. `--verify` could always ask whether
|
||||
a collaborator exists, so the "yet" was never needed.
|
||||
|
||||
📌 **Nobody edits these into being wrong** — the world moves and the allowance
|
||||
stays. That is why they survive review, and why the smell is worth naming:
|
||||
*leniency with an expiry date nobody set.*
|
||||
|
||||
`share put <file> --note "…" --for port` records the sender, the time, **the
|
||||
commit they were on**, and whether their tree was dirty. A capture with no
|
||||
provenance is not evidence, it is a picture.
|
||||
|
||||
Reference in New Issue
Block a user