change prompt handling

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

@@ -2,9 +2,25 @@
 
 ## 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.
+For an entity concept field, route the record using the `domain_id` of the
+selected, active standard mapping target. Do not infer the destination table
+from the source vocabulary, source code, source table, or caller hint when a
+valid standard target is available.
 
-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.
+For example, if a source item coded as a procedure maps to an active standard
+Drug concept, the entity belongs in `DRUG_EXPOSURE`. If an item that looks like
+a diagnosis maps to an active standard Measurement concept, it belongs in
+`MEASUREMENT`. The selected entity target's domain determines the table.
+
+Check that a proposed target is both standard (`standard_concept = 'S'`) and
+active before using its domain for routing. A target that is retired, updated,
+or a classification concept (`standard_concept = 'C'`) is not a valid entity
+target.
+
+If mapping produces multiple targets, or no valid standard target, do not
+silently choose a table based on one candidate. Preserve the source item and
+mapping evidence, flag the unresolved or multi-target decision, and use the
+fallback rule below only when a record still needs to be written.
 
 ## Domain → CDM table mapping
 
@@ -20,21 +36,30 @@ A source item coded as a procedure that maps to an RxNorm Ingredient goes to `DR
 | Visit | VISIT_OCCURRENCE |
 | Provider | PROVIDER |
 
-## Scope: the entity concept only
+## Scope: entity concepts versus value concepts
+
+This routing rule applies to the entity concept field — the concept that
+identifies the record, such as `condition_concept_id`,
+`measurement_concept_id`, or `observation_concept_id`.
+
+It does not route on `value_as_concept_id` or another subordinate value field.
+A value concept may have a different domain from the entity and the CDM table.
+For example, personal history may be represented by the Observation-domain
+`History of event` concept in `observation_concept_id`, with a Condition- or
+Procedure-domain concept in `value_as_concept_id`. Family history may instead
+use a pre-coordinated family-history concept in `observation_concept_id`.
 
-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.
+Do not create a Condition or Procedure row, or change the table, solely because
+a history value has that domain. Preserve the history, family relationship,
+negation, and temporal meaning represented by the source and mapping pattern.
 
 ## 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.
+If no active standard target is available, use `*_concept_id = 0` rather than
+NULL or an inactive/non-standard fallback. When a record must still be placed
+in a CDM table, use the best available domain signal from the source vocabulary,
+source table, and caller context. Treat that as a fallback decision, document
+it, and preserve the original source value for 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.
 

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

@@ -27,25 +27,119 @@ 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
+## Verify both ends of a mapping
 
-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.
+Before using a relationship to select an entity target, check the target
+concept itself:
+
+- It must be standard (`standard_concept = 'S'`), not a classification concept.
+- It must be active (`invalid_reason IS NULL` and
+  `valid_end_date = 2099-12-31`).
+
+A valid relationship row does not guarantee a valid target concept. In
+particular, `valid = true` describes the relationship row; it does not mean
+the target concept is active or standard. If a `Maps to` target is retired or
+updated, follow the replacement only when an active, standard successor is
+available. Otherwise preserve the source and flag the mapping for review.
+
+When a source maps to multiple targets, check whether the mapping is
+one-to-many by design. Preserve all supported targets and their roles; do not
+silently collapse them into one target or treat them as interchangeable.
+
+## Interpret relationship types narrowly
+
+Use each relationship only for the claim it supports:
+
+- `Maps to` identifies a mapping target. Verify that target before using it.
+- `Maps to value` supplies a value for a mapped entity; it does not replace
+  the entity target or determine the record's CDM table.
+- `Is a` expresses hierarchy. It may support ancestor or descendant queries,
+  but does not establish an exact mapping or equivalence.
+- Attribute relationships describe properties of a concept. They do not, by
+  themselves, establish identity or a mapping.
+- Equivalence-like or informational relationships such as `eq`, `cat`, and
+  `poss_eq` are evidence to inspect, not mapping instructions. Check their
+  meaning and specificity before using them.
+
+Do not treat metadata relationships as clinical meaning. For example,
+`Has status` describes SNOMED definition status, and `Has Module` identifies
+a module; neither is a clinical attribute or an identity path.
+
+## Preserve source meaning and qualifiers
+
+Keep the original source code and source value available when selecting or
+reviewing a target. A mapping may lose detail that matters for analysis; do
+not assume that laterality, approach, timing, status, negation, or other
+qualifiers survive unless the target explicitly represents them.
+
+For one-to-many mappings, preserve the role of each target. Do not assume the
+targets are interchangeable or that they mean the source concepts occurred
+together.
+
+For disjunctive source items such as “A or B”, do not map to both A and B as
+though both occurred. Prefer a target that preserves the disjunction; if none
+is available, use the least specific faithful target or flag the item for
+review.
+
+Do not assume hierarchy-based concept sets preserve source meaning across
+vocabularies. Check the relevant vocabulary and hierarchy before relying on
+ancestors or descendants; where coverage or placement is unreliable, retain
+the source code and document the limitation.
+
+Preserve historical, family-history, negated, and status concepts as such.
+Do not turn them into current diagnoses just because a related disease or
+procedure appears as a target or value.
+
+## Vocabulary preference is conditional
+
+Treat vocabulary preference as a tie-breaker between active standard concepts
+that represent the same meaning at the required level of specificity. It is
+not a rule to translate every source code into one preferred vocabulary.
+
+First establish what the source item represents, the target field it will
+populate, and the intended use. Then verify candidate meaning, domain,
+standardness, and active status. Preserve an appropriate active standard
+source concept when it already represents the recorded item. Do not prefer a
+candidate from another vocabulary solely because its vocabulary is listed
+below.
+
+### Condition
+
+SNOMED is the main clinical Condition backbone. ICD10CM, ICD9CM, and ICD10
+Condition concepts are generally non-standard and require an active `Maps to`
+target. Check one-to-many mappings and preserve source detail that the targets
+do not retain.
+
+ICDO3 histology-by-site combinations are standard Condition concepts in their
+own right. Do not replace them automatically with SNOMED or assume their
+hierarchy reliably captures histology or behaviour.
+
+### Procedure
+
+Do not default to SNOMED. CPT4, HCPCS, ICD10PCS, and ICD9Proc can contain active
+standard Procedure concepts. Preserve the source standard concept when it is
+the appropriate representation for the task, especially for claims or
+administrative data. Use SNOMED when it is the appropriate clinical
+representation, not as an automatic substitute.
+
+Do not assume a hierarchy or an informational equivalence link proves an exact
+mapping. In particular, verify that targets are active and treat
+ICD10PCS-to-SNOMED ancestry as potentially incomplete or misleading.
+
+### Measurement and Observation
+
+Choose based on what was recorded: an instrument, an administered procedure,
+a question or survey item, or a score. Do not assume that concepts for the same
+instrument in different vocabularies share a domain or an exact crosswalk.
+For example, LOINC survey items are in Observation, while SNOMED assessment
+scales are in Measurement. Keep instrument identity, administration, and score
+distinct where the source data distinguishes them.
+
+### Other domains
+
+Keep the existing Drug and other domain preferences as provisional defaults.
+Apply them only when candidates are active and equivalent at the required
+precision; revisit them when domain-specific audit evidence is available.
 
 ## Zero concept
 

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

@@ -1,12 +1,11 @@
 name: standard-concept-preference
 layer: core
-version: "1.0"
+version: "1.1"
 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).
+  with conditional, domain-specific vocabulary selection guidance.
 
 mechanisms:
   - context-inject

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

@@ -1,5 +1,5 @@
-# Standard concept preference rules
-# Consumed by the post-filter mechanism to rank or reject candidates.
+# Standard concept eligibility rules and provisional domain preferences.
+# These rules are currently declarative; see guidance.md for the resolution policy.
 
 active_concept_required:
   # Concepts must be active — not deprecated or replaced.
@@ -27,6 +27,10 @@ vocab_preference:
   - domain: Condition
     prefer: [SNOMED]
     over: [ICD10CM, ICD9CM, ICD10, MedDRA]
+    note: >
+      Tie-breaker only among active standard concepts representing the same
+      meaning at the required specificity. ICDO3 also has standard Condition
+      combinations; do not replace them automatically with SNOMED.
 
   - domain: Drug
     prefer: [RxNorm]
@@ -36,15 +40,18 @@ vocab_preference:
       RxNorm concept exists for the same clinical drug at the same precision level.
 
   - domain: Measurement
-    prefer: [LOINC]
-    secondary: [SNOMED]
+    note: >
+      No blanket ranking. Choose based on whether the source represents a
+      survey item, clinical assessment, finding, or score; verify the candidate
+      domain and preserve the source representation.
 
   - domain: Procedure
-    prefer: [SNOMED]
-    secondary: [CPT4]
     note: >
-      CPT4 is preferred for US procedural billing/claims context.
-      SNOMED preferred for clinical EHR data and non-US sources.
+      No blanket ranking. Standard source concepts in CPT4, HCPCS, ICD10PCS,
+      and ICD9Proc may map to themselves. Use SNOMED only when it is the
+      appropriate representation, not as an automatic replacement.
 
   - domain: Observation
-    prefer: [SNOMED, LOINC]
+    note: >
+      No blanket ranking. Distinguish survey items, observations, history
+      patterns, and other recorded entities by their meaning and target field.