Add sample chain-of-custody review assistant

sample-chain-of-custody-assistant/README.md

@@ -0,0 +1,77 @@
+# Sample Chain-of-Custody Review Assistant
+
+This module adds a deterministic assistant for reviewing wet-lab or clinical sample
+chain-of-custody packets before AI-generated research conclusions are released.
+
+It is scoped to synthetic/sample metadata only. It does not call external APIs,
+does not require credentials, and does not process real participant records.
+
+## Why This Belongs In The AI Research Assistant Suite
+
+AI review and reproducibility tools can miss a basic scientific failure mode:
+the sample used to support a claim may have incomplete custody evidence. This
+assistant checks whether every sample has enough documented handoffs, consent
+links, storage controls, assay-run alignment, and reviewer signoff before the
+project relies on the result.
+
+The assistant emits a deterministic `release`, `revise`, or `hold` decision with
+evidence-linked findings and remediation steps.
+
+## Checks
+
+- Missing consent or participant-link evidence.
+- Custody events with missing actor or signature fields.
+- Time gaps beyond the configured maximum transit window.
+- Storage temperature excursions against the sample's storage spec.
+- Blinding leaks in reviewer-visible metadata.
+- Assay runs that use quarantined samples, mismatched instruments, or missing QC.
+- Conclusions that rely on samples with unresolved high-risk custody findings.
+- Required reviewer signoff before release.
+
+## Usage
+
+```bash
+node sample-chain-of-custody-assistant/src/chain-custody-assistant.mjs \
+  sample-chain-of-custody-assistant/fixtures/sample-custody-packet.json \
+  --format markdown
+```
+
+JSON output:
+
+```bash
+node sample-chain-of-custody-assistant/src/chain-custody-assistant.mjs \
+  sample-chain-of-custody-assistant/fixtures/sample-custody-packet.json \
+  --format json
+```
+
+## Validation
+
+```bash
+node sample-chain-of-custody-assistant/test/run-tests.mjs
+```
+
+Expected result:
+
+```text
+sample chain-of-custody assistant tests passed
+```
+
+## Demo Artifacts
+
+- `demo/sample-report.md`
+- `demo/sample-report.json`
+- `demo/decision-flow.svg`
+- `demo/decision-flow.png`
+- `demo/sample-chain-of-custody-demo.mp4`
+
+## Scope Boundaries
+
+This assistant intentionally avoids:
+
+- live LIMS, EHR, cloud storage, or instrument connections;
+- real participant or patient data;
+- credential handling;
+- legal, medical, or regulatory advice;
+- replacing required human review.
+
+It is a pre-release guardrail that highlights evidence gaps for a reviewer.

sample-chain-of-custody-assistant/demo/sample-report.json

@@ -0,0 +1,119 @@
+{
+  "projectId": "SCI-CHAIN-001",
+  "title": "Cytokine drift after cold-chain interruption",
+  "generatedAt": "2026-06-01T12:00:00Z",
+  "assistant": "sample-chain-of-custody-review",
+  "decision": "hold",
+  "severityCounts": {
+    "critical": 4,
+    "high": 6,
+    "medium": 4,
+    "low": 0
+  },
+  "findings": [
+    {
+      "severity": "critical",
+      "sampleId": "S-1001,S-1002",
+      "check": "conclusion-release-gate",
+      "evidence": "Conclusion C-1 relies on sample(s) with critical custody findings.",
+      "remediation": "Hold this conclusion until critical sample custody issues are resolved."
+    },
+    {
+      "severity": "critical",
+      "sampleId": "S-1002",
+      "check": "assay-qc",
+      "evidence": "assay-run@2026-05-22T18:20:00Z has qcStatus=fail.",
+      "remediation": "Do not release conclusions using this assay until QC failure is resolved or rerun."
+    },
+    {
+      "severity": "critical",
+      "sampleId": "S-1002",
+      "check": "consent-link",
+      "evidence": "No consentId is attached to the sample metadata.",
+      "remediation": "Attach a verified consent record or remove this sample from AI-supported conclusions."
+    },
+    {
+      "severity": "critical",
+      "sampleId": "S-1002",
+      "check": "open-quarantine",
+      "evidence": "Open quarantine: temperature excursion pending QA disposition.",
+      "remediation": "Resolve QA quarantine or remove this sample from conclusions."
+    },
+    {
+      "severity": "high",
+      "sampleId": "S-1001",
+      "check": "blinding-leak",
+      "evidence": "Reviewer-visible fields include group/arm metadata while blindingGroup=exposed.",
+      "remediation": "Mask treatment-arm fields before AI review or document that the review is intentionally unblinded."
+    },
+    {
+      "severity": "high",
+      "sampleId": "S-1002",
+      "check": "blinding-leak",
+      "evidence": "Reviewer-visible fields include group/arm metadata while blindingGroup=exposed.",
+      "remediation": "Mask treatment-arm fields before AI review or document that the review is intentionally unblinded."
+    },
+    {
+      "severity": "high",
+      "sampleId": "S-1002",
+      "check": "reviewer-signoff",
+      "evidence": "No reviewerSignoff record is present.",
+      "remediation": "Obtain accountable QA/reviewer signoff before release."
+    },
+    {
+      "severity": "high",
+      "sampleId": "S-1002",
+      "check": "temperature-excursion",
+      "evidence": "storage@2026-05-22T16:45:00Z recorded 11.7C outside 2C-8C.",
+      "remediation": "Open a QA disposition, document stability impact, and quarantine the sample until resolved."
+    },
+    {
+      "severity": "high",
+      "sampleId": "S-1003",
+      "check": "conclusion-release-gate",
+      "evidence": "Conclusion C-2 relies on sample(s) with high-risk custody findings.",
+      "remediation": "Revise confidence language and require reviewer acceptance before release."
+    },
+    {
+      "severity": "high",
+      "sampleId": "S-1003",
+      "check": "required-custody-event",
+      "evidence": "Missing required custody event: assay-run.",
+      "remediation": "Add a signed assay-run custody event or exclude this sample from release."
+    },
+    {
+      "severity": "medium",
+      "sampleId": "S-1002",
+      "check": "custody-time-gap",
+      "evidence": "collect to accession gap is 7.8 hours.",
+      "remediation": "Add intermediate courier/storage handoff evidence or downgrade conclusions that rely on this sample."
+    },
+    {
+      "severity": "medium",
+      "sampleId": "S-1002",
+      "check": "handoff-signature",
+      "evidence": "accession@2026-05-22T16:30:00Z is missing actor or signature evidence.",
+      "remediation": "Add a signed handoff record with accountable actor and timestamp."
+    },
+    {
+      "severity": "medium",
+      "sampleId": "S-1002",
+      "check": "required-custody-event",
+      "evidence": "Missing required custody event: archive.",
+      "remediation": "Add a signed archive custody event or exclude this sample from release."
+    },
+    {
+      "severity": "medium",
+      "sampleId": "S-1003",
+      "check": "custody-time-gap",
+      "evidence": "storage to archive gap is 6.5 hours.",
+      "remediation": "Add intermediate courier/storage handoff evidence or downgrade conclusions that rely on this sample."
+    }
+  ],
+  "researchGapPrompts": [
+    "Which biomarkers remain stable after the observed cold-chain excursion window?",
+    "Would blinded AI review change the severity or interpretation of the reported effect?",
+    "What courier or intermediate storage metadata should be captured to close shipment evidence gaps?",
+    "Can the failed assay be rerun from archived aliquots, or should the conclusion be limited to unaffected samples?"
+  ]
+}

sample-chain-of-custody-assistant/demo/sample-report.md

@@ -0,0 +1,105 @@
+# Sample Chain-of-Custody Review: SCI-CHAIN-001
+
+Title: Cytokine drift after cold-chain interruption
+Decision: HOLD
+
+## Severity Counts
+
+- Critical: 4
+- High: 6
+- Medium: 4
+- Low: 0
+
+## Findings
+
+### [CRITICAL] conclusion-release-gate
+
+- Sample/conclusion: S-1001,S-1002
+- Evidence: Conclusion C-1 relies on sample(s) with critical custody findings.
+- Remediation: Hold this conclusion until critical sample custody issues are resolved.
+
+### [CRITICAL] assay-qc
+
+- Sample/conclusion: S-1002
+- Evidence: assay-run@2026-05-22T18:20:00Z has qcStatus=fail.
+- Remediation: Do not release conclusions using this assay until QC failure is resolved or rerun.
+
+### [CRITICAL] consent-link
+
+- Sample/conclusion: S-1002
+- Evidence: No consentId is attached to the sample metadata.
+- Remediation: Attach a verified consent record or remove this sample from AI-supported conclusions.
+
+### [CRITICAL] open-quarantine
+
+- Sample/conclusion: S-1002
+- Evidence: Open quarantine: temperature excursion pending QA disposition.
+- Remediation: Resolve QA quarantine or remove this sample from conclusions.
+
+### [HIGH] blinding-leak
+
+- Sample/conclusion: S-1001
+- Evidence: Reviewer-visible fields include group/arm metadata while blindingGroup=exposed.
+- Remediation: Mask treatment-arm fields before AI review or document that the review is intentionally unblinded.
+
+### [HIGH] blinding-leak
+
+- Sample/conclusion: S-1002
+- Evidence: Reviewer-visible fields include group/arm metadata while blindingGroup=exposed.
+- Remediation: Mask treatment-arm fields before AI review or document that the review is intentionally unblinded.
+
+### [HIGH] reviewer-signoff
+
+- Sample/conclusion: S-1002
+- Evidence: No reviewerSignoff record is present.
+- Remediation: Obtain accountable QA/reviewer signoff before release.
+
+### [HIGH] temperature-excursion
+
+- Sample/conclusion: S-1002
+- Evidence: storage@2026-05-22T16:45:00Z recorded 11.7C outside 2C-8C.
+- Remediation: Open a QA disposition, document stability impact, and quarantine the sample until resolved.
+
+### [HIGH] conclusion-release-gate
+
+- Sample/conclusion: S-1003
+- Evidence: Conclusion C-2 relies on sample(s) with high-risk custody findings.
+- Remediation: Revise confidence language and require reviewer acceptance before release.
+
+### [HIGH] required-custody-event
+
+- Sample/conclusion: S-1003
+- Evidence: Missing required custody event: assay-run.
+- Remediation: Add a signed assay-run custody event or exclude this sample from release.
+
+### [MEDIUM] custody-time-gap
+
+- Sample/conclusion: S-1002
+- Evidence: collect to accession gap is 7.8 hours.
+- Remediation: Add intermediate courier/storage handoff evidence or downgrade conclusions that rely on this sample.
+
+### [MEDIUM] handoff-signature
+
+- Sample/conclusion: S-1002
+- Evidence: accession@2026-05-22T16:30:00Z is missing actor or signature evidence.
+- Remediation: Add a signed handoff record with accountable actor and timestamp.
+
+### [MEDIUM] required-custody-event
+
+- Sample/conclusion: S-1002
+- Evidence: Missing required custody event: archive.
+- Remediation: Add a signed archive custody event or exclude this sample from release.
+
+### [MEDIUM] custody-time-gap
+
+- Sample/conclusion: S-1003
+- Evidence: storage to archive gap is 6.5 hours.
+- Remediation: Add intermediate courier/storage handoff evidence or downgrade conclusions that rely on this sample.
+
+## Research Gap Prompts
+
+- Which biomarkers remain stable after the observed cold-chain excursion window?
+- Would blinded AI review change the severity or interpretation of the reported effect?
+- What courier or intermediate storage metadata should be captured to close shipment evidence gaps?
+- Can the failed assay be rerun from archived aliquots, or should the conclusion be limited to unaffected samples?
+