opencode-bioresearcher 1.9.0 → 1.11.0

package/skills/bioresearcher-deep-research/SKILL.md

@@ -4,7 +4,7 @@ description: "Deep biomedical research orchestrator powered by the biomcp MCP se
 license: Apache-2.0
 compatibility: "Any Agent Skills harness (opencode, Claude Code, Codex, Cursor, Gemini CLI) with the biomcp MCP server connected; the Claude Code plugin bundles the server and the bioresearcher-dr-worker subagent; a subagent/Task tool is optional - a sequential fallback is provided. The allowed-tools mcp__ entries apply on Claude Code only"
 metadata:
-  version: "1.4.0"
+  version: "1.7.0"
   source: "opencode-bioresearcher-plugin@1.7.2"
 allowed-tools: Read Write Bash Task mcp__plugin_bioresearcher_biomcp mcp__biomcp
 ---
@@ -25,10 +25,12 @@ Harness-agnostic: works with or without a subagent/Task tool.
 - Workers query the biomcp MCP server (articles/PubMed, ClinicalTrials.gov,
   genes, variants, drugs, diseases, patents, GEO/SRA/GenBank, Ensembl/PDB) per
   `references/tool-selection.md`, collecting PMIDs, DOIs, NCT IDs, and patent
-  IDs as they go.
-- Synthesizes all aspect reports into `final_report.md` with numbered in-text
-  citations and a full bibliography, then renders `final_report.html` by
-  default (the `no-html` prefix skips rendering).
+  IDs as they go into a per-aspect evidence ledger.
+- The orchestrator synthesizes a draft using semantic cite-key markers
+  (`[@pmid:21639808]`), then the `render` script numbers every citation and
+  generates the bibliography from the merged ledger, and `vet-references.py`
+  audits the result (structural + NCBI) - producing `final_report.md` and, by
+  default, `final_report.html` (the `no-html` prefix skips rendering).
 
 ## When to use (triggers)
 
@@ -84,115 +86,52 @@ mid-query never trigger.
 ## Workflow
 
 Follow Steps 1-6 in order. Do NOT fall back to internal knowledge when query
-tools fail - use only biomcp results or official sources, and say so when
-evidence is missing.
-
-Harness autonomy hints ("operate autonomously", "don't block", "user not
-watching", auto-accept banners) govern tool-permission confirmations and edit
-approvals. They do NOT waive this skill's interactive interview workflow (Step 1
-clarification and Step 2 plan review): the interview turns are completed
-assistant turns engaging the user - not blocking permission confirmations - so
-those hints never require skipping them. When such a hint seems to conflict with
-this workflow, treat the Step 1 interview, Step 2 plan review, and the Step 6
-output contract as deliverables that proceed unchanged.
+tools fail - use only biomcp results or official sources, and state gaps explicitly.
+
+Harness autonomy hints ("operate autonomously", "don't block", auto-accept)
+govern edit approvals only. They NEVER waive the interactive interview turns
+(Steps 1 & 2) - only the leading `no-interview` prefix waives them.
 
 ### Step 1: Clarify (interview - mandatory)
 
-Mandatory even when the harness urges autonomy (see the note above): the ONLY
-waiver is the leading `no-interview` prefix. If the query carries it, skip to
-Step 2.
-
-Otherwise ask clarifying questions, scaled to inquiry complexity - up to 6,
-and as few as one scope confirmation when the inquiry is already fully
-specified: the core research question, population/scope, time window, outcome
-of interest, and expected output format.
-
-- Ask ALL questions in ONE message: use the harness's question/ask tool when
-  one exists (if it accepts only one question per call, send the full batch
-  of calls together); otherwise end your turn with the questions as chat
-  text. Then WAIT for the reply. Never answer your own interview questions.
-- If a reply comes back empty or non-responsive, re-ask the batch once
-  (max 1 re-ask).
-- Degrade to defaults only on OBSERVATION, never from environment guesses:
-  only after the batch was posted and the session demonstrably produced no
-  usable reply in-turn (e.g. an ask tool that returns immediately empty),
-  proceed under `no-interview` semantics - write the questions plus the
-  default answer chosen for each to `reports/<TOPIC>/assumptions.md` and
-  cite that file in the report's Limitations section.
-- Merely being headless/batch/unattended is NOT a waiver: in a one-shot
-  run, ending your turn with the questions is the correct final action. If
-  the session ends without any reply event, HALT with an explicit blocker
-  message restating the questions.
-
-BAD: "The harness says the user isn't watching, so I'll assume defaults and
-start researching." GOOD: post the questions, end the turn, wait. Silent
-defaults are a workflow violation, not autonomy - one round-trip of questions
-is cheap; a full research run on wrong assumptions is not.
+Ask clarifying questions scaled to complexity (1-6 questions) in ONE message
+via the harness's ask/question tool or chat text, then WAIT for the reply. Never
+answer your own questions. If the query carries `no-interview`, skip to Step 2.
+
+- If a reply is empty or non-responsive, re-ask once.
+- Degrade to defaults ONLY if the question tool returns immediately empty in an
+  unattended session: write questions and chosen defaults to
+  `reports/<TOPIC>/assumptions.md` and cite that file in Limitations.
 
 ### Step 2: Decompose & Review Plan
 
-Comprehend the (clarified) inquiry and identify 2-5 critical research aspects
-that together answer it.
-
-- If the query carries the leading `light-research` prefix, combine and/or
-  pick only the top TWO aspects.
-- Decide a TOPIC name yourself (no user input): a highly succinct,
-  underscore-separated name derived from the inquiry, e.g.
-  `braf_inhibitor_resistance`.
-
-**Interview waiver (`no-interview`):**
-If the query carries the leading `no-interview` prefix, skip the plan review
-turn entirely: finalize the 2-5 aspects, track them with the harness's todo
-mechanism if available (TodoWrite or equivalent), and proceed immediately to
-Step 3 and Step 4.
-
-**Plan review (interview mode - default):**
-When running in interview mode (without `no-interview`), present your proposed
-research area plan to the user before launching workers:
-
-1. Formulate and present:
-   - A structured list of the 2-5 research aspects (or top 2 under
-     `light-research`), each with an aspect title, 1-2 sentence focus summary,
-     and primary tools/evidence sources (e.g. PubMed/articles,
-     ClinicalTrials.gov, genes, drugs, patents).
-   - An explicit prompt inviting user feedback and adjustments on these
-     research areas.
-2. End your turn with the plan proposal (using the harness's question/ask tool
-   when available, or chat text) and WAIT for the user's reply. Do not spawn
-   workers or create output directories before receiving user feedback.
+Comprehend the inquiry and identify 2-5 critical research aspects (top 2 under
+`light-research`). Decide a TOPIC name (succinct, underscore-separated, e.g.
+`braf_inhibitor_resistance`). Each aspect's ABSTRACT defines INCLUSION and binding
+EXCLUSION criteria per `references/analysis-methods.md`.
+
+**Plan presentation budget:** keep the plan compact - one line per aspect (title,
+focus, primary tools); never paste raw ABSTRACTs into the question UI.
+
+**Plan review (default mode):**
+1. Present the 2-5 aspects to the user with tools/sources and invite feedback.
+2. End your turn (via ask tool or chat) and WAIT for the reply. Do not spawn
+   workers or create output directories before feedback.
 3. User feedback handling:
-   - **Case A (approval / "looks good" / "proceed"):** Proceed directly to
-     Step 3 and Step 4.
-   - **Case B (default feedback - modifications without re-review request):**
-     Incorporate the user's requested adjustments, additions, drops, or scope
-     changes into the research aspects immediately (strictly adhering to the
-     2-5 aspect ceiling, or top 2 under `light-research`). Then **PROCEED
-     DIRECTLY to Step 3 and Step 4. Do NOT ask for another round of
-     confirmation.**
-   - **Case C (special case - explicit re-confirmation requested):** ONLY if the
-     user explicitly asks to review or confirm the revised plan (e.g. "show me
-     the updated plan before starting" or "revise the plan and ask me again"),
-     present the updated plan in a new turn and wait for confirmation before
-     dispatching subagents (limit plan re-confirmations to at most 2 rounds).
-   - **User inquiries during review:** If the user asks a clarifying question
-     (e.g. "can we include pediatric trials?"), answer succinctly in 1-2
-     sentences, incorporate the suggested scope into the relevant aspect, and
-     proceed directly to Step 3 and Step 4 unless explicit re-confirmation was
-     demanded.
-
-**Degrade to defaults on OBSERVATION:**
-Like Step 1, degrade only after the plan was posted and the session
-demonstrably produced no usable reply in-turn (e.g. an ask tool returning
-immediately empty in unattended/headless runs): proceed under the initial
-proposed plan, record the default plan in `reports/<TOPIC>/assumptions.md`,
-and cite that file in the report's Limitations section.
-
-Track the finalized aspect list with the harness's todo mechanism if available
-(TodoWrite or equivalent); otherwise keep it in working memory.
+   - **Approval / "proceed":** Proceed directly to Step 3 and Step 4.
+   - **Feedback / modifications:** Incorporate adjustments immediately and
+     PROCEED DIRECTLY to Step 3 and Step 4. Do NOT ask for another confirmation.
+   - **Explicit re-confirmation requested:** Only if the user explicitly asks to
+     review the revised plan, present it in a new turn (max 2 rounds).
+4. **Waiver / Degrade:** Skip plan review turn if query has `no-interview`, or
+   degrade per Step 1 rules if unattended (record plan in `assumptions.md`).
+
+Track finalized aspects in the harness's todo tool (TodoWrite or equivalent).
 
 ### Step 3: Create the output directory
 
-Write a placeholder file to `reports/<TOPIC>/.gitkeep`. The write tool
+Write the durable research plan to `reports/<TOPIC>/plan.md` (aspect list,
+each aspect's ABSTRACT with boundaries, research items). The Write tool
 auto-creates parent directories - do NOT use bash mkdir for this.
 
 ### Step 4: Research each aspect
@@ -204,6 +143,13 @@ run the sequential tier below without fabrication - evidence gathering is
 unavailable until the server is wired (run the `bioresearcher-onboard`
 skill or see Prerequisites).
 
+**Tier dispatch hierarchy:** When a subagent tool (`task` or `Task`) is
+available in the harness, parallel worker dispatch (Tier A or Tier B) is
+MANDATORY to maintain research parallelism and isolated worker contexts.
+Subagents inherit all configured tools (biomcp, shell, filesystem) automatically;
+do NOT dispatch exploratory probe tasks to test tool access.
+Tier C is strictly a degraded fallback when no subagent tool exists.
+
 **Tier A - dedicated worker subagent (preferred when available):** if the
 harness offers the `bioresearcher-dr-worker` subagent type (installed with
 the bioresearcher Claude Code plugin; scoped name
@@ -214,11 +160,12 @@ worker reads `references/worker-protocol.md`, `references/tool-selection.md`,
 and `references/citations.md` itself at startup.
 
 **Tier B - generic subagent/Task tool:** assign each research aspect to one
-worker subagent, launched in parallel in batches of up to 5. Build each worker
-prompt from the template below. Inline into the prompt (workers may lack
-skill access): the worker rules, the per-domain tool cheatsheet from
-`references/tool-selection.md`, and the citation format summary from
-`references/citations.md`.
+  worker subagent, launched in parallel in batches of up to 5. Build each worker
+  prompt from the template below. Inline into the prompt (workers may lack
+  skill access): the worker rules, the per-domain tool cheatsheet from
+  `references/tool-selection.md`, the cite-key marker summary from
+  `references/citations.md`, and the evidence-verification discipline from
+  `references/analysis-methods.md`.
 
 Prompt template (Tiers A and B):
 
@@ -226,162 +173,183 @@ Prompt template (Tiers A and B):
 TOPIC: <TOPIC>
 YOUR RESEARCH FOCUS: <RESEARCH-ASPECT>
 DESCRIPTION: <ABSTRACT>
+SKILL_DIR: <absolute path to this skill's directory>  # Tier B only; a literal path string workers substitute into commands - NOT an env var
+EXECUTION RULE: Do NOT read or inspect evidence-ledger.py or other skill scripts; all schemas and commands are fully specified here.
 ```
 
-ABSTRACT is <200 words describing the exact focus and a list of detailed
-research items.
+ABSTRACT is <200 words describing the exact focus, a list of detailed
+research items, and the aspect's inclusion definition + binding exclusion
+criteria (negative examples welcome). Resolve `<skill_dir>`/`SKILL_DIR` to
+the absolute path before dispatch, substituting it into every inlined
+`<SKILL_DIR>` so Tier B workers never see a placeholder (both spellings
+denote the same path; a path the worker cannot resolve is a tool the worker
+does not have). Relay numeric caps from the user or plan into worker prompts
+VERBATIM - they are binding, never loosened in translation.
 
 Record finished workers via the todo list. If subagents are stuck without
 progress for too long, prompt the user: "If subagents are stuck without
-progress for too long, interrupt and ask me to resume work." Restart failed
-workers as needed (retry <= 3 per worker).
-
-**Tier C - sequential (no subagent tool):**
-
-Process aspects one at a time in the main conversation. For each aspect, apply
-the same worker rules from `references/worker-protocol.md` (tool selection per
-`references/tool-selection.md`, citation discipline and the evidence ledger per
-`references/citations.md` and worker-protocol rule 8, retry <= 3, no
-re-delegation) and write the same per-aspect files (report + ledger). State
-which aspect is being worked on before starting each one.
-
-**All tiers, per aspect:**
-
-- Query biomcp tools per `references/tool-selection.md`; filter at the source
-  (specific terms, `limit`, `sections`) rather than retrieving broadly.
-- Make MCP calls sequentially, not concurrently.
-- Collect identifiers for every source used: PMIDs/PMCIDs/DOIs (articles),
-  NCT IDs (trials), patent IDs, accessions (GEO/SRA), database IDs
-  (genes/drugs/variants).
-- Maintain the evidence ledger `reports/<TOPIC>/evidence/<ASPECT>.jsonl` per
-  `references/worker-protocol.md` rule 8: after EACH biomcp call, append one
-  record per potentially-citable source with fields copied verbatim from the
-  tool result, batching all records from one tool result into a single
-  `evidence-ledger.py add` call (never one call per record, never per-record
-  scratch files); title-less records (LitSense hints) are enriched via
-  `article_get(pmid)` before citing.
-- Write findings to `reports/<TOPIC>/<ASPECT>.md` (underscore-separated
-  ASPECT name) with in-text citations [1], [2], ... and a bibliography whose
-  entries are copied from the ledger.
-
-### Step 5: Synthesize
+progress for too long, interrupt and ask me to resume work."
+
+**Tier C - sequential (strictly when no subagent tool exists):**
+If the harness has no subagent tool (`task` / `Task`), process aspects one at a
+time in the main conversation per `references/worker-protocol.md`.
+
+**Worker completion gate (all tiers):**
+When each worker finishes, before marking the aspect complete in the todo list, run:
+```bash
+python3 <skill_dir>/scripts/evidence-ledger.py check \
+  reports/<TOPIC>/evidence/<ASPECT>.jsonl \
+  --markers reports/<TOPIC>/<ASPECT>.md
+```
+- Exit 0: mark aspect complete in todo list.
+- Exit 1:
+  - Trivial syntax/quarantine error in ledger: fix directly using Edit/Write.
+  - Missing records or unresolved markers: dispatch a top-up remediation worker
+    with the check diagnostic output per `references/worker-protocol.md` (max 2
+    remediation retries). Never guess or re-point IDs.
+  - If retries fail: strip the unresolved marker, qualify the claim in the
+    report with a caution note, log the failed ID in `## Evidence Gaps` and
+    `reports/<TOPIC>/assumptions.md`, and proceed.
+- Without Bash/Python access: re-read the aspect ledger and confirm every marker
+  in `<ASPECT>.md` resolves to a ledger record before marking complete.
+
+**Worker execution rules (summary):**
+Query biomcp sequentially per `references/tool-selection.md`, append records to
+`reports/<TOPIC>/evidence/<ASPECT>.jsonl` after each search using `evidence-ledger.py add`
+(never invent values), and write findings with `[@key]` markers to `reports/<TOPIC>/<ASPECT>.md`
+(no bibliography; PDB entries follow the dual-entity rule in `references/worker-protocol.md`).
+See `references/worker-protocol.md` for full schemas.
+
+### Step 5: Synthesize (cite-key draft)
 
 Read all per-aspect reports. Summarize findings into a succinct, accurate
 final report addressing the user's inquiry, following the mandatory 6-section
 structure in `references/report-template.md` (Executive Summary, Data Sources,
-Analysis Methodology, Findings, Limitations, References) with full
-bibliography. Reconcile conflicting findings across aspects explicitly rather
-than silently dropping one side. Write the synthesized draft to
-`reports/<TOPIC>/final_report.md`.
+Analysis Methodology, Findings, Limitations, References - the References
+section itself is generated later by `render`). Reconcile conflicting findings
+across aspects explicitly rather than silently dropping one side.
+
+Write the synthesized draft to `reports/<TOPIC>/final_report.draft.md` citing
+sources with the SAME semantic cite-key markers the workers used
+(`[@pmid:21639808]`, `[@nct:NCT04280705]`, `[@chembl:CHEMBL1229517]`, groups
+`[@a; @b]`). NEVER hand-number citations, never hand-write a References
+section, and never write ad-hoc scripts to assemble the report - numbering and
+bibliography come from `render` (Step 5b), which is the single numbering
+authority.
+
+When merging aspects, apply the evidence-verification discipline
+(`references/analysis-methods.md`): rules 3-5 gate framework adherence -
+findings that cannot be placed in the plan's framework go to Limitations with
+a note, never into improvised categories; re-check rules 1-2 whenever
+synthesis rewords a claim or transcribes a number from an aspect report.
 
 ### Step 5a: Merge + verify the evidence ledger
 
-Before composing the References section of `final_report.md`, consolidate
-and verify the per-aspect ledgers with the evidence-ledger script (fail-safe: network failure never
-blocks the report):
+Consolidate and verify the per-aspect ledgers with the evidence-ledger script
+(fail-safe: network failure never blocks the report):
 
 ```bash
 python3 <skill_dir>/scripts/evidence-ledger.py merge \
   -o reports/<TOPIC>/evidence/sources.jsonl 'reports/<TOPIC>/evidence/*.jsonl'
 python3 <skill_dir>/scripts/evidence-ledger.py verify \
   reports/<TOPIC>/evidence/sources.jsonl --apply
-python3 <skill_dir>/scripts/evidence-ledger.py keys \
-  reports/<TOPIC>/evidence/sources.jsonl
-python3 <skill_dir>/scripts/evidence-ledger.py bib \
-  reports/<TOPIC>/evidence/sources.jsonl --keys <comma-separated keys in citation order>
 ```
 
-- `merge` unions the per-aspect JSONLs (its own output and `_`-prefixed
-  quarantine files are excluded automatically; malformed lines are
-  quarantined to `evidence/_invalid.jsonl`).
+- `merge` unions the per-aspect JSONLs (malformed lines quarantined to `_invalid.jsonl`).
 - `verify` cross-checks article records against NCBI esummary and backfills
-  ONLY missing fields (epub-ahead-of-print records legitimately stay
-  locator-less - render them without a volume/pages slot). It also sets
-  titles on title-less records (e.g. LitSense hints the worker could not
-  enrich).
-- Compose the References section of `final_report.md` by copying the `bib`
-  output - do not re-type or paraphrase entries. Use the `keys` output (all
-  ledger keys, sorted) to pick the citation-ordered `--keys` list for `bib`.
-  When the script is unreachable (harnesses without filesystem access to
-  `<skill_dir>`), re-read `reports/<TOPIC>/evidence/sources.jsonl` and transcribe
-  entries from the records directly.
-
-### Step 5b: Vet references (independent NCBI verification)
-
-After synthesizing `reports/<TOPIC>/final_report.md`, run the independent
-reference vetting script as the FINAL safety net - after the Step 5a ledger
-verification it is expected to be a near-no-op, but still run it:
+  missing fields (including authors, title, journal, locators). Records with
+  conflicting titles or DOIs are flagged with warnings and left unverified.
+  `--apply` mutates the ledger file in place; review changes via script output.
+
+### Step 5b: Render the final report (numbering authority)
+
+```bash
+python3 <skill_dir>/scripts/evidence-ledger.py render \
+  reports/<TOPIC>/evidence/sources.jsonl reports/<TOPIC>/final_report.draft.md \
+  -o reports/<TOPIC>/final_report.md
+```
+
+`render` numbers every cite-key marker by order of first appearance
+(range-compressing groups), rewrites the markers in place, and appends the
+References section generated from the merged ledger. Hard-fail contract
+(exit 1, `final_report.md` NOT written): an unresolved citation key (with
+did-you-mean suggestions), any record that would render `[MISSING ...]`, or
+re-rendering an already-rendered document. On failure: fix the draft or the
+ledger and re-render - citation numbers and bibliography entries are NEVER
+edited by hand.
+
+When the script is unreachable (harnesses without filesystem access to
+`<skill_dir>`), deliver `final_report.draft.md` itself as the report artifact
+(cite-keys stay readable and resolvable) and state the gap in the final
+summary and Limitations - never hand-number citations as a workaround.
+
+### Step 5c: Vet references (structural audit + independent NCBI verification)
+
+After `final_report.md` is rendered, run the independent vetting script as the
+FINAL safety net:
 
 ```bash
 python3 <skill_dir>/scripts/vet-references.py reports/<TOPIC>/final_report.md --apply
 ```
 
-- **Fail-safe contract**: on API timeout, rate-limiting, or network failure, the
-  script exits 0 and keeps pre-vetting citations unchanged. Non-PMID citations
-  (clinical trials, patents, genes, web URLs) are automatically preserved.
-- If the script is unreachable (in harnesses without filesystem access to
-  `<skill_dir>`), proceed directly to Step 6 without blocking.
-- When run without `--apply`, the script outputs clean correction suggestions
-  for manual inspection before final HTML rendering.
+- Layer 1 (offline, hard exit 1): in-text citations contiguous [1]..[N],
+  numbered by order of appearance, N == bibliography entry count, zero
+  `[MISSING ...]`/None/undefined placeholders.
+- Layer 2 (fail-safe): on API timeout, rate-limiting, or network failure the
+  script exits 0 and keeps pre-vetting citations unchanged. Non-PMID
+  citations (clinical trials, patents, genes, web URLs) are preserved.
+- Exit 1 means STOP: repair the draft or ledger, re-render, and re-vet.
+- Warning disposition: every warning emitted during `verify` or `vet-references`
+  must be resolved (fixed in draft/ledger and re-rendered) or explicitly
+  justified in Limitations before Step 6.
+- `--apply` mutates `final_report.md` in place; review printed `- OLD:` / `+ NEW:`
+  updates (or use `--diff` for unified diffs).
+- If the script is unreachable, proceed to Step 6 with the rendered report and
+  state the gap in the final summary.
 
 ### Step 6: Write final report + HTML
 
 - Ensure `reports/<TOPIC>/final_report.md` is finalized and vetted.
-- Then render `reports/<TOPIC>/final_report.html` - ALWAYS by default,
-  unless the query carries the leading `no-html` prefix or the user
-  explicitly declined HTML. The markdown report is the complete deliverable;
-  HTML is only a rendering, so never block finishing the session on it.
-
-  Replace `<skill_dir>` with the full path to this skill's directory
-  (`${CLAUDE_PLUGIN_ROOT}/skills/bioresearcher-deep-research` on Claude Code
-  plugin installs; in harnesses that inject SKILL.md without filesystem
-  access the script is unreachable - go straight to the gap step below).
-  Run from the working directory containing `reports/<TOPIC>/` and anchor
-  the output path to the `final_report.md` location:
+- Then render `reports/<TOPIC>/final_report.html` (always by default, unless
+  `no-html` prefix was passed or user explicitly declined HTML).
+  The markdown report is the deliverable; HTML is only a rendering.
+
+  Anchor the output path to the `final_report.md` location:
 
   ```bash
   uv run --with markdown python <skill_dir>/scripts/markdown-to-html.py \
     reports/<TOPIC>/final_report.md -o reports/<TOPIC>/final_report.html
   ```
 
-  Conversion ladder - attempt in order; a rung fails if its tool is missing,
-  its command exits non-zero, or execution is denied; one attempt per rung,
-  then fall through:
-
+  Conversion ladder (attempt in order; fall through on failure):
   1. `uv` on PATH: the command above.
-  2. `python3 -c "import markdown"` succeeds: run
-     `python3 <skill_dir>/scripts/markdown-to-html.py` with the same args.
-  3. `pandoc` on PATH: `pandoc reports/<TOPIC>/final_report.md -o
-     reports/<TOPIC>/final_report.html --standalone` (its styling differs
-     from the script's GitHub-like CSS - that is not a failure).
-  4. No rung succeeded: keep markdown-only and state the gap explicitly in
-     the final summary (the reason + the `bioresearcher-python-setup-uv`
-     skill as remediation).
-
-  Never install converters into the environment (no apt/pip/npm installs);
-  `uv run --with` ephemeral overlays are the sanctioned exception. After a
-  successful rung, verify `final_report.html` exists and is non-empty before
-  declaring success. Do NOT read the full markdown into memory for the
-  conversion - pass the file path. The final summary must name which
-  artifacts exist and, when HTML is absent, why.
+  2. `python3 -c "import markdown"` succeeds: run `python3 <skill_dir>/scripts/markdown-to-html.py reports/<TOPIC>/final_report.md -o reports/<TOPIC>/final_report.html`.
+  3. `pandoc` on PATH: `pandoc reports/<TOPIC>/final_report.md -o reports/<TOPIC>/final_report.html --standalone`.
+  4. None succeeded: keep markdown-only; state reason in summary and Limitations.
+
+  Never run apt/pip/npm installs; `uv run --with` ephemeral overlays are the
+  sanctioned exception. Verify `final_report.html` exists and is non-empty before
+  declaring success.
 
 ## Output layout
 
 ```
 reports/<TOPIC>/
-├── .gitkeep
+├── plan.md                # durable research plan (Step 3; boundaries live here)
 ├── evidence/
 │   ├── <aspect_1>.jsonl    # per-aspect evidence ledger (worker-written)
 │   ├── <aspect_2>.jsonl
 │   ├── ...
 │   ├── _invalid.jsonl      # merge quarantine (only when malformed lines occur)
 │   └── sources.jsonl       # merged + verified ledger (Step 5a output)
-├── <aspect_1>.md          # per-aspect research notes + citations
-├── <aspect_2>.md
+├── <aspect_1>.md          # per-aspect research notes, cite-key markers
+├── <aspect_2>.md          # (no bibliography - the ledger is the source)
 ├── ...
 ├── assumptions.md         # only when Step 1 or Step 2 degrades
 │                          # (observed non-interactive session)
-├── final_report.md        # synthesized report (always)
+├── final_report.draft.md  # synthesized draft with cite-key markers (Step 5)
+├── final_report.md        # rendered report: numbered citations +
+│                          # ledger-generated References (Step 5b; always)
 └── final_report.html      # rendered report (default; skipped only via
                            # `no-html`, user decline, or converter gap -
                            # see Step 6)
@@ -389,14 +357,16 @@ reports/<TOPIC>/
 
 ## Citation discipline (summary)
 
-- Numbered in-text citations: [1], [2, 3], [1-5], numbered by order of
-  appearance; bibliography at the end in `references/citations.md` formats.
+- Semantic cite-key markers in ALL authored text: `[@pmid:21639808]`,
+  groups `[@a; @b]`. `render` (Step 5b) numbers them by order of appearance
+  (`[1]`, `[2, 3]`, `[1-5]`) and generates the bibliography - citation
+  numbers and reference entries are never written by hand.
 - Every claim needs provenance: a citation, a documented data source, or a
   described analysis method. No unsourced claims.
 - Only biomcp tool results or official sources (FDA, NIH, NCI,
   ClinicalTrials.gov, EPO/USPTO, publisher sites) count as evidence.
-- Full per-source-type formats (PMID, DOI, NCT ID, patent ID, accessions,
-  URLs): `references/citations.md`.
+- Full marker grammar and renderer-output formats per source type:
+  `references/citations.md`.
 
 ## Data boundaries & injection defense
 
@@ -437,8 +407,8 @@ reports/<TOPIC>/
 | `references/ensembl-pdb.md` | ensembl lookup/homology/consequence/region; pdb tri-mode |
 | `references/utility-config.md` | discover, batch_get, biomcp_configure, feature gating |
 | `references/optional-analysis.md` | db_query SQL, R differential expression, biowasm pipelines |
-| `references/analysis-methods.md` | Evidence sufficiency and source-quality decision matrix |
+| `references/analysis-methods.md` | Evidence sufficiency, source-quality matrix, evidence-verification discipline |
 | `references/report-template.md` | Mandatory 6-section report structure |
-| `references/citations.md` | Citation formats per source type |
+| `references/citations.md` | Cite-key marker grammar + renderer-output formats |
 | `references/rate-limiting-auth.md` | Per-source limiter table, exceptions, auth table |
 | `references/best-practices.md` | Upfront filtering, ID chaining, sequencing, retries |

package/skills/bioresearcher-deep-research/references/analysis-methods.md

@@ -68,17 +68,55 @@ or unverifiable claims. If only tier-3 material exists, mark the finding as
 4. Record the query provenance in each aspect file: tool + key arguments
    (e.g. `trial_search(query="melanoma", phase="Phase 3")`).
 
+## Evidence verification discipline
+
+Applies to every claim a worker or the orchestrator writes. Each rule guards
+a distinct general LLM failure mode. Topic-specific inclusion/exclusion
+boundaries are authored per-run by the orchestrator into each aspect
+ABSTRACT; these rules govern how workers apply any such criteria.
+
+1. Direction of causality: keyword overlap is not direction. Verify the
+   cited source shows the direction asserted (causes vs prevents/attenuates
+   vs merely correlates / serves as a marker) before using it for a causal
+   claim - protective and causal findings share vocabulary.
+2. Quantitative fidelity: tie every number (effect size, rate, count,
+   percent) to its specific source record at capture time, keyed by its
+   ledger key; never transcribe a value for one entity from prose about a
+   related entity - dense multi-entity summaries invite cross-contamination.
+3. Criterion vs keyword: matching the search terms is not satisfying the
+   research criterion. Check the source shows the entity meets the aspect's
+   inclusion definition; exclusion criteria in the plan are binding, and
+   keyword-matching candidates that fail them are noted as excluded, never
+   admitted to boost yield.
+4. Axis discipline: when the plan classifies findings along an axis, every
+   admitted finding must genuinely instantiate that axis; observations of a
+   different kind attach as secondary attributes, never as improvised
+   categories (e.g. an organism-level endpoint vs a molecular mechanism in
+   a mechanistic survey, or a legal-claim scope vs a technical feature in a
+   patent analysis). New categories are a plan change (orchestrator +
+   user), not a per-finding decision.
+5. Primary vs downstream: when attributing an effect to a mechanism, verify
+   the source establishes it as the initiating/primary cause rather than a
+   downstream consequence or a late-stage marker of an upstream process -
+   cascades share endpoints, so late-stage observations do not localize
+   origins.
+
 ## Synthesis rules (orchestrator)
 
 1. Read ALL aspect files before writing the final report.
 2. Structure findings by research question, not by aspect file order, when
    the aspects overlap.
-3. Re-number citations across aspects into one bibliography for
-   final_report.md.
+3. Cite with the workers' semantic cite-key markers in
+   `final_report.draft.md`; numbering and the bibliography come from
+   `render` (SKILL.md Step 5b) - never hand-number.
 4. Contradictions between aspects: present both with sources and, if
    unresolvable, list under Limitations.
 5. Confidence marking: state High/Medium/Low confidence per key finding
    based on source count and tier.
+6. Apply the evidence-verification discipline at merge time: rules 3-5 gate
+   framework adherence (unplaceable findings go to Limitations, never into
+   improvised categories); re-check rules 1-2 whenever synthesis rewords a
+   claim or transcribes a number from an aspect report.
 
 ## Failure modes
 

package/skills/bioresearcher-deep-research/references/best-practices.md

@@ -97,9 +97,9 @@ sessions rot the context and garble titles, years, and locators.
   missing fields are null, never invented).
 - Title-less hint records (LitSense) get enriched via `article_get(pmid)`
   before they may be cited.
-- Write the bibliography by RE-READING the ledger and copying fields - the
-  ledger is the single source of truth for every References entry; the
-  orchestrator merges + verifies it at Step 5a before the final report.
+- Cite with `[@key]` markers; bibliography entries are GENERATED by
+  `evidence-ledger.py render` from the merged ledger (Step 5b) - never
+  hand-copied, hand-numbered, or hand-composed.
 
 ## 9. Data validation before writing
 
@@ -114,5 +114,5 @@ correct), arrays non-empty, dates plausible, and values in sane ranges.
 - [ ] IDs chained via tool cross-links, not re-searched
 - [ ] Calls sequential; no sleep timers (except HPA/GEO-download exceptions)
 - [ ] Retries capped at 3; gaps recorded
-- [ ] Evidence ledger updated after each call; bibliography copied from it
-- [ ] Findings + identifiers written to the aspect file
+- [ ] Evidence ledger updated after each call and passing `check --markers <aspect>.md` (exit 0; Tier A no Bash: re-read the ledger and match the markers manually)
+- [ ] Findings + `[@key]` cite markers written to the aspect file