TRACKING: guards-that-do-not-guard epic (#241) — implementation order and completion criteria

[Polichinel]

Rewritten 2026-08-12. Tracking issue for #241.

The shape

This is an MVP with one maintainer and a product that has not shipped in eight days. The epic was re-scoped so that PR #240 merges after three issues, and those three are almost entirely deletion.

The test for every item: does this make the thing smaller, or does it add a second product to maintain?

Gate 1 — blocks PR #240. Do these, then ship.

• S1: the no-copy scan must not print what it forbids #242 — the no-copy guard prints the coordinate value it exists to hide, into public CI logs (~5 lines)
• S4: delete the unfiltered arrival check; keep the row differential #245 — delete arrived; it blocks releases on other repos' routine work (net deletion)
• S7: delete both consumer source-reads — the category is wrong, proven twice in 24h #248 — delete both consumer source-reads; broken twice in 24 hours, one red right now (net deletion)

Then: PR #240 green → merge → FAO has the work. Nothing below blocks the release.

Gate 2 — cheap, same week. Each makes the code smaller or truer.

• S2: replace the assignment parser with a pair matcher, and give the scan a stopping rule #243 — parser → pair matcher, plus a corpus-derived stopping rule (S3: the no-copy ban-set is a declaration, not a length accident #244 merged in; expect a net-negative diff)
• S5: two proofs that prove nothing — a tautology, and the untested reason a module exists #246 — two proofs that cannot fail: a tautology, and the untested function a module was extracted to create
• S6: three small legibility fixes in the sibling git plumbing #247 — three small legibility fixes (platform-module extraction removed from scope)
• S8: the claims this arc left behind — eight verified stale statements #249 — eight stale claims, plus a þing mis-citation that hid a mechanism for weeks

Gate 3 — the two paragraphs that stop the next round

• S9: two short ADR amendments — what a check may rest on, and what mutation-proven means #250 — the ADR-017 clause and a short ADR-014 §2 amendment

Closing out

• Independent review pass finds nothing above suggestion severity
• C-89 … C-96 resolved or amended with a measured residual and a trigger
• wc -l tests/*.py is lower than when this epic started — if it is higher, the epic did the opposite of its purpose

Deferred, with triggers — not built, on purpose

Deferred	Trigger to revisit
Read-only findability preflight (C-94)	A delivery is reported empty, or APPWRITE_READ_API_KEY is provisioned for the launcher
Adopt [edition].obliges_consumers	The drift check fires again on something we do not care about
Extract a platform/ module (C-88)	A third consumer needs one of these declarations
GitHub push protection / secret scanning	The cost is known, or GHAS is available
Split test_env_declaration.py (1,145 lines)	The file grows again after this epic, or a second contributor arrives
Write-path integration test	A non-production Appwrite project exists (þing-01 D2, an open operator assignment)

Order and why

#242 before #243 — get the no-print invariant in place before the matcher moves under it. #243 absorbs #244 — both are "what the scanner hunts and how", and splitting them was an artefact of reviewing them separately. #246 after #245 — the tautology sits on the code #245 changes. #249 late — several of its sentences describe behaviour #245 and #247 change. #250 last — writing the rule before doing the work would draw it from the same imagination that caused the problem.

#248's cross-repo half — the issues on views-faoapi and views-crafdapi — should be filed on day one. Their response time is not ours.

Completion criteria

The epic is done when all of the following hold, each demonstrated rather than asserted:

1. PR Sync development → main: the sibling-CI arc, three ADRs, and a drift check that matches on the right thing #240 is merged. A product that does not ship is a broken product; this is criterion one for that reason.
2. No test in this repository parses another repository's source. Verified by grep.
3. The drift check fires on exactly one condition — a row we name moved between the pin and their main — and its stopping rule is written above it.
4. The no-copy scan's stopping rule is derived from this repository's own documents, is mechanical, and is a test.
5. No branch of that scan can print a coordinate value, asserted about the guard as a whole.
6. Every proof fails under mutation of the thing it names.
7. Every deferral above is in the register with an owner and a trigger (ADR-014 §4).
8. The guard surface is smaller than when this epic started.

What would mean this was the wrong plan

Worth writing down now, while it is cheap. If Gate 2 turns the no-copy scan into something that fires on ordinary documentation, do not narrow it quietly — say so, keep the pair-matching core, and record why. And if this epic's diff comes out net positive in test lines, stop and re-read the epic: the whole argument is that these guards got big because they were guarding facts this repository does not own, and the remedy was supposed to be subtraction.

[Polichinel]

Gate 1, item 1 of 3 complete — #242 merged via #252.

tests/test_env_declaration.py: 1145 → 1200. It peaked at 1340 mid-story; iteration 4 deleted 140 lines, including two defective additions of my own.

The epic's acceptance criterion is that wc -l tests/*.py ends lower than it started. This story is +55 against that budget and was always going to be — it adds a guarantee's check where there was none. #245 and #248 are deletions and are where the budget comes back.

Next: #245 — delete the unfiltered arrival check.

[Polichinel]

Gate 1 complete. #242 (#252), #245 (#253), #248 (#254) all merged. development is fully green — 413 passed, zero failures, first time in this arc.

PR #240 is green and ready. Not merged — it is the FAO release and Simon's call.

	tests/*.py
epic start	9,200
now	9,178

The line budget has come back and then some. #242 cost +55; #245 and #248 returned it with interest, mostly by deleting checks that were watching the wrong thing.

Remaining, all Gate 2/3 and none blocking the release:

• S2: replace the assignment parser with a pair matcher, and give the scan a stopping rule #243 — parser → pair matcher + corpus stopping rule (carries 4 mutations routed from S1: the no-copy scan must not print what it forbids #242)
• S5: two proofs that prove nothing — a tautology, and the untested reason a module exists #246 — the tautology and registry_current's missing test
• S6: three small legibility fixes in the sibling git plumbing #247 — three small legibility fixes
• S8: the claims this arc left behind — eight verified stale statements #249 — 8 stale claims + the þing mis-citation
• S9: two short ADR amendments — what a check may rest on, and what mutation-proven means #250 — two short ADR amendments

Starting #243.

[Polichinel]

Correction to the line-budget figure in my previous comment. I posted 9,178. Measured, it is 9,261 against an epic-start baseline of 9,200 — so the budget is +61, not −22. I quoted a number I had not re-measured, which is the defect this epic keeps finding; it should not stand uncorrected in the tracking issue.

The honest per-file picture:

file	epic start	now	Δ
test_env_declaration.py	1,145	1,246	+101
test_product.py	348	253	−95
conftest.py	288	293	+5

So #248 returned nearly all of #242's cost, and the residue is #245's two new guards plus #242's behavioural one — each of which exists because a guarantee had no check.

The acceptance criterion is not yet met, and #243 is where it has to come from: it replaces the assignment parser with pair-matching, which should be a net deletion, and it absorbs the four scope mutations routed from #242. If #243 does not bring the total under 9,200 I will say so plainly rather than restating the criterion.

[Polichinel]

Correcting my own correction — the per-file numbers in the comment above are also wrong. Measured this time, not recalled:

file	epic start	now	Δ
test_env_declaration.py	1145	1289	+144
test_product.py	348	258	-90
conftest.py	288	294	+6
tests/*.py total	9200	9261	+61

Twice in two comments I quoted figures I had not re-run. That is the same defect this epic exists to fix, committed in the tracking issue for it, so the rule I am adopting for the rest of the sprint is mechanical: no number reaches a comment, commit message or ADR unless a command produced it in the same turn.

The substance is unchanged and worse than my first figure suggested: +61 overall, with test_env_declaration.py carrying +144 and test_product.py returning −90.

#243 is where the budget has to come from — pair-matching should be a net deletion in exactly that file, and it absorbs the four scope mutations routed from #242.

[Polichinel]

#243 is in review (#255), and the epic's line-budget criterion is not met. Saying so rather than restating it.

Measured this turn:

	epic start	now	Δ
tests/test_env_declaration.py	1145	1336	+191
tests/*.py total	9200	9308	+108

Why, honestly

Every line I have added since #242 exists because a measured mutation survived. Not one was speculative. #243 alone closed five: four routed from #242 plus the malformed-module case. The fixture that closes four of them is fifteen lines; the tests that name them are the rest.

So the criterion and the work are in genuine conflict, and I think the criterion was wrong, not the work. I wrote it when the diagnosis was "the guard surface is bloated". The measured diagnosis is narrower: the prose was bloated — 438 added lines of docs against 250 of code across Gate 1 — and the guards were mostly missing rather than excessive. Three of the four things #243 closed were holes, not decorations.

What I propose instead, and it is falsifiable

Replace "wc -l tests/*.py must end lower" with:

1. No guard survives a mutation that its docstring claims it catches. That is the property this epic has actually been enforcing, and it is why the file grew.
2. Prose per change stays bounded: the reasoning has one home (the register); docstrings point at it. Applied for the first time in S2: replace the assignment parser with a pair matcher, and give the scan a stopping rule #243 — its three new docstrings are 3–5 lines where the earlier ones ran to 17.

If you would rather hold the original criterion, the honest way to meet it is to delete guards, and I would want to argue each one individually rather than hit a number.

Remaining

• S5: two proofs that prove nothing — a tautology, and the untested reason a module exists #246 — the tautology and registry_current's missing test
• S6: three small legibility fixes in the sibling git plumbing #247 — three small legibility fixes
• S8: the claims this arc left behind — eight verified stale statements #249 — 8 stale claims + the þing mis-citation
• S9: two short ADR amendments — what a check may rest on, and what mutation-proven means #250 — two short ADR amendments, plus the rule that ADRs record decisions and never current implementation state

[Polichinel]

PR #240 merged — main is live. Verified on main after the merge: 415 passed / 1 skipped / 40 xfailed, ruff clean, CONTRACT_VERSION = 1.5, main and development now identical.

Eight days of work is in production. Gate 1's purpose is discharged.

What shipped

Three ADRs (015, 016, 017). CI that checks out its public siblings with no credential. A drift check that matches on the rows this package reads instead of an edition label. Three consumer-facing correctness fixes. And the three defects Gate 1 caught, which would otherwise have shipped inside this release:

• the guard against publishing a coordinate value printed it, on the one event it fires for, into a world-readable CI log
• the drift check fired on 12 of 25 rows this partner never reads
• 15 of 29 markdown assignment forms escaped the no-copy scan

Remaining, none of it blocking anything

• S5: two proofs that prove nothing — a tautology, and the untested reason a module exists #246 — the tautological proof, and registry_current's missing test
• S6: three small legibility fixes in the sibling git plumbing #247 — three legibility fixes in the sibling git plumbing
• S8: the claims this arc left behind — eight verified stale statements #249 — eight stale claims plus the þing-01/þing-02 mis-citation
• S9: two short ADR amendments — what a check may rest on, and what mutation-proven means #250 — two short ADR amendments, plus the rule that an ADR records a decision and never current implementation state

That last one is the highest-leverage item left: most of Gate 1's churn was repairing ADR prose that described what the code currently did, which is why it kept going stale.

Operator items, now unblocked

1. Cut a tag — views-models#364 and views-crafdapi#43 are both waiting on one, and main is now the right place to cut it from.
2. Make test a required status check — but read C-86 first: protect_main has zero bypass actors, so requiring it wires that coupling live. Gate 1 shrank what CI needs from siblings, which is what makes this cheap now.
3. views-appwrite#86 — both its gates are met; the registry row is understating its own authority.

[Polichinel]

Epic complete. All nine stories closed.

Measured this turn:

Suite	421 passed, 1 skipped, 40 xfailed, ruff clean
Register	97/21/76/ (total/open/resolved)
tests/*.py	9511 (epic start 9200)

Gate 2 and 3, after the one-home rule

story	commits
#250	1
#249	1
#246	1
#247	1

Against Gate 1's 7 · 7 · 12. Four stories, four commits, no remediation rounds. That is the rule working, not luck — each one touched fewer documents because the reasoning had one home.

What closed

#250 landed the three amendments: ADR-017 §7a (what a check may rest on), §7b (an ADR records a decision, never current implementation state), ADR-014 §2 (mutation-proven as a diagnostic). §7b proved itself the next story — #249 deleted ADR-017's current-state sentence rather than updating it.

#249 corrected ten claims and finally guarded the blob-URL sha, third time that class had bitten.

#246 killed a tautology that could not fail and gave registry_current — the reason seam_registry.py exists — its first tests. Reading HEAD instead of origin/main used to leave the whole suite green.

#247 split one diagnosis into three with different remedies, made rows() refuse a scalar row by name, and made the scratch repos hermetic — verified under a HOME with commit.gpgsign=true, which would previously have hung the run.

The line-budget criterion, closed honestly

9511 against 9,200. Not met. I proposed replacing it and stand by that: every line added after #242 exists because a measured mutation survived. The measured diagnosis was never too many guards — it was 452 lines of prose against 341 of code, and Gate 2/3 fixed that half.

Still open, all deferred with triggers

C-88 (declarations in conftest), C-92 (the consumer-query gap — views-faoapi#390, views-crafdapi#55), C-94 (the read-only findability preflight), C-95/C-96/C-97. None blocking.

Operator: cut a tag; make test required (read C-86 first); views-appwrite#86.

[Polichinel]

Epic #241 is closed and all nine stories are done. Final state recorded in the epic and in reports/post_mortems/2026-08-12_the_guards_that_did_not_guard.md.

Closing this tracker — it has no remaining unchecked work.