research-scan AGENTS.md

AGENTS.md — research-scan

Operating doctrine for this repo. Spec of record: research-scan-v1-spec.md — read the relevant section before changing behaviour it defines. Section references below (§9, §10.4) are to it.

Vocabulary

• run — one scan. A directory research/scans/<YYYY-MM-DD>-<slug>/ holding every stage's file, relative to the process's cwd: the repo for a local scan, $RESEARCH_SCAN_MCP_DATA/<scan_id>/ for one driven through the MCP adapter.
• cid — stable candidate id: first 12 hex of sha1 of the primary identifier, in the priority order doi > arxiv > pmid > norm(title)+year (§8.2). The join key across every file.
• origin — one discovery path that found a candidate (query, references, citations, recommendations). A paper keeps every origin it earns; origin count is a ranking signal.
• in-window / outside-window — inside the publication window, or an expansion reference from before it. Out-of-window papers are tagged, never dropped, and fill the foundational slots.
• [A] stage / [C] stage — a stage the agent performs under a rubric, versus one the CLI performs deterministically. plan, screen, rerank are [A]; everything else is [C].
• verified / flagged — a packet whose DOI resolved and whose title, year and first author match the live record, versus one kept with mismatches[] and an [UNVERIFIED] marker. Never silent.
• purpose — build | research | orient, declared on the brief's Purpose: line or inferred by the planner and written into the first sentence of brief_summary. Decides what counts as impact: which sub_criteria set is derived, what why_it_matters must argue, what screening rewards, and how the judge reads relevance. Not a schema field — it lives in prose, on purpose.
• profile — quick | standard | deep, chosen at init and recorded in manifest.defaults. Sets per-query depth, the pool cap, the out-of-window total for the run, and whether the gap round runs. Flags still override it.
• gap round — V1.1's one extra retrieval round, aimed by coverage.json at the sub-criteria round 1 covered thinnest. queries.json.round2 holds its queries, rNN/xrNN its batches. It runs exactly once; "round 1 / round 2" already means the screening passes, hence the name.
• slice — S0…S6 in §15. One slice = one commit = one demoable gate.