One literature review, nine stages, and a stage pointer that makes any of them resumable.

The Shape Of A Run

Three structural rules hold across all of them, and they are what keeps a hundred-paper run inside a single context window:

• A subagent receives bounded input — one paper, or one batch of PMIDs, plus the criteria and an output path. Never the corpus.
• A subagent writes its own result file and returns only the receipt {schema_version, task_id, status, output_path, summary}. Never raw paper text, never the full JSON.
• Subagents cannot spawn subagents, and the stage's output directory is shared — a subagent must not count, audit, or comment on files it did not write.

Choosing A Profile

The profile sets search breadth, appraisal depth, and which approval checkpoints show back to you. It is asked explicitly at Stage 0 — never inferred from how the question was phrased.

Scope tiers, and what each one adds

Stage 0 — Configure

Stage 0 does two jobs: establish what is reachable this session, and settle the handful of choices that cannot be inferred.

Connector preflight, every run

Tool availability is a property of the session, not of the skill. MCP servers attach at session start, so a connector authorized ten minutes ago is still absent until a new session starts. The agent checks its own tool list once, at Stage 0, and records what it found in config.json:

"connectors": {
  "pubmed_mcp": true,
  "scholar_gateway": false,
  "consensus": false,
  "checked_at": "2026-09-12T09:14:02Z"
}

That block is carried into the report's Methods section. A run that could not reach a source its profile assumes must say which source, and what it means for coverage.

The six questions

Stop after extraction

Orthogonal to the profile: pipeline.stop_after_stage: 5 in config.json runs search → screen → retrieve → extract and halts. No appraisal, no synthesis, no report, no promotion. It still runs the Stage 5 exit sync, so the extractions are immediately reusable by any later run that hits the same papers — including a different question.

This is a pause point, not a different pipeline. Clearing stop_after_stage and resuming continues the same run into Stage 6.

The run directory

<wiki>/outputs/deep-research/<slug>/          # wiki mode
<repo>/runs/<slug>/                            # standalone repo mode

  config.json      profile, filters, budgets, connectors, stage pointer
  engine.log       diagnostics, script failures, guard output
  taskboard.jsonl  one record per unit of work — never hand-edited
  events.jsonl     append-only retrieval log (evidence kernel)
  corpus.jsonl     one record per paper, all stages
  sources/         immutable text snapshots
  inputs/          run inputs
  workspace/       per-stage working records
  outputs/         protocol.md, report.md, digest.md, verification.json, result.json
  missing.md       quarantine + abstract-only blocks
  inbox/           drop PDFs here to resolve blocks

The stage pointer is the only thing a resume trusts

config.json's stage is bumped as each stage completes, in the same turn. A coordinator that carries the stage in its head leaves the pointer stale, and the next session restarts a stage that already finished. On resume, the agent reads config.json + taskboard.jsonl, continues incomplete and failed tasks, and does not re-prompt.

Stage 1 — Protocol

Question framing in the chosen framework, numbered inclusion/exclusion criteria (I1, E2, … — screening cites these ids), limits, and the planned search. Built from the Stage 0 selection-criteria answers, never invented fresh. Template: templates/protocol.md. At standard and above, the protocol and the search strategy are shown back and the run waits for approval.

Stage 2 — Search

Seed from the shared pool first, then design queries.

python3 scripts/pool.py seed --run-dir <run_dir> --wiki <root>    # or --repo <path>

Seeding scores the existing pool against this run's question, framework fields, and filters, and upserts likely papers into corpus.jsonl with source: pool and first_seen_query: pool-seed. They are candidates only — Stage 3 still screens them against the current protocol.

Orthogonality is a property of hit sets, not of strings

The failure this guards against: eight queries that are one query with the synonyms shuffled, producing one hit set, near-zero marginal yield, and a search log that looks thorough. Queries vary along four axes:

Two queries count as orthogonal when they differ on ≥2 axes and their hit sets satisfy Jaccard J < 0.6 with unique yield ≥ 15% each. A 4–8 query set must cover at least three values of axis A, three of B, two of C, and two of D — plus at least one pure text-word arm bounded by [edat] (the only arm that sees the last ~12 months), at least one null/negative-findings arm, and at least one citation-chaining arm with ≥3 independent seeds.

Anti-patterns the checklist rejects

Every query string, its NCBI-translated form, and its hit count are logged to workspace/search/<query_id>.json and reproduced verbatim in the report's Methods. Duplicate queries are detected and skipped before execution by corpus.py query-check. A failed orthogonality pair is replaced, never deleted — deleting shrinks the recorded strategy without improving it.

Stage 3 — Screen

Dedupe first (PMID → DOI → normalized title), then title/abstract triage against the numbered criteria. Each verdict records include/exclude/unclear plus the first failing criterion id, and flags retractions and expressions of concern. PMIDs are batched across subagents.

At systematic and max, two independent screeners run, with a third adjudicating every disagreement. The PRISMA log gets raw agreement plus counts:

GOOD  "Two screeners independently assessed 412 records; they disagreed on 37
       (raw agreement 91.0%). All 37 were adjudicated by a third worker;
       12 were adjudicated to include."

BAD   "Inter-rater reliability was good."

A kappa is reported only if it was actually computed from the full contingency table — named as Cohen's kappa, with the table shown. Raw agreement is never presented as kappa.

The included set is capped at max_articles, chosen by protocol relevance, and the report says how the cap was applied.

Stage 4 — Retrieve

Goal: full text, not abstracts. fulltext.py acquire walks a nine-rung ladder per paper until text is in hand, recording which rung succeeded. Records screened out are never acquired.

Why two rungs need the agent

A script cannot call an MCP tool. Rungs 1 and 7 therefore append a handoff task and keep walking the ladder — the run never blocks on either. The agent later reads fulltext.py status, calls the tool, writes the returned text verbatim to the task's result_path, and resolves it:

python3 scripts/fulltext.py status --run-dir <run>
# → mcp_tasks_pending: [...], browser_tasks_pending: [...]

python3 scripts/fulltext.py resolve-mcp     --run-dir <run> --evidence-id pmid:33333333 --text-file <path>
python3 scripts/fulltext.py resolve-browser --run-dir <run> --evidence-id pmid:33333333 --status unavailable

Re-running acquire picks up a dropped result file and is equivalent to calling resolve-* — they are the same code path, not two. If the tool reports no full text, resolving with --status unavailable marks the rung terminal so it is never retried.

The truncation detector

Rungs 1, 5, and 7 can all hand back an abstract wrapped in a page of teaser text. The same two checks apply to raw text as to stripped HTML, and either one firing is enough:

On fire: truncation_detected: true, status downgraded to abstract_only, and the reason written to the rung detail and engine.log (body_words=303<1500, paywall_marker=Access options). The text is still stored — it is a legitimate abstract — but every downstream claim carries the abstract-only label. The detector is deliberately trigger-happy: a false abstract_only costs a label; a false fulltext corrupts the appraisal.

A truncated success no longer stops the ladder. The first one is kept as a fallback while every remaining rung is tried for genuine full text. A later rung with real full text wins outright and clears any missing.md block; a later truncated result does not replace the fallback; rung 8 is preempted so quarantine never overwrites degraded-but-real text with status: missing.

OCR, and what is not installed

1. pdftotext -layout <pdf> -                       # always first
2. pdfminer.high_level.extract_text                # if pdftotext absent or empty
3. pdftoppm -r 300 -gray -png -f N -l N | tesseract # only if 1-2 yield < 100 chars

ocrmypdf is not installed and there is no whole-file OCR path. Per-page OCR is capped at 30 pages and disabled with --no-ocr; its use is recorded in the rung detail. pdfinfo metadata is not trusted for DOI recovery — page-1 text plus a 10\.\d{4,}/\S+ regex is.

Politeness is enforced, not aspirational

Two retries on network errors and HTTP 429/500/502/503/504 with linear backoff. Everything else fails the rung and moves on. Email comes from --email or $DEEP_RESEARCH_EMAIL.

Quarantine → inbox → resume

Stage 4 itself never stalls: it walks the ladder for every remaining record regardless of any single failure, and never asks mid-ladder whether to keep going. What stalls, deliberately, is the pipeline as a whole. Once acquisition has been attempted for every selected record, a non-empty missing.md halts the run before Stage 5 — regardless of which kind of block it holds:

An abstract-only block is not a lesser case to be waved through. You get one consolidated table of every blocked record with links, the rung reached, and the ask:

| Title | PMID     | DOI               | Rung | Status        | Links            |
|-------|----------|-------------------|------|---------------|------------------|
| ...   | 33333333 | 10.1000/paywalled | t8   | quarantined   | PubMed · DOI     |
| ...   | 42119772 | —                 | t1   | abstract-only | PubMed           |

Action: place the PDF in <run-dir>/inbox/ (any filename) and re-run.

systematic and max gate hard on this — extraction does not start until missing.md is empty. fast and standard may proceed on your say-so, with quarantined records tagged missing, abstract-only records used as-is, and the synthesis marked PROVISIONAL either way.

python3 scripts/library.py ingest-inbox --run-dir <run> --wiki <root>
python3 scripts/fulltext.py acquire --corpus <corpus.jsonl> --run-dir <run>

Ingestion matches each dropped PDF by page-1 DOI regex first, then by fuzzy title against quarantined records (normalized title slid across page-1 text, best ratio ≥ 0.85; titles under 25 normalized characters are never fuzzy-matched). Matched PDFs are filed into the library with sha256 dedupe, the corpus updated to source_tier: 0 / access_route: inbox_manual, and the block removed from missing.md. Unmatched PDFs stay in inbox/ and are listed with the reason — never guessed onto a record.

Stage 5 — Extract

Before dispatching a subagent for a paper, try the pool:

python3 scripts/pool.py reuse --run-dir <run> --wiki <root> --pmid <pmid>

matched: true with a non-null extraction means another run already extracted this exact paper. reuse has already copied that file into this run's workspace/extractions/ tagged "reused_from", and (wiki mode) re-registered every snapshot its spans cite into this run's own store — same source_id, content-addressed, so quotes verify locally exactly like a freshly extracted paper's. Skip the subagent, log the reuse.

Otherwise: one subagent per paper, opus, references/prompts/extract.md. Design, N, population, I/C, outcomes with effect + CI + direction, funding/COI, limitations, and spans with character offsets. evidence_basis is abstract_only whenever no full text was obtained.

A reused snapshot carries a register event, never fresh — the text was not retrieved in this run. C-FRESH-FETCH reports it as non-fresh accordingly; C-SNAPSHOT and C-SPAN pass normally, because the content is locally present and hash-verified. See Evidence kernel.

On stage completion, sync the pool and show the table:

python3 scripts/pool.py sync --run-dir <run>              # wiki mode
python3 scripts/registry.py promote --repo <path> --run-dir <run>   # repo mode

python3 scripts/status.py <run> --table

The table shows which papers were downloaded, in what format, and whether extraction ran — so you see corpus coverage before appraisal, including which rows were reused rather than freshly extracted. Stage 6 does not start while any row is still pending extraction.

Stage 6 — Appraise

Same reuse gate, called per paper (idempotent — this time it checks for a resolving appraisal_path). In repo mode pass --project <slug>: appraisal there is project-scoped, because risk of bias and certainty depend on the question being asked, not on the paper alone.

Otherwise one subagent per paper, opus. Tool selected by design — RoB 2 / ROBINS-I / Newcastle-Ottawa / AMSTAR-2 / QUADAS-2 / PROBAST / CASP / JBI / none — then GRADE domains. Abstract-only records are never appraised as if full text. Full routing and domain detail: Appraisal frameworks.

python3 scripts/pool.py sync --run-dir <run>
python3 scripts/registry.py appraise-promote --repo <path> --run-dir <run> --project <slug>

Stage 7 — Synthesize

Main thread only. Effect-direction tabulation, agreement and conflict with an explanation of why, certainty, gaps, and a hard-walled hypotheses section. One row per study-outcome, with precision classified rather than asserted:

Nulls are not estimated, conflicts are not averaged away, and appraisal constrains the verbs the report is allowed to use (see Downgrading claim strength).

Stage 7b — Digest

One subagent compresses the finished report (§1, §8, §9, §10, §11, §13, §15 only) into outputs/digest.md: an answer-first paragraph, a categorical outcomes table (outcome / direction / certainty / studies), and an ## Open Questions section merging gaps and hypotheses, each paired with what would resolve it. No new research, no re-derived judgement, the same GRADE wordings and the same hard wall as the source report.

This is the body that okf.py promote writes into research/reviews/<slug>.md. The full report stays linked from it as the audit trail — the digest does not replace §0–§16 for methods, PRISMA, or provenance detail.

Stage 8 — Assemble, Verify, Publish

Fixed order. Each step's output is the next step's input:

assemble.py run  →  verify.py run  →  render.py / html_report.py  →  okf.py promote --check  →  okf.py promote

• assemble.py decides which artifacts are admissible and writes outputs/result.json — the evidence ledger.
• verify.py runs the report checks plus the four kernel checks and writes outputs/verification.json.
• okf.py promote --check re-verifies integrity and writes nothing. It is mandatory before the real promote.
• Only then does promotion write concepts — and it fails closed: any failure aborts the whole promotion, never a partial bundle.

What the verifier checks

A fail makes the report provisional and blocks OKF promotion. The report is still delivered — outputs/report.md is preserved even when rendering, export, or promotion fails, and the failure is recorded in engine.log.

Report skeleton

Sixteen sections, each naming its data source. verify.py matches headings by regex, not by number, so renumbering or adding subsections is safe.

Citation is per claim, by markdown footnote keyed to a sources[].id. A claim resting on three studies carries three footnote references, not one covering footnote, and each footnote carries the appraisal verdict and evidence basis inline — which is what makes an abstract-only label survive copy-paste:

Group CBT reduced depressive symptoms at 12 weeks relative to waitlist
(SMD -0.41, 95% CI -0.68 to -0.14).[^pubmed-12345678]

[^pubmed-12345678]: Smith JA, Doe R, Muller K. Cognitive behavioral therapy for
    adolescent depression: a randomized trial. *J Example Med.* 2024;12(3):101-115.
    PMID [12345678](https://pubmed.ncbi.nlm.nih.gov/12345678/).
    DOI [10.1000/example](https://doi.org/10.1000/example).
    RoB 2: some concerns. Full text.

Guardrails And Progress

Budgets are enforced, not aspirational

max_subagents, max_parallel, max_wall_time, max_articles, max_fulltext_failures, and max_ocr_pages live under config.json's budgets. max_wall_time is seconds as a bare number, or a suffixed string (90m, 3h, 1d) — never a bare number meaning minutes.

The no-progress guard

Repeated identical tool calls, or repeated task assignment with no newly completed or blocked work, write diagnostics to engine.log, stop dispatch, and move to verification with a provisional report.

python3 scripts/corpus.py guard --run-dir <run>              # records a probe
python3 scripts/corpus.py guard --run-dir <run> --no-record  # status check only

Use --no-record for polling. Every recording call appends a probe, so checking the guard while a run is legitimately parked manufactures the very flat window it looks for. A board with nothing pending and nothing active reports idle: true — idle is not stuck.

Health alerts you should expect to see

A degraded run looks exactly like a healthy one unless someone says otherwise. Each of these is surfaced in the turn it is discovered, with the numbers:

Two rules override any instinct to keep a run looking clean. Never report a stage complete when part of it silently did not run — "10 of 25 full text" is the result, "acquisition complete" is not. And an empty result is a finding: if a query yields 7 records where hundreds were expected, the literature is thin, and the query is not quietly widened until the number looks respectable.

Progress updates

After every stage transition and at least once per batch of dispatched subagents, the agent runs status.py and posts the output. This applies to fast too — "report only" affects which artifacts are produced, not whether you can see what stage the run is in.

python3 scripts/status.py <run>            # stage, progress bar, counts
python3 scripts/status.py <run> --table    # per-paper coverage
python3 scripts/status.py <run> --missing  # blocked records only
python3 scripts/watch.py --run-dir <run>   # read-only TUI, attach to a live or finished run

The task board

Every unit of work is a record in taskboard.jsonl, and it is never hand-edited. All transitions go through the CLI, which computes inputs_hash, stamps timestamps, and appends:

python3 scripts/corpus.py task claim|complete|fail|block|list|next --stage <stage> [...]

Task ids follow <stage>:<key-kind>:<key> — extract:pmid:12345678. Completed outputs are immutable unless inputs_hash changes; failed tasks retry independently. The subagent receipt's summary is passed to task complete --summary so the one-line result lives on the board rather than only in the coordinator's context.