Skip to content

chore(external-validity): retire design-era working material from the study tree - #640

Merged
willhea merged 6 commits into
developfrom
worktree-ev-study-cleanup
Aug 15, 2026
Merged

chore(external-validity): retire design-era working material from the study tree#640
willhea merged 6 commits into
developfrom
worktree-ev-study-cleanup

Conversation

@willhea

@willhea willhea commented Aug 15, 2026

Copy link
Copy Markdown
Collaborator

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

Research artifacts are working material, not automatically permanent repository material. At closure, retain only artifacts needed to reproduce a consequential result, enforce an invariant, document a durable decision, or serve as a frozen input. Git history preserves the investigative record.

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.md under 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).

category n why it fails the retention test
generated probe evidence (results/xNN_*.json) 20 recorded only that an earlier run passed; no consumer, and each is regenerated by a probe still in the tree
development raster images (results/x19_raster_dev/) 16 referenced only by x19's own evidence file
obsolete probes 2 see below

probes/x06_m6_feasibility.py measured 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 superseded pdfium_hybrid/reconstruct_hybrid arms rather than the frozen H/X pair, so it exercises no current component. A17.1 transcribes its table inline.

probes/x19_raster_edge_diagnostic.py asked whether the visible left edge is displaced from the geometric x0. 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. x05 derives 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 defects ORACLE_INTEGRATION_NOT_VERIFIED without it. A committed expected-output oracle.
  • results/x00_design_pilot.json, results/x02_oracle_reference_defects.json — cited as MEASURED by PRE-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 retained METHODOLOGY_SURFACE files. Repointing those would mean editing a result-bearing file for a cosmetic reason.
  • Every other xNN probe — 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/.md under the study tree is visible to F9 whether or not the file is in METHODOLOGY_SURFACE. Handled through the existing mechanism, not around it:

  • A46 declares deletion commit 4b94672, naming all three protected files it touched.
  • Filed SUBSTANTIVE, 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.
  • No historical ledger prose is 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.
  • F9 was confirmed to actually fire on the deletion commit before A46 landed, so the declaration is closing a real red gate rather than a hypothetical one.

Nothing changed in membership, scoring rules, thresholds, architecture rules or frozen study semantics. PRE-REGISTRATION.md is untouched.

Safety

Baseline (origin/develop = d7c169d, PR #637/A45 merged) vs this branch — identical except F9's expected amendment count:

gate baseline after
x04 freeze/readiness F1–F11 COMPLETE · G1–G6 PASS · BOUNDARY ABSENT identical (F9 45→46 amendments, 82→83 commits)
x04 --self-test 36/36 36/36
x27 score_metrics 194/194 194/194
x29 execute_study 96/96 96/96
x23 control fixtures 55/55 55/55
x22 score input contract 52/52 52/52
x2_verify X2-a PASS, X2-b PASS / 1559 boundaries identical
full pytest 3423 passed, 33 skipped, 15 xfailed
ruff check . / ruff format --check clean / 241 formatted

Every 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.

x26 and x2_verify write artifacts that are retained and consumed — both rewrote byte-identically, so G6's ORACLE_EVIDENCE_STALE digest binding and G2's blob binding stay valid. The .gitignore guard 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_text symlinks, 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, no EXECUTION-START.json created, 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:

  • A — over-deletion of a frozen input. Removing results/x26_control_oracle.jsonG6 FAIL ORACLE_INTEGRATION_NOT_VERIFIED, readiness CLOSED. Removing results/design_runs/x05 FATAL rc=2, the design-exposure list becomes unreproducible. Both keeps are load-bearing, and over-deletion of this class is detectable.
  • B — missing live invariant owner. Removing probes/x2_verify.pyG2 FAIL (blob binding and live verifier exit 2), G5 FAIL MISSING 1/15, F9 red, readiness CLOSED. Three independent gates catch it.
  • C — deleted historical artifact. Removing results/x13_x_arm.json17/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

.gitignore gains 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 later git add -A would 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 with git check-ignore rather than assumed.

No new files are added anywhere; the temporary audit inventory was kept outside the repository and is not committed.

willhea and others added 6 commits August 15, 2026 11:06
… 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
willhea force-pushed the worktree-ev-study-cleanup branch from ae6fd66 to 7f8260d Compare August 15, 2026 15:48
@willhea
willhea marked this pull request as ready for review August 15, 2026 15:59
@willhea
willhea added this pull request to the merge queue Aug 15, 2026
Merged via the queue into develop with commit a2e045c Aug 15, 2026
31 checks passed
@willhea
willhea deleted the worktree-ev-study-cleanup branch August 15, 2026 16:05
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant