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
• Output and gate contract
• Offline Schema catalog

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:

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:

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:

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

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:

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:

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

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

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.