@peopl-health/nexus 5.71.5 → 5.71.6

package/lib/clinical/helpers/gradeEstimateHelper.js

@@ -68,16 +68,16 @@ function gradeEstimateSchema(description) {
       functional_anchor: {
         type: 'string',
         enum: FUNCTIONAL_ANCHORS,
-        description: 'What you ESTABLISHED about function, not what the clause says. Required whenever the rubric clause for your grade turns on ADL — grade 2 on instrumental ADL, grade 3 on self-care. `instrumental_adl_limited`: they told you the symptom stops them cooking, working, shopping, driving. `self_care_adl_limited`: it stops them bathing, dressing, feeding themselves. `not_limited`: you asked and it does NOT limit them — then that grade is ruled out, so assign the grade below rather than widening the range. `not_established`: you have not asked — then that grade is not yours to assert yet: put the grade below in best_estimate and leave the higher one live in possible_range. The exception is a grade the case already holds on a limitation established earlier in this same episode: there `not_established` just means you did not re-ask, and the grade stands.',
+        description: 'What you ESTABLISHED about function, not what the clause says. Required whenever the rubric clause for your grade turns on ADL — grade 2 on instrumental ADL, grade 3 on self-care. `instrumental_adl_limited`: they told you the symptom stops them cooking, working, shopping, driving. `self_care_adl_limited`: it stops them bathing, dressing, feeding themselves. `not_limited`: you asked and it does NOT limit them — the grade then stands only on another part of its clause (regular laxatives, moderate pain, a measured value); with nothing else met, record the grade below. `not_established`: you have not asked. Grade from the whole clause and the whole picture — a non-functional part of the clause that is met, or intensity, regimen, cycle day and trajectory that make that grade the most likely one — name in reasoning what supports it, keep the grade below in possible_range, and ask the patient the one functional question that would confirm it in your reply. Missing ADL information is not evidence that function is preserved, and it never moves a grade more than one step above what the evidence strictly shows. When the clause names a specific finding — manual evacuation indicated, at rest, IV fluids, hospitalization — that grade needs that finding: intensity words alone do not reach it, so record the grade the evidence meets and keep the higher one in possible_range.',
       },
       improvement_basis: {
         type: ['string', 'null'],
-        description: 'REQUIRED when best_estimate is lower than the grade this case already holds. Name the finding that no longer holds, in the patient\'s own terms — what they can do again, or the symptom that stopped. A grade only comes down when something specific resolved; "mejoró un poco" is not that, and neither is the absence of new complaints.',
+        description: 'REQUIRED when best_estimate is lower than the grade this case already holds. Name the finding that no longer holds, in the patient\'s own terms — what they can do again, or the symptom that stopped. A grade only comes down when something specific resolved; "mejoró un poco" is not that, and neither is the absence of new complaints. Correcting an over-call is the same: name the finding that rules the higher grade out ("cocina y trabaja como siempre").',
       },
       source: {
         type: 'string',
         enum: GRADE_SOURCES,
-        description: 'Where this grade came from. Required whenever you set best_estimate. `proctcae_composite`: you are carrying over the number the PRO-CTCAE triage already computed — say this even when you agree with it. `agent_adjudicated`: you read the grade_scale clauses yourself against what the patient said. `carried_forward`: the case\'s previous grade, unchanged, with no new evidence this turn.',
+        description: 'Where this grade came from. Required whenever you set best_estimate. `proctcae_composite`: you are carrying over the number the PRO-CTCAE triage already computed — say this even when you agree with it. When what the patient tells you this turn contradicts that number (they can do today what the questionnaire said they could not), what they tell you now wins: grade it yourself as `agent_adjudicated`. `agent_adjudicated`: you read the grade_scale clauses yourself against what the patient said. `carried_forward`: the case\'s previous grade, unchanged, with no new evidence this turn.',
       },
       matched_grade: {
         type: ['integer', 'null'],

package/lib/clinical/services/gradeAnchorService.js

@@ -18,21 +18,37 @@ function hasCuratedLadder(ctcaeTerm) {
   }
 }
 
-function anchorLeanedOnBy(ctcaeTerm, grade) {
-  if (!ctcaeTerm || !Number.isInteger(grade) || grade < 2) return null;
-  let clause = null;
+function gradeClause(ctcaeTerm, grade) {
   try {
-    clause = getCtcaeCatalog().getGradeScale(ctcaeTerm)?.[String(grade)]?.description || null;
+    return getCtcaeCatalog().getGradeScale(ctcaeTerm)?.[String(grade)]?.description || null;
   } catch {
     return null;
   }
+}
+
+function anchorLeanedOnBy(ctcaeTerm, grade) {
+  if (!ctcaeTerm || !Number.isInteger(grade) || grade < 2) return null;
+  const clause = gradeClause(ctcaeTerm, grade);
   if (!clause) return null;
   if (SELF_CARE.test(clause)) return 'self_care';
   if (INSTRUMENTAL.test(clause)) return 'instrumental';
   return null;
 }
 
-function gradeAnchorError({ ctcaeTerm, grade, anchor, possibleRange, previous = null, continuesEpisode = false }) {
+// CTCAE clauses list criteria separated by ';' — 'regular use of laxatives; limiting instrumental ADL'
+// is met by either part. Only a clause with nothing but the ADL part is ruled out by 'not_limited'.
+function clauseHasNonFunctionalCriterion(ctcaeTerm, grade) {
+  const clause = gradeClause(ctcaeTerm, grade) || '';
+  return clause.split(';').some((part) => part.trim() && !SELF_CARE.test(part) && !INSTRUMENTAL.test(part));
+}
+
+// 'not_limited' rules the functional part out; so does an instrumental-only limitation for a grade
+// whose clause turns on self-care.
+function rulesOutFunctionalPart(leaned, anchor) {
+  return anchor === 'not_limited' || (leaned === 'self_care' && anchor === 'instrumental_adl_limited');
+}
+
+function gradeAnchorError({ ctcaeTerm, grade, anchor }) {
   const leaned = anchorLeanedOnBy(ctcaeTerm, grade);
   if (!leaned) return null;
   const named = leaned === 'self_care' ? 'self-care' : 'instrumental';
@@ -40,24 +56,30 @@ function gradeAnchorError({ ctcaeTerm, grade, anchor, possibleRange, previous =
     return `functional_anchor is required for grade ${grade} of ${ctcaeTerm}: its rubric clause turns on ${named} ADL. `
       + `Say what you established — ${FUNCTIONAL_ANCHORS.join(', ')} — rather than restating the clause.`;
   }
-  if (SATISFIED_BY[leaned].has(anchor)) return null;
-  // The case already holds this grade on an anchor established earlier. 'not_established' here
-  // says "I did not re-ask this turn", not "nobody ever established it" — holding is honest.
-  if (anchor === 'not_established' && continuesEpisode && previous
-    && previous.bestEstimate === grade && SATISFIED_BY[leaned].has(previous.functionalAnchor)) return null;
-  const below = grade - 1;
-  if (anchor === 'not_limited') {
-    return `functional_anchor is 'not_limited', so the ${named} ADL limitation that grade ${grade} of ${ctcaeTerm} turns on is ruled OUT, not merely unknown. `
-      + `Assign grade ${below} — the highest grade whose clause the evidence actually satisfies.`;
+  if (rulesOutFunctionalPart(leaned, anchor) && !clauseHasNonFunctionalCriterion(ctcaeTerm, grade)) {
+    return `functional_anchor is '${anchor}', which rules out the ${named} ADL limitation that is the only criterion of grade ${grade} of ${ctcaeTerm}. `
+      + 'Record the grade whose clause the evidence does meet.';
+  }
+  return null;
+}
+
+// Advice, not a verdict: the grade stands as recorded and the agent learns what would confirm it.
+function gradeAnchorNotice({ ctcaeTerm, grade, anchor }) {
+  const leaned = anchorLeanedOnBy(ctcaeTerm, grade);
+  if (!leaned || !anchor || SATISFIED_BY[leaned].has(anchor)) return null;
+  const named = leaned === 'self_care' ? 'self-care' : 'instrumental';
+  if (rulesOutFunctionalPart(leaned, anchor)) {
+    return `Grade ${grade} of ${ctcaeTerm} can only stand on the non-functional part of its clause: the patient is not limited in ${named} ADL. `
+      + '`reasoning` must name that criterion; if it is not met, record the grade below.';
   }
-  const top = Array.isArray(possibleRange) ? possibleRange[1] : grade;
-  return `functional_anchor is '${anchor}', so the ${named} ADL limitation that grade ${grade} of ${ctcaeTerm} turns on is not established. `
-    + `best_estimate is the grade the evidence already carries, not the one it might reach: assign ${below} and keep ${grade} live as possible_range [${below}, ${top}]. `
-    + `Establish the ${named} ADL limitation and ${grade} becomes assertable.`;
+  return `Grade ${grade} of ${ctcaeTerm} was recorded without the ${named} ADL limitation its clause mentions. `
+    + 'That is fine when another part of the clause is met or the whole picture makes it the most likely grade — `reasoning` must name which. '
+    + 'Ask the patient the one functional question that would confirm it in your reply, and keep the grade below in possible_range.';
 }
 
 module.exports = {
   hasCuratedLadder,
   anchorLeanedOnBy,
   gradeAnchorError,
+  gradeAnchorNotice,
 };

package/lib/clinical/services/gradeClaimService.js

@@ -1,5 +1,5 @@
-const { CARRIED_FORWARD, parseGradeEstimate } = require('../helpers/gradeEstimateHelper');
-const { gradeAnchorError, hasCuratedLadder, anchorLeanedOnBy } = require('./gradeAnchorService');
+const { CARRIED_FORWARD } = require('../helpers/gradeEstimateHelper');
+const { gradeAnchorError, gradeAnchorNotice, hasCuratedLadder } = require('./gradeAnchorService');
 const { gradeSourceError, carriedForwardError } = require('./gradeSourceService');
 
 // A resolution names a finding. Length is not the test: 'ya come' names one and 'mejoró un poco'
@@ -14,16 +14,11 @@ const namesAResolution = (basis) => {
 };
 
 const GUARDS = [
-  ({ ctcaeTerm, grade, previous, recordsOngoingRead }) => {
+  ({ grade, previous, recordsOngoingRead }) => {
     if (!recordsOngoingRead) return null;
     const now = grade.bestEstimate;
     const before = previous && previous.bestEstimate;
     if (!Number.isInteger(now) || !Number.isInteger(before) || now >= before) return null;
-    // Only 'not_established' is exempt. It means the question was not asked, so the drop is the
-    // anchor guard's own remediation rather than a claim that anything got better. 'not_limited'
-    // is the opposite: the question WAS asked and the limitation is gone — a finding, and the
-    // thing this field exists to record.
-    if (grade.functionalAnchor === 'not_established' && now === before - 1 && anchorLeanedOnBy(ctcaeTerm, before)) return null;
     if (namesAResolution(grade.improvementBasis)) return null;
     return `best_estimate ${now} is below the grade ${before} this case already holds, so this call records an improvement. `
       + 'Name what resolved in `improvement_basis`: the finding that no longer holds, in the patient\'s own terms — a placeholder is not one. '
@@ -50,13 +45,10 @@ const GUARDS = [
     hasLadder: hasCuratedLadder(ctcaeTerm),
     trace,
   }),
-  ({ ctcaeTerm, grade, previous, continuesEpisode }) => gradeAnchorError({
+  ({ ctcaeTerm, grade }) => gradeAnchorError({
     ctcaeTerm,
     grade: grade.bestEstimate ?? null,
     anchor: grade.functionalAnchor ?? null,
-    possibleRange: grade.possibleRange ?? null,
-    previous,
-    continuesEpisode,
   }),
 ];
 
@@ -70,4 +62,12 @@ function gradeClaimError({ ctcaeTerm, grade, stated = null, previous = null, res
   return null;
 }
 
-module.exports = { gradeClaimError };
+function gradeClaimNotice({ ctcaeTerm, grade }) {
+  return gradeAnchorNotice({
+    ctcaeTerm,
+    grade: grade?.bestEstimate ?? null,
+    anchor: grade?.functionalAnchor ?? null,
+  });
+}
+
+module.exports = { gradeClaimError, gradeClaimNotice };

package/lib/clinical/tools/openConditionTool.js

@@ -4,7 +4,7 @@ const { GRADE_CONFIDENCE_LEVELS, GRADE_MIN, GRADE_MAX, gradeEstimateSchema, pars
 const { ceilingGapError } = require('../helpers/ceilingGapHelper');
 const { mentionProvenanceError } = require('../helpers/evidenceAnchorHelper');
 const { ctcaeTermError } = require('../services/ctcaeTermService');
-const { gradeClaimError } = require('../services/gradeClaimService');
+const { gradeClaimError, gradeClaimNotice } = require('../services/gradeClaimService');
 const { armOpenCeilingNet } = require('../services/contingencyDispatchService');
 const { readSymptomCases, storeSymptomCase } = require('../../fhir');
 const { ManagedSymptom, OPEN_STATUSES, CLOSED_STATUSES, FUNCTIONAL_ANCHORS } = require('../../shared/dtos/ManagedSymptom');
@@ -13,7 +13,7 @@ const { isArmOnOpenCeilingLive } = require('../flags/contingencyFlags');
 
 const definition = {
   name: 'openCondition',
-  description: '**Does:** Opens a NEW agent-tracked symptom case (Condition + initial ClinicalImpression) for a symptom term with no open case — the longitudinal expediente that groups 1..N episodes of the same `ctcae_term`.\n\n**Required inputs:** `ctcae_term` (English snake_case catalog key — e.g. `fever`, `pain`, `dyspnea`; use `other` only when no catalog term fits), `episode_id` (the intake episode this case wraps), `mention_id` (the intake mention that opened the case), `verbatim_quote` (exact substring of the patient message). Optional `temporality`, `grade_estimate` (`{best_estimate, confidence, possible_range, reasoning}`).\n\n**When to call:** when the turn surfaces a symptom with no open case on this `ctcae_term`. Use `recordClinicalImpression` if a case is already open — do NOT call `openCondition` twice for the same symptom.\n\n**When NOT to call:**\n- For a new episode or subsequent assessment of an EXISTING open case — use `recordClinicalImpression`.\n- For a symptom that already has a case which was closed, resolved or deactivated — the same symptom returning is a recurrence of that case, not a new one. Reopen it with `updateConditionStatus(transition=\'reactivate\')`. This tool refuses the duplicate with `DORMANT_CASE_EXISTS` and names the case.\n\n**Returns:** `case_id`, `action_taken` (`opened`), `status`, `ctcae_term`, `episode_ids`, `current_episode_id`, `grade_estimate`, `temporality`, `trajectory`. Fails hard with `case_already_open_for_term` + `existing_case_id` when an open case already exists for the term — recover via `recordClinicalImpression`.\n\n**Side effects:** writes a FHIR `Condition` + head `ClinicalImpression` + `Provenance`.',
+  description: '**Does:** Opens a NEW agent-tracked symptom case (Condition + initial ClinicalImpression) for a symptom term with no open case — the longitudinal expediente that groups 1..N episodes of the same `ctcae_term`.\n\n**Required inputs:** `ctcae_term` (English snake_case catalog key — e.g. `fever`, `pain`, `dyspnea`; use `other` only when no catalog term fits), `episode_id` (the intake episode this case wraps), `mention_id` (the intake mention that opened the case), `verbatim_quote` (exact substring of the patient message). Optional `temporality`, `grade_estimate` (`{best_estimate, confidence, possible_range, reasoning}`).\n\n**When to call:** when the turn surfaces a symptom with no open case on this `ctcae_term`. Use `recordClinicalImpression` if a case is already open — do NOT call `openCondition` twice for the same symptom.\n\n**When NOT to call:**\n- For a new episode or subsequent assessment of an EXISTING open case — use `recordClinicalImpression`.\n- For a symptom that already has a case which was closed, resolved or deactivated — the same symptom returning is a recurrence of that case, not a new one. Reopen it with `updateConditionStatus(transition=\'reactivate\')`. This tool refuses the duplicate with `DORMANT_CASE_EXISTS` and names the case.\n\n**Returns:** `case_id`, `action_taken` (`opened`), `status`, `ctcae_term`, `episode_ids`, `current_episode_id`, `grade_estimate`, `temporality`, `trajectory`, and `grade_notice` when the grade was recorded without the ADL limitation its clause mentions — advisory: the grade was stored as given. Fails hard with `case_already_open_for_term` + `existing_case_id` when an open case already exists for the term — recover via `recordClinicalImpression`.\n\n**Side effects:** writes a FHIR `Condition` + head `ClinicalImpression` + `Provenance`.',
   strict: false,
   parameters: {
     type: 'object',
@@ -125,6 +125,7 @@ async function handler(args = {}, context = {}) {
     const gradesTheCase = hasGradeSignal(args?.grade_estimate);
     const claimGap = gradesTheCase ? gradeClaimError({ ctcaeTerm, grade, trace: runtime?.trace || null }) : null;
     if (claimGap) return JSON.stringify({ success: false, error: claimGap, data: {} });
+    const gradeNotice = gradesTheCase ? gradeClaimNotice({ ctcaeTerm, grade }) : null;
     const ceilingGap = gradesTheCase ? ceilingGapError(args, 'openCondition') : null;
     if (ceilingGap) return JSON.stringify({ success: false, error: ceilingGap, data: {} });
     const managedSymptom = new ManagedSymptom({
@@ -183,6 +184,7 @@ async function handler(args = {}, context = {}) {
         grade_estimate: projectGradeEstimate(latestAssessment.grade),
         temporality: condition.temporality,
         trajectory: { direction: latestAssessment.trajectory || 'unknown' },
+        ...(gradeNotice ? { grade_notice: gradeNotice } : {}),
       },
     });
   } catch (err) {

package/lib/clinical/tools/recordClinicalImpressionTool.js

@@ -5,7 +5,7 @@ const { ceilingGapError } = require('../helpers/ceilingGapHelper');
 const { mentionProvenanceError } = require('../helpers/evidenceAnchorHelper');
 const { MEDICATION_NAMING_RULE } = require('../helpers/medicationNamingRule');
 const { resolveCloseReason, closePatch, runCloseCascade } = require('../services/conditionCloseService');
-const { gradeClaimError } = require('../services/gradeClaimService');
+const { gradeClaimError, gradeClaimNotice } = require('../services/gradeClaimService');
 const { armOpenCeilingNet } = require('../services/contingencyDispatchService');
 const { inputConsistency, statedReasoning } = require('../services/impressionValidationService');
 const { isArmOnOpenCeilingLive } = require('../flags/contingencyFlags');
@@ -15,7 +15,7 @@ const { logger } = require('../../utils/logger');
 
 const definition = {
   name: 'recordClinicalImpression',
-  description: '**Does:** Evolves an existing symptom case by `event`. `add_evidence`: new mention on the current episode (requires `characterizing` + a grade or trajectory). `new_episode`: a new episode for the same `ctcae_term` — attaches it and returns the case to `characterizing`. `resolve_episode`: the current episode resolved — case goes to `monitoring`. `close`: terminal — status `closed`, requires `close_reason` from the closed vocabulary.\n\nAn impression is a grading act plus the reasoning behind it: `grade_estimate` carries your most likely grade with its confidence and range, and `reasoning` names, in one or two sentences, what you think is going on. `reasoning` is REQUIRED on every call and is the canonical per-case rationale — it lands on the clinical record, and the routing trace references it rather than restating it. Omitting it does not fail the write, but the impression is then a grade with no clinical reasoning behind it and the envelope says so in `input_consistency`. Grade-specific justification (the matched `grade_scale` clause) belongs inside `grade_estimate.reasoning`.\n\n**Required inputs:** `case_id` (from `openCondition` or `getActiveSymptomLandscape`), `event`, `reasoning`. Per-event: `add_evidence`/`new_episode` require `mention_id`, `missing_for_higher_grade`, plus at least one of `grade_estimate` or `trajectory_direction`; `new_episode` also requires `episode_id`; `close` requires `close_reason`, and it must be one of `resolved` | `team_resolved` | `resolved_spontaneously` | `resolved_by_intervention` (the symptom ENDED — this stamps `abatement_at`) or `escalated_to_team` | `patient_transferred` | `stale_no_activity` (stop tracking WITHOUT claiming an end — `abatement_at` stays null). Never claim a resolution nobody observed; free text is rejected.\n\n**Returns:** `case_id`, `action_taken`, `status`, `ctcae_term`, `episode_ids`, `current_episode_id`, `mention_ids`, `grade_estimate`, `temporality`, `trajectory`, `decision_posture`, `close_reason`, `abatement_at`, plus `input_consistency` when the call under-specified something. Fails hard on status guards (e.g. `add_evidence` on a non-`characterizing` case), duplicate `mention_id`, or an already-attached `episode_id`.\n\n**Side effects:** appends a FHIR `ClinicalImpression` to the case chain and repoints the head; updates the `Condition` lifecycle. `close` also retires any contingency net guarding the case (returned as `auto_resolved_contingency_plans`) — a closed case never keeps writing to the patient — and prunes the case from its active clusters, dissolving one that drops below 2 members (`pruned_clusters`, `dissolved_clusters`).',
+  description: '**Does:** Evolves an existing symptom case by `event`. `add_evidence`: new mention on the current episode (requires `characterizing` + a grade or trajectory). `new_episode`: a new episode for the same `ctcae_term` — attaches it and returns the case to `characterizing`. `resolve_episode`: the current episode resolved — case goes to `monitoring`. `close`: terminal — status `closed`, requires `close_reason` from the closed vocabulary.\n\nAn impression is a grading act plus the reasoning behind it: `grade_estimate` carries your most likely grade with its confidence and range, and `reasoning` names, in one or two sentences, what you think is going on. `reasoning` is REQUIRED on every call and is the canonical per-case rationale — it lands on the clinical record, and the routing trace references it rather than restating it. Omitting it does not fail the write, but the impression is then a grade with no clinical reasoning behind it and the envelope says so in `input_consistency`. Grade-specific justification (the matched `grade_scale` clause) belongs inside `grade_estimate.reasoning`.\n\n**Required inputs:** `case_id` (from `openCondition` or `getActiveSymptomLandscape`), `event`, `reasoning`. Per-event: `add_evidence`/`new_episode` require `mention_id`, `missing_for_higher_grade`, plus at least one of `grade_estimate` or `trajectory_direction`; `new_episode` also requires `episode_id`; `close` requires `close_reason`, and it must be one of `resolved` | `team_resolved` | `resolved_spontaneously` | `resolved_by_intervention` (the symptom ENDED — this stamps `abatement_at`) or `escalated_to_team` | `patient_transferred` | `stale_no_activity` (stop tracking WITHOUT claiming an end — `abatement_at` stays null). Never claim a resolution nobody observed; free text is rejected.\n\n**Returns:** `case_id`, `action_taken`, `status`, `ctcae_term`, `episode_ids`, `current_episode_id`, `mention_ids`, `grade_estimate`, `temporality`, `trajectory`, `decision_posture`, `close_reason`, `abatement_at`, plus `input_consistency` when the call under-specified something, and `grade_notice` when the grade was recorded without the ADL limitation its clause mentions — advisory: the grade was stored as given. Fails hard on status guards (e.g. `add_evidence` on a non-`characterizing` case), duplicate `mention_id`, or an already-attached `episode_id`.\n\n**Side effects:** appends a FHIR `ClinicalImpression` to the case chain and repoints the head; updates the `Condition` lifecycle. `close` also retires any contingency net guarding the case (returned as `auto_resolved_contingency_plans`) — a closed case never keeps writing to the patient — and prunes the case from its active clusters, dissolving one that drops below 2 members (`pruned_clusters`, `dissolved_clusters`).',
   strict: false,
   parameters: {
     type: 'object',
@@ -351,6 +351,8 @@ async function handler(args = {}, context = {}) {
 
     const { condition, latestAssessment } = result;
     const consistency = inputConsistency(args);
+    const freshRead = ONGOING_READ_EVENTS.includes(event) && hasGradeSignal(args?.grade_estimate) && !isCarriedForward(args.grade_estimate);
+    const gradeNotice = freshRead ? gradeClaimNotice({ ctcaeTerm: condition.ctcaeTerm, grade: latestAssessment.grade }) : null;
     return JSON.stringify({
       success: true,
       data: {
@@ -371,6 +373,7 @@ async function handler(args = {}, context = {}) {
         close_reason: condition.closeReason,
         abatement_at: condition.abatementAt,
         ...(consistency.length ? { input_consistency: consistency } : {}),
+        ...(gradeNotice ? { grade_notice: gradeNotice } : {}),
       },
     });
   } catch (err) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@peopl-health/nexus",
-  "version": "5.71.5",
+  "version": "5.71.6",
   "description": "Core messaging and assistant library for WhatsApp communication platforms",
   "keywords": [
     "whatsapp",