opencode-bioresearcher 1.12.0 → 1.13.0

package/agents/bioresearcher-dr-worker.md

@@ -5,7 +5,7 @@ permissions:
   - {action: shell, resource: "*", effect: deny}
   - {action: subagent, resource: "*", effect: deny}
 ---
-<!-- bioresearcher-stamp v1.12.0 -->
+<!-- bioresearcher-stamp v1.13.0 -->
 
 You are a bioresearcher deep-research aspect worker. The orchestrator assigned
 you exactly ONE research aspect of a TOPIC. You call the biomcp MCP server's

package/connector-meta.json

@@ -7,7 +7,7 @@
   "description_en": "Biomedical research plugin for OpenCode v2: delivers the bioresearcher skills and the deep-research subagent via the v2 plugin API; the biomcp MCP server (literature, clinical trials, genes, variants, drugs, diseases, patents) is wired through mcp.servers config.",
   "source": "bioresearcher",
   "type": "plugin",
-  "version": "1.12.0",
+  "version": "1.13.0",
   "harness": "opencode",
   "examples_zh": [
     "帮我做一个关于肿瘤免疫治疗的多方面文献综述并附引用",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opencode-bioresearcher",
-  "version": "1.12.0",
+  "version": "1.13.0",
   "description": "Biomedical research plugin for OpenCode: biomcp MCP server tools, scientific plotting skills, and deep-research subagent",
   "type": "module",
   "main": "index.js",

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

@@ -1,10 +1,10 @@
 ---
 name: bioresearcher-deep-research
-description: "Deep biomedical research orchestrator powered by the biomcp MCP server: clarifies the question, aligns research area plan with user, decomposes into 2-5 aspects, researches each aspect via subagents (sequential fallback), and synthesizes a fully cited report. Use for deep research, literature review, clinical trials, drugs, genes, variants, diseases, patents, PubMed, functional genomics, biomcp."
+description: "Deep biomedical research orchestrator powered by the biomcp MCP server: clarifies the question, aligns research area plan with user, decomposes into 2-5 aspects, researches each aspect via subagents (sequential fallback), and synthesizes a fully cited report; optional map-first empirical cartography for category/landscape questions. Use for deep research, literature review, clinical trials, drugs, genes, variants, diseases, patents, PubMed, functional genomics, biomcp."
 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.8.0"
+  version: "1.9.0"
   source: "opencode-bioresearcher-plugin@1.7.2"
 allowed-tools: Read Write Bash Task mcp__plugin_bioresearcher_biomcp mcp__biomcp
 ---
@@ -31,6 +31,10 @@ Harness-agnostic: works with or without a subagent/Task tool.
   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).
+- Optionally (map-first mode, for category-discovery questions) maps the
+  field's method/category landscape empirically BEFORE plan review via
+  scoped + anti-pinned cartography workers - see
+  `references/cartography.md`.
 
 ## When to use (triggers)
 
@@ -41,6 +45,8 @@ Harness-agnostic: works with or without a subagent/Task tool.
 - Gene / variant / disease questions (annotations, associations, evidence).
 - Patent landscape or prior-art questions.
 - Multi-entity questions spanning several of the above.
+- Category/landscape discovery ("what methods/approaches/classes exist for
+  X", "landscape of X") - offer the map-first mode (Step 1).
 
 Single-fact lookups (e.g. "what is the HGNC symbol for HER2") do not need the
 full workflow - answer directly with the matching biomcp tool using
@@ -82,6 +88,7 @@ mid-query never trigger.
 | `no-interview` | Skip the interview workflow entirely (both Step 1 questions and Step 2 plan review) |
 | `light-research` | Combine and/or pick only the top TWO aspects (Step 2) |
 | `no-html` | Skip the Step 6 HTML rendering (markdown-only output) |
+| `map-first` | Run empirical field cartography (Step 1.5) before plan review, for category-discovery questions - see `references/cartography.md` |
 
 ## Workflow
 
@@ -103,6 +110,29 @@ answer your own questions. If the query carries `no-interview`, skip to Step 2.
   unattended session: write questions and chosen defaults to
   `reports/<TOPIC>/assumptions.md` and cite that file in Limitations.
 
+**Map-first offer (conditional):** if the query is category-discovery shaped
+(the deliverable is a taxonomy/landscape: "what methods/approaches/classes/
+evidence types exist", "landscape of", "how is X done across ..."), include
+ONE additional interview question offering empirical cartography (recommend
+ON); if accepted, confirm the PRIMARY SCOPE in the same message per
+`references/cartography.md`. Entity-anchored queries: never ask. The
+`map-first` prefix forces the mode on without the question. When the mode is
+off (not offered or declined), Steps 1-6 run exactly as if this feature did
+not exist.
+
+### Step 1.5: Cartography (map-first mode only)
+
+Skipped entirely when map-first is off. Dispatch cartographers per
+`references/cartography.md`: 2 focus-tier axes scoped to the confirmed
+primary scope (synthesis-mining, boundary-vocabulary) plus 1-2 anti-pinned
+context axes, using the same tier dispatch, ledger discipline, and
+completion gates as Step 4 (cartographer template and anti-pinning contract
+live in the reference). Then merge the axis maps into
+`reports/<TOPIC>/category_taxonomy.md` (tiered categories, coverage audit
+against >= 2 scope-internal syntheses, unanchored leads); the venue-sweep
+remediation axis fires only when syntheses are scarce. Cartography ledgers
+land in `evidence/` and merge in Step 5a like any aspect ledger.
+
 ### Step 2: Decompose & Review Plan
 
 Comprehend the inquiry and identify 2-5 critical research aspects (top 2 under
@@ -126,6 +156,14 @@ focus, primary tools); never paste raw ABSTRACTs into the question UI.
 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`).
 
+**Map-first variant:** the plan review operates on the category taxonomy
+(`references/cartography.md`): present tiers, coverage-audit results, and a
+recommended selection; iterate until confirmed - this taxonomy walk-through
+IS the plan review, non-waivable except by `no-interview` (autonomous
+conversion records its rationale in `assumptions.md`). Selected categories
+become the aspects; each still gets a full deep-dive ABSTRACT with binding
+inclusion/exclusion criteria.
+
 Track finalized aspects in the harness's todo tool (TodoWrite or equivalent).
 
 ### Step 3: Create the output directory
@@ -226,7 +264,9 @@ 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 - the References
-section itself is generated later by `render`). Reconcile conflicting findings
+section itself is generated later by `render`). Under map-first, also apply
+that reference's optional landscape and decision-guide sections (decision
+guide default-on). Reconcile conflicting findings
 across aspects explicitly rather than silently dropping one side.
 
 Write the synthesized draft to `reports/<TOPIC>/final_report.draft.md` citing
@@ -336,9 +376,14 @@ python3 <skill_dir>/scripts/vet-references.py reports/<TOPIC>/final_report.md --
 ```
 reports/<TOPIC>/
 ├── plan.md                # durable research plan (Step 3; boundaries live here)
+├── category_map_<axis>.md # per-axis cartography maps (map-first only)
+├── category_taxonomy.md   # merged tiered taxonomy + coverage audit
+│                          # (map-first only)
 ├── evidence/
 │   ├── <aspect_1>.jsonl    # per-aspect evidence ledger (worker-written)
 │   ├── <aspect_2>.jsonl
+│   ├── cartography_<axis>.jsonl  # cartography ledgers (map-first only;
+│   │                             # merge like aspect ledgers)
 │   ├── ...
 │   ├── _invalid.jsonl      # merge quarantine (only when malformed lines occur)
 │   └── sources.jsonl       # merged + verified ledger (Step 5a output)
@@ -395,6 +440,7 @@ reports/<TOPIC>/
 | File | Contents |
 |------|----------|
 | `references/worker-protocol.md` | Worker prompt template, file protocol, no re-delegation, retry/degrade rules |
+| `references/cartography.md` | map-first mode: scopes, axis archetypes, anti-pinning contract, taxonomy + coverage audit, interaction matrix |
 | `references/tool-selection.md` | Question-type to tool decision tree; sections/limit/pagination patterns; biomcp_ prefix note |
 | `references/article-literature.md` | article_search / article_get: sources, dateRange, citations |
 | `references/clinical-trials.md` | trial_search / trial_get: filters, cursor paging, sections |

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

@@ -31,6 +31,7 @@ An aspect is DONE when ALL of these hold:
 | Variant evidence | Variant annotation + (if token) OncoKB + trials | variant_search, variant_get, variant_oncokb |
 | Patent landscape | 10-30 patents incl. seminal prior art | patent_search, patent_get |
 | Dataset hunt | Candidate accessions + linked publication | geo_search, sra_search, genbank_search |
+| Category cartography (map-first) | 15-30 anchored categories per axis; every category >= 1 synthesis structure or >= 2 primaries | article_search, article_get |
 
 ## Source-quality rules
 
@@ -118,6 +119,20 @@ ABSTRACT; these rules govern how workers apply any such criteria.
    improvised categories); re-check rules 1-2 whenever synthesis rewords a
    claim or transcribes a number from an aspect report.
 
+## Cartography discipline (map-first mode)
+
+- Category anchoring bar: a listed category needs >= 1 retrieved synthesis
+  whose structure demonstrably contains it, or >= 2 primary records -
+  keyword overlap is not coverage (anti-pinning contract:
+  `references/cartography.md`).
+- Scope-relative tiers: adoption tiers (1/2/3) are relative to the primary
+  scope's own practice; state the reference frame, never present a tier as
+  absolute.
+- Coverage audit: the merged taxonomy is reconciled against >= 2
+  scope-internal syntheses; synthesis-enumerated categories missing from
+  the map are added or declared as gaps - silent omission is the failure
+  mode this audit exists to catch.
+
 ## Failure modes
 
 | Symptom | Fix |

package/skills/bioresearcher-deep-research/references/cartography.md

@@ -0,0 +1,190 @@
+# Empirical Cartography (map-first mode)
+
+Optional Stage-1 field mapping for the deep-research skill: discover the
+method/category landscape empirically BEFORE proposing the research plan,
+then run the standard aspect workflow on user-selected categories. This mode
+is field-, community-, and question-agnostic: it applies to any
+category-discovery question in the biomedical realm (methods, approaches,
+evidence classes, taxonomies, landscapes), in any discipline.
+
+## When map-first applies
+
+- OFFER it (inside the Step 1 interview, one extra question, only when the
+  query is category-discovery shaped): the deliverable is a taxonomy or
+  landscape - "what methods/approaches/classes/evidence types exist for X",
+  "landscape of X", "how is X done across ...", "categories of X".
+- Do NOT offer for entity-anchored queries (one drug, variant, trial, gene,
+  disease) - the default workflow is already right.
+- The `map-first` prefix forces the mode on without the offer question.
+- Default OFF: with map-first off, every workflow step, file, gate, and
+  report section is identical to the non-cartography skill. The only
+  default-mode addition is the conditional offer question itself.
+
+## Primary scope vs context scope
+
+The user designates a PRIMARY SCOPE - the literature segment where category
+recall is the success criterion - defined by any combination of community,
+discipline, disease/therapeutic area, modality, technique family, organism,
+data type, or question type. Everything else is CONTEXT SCOPE: mapped for
+awareness, never exhaustively. The orchestrator infers a candidate primary
+scope from query vocabulary (e.g. "industry-ready", "clinical practice",
+"food science", "diagnostic assay development") and asks for confirmation
+in the same interview message - the recall target depends on it, and users
+rarely name it spontaneously. If the user declines to specify, run with the
+scope implied by the query terms and record the assumption in plan.md.
+
+## Two-tier dispatch
+
+Focus tier (2 workers, scoped to the primary scope, method-unpinned):
+
+- `cartography_synthesis_mining` - transcribe the scope's OWN synthesis
+  ecosystem (reviews, guidelines, consensus statements, position papers,
+  protocol series): harvest their section structures as candidate
+  categories and expand via backward citations (article_get
+  sections=["citation"]) to founding anchors. The scope's own taxonomies
+  are the recall target.
+- `cartography_boundary_vocabulary` - hunt categories that answer the
+  question's underlying information need but self-describe under different
+  terms: adjacent vocabulary, hypernyms, enabling/auxiliary measurements,
+  neighboring endpoints. Ask, per formulation of the information need:
+  "what does this scope call the things that do X?"
+
+Context tier (1-2 workers, fully anti-pinned, breadth across the rest of
+the field) - pick archetypes by question shape:
+
+- `cartography_context_principle` - enumerate the distinct
+  experimental/analytical principles by which the question is answered;
+  let the categories emerge from retrieved records.
+- `cartography_context_casespace` - partition the question's object space
+  (barriers, diseases, organisms, tissues, modalities - whatever partitions
+  it) and map category coverage per stratum.
+- `cartography_context_segment` - sweep how OTHER communities/disciplines
+  frame and categorize the same question; vocabulary differences are
+  themselves findings.
+
+Budget: ~15-25 biomcp calls per cartographer (hard cap 30); parallel
+batches of up to 5; Tier A/B dispatch and the Tier C sequential fallback
+follow SKILL.md Step 4, using the cartographer template below.
+
+Conditional remediation axis (orchestrator-dispatched after the focus tier
+returns, only when needed):
+
+- `cartography_venue_sweep` - fires IFF the focus tier found fewer than two
+  field-spanning syntheses OR the interview flagged an emerging area: sweep
+  the primary scope's primary-literature venues for categories its thin
+  synthesis ecosystem under-covers.
+
+## Anti-pinning contract (binding on every cartographer)
+
+1. No method names, assay names, or category lists enter a cartographer
+   prompt. Focus-tier prompts pin the PRIMARY SCOPE and the question's
+   information need - never methods. Context-tier prompts pin nothing but
+   the question.
+2. A category may be listed ONLY if anchored in retrieved records: either
+   >= 1 retrieved synthesis whose structure demonstrably contains it, OR
+   >= 2 primary records found via search.
+3. Never assert a category from model memory; memory shapes query design
+   only. A failed query line is logged under Evidence Gaps - never turned
+   into a category.
+4. Probe deliberately across the assigned axis before concluding; do not
+   stop at the first handful of categories.
+
+## Cartographer prompt template
+
+```md
+TOPIC: <TOPIC>
+YOUR RESEARCH FOCUS: cartography_<axis>
+AXIS: <archetype name + one-line instantiation, e.g. "case-space partition:
+the variable that partitions this question's object space is <variable>">
+PRIMARY SCOPE: <primary scope - focus tier only; context tier: "none -
+stay anti-pinned">
+MISSION: Produce an empirically anchored, high-level map of the major
+method/category families for <question>, entering the field from your
+axis. 15-30 categories maximum (merge near-duplicates and say so).
+OUTPUT: reports/<TOPIC>/category_map_<axis>.md (title; one-paragraph scope
+summary; ONE subsection per category: name, one-line description, 1-3
+anchor papers as cite-key markers, maturity signals - synthesis existence,
+approximate hit volume, founding era - and which queries surfaced it; then
+"## Query Log" and "## Evidence Gaps" with failed query lines) plus
+reports/<TOPIC>/evidence/cartography_<axis>.jsonl.
+SKILL_DIR: <absolute skill dir>   # Tier B only; resolve before dispatch
+EXECUTION RULE: Do NOT read or inspect evidence-ledger.py or other skill
+scripts; all schemas and commands are fully specified here.
+```
+
+Tier B orchestrators additionally inline the anti-pinning contract, the
+anchoring rule, the ledger discipline (worker-protocol.md rules 5-8), and
+the completion-gate command. Cartographers follow every Worker rule in
+`references/worker-protocol.md` (sequential calls, retry ladder, verbatim
+ledger records, no bibliography) with the category map replacing the
+aspect report and `check --markers category_map_<axis>.md` as the gate.
+
+## Taxonomy merge + coverage audit (orchestrator)
+
+Merge all axis maps into `reports/<TOPIC>/category_taxonomy.md`:
+
+- Deduplicated category list; per category: name, one-line description,
+  anchors, maturity signals, surfaced-by axes (cross-axis confirmation is
+  a robustness signal), and an adoption tier (1 = established /
+  industry-grade, 2 = discovery-grade, 3 = emerging/niche) - tiers are
+  scope-relative and the taxonomy must say so explicitly.
+- "## Coverage Audit" section: reconcile the merged map against the
+  enumerated method/category lists of >= 2 scope-internal syntheses. Any
+  category a synthesis enumerates that the map lacks must be added (with
+  anchors) or explained as a declared gap. If the scope yielded fewer than
+  2 syntheses, anchor the audit on cross-axis overlap instead and flag
+  synthesis scarcity (this also triggers the venue-sweep remediation).
+- "## Unanchored Leads" section: suspected-but-unanchored territories,
+  listed as the query lines tried - never as categories.
+
+## Interaction matrix
+
+| Mode | Behavior |
+|------|----------|
+| Default, heuristic fired | Step 1 interview includes ONE offer question ("empirical field mapping first?" - recommend ON) and, if accepted, primary-scope confirmation in the same message; nothing else changes |
+| Default, heuristic not fired | Identical to the non-cartography skill: no question, no cartography files |
+| `map-first` | Cartography on without the offer question; the interview still runs (scope + clarifiers) unless `no-interview` is also present |
+| `map-first` + `no-interview` | Cartography on; taxonomy -> plan conversion is autonomous: record the category-selection rationale and coverage-audit outcome in plan.md + assumptions.md, and state in the report Limitations that scope selection was not user-reviewed |
+| `no-interview` alone | Identical to the non-cartography skill (Step 1 is skipped, so no offer fires) |
+
+Cartography does NOT waive the Step 2 plan review: with map-first on (and
+no `no-interview`), the taxonomy walk-through IS the plan review - present
+the taxonomy with tiers, coverage-audit results, and a recommended category
+selection, then iterate with the user until the plan is confirmed (same
+rounding rules as Step 2). Selected categories become the Step 3 aspects
+(standard deep-dive ABSTRACTs; the taxonomy's inclusion signals seed the
+ABSTRACT boundaries; the set may exceed 5 when the user insists - batch
+dispatches accordingly). Categories discovered but not selected stay
+citable: their cartography ledgers merge into sources.jsonl in Step 5a
+like any aspect ledger, and the report carries them in the optional
+landscape section (`references/report-template.md`).
+
+## Report integration
+
+- Landscape section (map-first only): one line per discovered-but-
+  unselected category, citing its cartography anchors - acknowledged, not
+  researched; the report must say so.
+- Decision guide by question scenario (map-first default-on): one compact
+  "scenario -> recommended method sequence -> tier -> caveat" table per
+  user-confirmed question scenario, built only from ledger-verified
+  sources, tiers labeled scope-relative.
+- The field's own taxonomy disagreements (syntheses classifying the same
+  subject differently) are reported in Analysis Methodology or Findings,
+  never silently resolved.
+
+## Degradation + consistency
+
+- No subagent tool: run axes sequentially in the main conversation (same
+  contract, leaner budgets).
+- Server unavailable: cartography cannot run - proceed with the default
+  workflow and say so explicitly.
+- map-first OFF: behavior is identical to the non-cartography skill
+  (steps, files, gates, report structure). The existing agent-test
+  deep-research suite (q01-q07) is the regression guarantee and stays
+  unchanged.
+
+## Out of scope / future work
+
+- Report update mode (re-running an existing report): a verify-and-refresh
+  worker tier for previously covered core areas - deliberately NOT part of
+  map-first, which always researches from scratch.

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

@@ -67,6 +67,23 @@ the source of truth for citations]
 [queries that failed after retries, with reasons]
 ```
 
+## Map-first optional sections
+
+When the run used empirical cartography (SKILL.md Step 1.5), two OPTIONAL
+sections extend the mandatory structure. Both cite through the normal
+merged-ledger markers - cartography anchors are ordinary ledger records.
+
+- **Landscape** (inside Findings, after the selected aspects): one line per
+  discovered-but-unselected category, citing its cartography anchors -
+  acknowledged, not researched; the report must say so explicitly.
+- **Decision guide by question scenario** (after the findings/evidence
+  tables; DEFAULT-ON in map-first mode, skippable only if the user
+  declines): one compact table per user-confirmed question scenario -
+  scenario | recommended method sequence | tier | caveat - built only from
+  ledger-verified sources, with tiers labeled scope-relative.
+- Taxonomy disagreements between the field's own syntheses are reported in
+  Analysis Methodology or Findings - never silently resolved.
+
 ## Citation placement rules
 
 - Authored text uses semantic cite-key markers `[@pmid:...]`, groups

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

@@ -38,6 +38,18 @@ EXECUTION RULE: Do NOT read or inspect evidence-ledger.py or other skill scripts
   startup (via `${CLAUDE_PLUGIN_ROOT}`); the orchestrator sends ONLY the
   filled-in template below.
 
+## Cartographer workers (map-first mode)
+
+Cartography axes use the SAME worker contract (rules 1-9, file protocol,
+completion gate) with two substitutions: the deliverable is a CATEGORY MAP
+(`reports/<TOPIC>/category_map_<axis>.md`: one subsection per anchored
+category - name, one-line description, 1-3 anchor markers, maturity signals,
+surfacing queries - plus a Query Log and Evidence Gaps) instead of an aspect
+report, and the focus name is `cartography_<axis>`. The dispatch prompt
+template, axis archetypes, anti-pinning contract, and anchoring rule live in
+`references/cartography.md`. Tier A workers read that file too when the
+assigned focus starts with `cartography_`.
+
 ## File protocol
 
 - Output files (exactly TWO - together they are the self-contained
@@ -132,7 +144,10 @@ EXECUTION RULE: Do NOT read or inspect evidence-ledger.py or other skill scripts
       `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 records via a shell heredoc
+      resolves to nothing and breaks the call). Anchor every shell command
+      to the workspace root (`cd <workspace root> && python3 <SKILL_DIR>/...`)
+      so relative report paths resolve regardless of the shell's starting
+      directory. Pass records via a shell heredoc
       or with an array/JSONL file (`add <file> @<batch.json>`):
       ```bash
       python3 <SKILL_DIR>/scripts/evidence-ledger.py add reports/<TOPIC>/evidence/<YOUR-FOCUS>.jsonl --stdin << 'EOF'