Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
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
21 changes: 21 additions & 0 deletions .gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -114,6 +114,27 @@ docs/research/provision-matching/probes/merged_labels.json
# No trailing slash, per the #319 symlink reasoning above.
docs/research/pdf-backend-bakeoff/holdout

# External-validity probe evidence (A46). Running any xNN probe rewrites its own evidence
# file, so after the A46 cleanup these reappear as untracked artifacts and a later `git add -A`
# would silently re-commit the working material that was retired. Ignored rather than left
# loose. They are regenerated by running the probe; git history holds the removed versions.
#
# The negations are the artifacts something actually READS or that a byte-frozen document
# cites — dropping one un-tracks a live gate input, so only change this list together with
# the consumer that justifies it. A new committed artifact needs a new negation here.
docs/research/pdf-backend-bakeoff/validation/external-validity/results/x*.json
# G2 reads this one; G6 defects ORACLE_INTEGRATION_NOT_VERIFIED without the other.
!docs/research/pdf-backend-bakeoff/validation/external-validity/results/x2_contract_assertions.json
!docs/research/pdf-backend-bakeoff/validation/external-validity/results/x26_control_oracle.json
# Cited as MEASURED by PRE-REGISTRATION.md, which is byte-frozen and can never be repointed.
!docs/research/pdf-backend-bakeoff/validation/external-validity/results/x00_design_pilot.json
!docs/research/pdf-backend-bakeoff/validation/external-validity/results/x02_oracle_reference_defects.json
# Named by retained METHODOLOGY_SURFACE files (cross_engine_control, run_hybrid, run_extended,
# reconstruct_extended_corrected), which may not be edited for a cosmetic reason.
!docs/research/pdf-backend-bakeoff/validation/external-validity/results/x09_skeleton_cross_engine.json
!docs/research/pdf-backend-bakeoff/validation/external-validity/results/x11_provenance_chain.json
!docs/research/pdf-backend-bakeoff/validation/external-validity/results/x13_x_arm.json

# Build artifacts. The project became buildable in #398, so `uv build` now produces
# these where it never used to. `build/` matters beyond tidiness: some backends copy
# the package's own .py files into it, and a directory holding Python that is neither
Expand Down
9 changes: 6 additions & 3 deletions AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -89,13 +89,16 @@ A comment describes the code as it is **now**. History and rejected alternatives

Probes, audits, spikes and study write-ups are **working material, not automatically permanent repository material.** At closure, retain an artifact only if it is needed to reproduce a consequential result, enforce an invariant, document a durable decision, or serve as a frozen input. **Delete the rest** — Git history preserves the investigative record. Retention is the exception that needs a reason, and "it was expensive to produce" is not one.

Apply that strictly: "useful history", "might be interesting later", "shows how we got here" and "was once reviewed" are not retention reasons, because every one of them is satisfied by `git log`. Judge an artifact by the consequential role it plays **now**, never by its filename, its age, or how much history it carries. The inverse error is just as real, so decide by tracing consumers — under `docs/research/` a generated JSON that looks like a stale run log may be a committed expected-output oracle a gate reads, and a probe that looks superseded may be the only executable negative control of a rule still in force. Before removing one, check imports, direct path reads, subprocess calls, gate inputs, and any doc that names it as a *current* requirement.

When deleting research, **remove or update live references to it**, and move any durable conclusion into its authoritative current home: an ADR, the architecture documentation, an executable test, or a frozen fixture. Do not write an archival summary, a tombstone map or a closure document whose only job is to record what was deleted — that is a new artifact with the same problem, and a pointer into history is one more thing that can be wrong.

The failure this prevents is subtler than rot. A probe that no longer runs at least announces itself; a probe that still runs can publish a quantity the project has since disowned, and passing a check makes it look current. So the question at closure is not "does it work?" but "does it still answer a live question?"
The failure this prevents is subtler than rot. A probe that no longer runs at least announces itself; a probe that still runs can publish a quantity the project has since disowned, and passing a check makes it look current. So the question at closure is not "does it work?" but "does it still answer a live question?" `tests/test_research_probes.py` runs the probes it declares runnable against a closed manifest, so a probe added later is either run or the gate fails.

So the gate executes (which catches the first two), and retirement is judged on whether the artifact still answers a live question (which catches the third). `tests/test_research_probes.py` runs the probes it declares runnable against a closed manifest, so a probe added later is either run or the gate fails.
Two rules that decide the ambiguous cases:

When retiring an artifact, record in the document that cited it **which executable test inherited its question**, and pin the commit it stays readable at. A reproduction claim pointing at a deleted file is the defect this is meant to avoid, not the price of avoiding it.
- **Prove claimed regenerability rather than assuming it.** If an artifact is being deleted because surviving machinery can reproduce it, re-run the producer and confirm that claim. Failure to regenerate is a reason to re-check the four criteria above; it is not, by itself, a retention reason — a one-off diagnostic that nothing needs is just as disposable when its producer is gone.
- **A dangling reference is acceptable only where the referring document can be appended to.** If a byte-frozen document (a pre-registration, a sealed manifest) cites the artifact, it can never be given a pointer to git history — so retain the artifact instead. An append-only ledger can simply record where the removed file resolves, which is the one place a history pointer earns its keep.

## Architecture decisions

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -45,8 +45,8 @@ never re-derives an earlier stage's decisions.

## 2. `build_frames.py` — **BUILT (A31)**

Implemented and tested on SYNTHETIC + DEVELOPMENT material only; evidence in
`results/x17_build_frames.json`, **56/56 controls passing**. No canonical `results/frames.json`
Implemented and tested on SYNTHETIC + DEVELOPMENT material only; evidence is regenerated by
running `x17_build_frames.py`, **56/56 controls passing**. No canonical `results/frames.json`
exists. The D-frame is emitted as a **complete census** — the A10/A27.3 budget is not applied
here. Anchor equality uses the **whole emitted production `Anchor` value**; no reduced
signature was invented. No runner instrumentation was added: each arm's anchors come from the
Expand Down Expand Up @@ -372,7 +372,7 @@ a pre-committed sentence, and must refuse to emit any comparative-accuracy claim

### RESOLVED by measurement — 7.4 anchor→neutral bridge

**Proven, not argued** (`x14_anchor_bridge.py`, `results/x14_anchor_bridge.json`):
**Proven, not argued** (run `x14_anchor_bridge.py`):

```
Anchor(page_number, line_number) <- line_number is the GPO PRINTED margin number
Expand Down Expand Up @@ -426,7 +426,7 @@ enforce it.
| §4.5 P-head was a caller obligation | **A30.4** — `filter_keys` now takes `(key, kind, population)` and applies both restrictions itself |
| blind-ID uniqueness was only synthetic | **A30.5** — asserted over the **realized** set; a collision aborts the build |

**Proven, not argued** (`x16_occurrence_identity.py`, `results/x16_occurrence_identity.json`):
**Proven, not argued** (run `x16_occurrence_identity.py`):

```
instrumented mirror == production extract_anchors every DEVELOPMENT page consumed
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -6071,6 +6071,74 @@ opening any document and nothing measured, since the gate reads keys only.

---

## A46 — SUBSTANTIVE. Design-era working material is retired from the tree

```json
{"id": "A46", "class": "SUBSTANTIVE",
"commits": ["4b808e2"],
"confirmatory_output_at_time": "none",
"affects_membership": false, "affects_scoring_rule": false,
"files_touched": ["probes/x06_m6_feasibility.py", "probes/x19_raster_edge_diagnostic.py",
"HARNESS-PLAN.md"],
"supersedes_text_in": "none -- NO frozen rule changes. No metric, threshold, denominator, control fixture, population, adjudication route, decision rule or F/G gate moves. G5's surface stays 15 files and no member of it is touched",
"status": "COMPLETE. Boundary ABSENT, execution FORBIDDEN"}
```

**The retention rule being applied.** Research artifacts are working material, not
automatically permanent repository material. At closure, an artifact is retained only if it
is needed to reproduce a consequential result, enforce an invariant, document a durable
decision, or serve as a frozen input — plus, here, anything the still-active Run 2 execution
path needs. Git history preserves the investigative record. "Useful history", "shows how we
got here" and "was once reviewed" are not retention reasons.

**Two probes are removed**, and neither owns a live invariant:

- **`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 does not exercise any
current component. A17.1's table transcribes its finding inline.
- **`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. Its 16 development raster PNGs
are referenced only by its own evidence file.

**Twenty generated evidence artifacts are removed.** Their only role was recording that an
earlier probe run passed; nothing reads them. Each is regenerated by a probe that remains in
the tree, and regenerability was measured rather than assumed: every committed probe artifact
in this study was re-run before the deletion and rewrote **byte-identically**, leaving the
tree clean.

**Earlier links in this ledger resolve in git history.** A17/A19/A21/A22/A23/A24.2 and A41
link `results/x06_m6_feasibility.json`, `x07_neutral_geometry.json`,
`x08_neutral_identity.json`, `x10_reconstruction_signature.json`,
`x12_skeleton_eligibility.json` and `x27_score_metrics.json` as MEASURED evidence. Those
amendments are **not rewritten** — the ledger is an append-only record, and editing a past
entry to hide a removal would be the defect, not the fix. Read those links at **`4b808e2~1`**.
Each amendment already transcribes its numbers inline, so the reasoning stands without them.

**What was deliberately NOT removed, and why.** The line is that a dangling reference is
acceptable only where the referring document can be appended to, as this ledger can:

| retained | why it could not go |
|---|---|
| `holdout/`, `control_fixtures/`, `holdout_membership.json`, `contamination.json`, `design_exposure.json`, `control_fixtures.json` | frozen inputs to F1/F2/F3/F7/F8/F10/F11, G4 and G6 |
| `results/x2_contract_assertions.json` | G2 reads it |
| `results/x26_control_oracle.json` | G6 defects `ORACLE_INTEGRATION_NOT_VERIFIED` without it |
| `results/design_runs/*.log` | `x05` **derives** the design-exposure list from them; a primary source, not a log dump |
| `results/x00_design_pilot.json`, `results/x02_oracle_reference_defects.json` | cited as MEASURED by **`PRE-REGISTRATION.md`**, which is byte-frozen and can never carry a pointer to git history |
| `results/x09_skeleton_cross_engine.json`, `x11_provenance_chain.json`, `x13_x_arm.json` | named by retained METHODOLOGY_SURFACE files; repointing those would edit a result-bearing file for a cosmetic reason |
| every other `xNN` probe | each is the executable control over a retained live component |

**Why SUBSTANTIVE and not TOOLING or CLERICAL.** All three protected files are already
declared under SUBSTANTIVE amendments (A17/A18/A20, A32, A27/A28/A30/A31/A33/A34), and x04
refuses a file declared under both a SUBSTANTIVE and a TOOLING amendment. CLERICAL would
misdescribe the removal of two executable probes as a typo fix. The change alters no scoring
rule, so `affects_scoring_rule` is **false** — but removing study machinery is a material act
and is recorded as one, which also means it would be forbidden after the boundary opens.

---

## A18 — the commit ↔ file accounting of record

```json
Expand Down
Loading