chore(external-validity): retire design-era working material from the study tree - #640
Merged
Conversation
… tree
Applies the standing research-artifact retention rule to the external-validity
study: an artifact stays only if it reproduces a consequential result, enforces
an invariant, documents a durable decision, serves as a frozen input, or is
needed by the still-active Run 2 execution path. Git history holds the rest.
Removed, none of them read by any code, gate, test or CI job:
* probes/x06_m6_feasibility.py -- M6 is STRUCK by A20 and HARNESS-PLAN
implements "section 6 (M0-M9 minus M6)", so the question it measured is no
longer in the methodology. It runs the superseded pdfium_hybrid /
reconstruct_hybrid arms, not the frozen H/X pair.
* probes/x19_raster_edge_diagnostic.py -- an A32 raster diagnostic that
states no pass threshold; the ruling it informed (A30.3 stands) is frozen
in the ledger.
* results/x19_raster_dev/ -- 16 development raster PNGs, referenced only by
x19's own evidence file.
* 20 generated probe evidence artifacts whose sole role was recording that an
earlier run passed. Every one is regenerated byte-identically by a probe
that remains in the tree.
Deliberately retained, each with a live consumer or an unrepairable citation:
* the frozen inputs -- holdout/, control_fixtures/, holdout_membership.json,
contamination.json, design_exposure.json, control_fixtures.json,
x2_contract_assertions.json (G2) and x26_control_oracle.json (G6 fails
ORACLE_INTEGRATION_NOT_VERIFIED without it).
* results/design_runs/*.log -- x05 DERIVES the design-exposure list from
them; they are a primary source, not a log dump.
* x00 and x02 evidence -- cited as MEASURED by PRE-REGISTRATION.md, which is
byte-frozen and cannot be given a pointer to git history.
* x09, x11 and x13 evidence -- named by retained METHODOLOGY_SURFACE files.
Repointing those would edit a result-bearing file for a cosmetic reason.
No membership, scoring rule, threshold, architecture rule or frozen study
semantic changes. G5's surface stays 15 files. The execution boundary stays
ABSENT and no confirmatory artifact is created.
HARNESS-PLAN.md's three citations of removed evidence files now name the probe
that regenerates them.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
A46 states the retention rule the cleanup applied, why x06 and x19 own no live invariant (M6 is STRUCK by A20; x19 states no pass threshold and A32's ruling is frozen), and the measured basis for calling the removed evidence regenerable -- every committed probe artifact was re-run first and rewrote byte-identically. Earlier ledger entries are NOT rewritten. A17/A19/A21/A22/A23/A24.2 and A41 keep their MEASURED links; A46 records that they resolve at 4b94672~1 and that each amendment already transcribes its numbers inline. Filed SUBSTANTIVE with affects_scoring_rule false: all three protected files are already SUBSTANTIVE-declared, so TOOLING would trip x04's dual-class refusal, and CLERICAL would misdescribe removing two executable probes. F9: 4b94672 declared, naming all three protected files it touched. 46 amendments declaring 83 commits, all protected commits accounted for. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Research output was accumulating in the tree by default, because nothing said otherwise: every probe, evidence dump and diagnostic image a study produced stayed permanent simply by having been committed once. States the retention rule, and the two tests that decide the ambiguous cases -- prove regenerability by re-running the producer rather than assuming it, and retain an artifact whenever the document citing it is byte-frozen and so can never be given a pointer to git history. Also warns against the inverse error, which is the more expensive one here: a generated JSON under docs/research/ may be a committed expected-output oracle a gate reads, and an old-looking probe may be the only executable negative control of a rule still in force. Decide by tracing consumers, not by filename or age. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Running any external-validity xNN probe rewrites its own evidence file. After A46 removed the artifacts nothing reads, those files reappear as UNTRACKED after a routine probe run, so a later `git add -A` would silently restore the working material the cleanup retired -- and the restore would look like ordinary probe output, not like a reverted decision. The negations are the artifacts something actually reads (G2's X2 evidence, G6's control-oracle evidence), that a byte-frozen document cites (x00/x02 in PRE-REGISTRATION.md), or that a retained METHODOLOGY_SURFACE file names. Verified both directions rather than assuming the pattern: `git check-ignore` matches x27/x29 on the x*.json rule and matches NONE of the seven negated paths. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
…on category The bullet ended "an artifact no surviving code can reproduce is a frozen input whatever it looks like." That is not the policy. Irreproducibility on its own does not make something a frozen input: a one-off diagnostic nothing needs can be irreproducible and still fail all four criteria. As written it converted "we lost the producer" into a standing reason to keep a file forever -- and losing a producer is an ordinary accident, so that category would have grown quietly and rebuilt the accumulation problem the rule exists to prevent. Failure to regenerate is now a reason to re-check the four criteria, not a retention reason in itself. No retention decision in this branch rested on the wrong reading: design_runs is kept because x05 derives a consequential result from it, x26 because G6 reads it, x00/x02 because a byte-frozen document cites them. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Rebasing onto develop after #638 rewrote every commit SHA on this branch, so A46's declared `4b94672` named a commit no longer reachable from HEAD and F9 went RED on the deletion commit as undeclared. Re-declared as `4b808e2`, and the one prose citation of `4b94672~1` moved with it. Mechanical only: no amendment text, class, file list or retention decision changes, and the deletion set is byte-identical across the rebase. Expect to repeat this on any future rebase of this branch -- F9 binds declarations to commits, so a rewritten SHA is always a stale declaration. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
willhea
force-pushed
the
worktree-ev-study-cleanup
branch
from
August 15, 2026 15:48
ae6fd66 to
7f8260d
Compare
willhea
marked this pull request as ready for review
August 15, 2026 15:59
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Repository hygiene for the PDF external-validity study. No methodology changes. The study is not being declared complete: Run 2 is still the intended next step, and everything its execution path needs is retained.
Policy
Applied strictly — "useful history" and "was once reviewed" are not retention reasons — but decided by tracing consumers, never by filename or age. The rule is now standing, in
AGENTS.mdunder a new "Research artifacts" section, so future research work does not re-accumulate by default.Removed
38 files, 797 KB. Nothing removed is read by any code, gate, test or CI job; that was verified mechanically, not by eye (every basename grepped repo-wide, with the producing probe's own output-path line excluded as a write target rather than a read).
results/xNN_*.json)results/x19_raster_dev/)probes/x06_m6_feasibility.pymeasured whether M6 could be adjudicated inside a 6–10 line region. A20 STRUCK M6 and HARNESS-PLAN implements "§6 (M0–M9 minus M6)", so the question is no longer in the methodology; it also drives the supersededpdfium_hybrid/reconstruct_hybridarms rather than the frozen H/X pair, so it exercises no current component. A17.1 transcribes its table inline.probes/x19_raster_edge_diagnostic.pyasked whether the visible left edge is displaced from the geometricx0. It states no pass threshold by construction, and the ruling it informed (A30.3 stands, no tolerance) is frozen in A32.Regenerability was measured, not assumed: every committed probe artifact in the study was re-run before deletion and rewrote byte-identically, leaving the tree clean.
Kept
The audit reversed several of the obvious-looking deletion candidates. The ones worth naming:
results/design_runs/*.log— these look like run logs and are not.x05derives the design-exposure list from them, and that list disqualifies documents from the frozen population (F3) and feeds G4. A primary source.results/x26_control_oracle.json— looks like historical probe output; G6 defectsORACLE_INTEGRATION_NOT_VERIFIEDwithout it. A committed expected-output oracle.results/x00_design_pilot.json,results/x02_oracle_reference_defects.json— cited as MEASURED byPRE-REGISTRATION.md, which is byte-frozen (F4 depends on its last-modifying commit) and can therefore never be given a pointer to git history.results/x09_…,x11_…,x13_…— named by retainedMETHODOLOGY_SURFACEfiles. Repointing those would mean editing a result-bearing file for a cosmetic reason.xNNprobe — each is the executable control over a retained live component.The line that decided the ambiguous cases: a dangling reference is acceptable only where the referring document can be appended to. The ledger can record where a removed file resolves; a byte-frozen pre-registration cannot, so what it cites stays.
Governance (F9)
Deleting a
.py/.mdunder the study tree is visible to F9 whether or not the file is inMETHODOLOGY_SURFACE. Handled through the existing mechanism, not around it:4b94672, naming all three protected files it touched.affects_scoring_rule: false. Not TOOLING: all three files are already SUBSTANTIVE-declared and x04 refuses a file declared under both. Not CLERICAL: that would misdescribe removing two executable probes as a typo fix.4b94672~1and that each amendment already transcribes its numbers inline.Nothing changed in membership, scoring rules, thresholds, architecture rules or frozen study semantics.
PRE-REGISTRATION.mdis untouched.Safety
Baseline (
origin/develop=d7c169d, PR #637/A45 merged) vs this branch — identical except F9's expected amendment count:--self-testruff check ./ruff format --checkEvery other retained invariant owner was also run, since a removed artifact that turned out to be consumed would surface here: x21 117/117 · x28 92/92 · x15 64/64 · x17 56/56 · x26 12/12 · x24 16/16.
x26andx2_verifywrite artifacts that are retained and consumed — both rewrote byte-identically, so G6'sORACLE_EVIDENCE_STALEdigest binding and G2's blob binding stay valid. The.gitignoreguard was then confirmed live: after nine probe runs the working tree is clean, the regenerated transient artifacts show as ignored, and every negated artifact stayed tracked.The 33 pytest skips are benign fixture-shape skips (shell bills with no amounts) and update-mode guards; none is a corpus-degraded or silently-skipped schema gate. This worktree has no
bills_corpus/bills_bulk_textsymlinks, which affects only provision-matching research tests unrelated to this change.Explicitly verified: frozen population unchanged (17 members, membership blob
d2731d6a== frozen blob); holdout bytes unchanged (F2/F11); G5 surface still 15 files, none missing; G6 still N-A 8 / N-B 8 / N-C 4, 0 defects; the A45 cross-engine authority repair still live (x29 96/96 includes its controls); execution boundary still ABSENT, noEXECUTION-START.jsoncreated, no confirmatory artifact written, no holdout extraction run, and no 1.1 GB artifact introduced.Falsification
Readiness must not go green merely because a control was deleted, so that was tested rather than argued. Each fault was injected and reverted, tree clean after each:
results/x26_control_oracle.json→ G6 FAILORACLE_INTEGRATION_NOT_VERIFIED, readiness CLOSED. Removingresults/design_runs/→x05FATAL rc=2, the design-exposure list becomes unreproducible. Both keeps are load-bearing, and over-deletion of this class is detectable.probes/x2_verify.py→ G2 FAIL (blob binding and live verifier exit 2), G5 FAILMISSING 1/15, F9 red, readiness CLOSED. Three independent gates catch it.results/x13_x_arm.json→ 17/17 PASS, FREEZE COMPLETE, READINESS OPEN, BOUNDARY ABSENT. Semantically unchanged.A and C together are the point: the gates fail on a frozen input and are indifferent to a historical artifact, so the two classes are distinguishable rather than uniformly invisible. Because C is invisible to the gates by design, the no-consumer proof for that class is the mechanical reference sweep above, not the green suite.
Also
.gitignoregains the study's transient probe evidence. Running any xNN probe rewrites its own evidence file, so after this cleanup those reappear as untracked and a latergit add -Awould silently restore the retired material, looking like ordinary probe output rather than a reverted decision. The seven retained artifacts are negated, and both directions were checked withgit check-ignorerather than assumed.No new files are added anywhere; the temporary audit inventory was kept outside the repository and is not committed.