A pass is one bounded research effort with a declared scope, a declared verification grade, and a written trail: mirrored primaries → tagged holdings document(s) → README updates. Passes are how a corpus grows; nothing enters any other way.
| Grade | What it buys | What it may touch |
|---|---|---|
| retrieval | Fast map of a target: primary artifacts found, mirrored, read; claims tagged (author-claimed, single-source, [reported]…); reception noted. Single agent per target, no refutation round. |
external/ holdings + READMEs only. Nothing enters distilled/. Distillation candidates are flagged for a later adversarial pass. |
| adversarial | Claims a decision can rest on. Fan-out to primaries with identity checks (right paper, right version, right authors — confabulated citations are common), claim extraction, then a refutation round: each load-bearing claim through ≥3 independent verification lenses (source-fidelity: does the primary actually say this; methodology/regime-fit: does the method support it, in what regime; independent-replication: who else found it). A claim killed by ≥2/3 lenses dies; corrections are recorded. | May feed Operation 3 (distill). Keep the machine-readable verification record (per-claim verdicts) committed alongside the holdings doc. |
Record the grade in the holdings document's provenance header: the machine-legible
part in its OKF frontmatter (start from the kit's
templates/corpus/external/_holdings.md.tmpl; field set per CONVENTIONS.md, "OKF
alignment"), the rest as prose immediately below — agent count/models, what was fanned
out, what was mirrored, and what the grade means for the reader ("nothing here entered
distilled/" for retrieval).
Where a subtopic's evidence is a surface of numbers rather than a set of claims —
prices, latencies, bandwidths, capacities, adoption shares — write a Parameters document
alongside the holdings doc, from templates/corpus/external/_parameters.md.tmpl. It
carries the same provenance header and grade. The split is by shape, not importance: a
number whose meaning depends on the conditions it was measured under belongs in a table
with a regime column; a claim belongs in prose with an inline evidence tag.
Where a lake corpus exists (see CONVENTIONS.md, "Lake and project profiles"), external
evidence from any pass lands in the lake — one edition of every holding, whichever
project motivated the work. The provenance header names the motivating consumer
(one of the lake README's named consumers), and the pass-narrative entry ends with an
implications line naming any other consumers the findings plausibly implicate.
Before mirroring anything, grep XREF.md's shared-source report — if the URL is
already held, extend the existing mirror instead of re-fetching.
- Every primary artifact gets a local mirror at the corpus's declared mirror location
(large binary mirrors live outside the corpus repo; the corpus stores the pointer):
pages as extracted text/markdown, papers as PDFs, repositories as
git clone --depth 1pinned to a SHA recorded in the manifest. - Each mirror directory carries a
MANIFEST.md: local file → source URL, retrieval date, type, approximate size. Un-mirrorable sources (paywalls, bot-blocked, deleted) are listed in the manifest as such — the gap is part of the record. - Live external ledgers (leaderboards, status files) are snapshotted with their date; the holdings doc cites the snapshot, never "the current state."
- Primary sources first; label secondary coverage (press, forums, threads) as secondary and use it for reception, never for the claim itself.
- Author-claimed vs independently confirmed vs disputed — every number carries one of these, with who confirmed. A party's unreplicated measurement of its own system is Tier C (see GRADING.md).
- No fabrication; absence is a finding. If the target doesn't exist under the searched name, say so and report the closest real thing, noting the mismatch.
- Quotes: at most a few per source, each under 15 words, attributed. Summaries in the pass author's own words, substantially shorter than the source.
- Dates and URLs on everything. A claim without a date cannot decay gracefully.
- Citations section. The holdings doc's source list goes under a numbered
# Citationsheading (OKF §8; format per CONVENTIONS.md, "OKF alignment"). - Regime labels on headline numbers (see CONVENTIONS.md): source hedging is not
enough — mark whether the method licenses the number (
{held-out},{in-distribution},{unstated-N},{within-noise},{wide-CI}).
- One sub-agent per target or cluster; give each: the mission, the mirror directory, the discipline block above, and a required report structure (identity/provenance → mechanism → claims with verification tags → artifact inventory → reception → open questions).
- Tell agents their final message is data for the orchestrator, and that treating search summaries as leads (verify against the primary before reporting) is mandatory — a good agent reports which candidate claims it discarded as unverifiable.
- Where a generic deep-research skill is available, it can serve as the adversarial-grade engine; the corpus adds what it lacks — mirrors, tags, distillation, corrections, decay.
- The holdings document(s) under the right
external/<subtopic>/(new subtopic → new folder with a scoped README from the kit template; empty folders are legitimate queue markers). - The subtopic README: holdings list + open questions.
- The corpus README: pass narrative (one entry: date, method, what it added), recheck schedule additions, corrections if the pass falsified anything already held.
- terminology.md for new terms of art.
- OKF hygiene: every new doc carries frontmatter with its
type; every doc the pass meaningfully changed gets itstimestamprefreshed. - The guard test passes:
python3 -m unittest tests.test_reference -q. - Commit per the host repo's discipline (branch-first where mainline is protected).
- Lake corpora only: regenerate
XREF.md(python3 index.py) — its diff is the pass's new-connections report; register any new tags in the terminology tag registry.