opencode-bioresearcher 1.9.0 → 1.10.0

package/skills/bioresearcher-deep-research/references/report-template.md

@@ -45,7 +45,8 @@ Key findings:
 [Generalizability: where findings apply and where they may not]
 
   ## References
-[Numbered bibliography in references/citations.md format, ordered by first appearance]
+[GENERATED by render from the merged ledger - numbered by first appearance;
+authored drafts end before this section]
 ```
 
 ## Per-aspect file structure (lighter)
@@ -56,25 +57,25 @@ Key findings:
 Scope: [1 paragraph from the worker ABSTRACT]
 
   ## Findings
-[Findings with in-text citations [1], [2, 3]]
+[Findings with cite-key markers [@pmid:...]; no bibliography - the ledger is
+the source of truth for citations]
 
   ## Tool / Query Log
 [tool + key arguments, e.g. article_search(query="...", dateRange="2021-01-01/", limit=15)]
 
   ## Evidence Gaps
 [queries that failed after retries, with reasons]
-
-  ## References
-[numbered bibliography]
 ```
 
 ## Citation placement rules
 
-- In-text: [1] single; [2, 3] list; [1-5] range - numbered by ORDER OF
-  APPEARANCE across the document.
+- Authored text uses semantic cite-key markers `[@pmid:...]`, groups
+  `[@a; @b]`; `render` (SKILL.md Step 5b) numbers them by ORDER OF
+  APPEARANCE across the document and range-compresses groups.
 - The Executive Summary cites only the most critical sources.
-- Every table row with a number has a Source column.
-- Bibliography is ordered by number, not alphabetized.
+- Every table row with a number has a Source column (cite-key markers).
+- The References section is generated by `render` from the merged ledger and
+  ordered by number, not alphabetized.
 
 ## Provenance standard
 
@@ -100,15 +101,16 @@ combination [4]."
 
 - [ ] All six sections present, in order
 - [ ] Every claim has provenance (citation / source / method)
-- [ ] All in-text [N] present in References; no orphan references
+- [ ] Draft authored with cite-key markers; `render` exited 0 (all keys
+      resolved, no [MISSING ...] entries)
+- [ ] `vet-references.py` structural audit PASS (contiguous [1]..[N], N ==
+      bibliography count, no placeholders)
 - [ ] Identifiers included in references (PMIDs, DOIs, NCT IDs, patent IDs, accessions)
 - [ ] Access dates for web/official-site sources
 - [ ] Limitations honest about gaps and auth-gated tools not used
-- [ ] Findings re-numbered into one bibliography in final_report.md
-- [ ] References vetted against NCBI via vet-references.py (volume, issue, pages backfilled)
-- [ ] References generated from evidence/sources.jsonl (ledger-first: every
-      entry copied from a ledger record - worker-protocol rule 8, Step 5a)
 - [ ] Conflicting findings surfaced, not silently dropped
+- [ ] Findings obey the plan's inclusion/exclusion boundaries and the
+      evidence-verification discipline (analysis-methods.md)
 
 ## Common mistakes
 

package/skills/bioresearcher-deep-research/references/worker-protocol.md

@@ -17,35 +17,45 @@ clarification and plan review are exclusively the orchestrator's domain (SKILL.m
 TOPIC: <TOPIC>
 YOUR RESEARCH FOCUS: <RESEARCH-ASPECT>
 DESCRIPTION: <ABSTRACT>
+SKILL_DIR: <absolute skill dir>   # Tier B only; resolve before dispatch
 ```
 
-- ABSTRACT: <200 words describing the exact focus of the aspect and a list of
-  detailed research items to investigate.
+- ABSTRACT: <200 words describing the exact focus, a list of detailed
+  research items to investigate, and the aspect's inclusion definition +
+  binding exclusion criteria (negative examples welcome). Numeric caps
+  inside it (source limits, call budgets) are binding on the worker.
 - Tier B (generic subagent): the orchestrator should ALSO inline into the
   prompt the Worker Rules below, the per-domain tool cheatsheet from
-  `references/tool-selection.md`, and the citation format summary from
-  `references/citations.md` - generic subagents may not have access to this
-  skill's files.
+  `references/tool-selection.md`, the cite-key marker summary from
+  `references/citations.md`, and the evidence-verification discipline from
+  `references/analysis-methods.md` - generic subagents may not have access
+  to this skill's files. The template's `SKILL_DIR` line carries the
+  resolved absolute script path.
 - Tier A (dedicated `bioresearcher-dr-worker` plugin subagent): the worker
-  reads this file plus `references/tool-selection.md` and
-  `references/citations.md` itself at startup (via
-  `${CLAUDE_PLUGIN_ROOT}`); the orchestrator sends ONLY the filled-in
-  template below.
+  reads this file plus `references/tool-selection.md`,
+  `references/citations.md`, and `references/analysis-methods.md` itself at
+  startup (via `${CLAUDE_PLUGIN_ROOT}`); the orchestrator sends ONLY the
+  filled-in template below.
 
 ## File protocol
 
-- Output files (exactly TWO):
+- Output files (exactly TWO - together they are the self-contained
+  deliverable for the aspect):
   - `reports/<TOPIC>/<YOUR-FOCUS>.md` — the aspect report, where `<YOUR-FOCUS>`
     is the underscore-separated aspect name (e.g. `clinical_landscape.md`).
   - `reports/<TOPIC>/evidence/<YOUR-FOCUS>.jsonl` — the evidence ledger, one
-    JSON record per potentially-citable source (see Worker rule 8).
+    JSON record per potentially-citable source (see Worker rule 8). The
+    ledger supplies every bibliography entry later; the pair
+    (report + ledger) must be understandable without any other context.
 - The write tool auto-creates parent directories - never use bash mkdir.
-- The report file must be self-contained: a reader should understand the
-  findings, the tools/queries used, and the sources cited without any other
-  context.
 - Report file structure: title, one-paragraph scope summary, findings with
-  in-text citations, tool/query log (which biomcp tools + key argument
-  values), and a full bibliography.
+  cite-key markers, tool/query log (which biomcp tools + key argument
+  values), and explicit evidence gaps. No bibliography section - the
+  orchestrator's `render` step generates numbering and References from the
+  ledger.
+- The ABSTRACT the orchestrator sends you defines the aspect's inclusion
+  definition and binding exclusion criteria; apply them per
+  `references/analysis-methods.md` (criterion vs keyword).
 
 ## Worker rules
 
@@ -60,9 +70,11 @@ DESCRIPTION: <ABSTRACT>
    and GEO supplementary downloads, which are unthrottled - space those out.
 4. No internal knowledge: use only biomcp tool results or official sources.
    If evidence is missing after retries, say so explicitly in the report.
-5. Citations: every claim gets [N] references; keep a numbered bibliography in
-   `references/citations.md` format. Capture identifiers as you go: PMIDs,
-  PMCIDs, DOIs, NCT IDs, patent IDs, GEO/SRA accessions, database IDs.
+5. Citations: every claim gets a semantic cite-key marker - `[@pmid:21639808]`,
+   groups `[@pmid:a; @nct:NCT00000000]` - using the keys the ledger actually
+   derived (the `add` banner echoes them). Capture identifiers as you go:
+   PMIDs, PMCIDs, DOIs, NCT IDs, patent IDs, GEO/SRA accessions, database IDs.
+   Never hand-number citations and never write a bibliography.
 6. Retry logic: if a query fails, wait a few seconds, retry with a simpler
    query; at most 3 attempts per query before recording the gap and moving on.
 7. Writing: succinct, accurate, professional - academic standard.
@@ -103,19 +115,53 @@ DESCRIPTION: <ABSTRACT>
       take the standard retry ladder (rule 6), then leave the record in the
       ledger with a gap note in the aspect file - the orchestrator's verify
       step backfills what it can.
-    - With Bash available: append with
-      `python3 <skill_dir>/scripts/evidence-ledger.py add <file> --stdin`,
-      passing a JSON ARRAY of the batch's records (a heredoc works well), or
-      equivalently `add <file> @<batch.json>` with an array file. Both
-      validate, normalize, and accept every record in one call. A single
-      inline `'<record JSON>'` argument remains fine for one-off records.
-      Do NOT issue one `add` per record and do NOT write per-record scratch
-      files first - every append is a tool call (an LLM turn), so batch per
-      search result. Without Bash: write raw JSONL lines with the Write
-      tool; the orchestrator's merge validates them.
-    - BEFORE writing the bibliography, RE-READ your ledger file; compose
-      every References entry by COPYING ledger fields. A bibliography entry
-      must not contain any field absent from the ledger.
+    - With Bash available (the orchestrator provides `SKILL_DIR` in the
+      prompt): append with
+      `python3 <SKILL_DIR>/scripts/evidence-ledger.py add <file> --stdin`,
+      substituting the SKILL_DIR value from your prompt LITERALLY - it is a
+      path string, NOT an environment variable (`$SKILL_DIR` in a shell
+      resolves to nothing and breaks the call). Pass a JSON ARRAY of the
+      batch's records (a heredoc works well), or equivalently
+      `add <file> @<batch.json>` with an array file. Both validate,
+      normalize, and accept every record in one call, and the banner echoes
+      the derived canonical keys - cite those keys. Re-adding the same key
+      MERGES fill-only (never overwrites a non-null value): later adds for
+      the same source are safe and expected (e.g. enriching a record after a
+      `_get` call), and a key that lives only in another aspect's ledger is
+      remedied by re-adding the record to your OWN ledger. Do NOT issue one
+      `add` per record and do NOT write per-record scratch files first -
+      every append is a tool call (an LLM turn), so batch per search result.
+      `retrieved_at` carries the real UTC time of the call (e.g.
+      `date -u +%Y-%m-%dT%H:%M:%SZ`) - never a rounded or placeholder
+      timestamp. Fields the tool did not return stay null; values inferred
+      from your own query parameters (e.g. a phase filter) may enter `meta`
+      ONLY with the filter captured in `provenance.args` and the inference
+      disclosed in the report. Without Bash ONLY (e.g. the Claude plugin
+      worker): write raw JSONL lines with the Write tool; the orchestrator's
+      merge validates them.
+    - BEFORE reporting completion, run
+      `python3 <SKILL_DIR>/scripts/evidence-ledger.py check <file> --markers <YOUR-FOCUS>.md` -
+      it must exit 0: no quarantined lines, and every `[@key]` marker in
+      your aspect file resolves to a ledger record (markers are ONLY for
+      resolvable cited sources - a mention-by-id in prose stays plain text,
+      e.g. "the pivotal trial, NCT02435849, was not found"). Without Bash,
+      re-read the ledger and match the markers manually.
+9. Evidence quality: apply the evidence-verification discipline
+   (`references/analysis-methods.md`) to every claim - direction of
+   causality, quantitative fidelity, criterion vs keyword, axis discipline,
+   primary vs downstream.
+
+## Restart / gap top-up (orchestrator-dispatched)
+
+Aspect-file ownership is SERIALIZED, never concurrent: a top-up worker
+adopts the original worker's contract only after that worker has terminated.
+The orchestrator dispatches it with the prior worker's evidence-gaps list:
+
+- Append to the SAME per-aspect ledger via `add` (upsert merge is safe).
+- Update the SAME aspect .md via read-then-targeted edits confined to the
+  gap sections - never rewrite unrelated content, other aspects, or the
+  orchestrator's draft.
+- End with `check <file> --markers <aspect>.md` (exit 0) before reporting.
 
 ## Retry ladder (per query)
 
@@ -135,8 +181,8 @@ attempt 3: alternate tool/source (see references/tool-selection.md routing)
   inlined cheatsheet (Tier B). Do not mix tiers within one topic.
 - Launch workers in parallel in batches of up to 5.
 - Track each aspect in the todo list; mark complete when its output file
-  exists, ends with a bibliography, AND its evidence ledger file exists with
-  at least one record per cited source.
+  exists with cite-key markers throughout AND its evidence ledger file
+  exists, passes `check --markers` (exit 0), and covers every cited key.
 - If a worker fails or stalls, restart it (same prompt), max 3 restarts.
 - Tell the user up front: "If subagents are stuck without progress for too
   long, interrupt and ask me to resume work."
@@ -147,8 +193,8 @@ If the harness has no subagent/Task tool, the SAME protocol runs inline in the
 main conversation, one aspect at a time:
 
 1. Announce the aspect being worked on.
-2. Apply Worker rules 2-8 exactly (same tool selection, retries, citation
-   discipline, evidence ledger, file protocol).
+2. Apply Worker rules 2-9 exactly (same tool selection, retries, citation
+   discipline, evidence ledger, evidence quality, file protocol).
 3. Write `reports/<TOPIC>/<ASPECT>.md` and
    `reports/<TOPIC>/evidence/<ASPECT>.jsonl` before moving to the next aspect.
 4. After the last aspect, proceed to synthesis (SKILL.md Step 5).
@@ -160,10 +206,14 @@ Sequential mode trades latency for context - keep per-aspect tool calls lean
 
 - [ ] Output file exists at `reports/<TOPIC>/<ASPECT>.md`
 - [ ] Evidence ledger exists at `reports/<TOPIC>/evidence/<ASPECT>.jsonl`
-      with at least one record per cited source (rule 8)
+      and passes `evidence-ledger.py check <file> --markers <ASPECT>.md`
+      with exit 0 (Tier A without Bash: re-read the ledger and match the
+      markers manually)
+- [ ] Every cite-key marker `[@...]` used in the aspect file resolves to a
+      ledger record (no invented keys)
 - [ ] Every claim has a citation, source note, or method note
-- [ ] Bibliography present, numbered by order of appearance, every entry
-      copied from ledger fields (no field absent from the ledger)
+- [ ] Findings obey the aspect's inclusion/exclusion boundaries and the
+      evidence-verification discipline
 - [ ] Identifiers included (PMIDs / DOIs / NCT IDs / patent IDs / accessions)
 - [ ] Tool/query log included
 - [ ] Evidence gaps (if any) explicitly listed