ref-manager · PLAN-v2.md · phases 12–18

Knowledge Layer v2

Phases 0–11 built the library: claims with provenance, an alias-matched concept graph, study grouping, appraisal, gaps and two-hop hypotheses. v2 adds typed claims, an ontology anchored to MeSH, deterministic evidence profiles, and evidence-first discovery. Every new component stays rebuildable and every judgement that changes structure goes through you.

EXISTING · PHASES 0–11 ADDED · PHASES 12–18 YOU claims.json PICO fields · locator · span v1 claims stay readable concepts.jsonl slug + exact-match aliases one alias, one concept relations.jsonl 5 evidential edge types contradicts needs review studies · datasets grouping you assert appraise.py RoB 2 · NOS · AMSTAR-2 gaps · hypothesize 4 gap types · 2-hop ABC PubMed novelty check catalog.sqlite FTS5 + MeSH query expansion no vectors (D3) upgrade extend extend feed upgrade 12 Claim v2 — one typed triple subject predicate object role own_result · background · interpretation · cited = pointer context population · method · modality · dataset checks span verbatim · locator · fields · direction + LLM label, display only entities map to concepts 13 Ontology — anchored, reviewed MeSH tree local file · pinned year Local concepts typed · aliases · ambiguity match: exact · broader · narrower · none · hierarchy · merge · split auto only on exact alias / MeSH-ID reuse — everything else is a proposal 12 Graph — reported & reviewed edges evidential supports · potential_conflict · contradicts · replicates semantic increases · decreases · no_effect_on · measures · targets … inferred paths: computed on demand, frozen only inside artifacts aggregate own_result claims 14 Evidence profile — no single score MODERATE quality consistency replication statistics modalities independent 3–7 rule table v3 · full tier 9 · abstract tier 14 · null counted as 0 15 Discovery — every output labelled Conflicts split by context Gap matrix project axes Hypotheses ≤3 hops · routes Opportunities your resources 16 Explorer local static HTML no upload · file:// 18 Examples · cites opt-in, versioned bumps prompt version 17 Embeddings only if eval recall falls below threshold /ref:verify ontology proposals merges → edges pending ambiguous aliases contradicts + rationale moderator hypotheses batch per project rejected proposals kept to suppress repeats AVAILABLE TO YOU datasets --available methods --available people --collaborator /ref:eval baseline recorded in phase 12, before changes
added in v2 existing, phases 0–11 conditional (phase 17) your review or your resources
Claims gain one typed triple and a role, so only a paper's own results count as evidence. Concepts are anchored to a pinned MeSH year, and any structural change becomes a proposal you review. The graph stores only reported and reviewed edges; inferred paths are computed on demand. Evidence profiles report components, an independence range and a band, never a single score, and discovery builds on them. Bars and counts in the profile are illustrative.

Decisions behind the layer

AreaDecisionPhase
graph sourcelibrary claims only; no external knowledge-base import12
entity typessmall generic core of 10, extended only by schema bump12
predicatesclosed list; associated_with fallback keeps the original verb12
cited claimssearchable pointers, never evidence12
confidencedeterministic checks; LLM label shown, never scored12
migrationv1 claims stay; /ref:extract --upgrade per selector12
hierarchylocal MeSH descriptor file, pinned year13
auto-applyexact alias / MeSH-ID reuse only; the rest is a proposal13
mergere-point edges, reviewed decisions → pending13
independencemin–max range; ungrouped papers widen it14
summaryrule-derived band, no 0–100 score14
discoverydeterministic splits, project axes, ≤3 hops, explicit feasibility match15
explorerlocal static HTML; personal content opt-in16
embeddingsonly if measured recall falls below threshold17
feedbackopt-in versioned example sets18

New and extended commands

Claims & graph · phase 12

new/ref:eval add | run | compare
labelled questions and recall at the candidate budget; the baseline is recorded before any retrieval change
ext/ref:extract --upgrade <selector>
re-extract chosen papers to claim v2: typed triple, role, context entities, extraction checks
ext/ref:weave
semantic edges from triples; null results recorded; only own_result claims support edges
ext/ref:concept create --type <type>
typed concepts; find reports ambiguous matches instead of picking one

Ontology · phase 13

new/ref:ontology sync-mesh --year <yyyy>
download and pin one MeSH descriptor year; build the tree in the catalog
new/ref:ontology backfill-mesh <selector>
MeSH headings from preserved raw metadata into dated mesh.json observations
new/ref:ontology map | parent
propose a MeSH mapping (exact / broader / narrower / none) or a broader–narrower link
new/ref:ontology merge | split
restructure concepts with a rationale; edges re-pointed, reviewed decisions set to pending
new/ref:ontology tree | ambiguous | proposals
inspect hierarchy, ambiguous aliases, and the pending queue
ext/ref:add
captures MeSH headings at ingest
ext/ref:verify proposals --batch
review ontology proposals, merges, and pending relation reviews per project

Evidence · phase 14

new/ref:evidence <relation> | --pair <a> <b>
component profile, independence range, tier split, band, and rule-table version
ext/ref:compare · ask · summarize · review
band and profile column; statements labelled reported, replicated, contradictory, inferred, or hypothesis

Discovery · phase 15

ext/ref:gaps --explain-conflicts
split conflicting claims by context fields; optional moderator hypothesis, always labelled
ext/ref:gaps --matrix --project <slug>
coverage grid over declared axes; empty cells read “none in this library”
ext/ref:project axes <slug> <axis…>
declare matrix axes as entity types or concept subtrees
ext/ref:hypothesize --hops 3 --budget <n>
independent routes with distinct PMIDs per hop, modality convergence, truncation reported
ext/ref:study … --available · /ref:person --collaborator
mark datasets, methods, and people available to you
new/ref:opportunities --project <slug>
join frozen gaps, conflicts, and hypotheses to your resources; each row names what makes it feasible

Explore, retrieve, learn · phases 16–18

new/ref:explore <selector> | --concept <id>
offline HTML explorer with filters, neighbours, evidence drawer, hubs and communities; --include-personal to add notes
new/ref:examples curate | list | activate
versioned extraction example sets built from reviewed corrections
ext/ref:related --cites <pmid…>
persist resolved references as paper-to-paper cites edges
ext/ref:ask (conditional)
hybrid lexical + embedding retrieval, only if phase 17 is triggered

Build order

PhaseDeliverableKey gate
12eval baseline · claim v2 · entity types · predicates · relation v2cited claims never support edges; v1 library rebuilds identically
13MeSH capture · ontology · proposals · merge/splitmerged IDs keep resolving; ambiguous aliases never auto-resolve
14evidence profiles · bands · labelsshared-dataset papers collapse; no single numeric score shown
15conflicts · gap matrix · 3-hop hypotheses · opportunitiesdistinct PMIDs per hop; every opportunity names its resource
16local graph explorerno network requests; every edge reaches a passage
17embeddings, if triggeredrecall beats the phase 12 baseline without regressions
18extraction examples · cites edgesno claim changes without explicit re-extraction

Order: 12 → 13 → 14, then re-plan 15–18 after running them on one real thesis question.