groundworkers 0.3.2__tar.gz → 0.3.3__tar.gz

{groundworkers-0.3.2 → groundworkers-0.3.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: groundworkers
-Version: 0.3.2
+Version: 0.3.3
 Summary: Groundworkers MCP server — read-only agentive access to OMOP vocabularies, concept graphs, and embeddings.
 Requires-Python: >=3.12
 Description-Content-Type: text/markdown
@@ -63,8 +63,19 @@ No patient-level writes. No session state. No transport-specific business logic.
 - exact, normalized, full-text, and embedding-backed retrieval
 - mapping-oriented candidate bundles and context assembly
 - stateless source-planning workflows
+- bundled baseline knowledge packs for reusable mapping and planning context
 - LLM-backed text normalization and domain classification
 
+## Knowledge Packs
+
+`groundworkers` ships with bundled baseline knowledge packs inside the package.
+These packs are available by default and provide reusable guidance and rules
+that apply broadly across deployments.
+
+Site-specific or localisation packs are added through the shared stack config
+via `tools.groundworkers.knowledge.packs_root`. When a configured pack has the
+same `layer` and `name` as a bundled baseline pack, the configured copy wins.
+
 ## Runtime model
 
 ```mermaid

{groundworkers-0.3.2 → groundworkers-0.3.3}/README.md

@@ -17,8 +17,19 @@ No patient-level writes. No session state. No transport-specific business logic.
 - exact, normalized, full-text, and embedding-backed retrieval
 - mapping-oriented candidate bundles and context assembly
 - stateless source-planning workflows
+- bundled baseline knowledge packs for reusable mapping and planning context
 - LLM-backed text normalization and domain classification
 
+## Knowledge Packs
+
+`groundworkers` ships with bundled baseline knowledge packs inside the package.
+These packs are available by default and provide reusable guidance and rules
+that apply broadly across deployments.
+
+Site-specific or localisation packs are added through the shared stack config
+via `tools.groundworkers.knowledge.packs_root`. When a configured pack has the
+same `layer` and `name` as a bundled baseline pack, the configured copy wins.
+
 ## Runtime model
 
 ```mermaid

{groundworkers-0.3.2 → groundworkers-0.3.3}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "groundworkers"
-version = "0.3.2"
+version = "0.3.3"
 description = "Groundworkers MCP server — read-only agentive access to OMOP vocabularies, concept graphs, and embeddings."
 readme = "README.md"
 requires-python = ">=3.12"
@@ -72,6 +72,12 @@ package-dir = {"" = "src"}
 [tool.setuptools.packages.find]
 where = ["src"]
 
+[tool.setuptools.package-data]
+groundworkers = [
+  "knowledge/packs/*/*/*.md",
+  "knowledge/packs/*/*/*.yaml",
+]
+
 [tool.pytest.ini_options]
 testpaths = ["tests"]
 markers = [

{groundworkers-0.3.2 → groundworkers-0.3.3}/src/groundworkers/app.py

@@ -182,7 +182,9 @@ def build_services(config: AppConfig, adapters: Adapters) -> Services:
         assisted_classifier = AssistedColumnRoleClassifier(adapters.llm)
     services.source_planning = SourcePlanningService(assisted_classifier=assisted_classifier)
     if adapters.omop_graph is not None:
-        services.graph = GraphService(adapters.omop_graph)
+        # cdm is optional; only the classified-edge traversals
+        # (concept_associations / concept_extended_inheritance) require it.
+        services.graph = GraphService(adapters.omop_graph, adapters.cdm)
         services.grounding = ConceptGroundingService(
             services.graph,
             min_fulltext_overlap=config.grounding.min_fulltext_overlap,

groundworkers-0.3.3/src/groundworkers/knowledge/packs/core/criteria-gate-yesno/guidance.md

@@ -0,0 +1,57 @@
+# "Meets Criteria For..." Yes/No Gates
+
+## The pattern
+
+Source instruments frequently ask a dichotomous question that determines
+whether a diagnosis, syndrome, or clinical state applies: "Does the
+participant meet the criteria for dementia?", "Does the participant meet
+criteria for MCI?", "Does the participant meet criteria for MBI?". These are
+not ordinary categorical Yes/No observations — they are a gate on whether a
+specific standard concept should be asserted for this participant at all.
+
+## The model
+
+- **Yes (1)**: emit one record for the underlying concept — CONDITION_OCCURRENCE
+  when the concept's domain is Condition, OBSERVATION otherwise (per
+  `domain-routing`).
+- **No (0)**: emit nothing. Do not write a parallel OBSERVATION record coding
+  the negative answer with a generic "No" value_as_concept_id.
+
+This differs from an ordinary Yes/No categorical item (e.g. "does the
+participant currently smoke?"), where both directions are independently
+informative and both get recorded. The distinguishing feature of a criteria
+gate is that a "No" answer only means "the named concept does not apply" —
+it carries no positive clinical content of its own.
+
+## The exception
+
+Before defaulting to "No → nothing", check whether a standard concept exists
+for the *negative* finding specifically (e.g. an explicit "criteria not met"
+or "absence of X" concept distinct from a generic negation). This is
+uncommon — most vocabularies do not pre-coordinate the negative case — but
+when one exists, use it rather than suppressing the record.
+
+## Detection
+
+Look for phrasing such as "meet(s) criteria for", "meet(s) the criteria for",
+"meets any criteria for" in the field label, where the field is a radio/Yes-No
+item gating a specific diagnostic concept. Ordinary presence/absence
+checkboxes and self-report Yes/No items that are not framed as a diagnostic
+criteria determination are out of scope for this pattern — apply
+`value-representation`'s normal Yes/No handling to those instead.
+
+## What not to do
+
+- Do not write a `value_as_concept_id`-coded "No" record for a criteria gate —
+  it adds a row with no clinical content and implies a false symmetry between
+  meeting and not meeting diagnostic criteria.
+- Do not use this pattern for items where "No" is itself independently
+  meaningful (e.g. a clinician confidence judgment, a symptom checklist item)
+  — only apply it to fields that are literally asking whether the participant
+  meets criteria for a named concept.
+
+## See also
+
+`diagnosis-role-modifier` often applies to the same syndromes downstream of a
+criteria gate — once a diagnosis is asserted via a "Yes", a separate role/status
+field may further qualify it.

groundworkers-0.3.3/src/groundworkers/knowledge/packs/core/criteria-gate-yesno/manifest.yaml

@@ -0,0 +1,22 @@
+name: criteria-gate-yesno
+layer: core
+version: "1.0"
+shareability: public
+scope_summary: >
+  Yes/No fields phrased as "meets criteria for X" are a gate on asserting a
+  concept, not an ordinary categorical observation: Yes emits one record for
+  the concept (CONDITION_OCCURRENCE or OBSERVATION per its domain), No emits
+  nothing. Check for an explicit negative-finding concept before defaulting
+  to suppression. Does not apply to ordinary Yes/No items where both
+  directions are independently informative.
+
+mechanisms:
+  - context-inject
+
+applicability:
+  always: true
+
+see_also:
+  - diagnosis-role-modifier
+  - domain-routing
+  - value-representation

groundworkers-0.3.3/src/groundworkers/knowledge/packs/core/diagnosis-role-modifier/guidance.md

@@ -0,0 +1,90 @@
+# Diagnosis + Role/Status Modifier
+
+## The pattern
+
+Some source instruments split a single clinical fact across two fields:
+
+1. A **presence field** — does the participant have this diagnosis/finding at all?
+2. A **role/status field** — what is its status or role relative to the participant's
+   overall clinical picture (primary, contributing, non-contributing; primary vs.
+   secondary; admitting vs. discharge; provisional vs. confirmed)?
+
+This is a two-source, one-target mapping: both fields describe the *same*
+CONDITION_OCCURRENCE record, not two independent facts. Do not emit a second,
+freestanding OBSERVATION record to carry the role — populate
+`CONDITION_OCCURRENCE.condition_status_concept_id` on the same record instead.
+
+## Detection
+
+Look for a presence/diagnosis field paired with a sibling field whose label reads
+as a status, role, or type qualifier of that same diagnosis (often suffixed or
+named similarly — e.g. `xdx` + `xdxif`, `xdx` + `xdx_role`). The pairing is
+usually confirmed by the branching logic or field note referencing the diagnosis
+field, and by choice lists such as "Primary / Contributing / Non-contributing" or
+"Primary / Secondary".
+
+## The model
+
+| Field | Value |
+|---|---|
+| Table | CONDITION_OCCURRENCE |
+| condition_concept_id | standard concept for the diagnosis (from the presence field) |
+| condition_status_concept_id | standard concept from the **Condition Status** vocabulary, selected using the role field's value |
+
+`Condition Status` is its own OMOP vocabulary/domain. Commonly available concepts include:
+
+| concept_id | concept_name |
+|---|---|
+| 32902 | Primary diagnosis |
+| 32908 | Secondary diagnosis |
+| 32890 | Admission diagnosis |
+| 32896 | Discharge diagnosis |
+| 32899 | Preliminary diagnosis |
+| 32893 | Confirmed diagnosis |
+
+There is no dedicated "Contributing diagnosis" concept — map a "contributing"
+role to **Secondary diagnosis (32908)**, the closest available status, and note
+the approximation in the mapping's notes/comments.
+
+## Non-contributing (and other null-role values)
+
+A role value that means "not actually relevant/contributing" (e.g.
+"Non-contributing") is not a status to record — it means the diagnosis should
+not be asserted at all for this record. **Suppress the CONDITION_OCCURRENCE
+record entirely** when the role field carries this value, rather than writing
+a record with an empty or misleading condition_status_concept_id.
+
+## What not to do
+
+- Do not create a second OBSERVATION row (concept_id=0 or otherwise) just to
+  carry the role/status value as free text or a generic categorical code —
+  that treats a modifier of the diagnosis as an independent clinical fact.
+- Do not populate condition_status_concept_id with a source-local code; always
+  resolve it to a standard Condition Status concept.
+- Do not assert the CONDITION_OCCURRENCE record when the paired role field
+  indicates the diagnosis is non-contributing/not applicable.
+
+## Output structure: representing the merge in a row-per-source-field ETL format
+
+When the mapping output is authored as one row per source field, this pattern
+is an n:1 merge (two source fields, one CDM record) and needs an explicit way
+to say "this record's condition_status_concept_id comes from a second field."
+The convention used in this pipeline is three additional columns on the
+presence field's row:
+
+- `secondary_source_field` — the source field supplying the role/status value
+- `secondary_target_column` — the CDM column it populates (`condition_status_concept_id`)
+- `secondary_code_map` — `source_code:concept_id` pairs, pipe-separated, with the
+  literal token `SUPPRESS` for any code that should drop the record
+  (e.g. `1:32902|2:32908|3:SUPPRESS`)
+
+The role field itself gets no row of its own — it is consumed entirely by the
+presence field's row. This same three-column mechanism generalizes to other
+n:1 merges beyond diagnosis role (e.g. a presence flag paired with a severity
+or laterality modifier), not just condition status.
+
+## See also
+
+`pre-coordinated-split` covers the related but distinct case where a *single*
+source concept's vocabulary relationships decompose into an entity + value —
+this pack covers two *separate* source fields describing one record.

groundworkers-0.3.3/src/groundworkers/knowledge/packs/core/diagnosis-role-modifier/manifest.yaml

@@ -0,0 +1,28 @@
+name: diagnosis-role-modifier
+layer: core
+version: "1.0"
+shareability: public
+scope_summary: >
+  When a diagnosis/finding is captured across two source fields — a presence
+  field and a separate role/status field (primary/contributing/non-contributing,
+  primary/secondary, admitting/discharge, etc.) — model it as one
+  CONDITION_OCCURRENCE record with condition_status_concept_id populated from
+  the role field, not as two independent records. A non-contributing/not-
+  applicable role suppresses the record entirely. Includes the
+  secondary_source_field/secondary_target_column/secondary_code_map
+  convention for representing this n:1 merge in a row-per-source-field ETL
+  output.
+
+mechanisms:
+  - context-inject
+  - post-filter
+
+applicability:
+  always: false
+  domains:
+    - Condition
+
+see_also:
+  - pre-coordinated-split
+  - domain-routing
+  - standard-concept-preference

groundworkers-0.3.3/src/groundworkers/knowledge/packs/core/domain-routing/guidance.md

@@ -0,0 +1,45 @@
+# Domain Routing
+
+## The fundamental rule
+
+The `domain_id` of the **target standard concept** determines which CDM table a record is written to — not the domain implied by the source code, source vocabulary, or source table structure.
+
+A source item coded as a procedure that maps to an RxNorm Ingredient goes to `DRUG_EXPOSURE`, not `PROCEDURE_OCCURRENCE`. A source item that looks like a diagnosis but maps to a LOINC measurement concept goes to `MEASUREMENT`. The target concept is authoritative.
+
+## Domain → CDM table mapping
+
+| domain_id | Primary CDM table |
+|-----------|-------------------|
+| Condition | CONDITION_OCCURRENCE |
+| Drug | DRUG_EXPOSURE |
+| Measurement | MEASUREMENT |
+| Observation | OBSERVATION |
+| Procedure | PROCEDURE_OCCURRENCE |
+| Device | DEVICE_EXPOSURE |
+| Specimen | SPECIMEN |
+| Visit | VISIT_OCCURRENCE |
+| Provider | PROVIDER |
+
+## Scope: the entity concept only
+
+This rule routes on the domain of the **entity** concept — the one going into
+`measurement_concept_id`, `observation_concept_id`, `condition_concept_id`, etc.
+It does not apply to `value_as_concept_id` or other subordinate value fields.
+A value concept may legitimately come from a different domain than the record
+it lives in — e.g. a Condition-domain concept (a plain diagnosis) used as
+`value_as_concept_id` on an OBSERVATION row for a history-of or family-history
+pattern (see `history-of-event`). Do not re-route a record to a different CDM
+table because its value concept's domain differs from the entity concept's
+domain — only the entity concept's domain decides the table.
+
+## Unmapped source items (concept_id = 0)
+
+When no valid standard concept mapping exists, set `*_concept_id = 0` (not NULL). The record still belongs in a CDM table — route using the best available domain signal (source vocabulary, source table, or caller context). Document the zero-mapping so it surfaces in data quality review.
+
+Do not omit a record solely because no mapping was found. The source value is preserved in `*_source_value` and the zero-mapped record remains queryable.
+
+## What not to do
+
+- Do not route based on the source vocabulary (ICD codes are not always Condition; NDC codes are almost always Drug but verify the target concept's domain).
+- Do not route based on the source table name or caller hint alone.
+- Do not use concept_id = NULL — zero-mapping is the standard for unmapped concepts.

groundworkers-0.3.3/src/groundworkers/knowledge/packs/core/domain-routing/manifest.yaml

@@ -0,0 +1,20 @@
+name: domain-routing
+layer: core
+version: "1.0"
+shareability: public
+scope_summary: >
+  The domain_id of the target standard concept — not the source — is the
+  authoritative signal for which CDM table a record belongs in. Includes
+  the canonical domain-to-table mapping and the concept_id=0 fallback rule
+  for unmapped source items.
+
+mechanisms:
+  - context-inject
+  - pre-compute
+
+applicability:
+  always: true
+
+see_also:
+  - standard-concept-preference
+  - one-to-many-mapping

groundworkers-0.3.3/src/groundworkers/knowledge/packs/core/domain-routing/rules.yaml

@@ -0,0 +1,17 @@
+domain_to_table:
+  Condition: CONDITION_OCCURRENCE
+  Drug: DRUG_EXPOSURE
+  Measurement: MEASUREMENT
+  Observation: OBSERVATION
+  Procedure: PROCEDURE_OCCURRENCE
+  Device: DEVICE_EXPOSURE
+  Specimen: SPECIMEN
+  Visit: VISIT_OCCURRENCE
+  Provider: PROVIDER
+
+unmapped_concept_id: 0
+
+routing_signal_priority:
+  - target_concept_domain_id   # authoritative
+  - source_vocabulary_hint     # fallback when target not yet resolved
+  - caller_context_hint        # last resort

groundworkers-0.3.3/src/groundworkers/knowledge/packs/core/drug-concept-granularity/guidance.md

@@ -0,0 +1,52 @@
+# Drug Concept Granularity
+
+## RxNorm concept hierarchy
+
+RxNorm organises drug concepts into levels of specificity. Standard mapping targets
+exist at multiple levels, and the appropriate level depends on what information the
+source provides.
+
+| RxNorm concept class | Contains | Example |
+|---------------------|----------|---------|
+| Ingredient | Active substance only | Metformin |
+| Clinical Drug Component | Ingredient + strength | Metformin 500 MG |
+| Clinical Drug Form | Ingredient + dose form | Metformin Oral Tablet |
+| Clinical Drug | Ingredient + strength + dose form | Metformin 500 MG Oral Tablet |
+| Branded Drug | Clinical Drug + brand name | Glucophage 500 MG Oral Tablet |
+| Marketed Product | Branded + packaging | Glucophage 500 MG Oral Tablet [30 Tablet] |
+
+## Selection rule
+
+**Use the most specific level the source data supports, up to Clinical Drug.**
+
+- Source provides only drug name (no dose, no form) → map to **Ingredient**
+- Source provides drug name + dose form → map to **Clinical Drug Form**
+- Source provides drug name + strength + dose form → map to **Clinical Drug**
+- Source provides dose but not form (or vice versa) → map to **Clinical Drug Component** or **Clinical Drug Form** as appropriate; prefer Ingredient if precision would be misleading
+
+**Branded Drug and Marketed Product are not valid standard mapping targets.** Even
+when the source specifies a brand name, map to the equivalent Clinical Drug or
+Ingredient (which carries standard_concept = 'S'). Brand names are preserved in
+`drug_source_value`.
+
+## Why this matters
+
+Mapping all drug concepts to Ingredient level maximises analytical cohesion: queries
+for "Metformin" will find records regardless of formulation. Mapping too high (always
+Ingredient) when formulation is known loses clinically meaningful precision. Mapping
+to Branded level fragments the same clinical drug across multiple non-standard
+concepts and breaks standard vocabulary queries.
+
+## Dose form and strength information in source data dictionaries
+
+Source data dictionaries often carry drug labels that include partial formulation
+information ("Metformin HCl 500mg tabs"). Extract what is explicitly present in the
+label; do not infer formulation from context. If the dose/form in the label is
+ambiguous or inconsistent with known products, fall back to Ingredient.
+
+## RxNorm Extension
+
+When no RxNorm Ingredient or Clinical Drug exists for a drug (typically non-US
+drugs or novel agents), RxNorm Extension provides equivalent concepts with the
+same class hierarchy. Apply the same granularity rules. Prefer core RxNorm over
+RxNorm Extension when both cover the same entity.

groundworkers-0.3.3/src/groundworkers/knowledge/packs/core/drug-concept-granularity/manifest.yaml

@@ -0,0 +1,22 @@
+name: drug-concept-granularity
+layer: core
+version: "1.0"
+shareability: public
+scope_summary: >
+  RxNorm concept level selection for drug mappings: prefer Ingredient when
+  dose/form/strength are unavailable; prefer Clinical Drug when they are known.
+  Branded Drug and Marketed Product are not valid standard mapping targets.
+  Applies to all drug concept mapping regardless of source system.
+
+mechanisms:
+  - context-inject
+  - post-filter
+
+applicability:
+  always: false
+  domains:
+    - Drug
+
+see_also:
+  - standard-concept-preference
+  - domain-routing

groundworkers-0.3.3/src/groundworkers/knowledge/packs/core/drug-concept-granularity/rules.yaml

@@ -0,0 +1,22 @@
+# Drug concept granularity selection rules
+# Applied as post-filter to drug domain candidates.
+
+target_concept_class_preference:
+  # Ordered from most preferred (given sufficient source data) to least.
+  - concept_class_id: Clinical Drug
+    requires_source_fields: [strength, dose_form]
+  - concept_class_id: Clinical Drug Form
+    requires_source_fields: [dose_form]
+  - concept_class_id: Clinical Drug Component
+    requires_source_fields: [strength]
+  - concept_class_id: Ingredient
+    requires_source_fields: []  # always acceptable fallback
+
+reject_concept_classes:
+  - Branded Drug        # standard_concept != 'S', brand name not a CDM target
+  - Marketed Product    # packaging level, not a clinical concept
+  - Clinical Pack       # multi-drug packages, not direct mapping targets
+
+vocab_preference_within_class:
+  - RxNorm              # always prefer core RxNorm
+  - RxNorm Extension    # fallback for drugs absent from core RxNorm

groundworkers-0.3.3/src/groundworkers/knowledge/packs/core/history-of-event/guidance.md

@@ -0,0 +1,58 @@
+# History-of-Event Pattern
+
+## The model
+
+When a source item describes a patient's *history* of a condition, event, or
+procedure, the correct OMOP representation is:
+
+| Field | Value |
+|---|---|
+| Table | OBSERVATION |
+| observation_concept_id | 4214956 (History of event) |
+| value_as_concept_id | standard concept for the actual condition or event |
+
+The entity concept is always 4214956. The clinical content goes in value_as_concept_id.
+Do not populate CONDITION_OCCURRENCE for these items.
+
+## Detection
+
+Applies when the source label contains phrasing such as:
+"history of", "h/o", "past history of", "prior history of", "previous history of",
+"hx of", "Hx:", "prior diagnosis of".
+
+## Family history
+
+Family history follows the same structural pattern but uses a different entity concept:
+
+| Field | Value |
+|---|---|
+| observation_concept_id | 4167217 (Family history of clinical finding) |
+| value_as_concept_id | standard concept for the familial condition |
+
+### Choosing the value concept
+
+Many vocabularies (SNOMED in particular) pre-coordinate a "Family history of X"
+concept for common conditions (e.g. concept 4326002 "Family history of dementia",
+concept_class Context-dependent). Do not use one of these pre-coordinated
+concepts as value_as_concept_id — that doubles up the family-history context
+(the entity concept already says "family history of"; the value should be the
+*plain* condition, e.g. concept 4182210 "Dementia", not 4326002). Search for the
+plain condition/finding concept for the value, the same as you would if mapping
+the condition directly in CONDITION_OCCURRENCE, and pair it with the 4167217
+entity concept.
+
+## What not to do
+
+- Do not map "history of MI" to the myocardial infarction concept in
+  CONDITION_OCCURRENCE. The distinction between current condition and reported
+  history is clinically and analytically important.
+- Do not leave value_as_concept_id empty. If the condition cannot be mapped,
+  the item is unmappable — do not create a partial record with only the history
+  entity concept.
+
+## Downstream implications
+
+CONDITION_OCCURRENCE is not populated for history-of items. Cohort definitions
+and prevalence queries that rely on CONDITION_OCCURRENCE will not count these
+records. Analysts querying "ever had condition X" must also search OBSERVATION
+for history-of records if the source data uses history-of phrasing.

groundworkers-0.3.3/src/groundworkers/knowledge/packs/core/history-of-event/manifest.yaml

@@ -0,0 +1,18 @@
+name: history-of-event
+layer: core
+version: "1.0"
+shareability: public
+scope_summary: >
+  OMOP model for source items describing a patient's history of a clinical event.
+  Source labels with "history of" phrasing always map to OBSERVATION 4214956 (History
+  of event) with the actual condition or finding in value_as_concept_id — never to
+  CONDITION_OCCURRENCE. Includes family history variant.
+
+mechanisms:
+  - context-inject
+
+applicability:
+  always: true
+
+see_also:
+  - value-representation

groundworkers-0.3.3/src/groundworkers/knowledge/packs/core/standard-concept-preference/guidance.md

@@ -0,0 +1,55 @@
+# Standard Concept Selection
+
+## Concepts must be active
+
+Before selecting any standard concept as a mapping target, verify it is active:
+- `INVALID_REASON IS NULL` (not deprecated, not updated, not deleted)
+- `VALID_END_DATE = 2099-12-31` (OHDSI convention for currently active concepts)
+
+Deprecated concepts (INVALID_REASON = 'D') and concepts that have been replaced
+(INVALID_REASON = 'U') must not be used as mapping targets, even if they have
+standard_concept = 'S'. For replaced concepts, follow the `Maps to` relationship
+from the deprecated concept to find its active successor.
+
+## Standard concepts are required for entity fields
+
+A concept is standard when standard_concept = 'S' in the CONCEPT table.
+All entity concept fields (condition_concept_id, measurement_concept_id,
+observation_concept_id, drug_concept_id, etc.) must be populated with
+standard concepts only.
+
+Non-standard concepts belong in source_concept_id, not entity concept fields.
+
+## Classification concepts are not valid mapping targets
+
+Concepts with standard_concept = 'C' are classification nodes — they exist in
+the hierarchy to support ancestor queries but are not intended as direct mapping
+targets. If a candidate search returns a classification concept, look at its
+standard descendants to find the appropriate specific concept.
+
+## Vocabulary precedence by domain
+
+When multiple vocabularies offer standard concepts for the same clinical entity,
+prefer by domain:
+
+**Condition**: SNOMED CT preferred. ICD-10CM/ICD-9CM are non-standard and require
+a "Maps to" relationship to reach the standard SNOMED target.
+
+**Drug**: RxNorm preferred. RxNorm Extension covers drugs not yet in core RxNorm;
+use it only when no RxNorm equivalent exists for the same clinical drug.
+
+**Measurement**: LOINC preferred for lab tests and clinical assessments with
+established LOINC codes. SNOMED for findings without LOINC representation.
+
+**Procedure**: SNOMED preferred for clinical EHR data. CPT4 preferred for US
+procedural billing or claims context.
+
+**Observation**: SNOMED preferred. LOINC for social and functional observations
+that have LOINC panel/question codes.
+
+## Zero concept
+
+When no suitable standard concept exists, use concept_id = 0 (no matching concept).
+Do not use a non-standard concept as a fallback for an entity concept field.
+concept_id = 0 is the explicit signal that mapping was not possible; it is
+preferable to a misleading non-standard concept.

groundworkers-0.3.3/src/groundworkers/knowledge/packs/core/standard-concept-preference/manifest.yaml

@@ -0,0 +1,16 @@
+name: standard-concept-preference
+layer: core
+version: "1.0"
+shareability: public
+scope_summary: >
+  Rules for selecting standard concepts as mapping targets: standard_concept='S'
+  required for entity fields, classification concepts ('C') are not valid targets,
+  and vocabulary precedence by domain (SNOMED for conditions, RxNorm over RxNorm
+  Extension for drugs, LOINC for measurements).
+
+mechanisms:
+  - context-inject
+  - post-filter
+
+applicability:
+  always: true