# Research Literature Evidence > Build an append-only, auditable path from preregistered literature searches to precisely located evidence candidates while keeping snippets, OCR, AI interpretations, self-attested human review, synthetic fixtures, and unclear rights from becoming academic or public evidence. Use for books, papers, catalogues, webpages, inscriptions, and other research sources when queries, discoveries, failures, editions, carriers, locators, excerpts, conflicts, and review gates must remain reproducible. - Skill: `lx050/research-literature-evidence` (Agent Skill, multi-file: 13 files) - Install (CLI): `npx skillmds@latest add lx050/research-literature-evidence` - Raw SKILL.md: https://api.skillmd.com/api/skills/lx050/research-literature-evidence/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Research & Search - Author: Lx050 (https://skillmd.com/u/lx050) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/lx050/research-literature-evidence --- # Research Literature Evidence Turn literature work into a reproducible research process, not a polished answer. The controller records what was planned, searched, found, excluded, inaccessible, located, quoted, inferred, contradicted, and still unverified. Release 1.2.0 has two deliberately different, immutable lanes: - `synthetic-test-only`: a fully runnable engineering lane using obviously fictional UTF-8 bytes. It proves only that the recorder, hashes, locators, reducer, and bundle verifier work. It is permanently nonacademic and nonpublic. - `real-research`: an audit lane for plans, queries, discoveries, bounded outcomes, and L0/L1 bibliographic candidates. It initializes only from an orchestrator 1.4.0 route 1.3 plus the current local route-verification report. Real carrier admission, evidence-ready cards, public excerpts, ResearchCase `SRC`, and text-structure authority remain blocked until external acquisition, provenance, rights, and trusted-human verifiers exist. An integrity pass never means that a historical claim is true. ## Required reading Read these before creating inputs: - [Input contract](references/input-contract.md) - [Output and gate contract](references/output-contract.md) - [Offline Schema catalog](references/schema-catalog.json) Use absolute paths. Inputs must be new, single-link regular UTF-8 JSON files. Never pass credentials, cookies, access tokens, private download URLs, or restricted source text in free-text fields. ## Non-negotiable evidence rules 1. Write the plan before the first query event. Event order proves only local sequence, not real-world time. 2. A search result or snippet is a `DiscoveryRecord`, never an excerpt or source claim. 3. OCR and AI may propose locators or interpretations. Their origin taint must remain; renaming a field never makes the text verbatim evidence. 4. A source is a specific work, edition, version, and carrier. Same title or URL is not identity. 5. A locator must bind exact current bytes. In the runnable synthetic lane this is a zero-based UTF-8 byte range with prefix/suffix anchors. 6. Source wording, normalization, translation, interpretation, and research conclusion are separate objects. 7. Human identity, direct inspection, rights, DOI validity, independence, and publication permission cannot be self-attested in JSON. 8. Preserve zero results, access failures, exclusions, conflicts, superseded versions, and counterevidence. Do not overwrite history. 9. Synthetic lineage is inherited from the workspace root and cannot be removed by changing a later record. 10. If a required verifier or proof is absent, return `block` or `unresolved`; never fill the gap with an AI guess. ## Workflow ### 1. Choose a lane and create immutable inputs Create a ResearchCase snapshot and a literature plan. Synthetic IDs must start with `SYN-`; real IDs must not. The plan must contain atomic evidence needs, disconfirming evidence, source classes, databases, languages, inclusion/exclusion rules, query families, and stop conditions. Use the complete orchestrator ResearchCase core shape. Every `plan.hypothesis_ids` value must exist in `case.hypotheses`. Initialize a permanent synthetic engineering workspace without route arguments: ```bash python3 scripts/literature_evidence.py init \ --workspace /absolute/new-workspace \ --workspace-id SYN-LIT-WORKSPACE-001 \ --case /absolute/case.json \ --plan /absolute/plan.json ``` For real research, obtain a current route 1.3 that proposes this Skill, then preserve the JSON emitted by the orchestrator's local `verify-route` command in a new ordinary file. The route may arrive on either of two lanes, and the workspace binds whichever one it came from: - automatic handoff: the route also selects this Skill in `next_skills`, and its typed gate is `executable: true` with reason code `bounded-real-research-logging-authorized`; - proposed behind a human gate: the route stopped with `gate_status: block`, an action of `human_review` or `stop_unresolved`, and an empty `next_skills`, and its typed gate is `executable: false` with reason code `bounded-real-research-logging-proposed-behind-human-gate`. Every capability bound is identical; only automatic execution was withdrawn, and a human chose to run this bounded audit lane anyway. Any other combination fails closed. Initialize with all four bound inputs: ```bash python3 scripts/literature_evidence.py init \ --workspace /absolute/new-real-workspace \ --workspace-id LIT-WORKSPACE-001 \ --case /absolute/research-case.json \ --plan /absolute/literature-plan.json \ --handoff-route /absolute/current-route.json \ --handoff-verification /absolute/current-route-verification.json ``` Synthetic init rejects either handoff option. Real init requires both. The real gate must use execution profile `real-research-audit-v1`; it authorizes only plan, query, discovery, bounded outcome, and real L0/L1 source-candidate logging. The workspace binds and rechecks the exact current route, verification report, case, and plan bytes on every load. A local route-verification report is reproducible policy evidence, not a signature, authenticated identity, or external timestamp. Never edit workspace JSONL files by hand. An amendment is a new event; it does not erase the initial plan. If a crash leaves a derived-view mismatch, do not edit the row. Preserve the old views and rebuild them from authoritative events: ```bash python3 scripts/literature_evidence.py rebuild-derived-views \ --workspace /absolute/workspace \ --backup /absolute/new-recovery-backup \ --report /absolute/new-recovery-report.json ``` ### 2. Record the search, including failure ```bash python3 scripts/literature_evidence.py record-query \ --workspace /absolute/workspace --record /absolute/query.json python3 scripts/literature_evidence.py record-discovery \ --workspace /absolute/workspace --record /absolute/discovery.json python3 scripts/literature_evidence.py record-outcome \ --workspace /absolute/workspace --record /absolute/outcome.json ``` For manual web/UI searching, state that the observation is human-declared. A recorded zero count supports only a bounded statement about the recorded provider, query, pages, language, time, and truncation rule. Access failure never proves absence. ### 3. Register and locate only what the lane permits In `real-research`, `register-source` may record only an L0/L1 candidate with no carrier bytes and no verified identifier or rights assertion. In `synthetic-test-only`, register the fictional carrier and add a recomputable locator and excerpt candidate: ```bash python3 scripts/literature_evidence.py register-source \ --workspace /absolute/workspace --record /absolute/source.json python3 scripts/literature_evidence.py add-locator \ --workspace /absolute/workspace --record /absolute/locator.json python3 scripts/literature_evidence.py add-excerpt-candidate \ --workspace /absolute/workspace --record /absolute/excerpt.json ``` The controller recomputes the carrier, byte range, anchors, and excerpt digest. A snippet/OCR/AI-origin candidate remains ineligible even if its text matches. ### 4. Keep candidate evidence and interpretation separate Register synthetic lineage and a publication-blocked quote policy before adding a synthetic draft card: ```bash python3 scripts/literature_evidence.py record-independence-group \ --workspace /absolute/workspace --record /absolute/group.json python3 scripts/literature_evidence.py record-quote-policy \ --workspace /absolute/workspace --record /absolute/quote-policy.json python3 scripts/literature_evidence.py add-card \ --workspace /absolute/workspace --record /absolute/card.json python3 scripts/literature_evidence.py record-interpretation \ --workspace /absolute/workspace --record /absolute/interpretation.json python3 scripts/literature_evidence.py record-conflict \ --workspace /absolute/workspace --record /absolute/conflict.json ``` `add-card` creates only a candidate. It cannot compute semantic directness or promote a claim. Use one atomic claim component per claim-fit entry and record uncovered components explicitly. ### 5. Treat human review and downstream admission as external gates `review-card`, `project-research-case`, and `bind-authority` deliberately return exit `5` in this release. A JSON field such as `actor_type: researcher`, `trusted: true`, `human-checked`, or `verified-open` is not authentication. Do not retry by changing labels. Record the block and request the missing external review, rights, acquisition, provenance, or consumer-verifier capability. ### 6. Verify before reporting ```bash python3 scripts/literature_evidence.py verify \ --workspace /absolute/workspace \ --check-files \ --report /absolute/new-verification-report.json ``` Exit `0` means the allowed integrity contract passed. Inspect every named gate in the report; publication, trusted-human, real-source admission, ResearchCase admission, and text-structure authority remain separate. A committed workspace states which build of this Skill wrote it, and is verified against that build's contract, not against the installed build's. `1.1.0` and `1.2.0` are the recognised writer versions (`STORED_SKILL_VERSION_CONTRACTS`); an unrecognised version fails closed. Two consequences: - A workspace written by another version is **read-only** here: `verify` and `export` work, every `record-*` command refuses. Builds lock different files, so appending from two of them would not be mutually exclusive. - `verify` reports the cross-version read in `proof_boundary`, naming every implementation file whose bytes this build does not hold. Those recorded provenance hashes were not re-derived from any file, so for a cross-version read `implementation_binding_valid` states only that the binding names the exact implementation file set in the fixed order. The workspace's own bound inputs are still rechecked byte for byte and any change there is still a hard failure. A workspace written by the **installed** build gets no such tolerance: its `implementation_binding` must still equal this build's own files exactly, path, hash and size, or `verify` exits `4` `current-file-drift` and every `record-*` command refuses. The recorded `path` values are compared, never opened — the comparison is against this build's own files, located from the script's own location — so a workspace cannot point verification at a FIFO to hang it or at a symlink to fake its provenance. Starting new work is unaffected: `init` still requires a route from the current orchestrator contract only. ### 7. Export only a permanently blocked synthetic inspection bundle ```bash python3 scripts/literature_evidence.py export \ --workspace /absolute/synthetic-workspace \ --profile synthetic-test \ --output /absolute/new-bundle python3 scripts/literature_evidence.py verify-bundle \ --workspace /absolute/synthetic-workspace \ --bundle /absolute/new-bundle \ --report /absolute/new-bundle-report.json ``` The verifier compares the bundle with the current source workspace, not just the bundle manifest. `public` export always blocks in 1.2.0. A synthetic inspection bundle still says `academic_use: prohibited`, `public_demo_use: prohibited`, and `publication_gate: block`. ## Exit codes | Code | Meaning | |---:|---| | `0` | Requested integrity/recording action completed within the declared lane | | `2` | Input, path, or pre-existing-output error; no workspace append | | `3` | Schema, event chain, reducer, or reference integrity failure | | `4` | Current bytes, locator, excerpt, or bundle drift | | `5` | Research, identity, rights, synthetic, admission, or publication gate blocked | A scientifically correct run may end blocked. Do not collapse codes `0` and `5` into a generic success/failure label. ## Multi-Agent handoff Give each Agent only the files and command it needs. The search Agent records plans, queries, discoveries, and failures; a source Agent proposes exact source identities; a locator Agent binds bytes; a card Agent creates candidates; an independent reviewer must use a future trusted verifier. A reflection Agent consumes verification reports, conflicts, and negative outcomes to amend the next plan. Every Agent writes its inputs, outputs, commands, and failure logs through the project run ledger. No Agent may approve its own evidence, manufacture missing metadata, erase a negative result, or reinterpret a gate block as permission.