Add causal claim validity guard

causal-claim-validity-guard/README.md

@@ -0,0 +1,48 @@
+# Causal Claim Validity Guard
+
+This module adds a focused causal-claim review gate for the AI-Powered Research Assistant Suite in issue `#16`.
+
+Scientific manuscripts often drift from careful associational language into causal conclusions. The guard inspects synthetic review packets and determines whether AI-generated peer-review output should be released, revised, or held until the causal claim is supported.
+
+## Scope
+
+- Detects causal-language overreach in manuscript claims and conclusions.
+- Checks whether the study design can support causal language.
+- Flags missing comparator/control support, temporal-order gaps, confounder handling gaps, and effect-size uncertainty.
+- Produces evidence-linked remediation items suitable for authors, internal reviewers, or automated pre-submission checks.
+- Uses synthetic data only.
+- Uses no external AI APIs, credentials, private manuscripts, payment systems, or network calls.
+
+## Requirement Map
+
+| Issue #16 capability | Implementation |
+| --- | --- |
+| Auto peer review reports | Emits structured reviewer findings, severity, decision, and remediation. |
+| Methodological red flags | Detects design/evidence mismatch, missing controls, confounder gaps, and uncertainty gaps. |
+| Claims vs evidence alignment | Compares claim intent, causal wording, study design, temporal evidence, and comparator evidence. |
+| Adaptive templates per domain | Supports packet-level `domain` and domain-specific reviewer note generation. |
+| Reproducible deterministic output | Demo and tests use fixed synthetic packets and deterministic scoring. |
+
+## Run
+
+```bash
+npm test
+npm run demo
+npm run check
+```
+
+Demo artifacts are written to `artifacts/`:
+
+- `causal-claim-review.json`
+- `causal-claim-review.md`
+- `causal-claim-summary.svg`
+
+## Decisions
+
+- `RELEASE`: evidence supports the causal wording.
+- `REVISE`: the manuscript can likely be repaired with clearer language or additional evidence.
+- `HOLD`: the causal claim is not safe to release without material methodological support.
+
+## AI Assistance Disclosure
+
+Implemented with Codex assistance and locally verified with deterministic tests and generated artifacts.

causal-claim-validity-guard/artifacts/causal-claim-review.json

@@ -0,0 +1,129 @@
+{
+  "generatedAt": "2026-08-15T20:24:14.343Z",
+  "packetCount": 4,
+  "decisionCounts": {
+    "RELEASE": 2,
+    "REVISE": 1,
+    "HOLD": 1
+  },
+  "reviews": [
+    {
+      "id": "cardio-rct-001",
+      "title": "Remote coaching reduces systolic blood pressure in high-risk adults",
+      "domain": "clinical trials",
+      "decision": "RELEASE",
+      "confidence": 0.95,
+      "causalLanguageDetected": true,
+      "findingCount": 0,
+      "findings": [],
+      "reviewerNote": "clinical trials: causal wording is aligned with the study design and evidence packet."
+    },
+    {
+      "id": "education-cross-sectional-002",
+      "title": "Daily tutoring app usage improves mathematics scores",
+      "domain": "education",
+      "decision": "HOLD",
+      "confidence": 0.15,
+      "causalLanguageDetected": true,
+      "findingCount": 5,
+      "findings": [
+        {
+          "code": "DESIGN_CANNOT_SUPPORT_CAUSAL_LANGUAGE",
+          "severity": "critical",
+          "message": "The manuscript uses causal language, but the stated design does not independently support causal inference.",
+          "evidence": {
+            "design": "cross_sectional",
+            "claim": "Daily tutoring app usage improves mathematics scores."
+          },
+          "remediation": "Replace causal verbs with associational language or add a causal identification strategy with assumptions and diagnostics."
+        },
+        {
+          "code": "MISSING_COMPARATOR",
+          "severity": "major",
+          "message": "Causal review requires a comparator, control, counterfactual, or explicit quasi-experimental contrast.",
+          "evidence": {
+            "hasComparator": false
+          },
+          "remediation": "Add a comparator/control description and explain why it approximates the counterfactual."
+        },
+        {
+          "code": "TEMPORAL_ORDER_GAP",
+          "severity": "major",
+          "message": "The evidence packet does not show that exposure or intervention preceded the outcome.",
+          "evidence": {
+            "temporalOrder": false
+          },
+          "remediation": "Document timing of exposure, intervention, measurement, and outcome windows."
+        },
+        {
+          "code": "CONFOUNDER_STRATEGY_MISSING",
+          "severity": "major",
+          "message": "No confounder strategy is described for a causal claim.",
+          "evidence": {
+            "confounderStrategy": null
+          },
+          "remediation": "Describe randomization, matching, adjustment, stratification, sensitivity analysis, or a defensible natural experiment."
+        },
+        {
+          "code": "UNCERTAINTY_NOT_REPORTED",
+          "severity": "minor",
+          "message": "The packet reports an effect size without an uncertainty interval.",
+          "evidence": {
+            "effectSize": "0.31 SD",
+            "confidenceInterval": null
+          },
+          "remediation": "Add confidence, credible, or bootstrap intervals and specify the estimation method."
+        }
+      ],
+      "reviewerNote": "education: HOLD before release because the manuscript uses causal language, but the stated design does not independently support causal inference."
+    },
+    {
+      "id": "ecology-longitudinal-003",
+      "title": "Wetland restoration is associated with higher amphibian diversity",
+      "domain": "ecology",
+      "decision": "RELEASE",
+      "confidence": 0.95,
+      "causalLanguageDetected": false,
+      "findingCount": 0,
+      "findings": [],
+      "reviewerNote": "ecology: causal wording is aligned with the study design and evidence packet."
+    },
+    {
+      "id": "oncology-subgroup-004",
+      "title": "Dose timing prevents relapse in a small oncology subgroup",
+      "domain": "oncology",
+      "decision": "REVISE",
+      "confidence": 0.79,
+      "causalLanguageDetected": true,
+      "findingCount": 2,
+      "findings": [
+        {
+          "code": "UNCERTAINTY_NOT_REPORTED",
+          "severity": "minor",
+          "message": "The packet reports an effect size without an uncertainty interval.",
+          "evidence": {
+            "effectSize": "hazard ratio 0.72",
+            "confidenceInterval": null
+          },
+          "remediation": "Add confidence, credible, or bootstrap intervals and specify the estimation method."
+        },
+        {
+          "code": "UNDERPOWERED_SUBGROUP_CAUSAL_CLAIM",
+          "severity": "minor",
+          "message": "At least one subgroup claim uses causal language without a powered subgroup analysis.",
+          "evidence": {
+            "subgroups": [
+              {
+                "name": "biomarker-positive subgroup",
+                "claim": "dose timing prevents relapse",
+                "powered": false
+              }
+            ]
+          },
+          "remediation": "Mark subgroup findings exploratory unless power and multiplicity controls are documented."
+        }
+      ],
+      "reviewerNote": "oncology: REVISE before release because the packet reports an effect size without an uncertainty interval."
+    }
+  ]
+}

causal-claim-validity-guard/artifacts/causal-claim-review.md

@@ -0,0 +1,46 @@
+# Causal Claim Validity Review
+
+Generated: 2026-08-15T20:24:14.343Z
+
+## Decision Counts
+
+- RELEASE: 2
+- REVISE: 1
+- HOLD: 1
+
+## Packet Reviews
+
+### Remote coaching reduces systolic blood pressure in high-risk adults
+Decision: RELEASE
+Confidence: 0.95
+Reviewer note: clinical trials: causal wording is aligned with the study design and evidence packet.
+
+### Daily tutoring app usage improves mathematics scores
+Decision: HOLD
+Confidence: 0.15
+Reviewer note: education: HOLD before release because the manuscript uses causal language, but the stated design does not independently support causal inference.
+- CRITICAL DESIGN_CANNOT_SUPPORT_CAUSAL_LANGUAGE: The manuscript uses causal language, but the stated design does not independently support causal inference.
+  Remediation: Replace causal verbs with associational language or add a causal identification strategy with assumptions and diagnostics.
+- MAJOR MISSING_COMPARATOR: Causal review requires a comparator, control, counterfactual, or explicit quasi-experimental contrast.
+  Remediation: Add a comparator/control description and explain why it approximates the counterfactual.
+- MAJOR TEMPORAL_ORDER_GAP: The evidence packet does not show that exposure or intervention preceded the outcome.
+  Remediation: Document timing of exposure, intervention, measurement, and outcome windows.
+- MAJOR CONFOUNDER_STRATEGY_MISSING: No confounder strategy is described for a causal claim.
+  Remediation: Describe randomization, matching, adjustment, stratification, sensitivity analysis, or a defensible natural experiment.
+- MINOR UNCERTAINTY_NOT_REPORTED: The packet reports an effect size without an uncertainty interval.
+  Remediation: Add confidence, credible, or bootstrap intervals and specify the estimation method.
+
+### Wetland restoration is associated with higher amphibian diversity
+Decision: RELEASE
+Confidence: 0.95
+Reviewer note: ecology: causal wording is aligned with the study design and evidence packet.
+
+### Dose timing prevents relapse in a small oncology subgroup
+Decision: REVISE
+Confidence: 0.79
+Reviewer note: oncology: REVISE before release because the packet reports an effect size without an uncertainty interval.
+- MINOR UNCERTAINTY_NOT_REPORTED: The packet reports an effect size without an uncertainty interval.
+  Remediation: Add confidence, credible, or bootstrap intervals and specify the estimation method.
+- MINOR UNDERPOWERED_SUBGROUP_CAUSAL_CLAIM: At least one subgroup claim uses causal language without a powered subgroup analysis.
+  Remediation: Mark subgroup findings exploratory unless power and multiplicity controls are documented.
+

causal-claim-validity-guard/data/sample_review_packets.json

@@ -0,0 +1,85 @@
+[
+  {
+    "id": "cardio-rct-001",
+    "title": "Remote coaching reduces systolic blood pressure in high-risk adults",
+    "domain": "clinical trials",
+    "claim": {
+      "intent": "causal",
+      "text": "Remote coaching reduces systolic blood pressure after twelve weeks."
+    },
+    "evidence": {
+      "design": "randomized_controlled_trial",
+      "hasComparator": true,
+      "temporalOrder": true,
+      "confounderStrategy": "blocked randomization with prespecified covariate balance checks",
+      "effectSize": "-7.4 mmHg",
+      "confidenceInterval": "95% CI -10.1 to -4.9",
+      "subgroups": [
+        {
+          "name": "participants over 65",
+          "claim": "coaching may reduce systolic blood pressure",
+          "powered": true
+        }
+      ]
+    },
+    "conclusion": "Remote coaching reduces systolic blood pressure in the randomized study population."
+  },
+  {
+    "id": "education-cross-sectional-002",
+    "title": "Daily tutoring app usage improves mathematics scores",
+    "domain": "education",
+    "claim": {
+      "intent": "causal",
+      "text": "Daily tutoring app usage improves mathematics scores."
+    },
+    "evidence": {
+      "design": "cross_sectional",
+      "hasComparator": false,
+      "temporalOrder": false,
+      "effectSize": "0.31 SD"
+    },
+    "conclusion": "The tutoring app drives higher scores across schools."
+  },
+  {
+    "id": "ecology-longitudinal-003",
+    "title": "Wetland restoration is associated with higher amphibian diversity",
+    "domain": "ecology",
+    "claim": {
+      "intent": "associational",
+      "text": "Wetland restoration is associated with higher amphibian diversity."
+    },
+    "evidence": {
+      "design": "longitudinal_observational",
+      "hasComparator": true,
+      "temporalOrder": true,
+      "confounderStrategy": "matched watersheds and rainfall adjustment",
+      "effectSize": "18% higher species richness",
+      "confidenceInterval": "95% CI 6% to 29%"
+    },
+    "conclusion": "Wetland restoration is associated with higher observed amphibian diversity after adjustment."
+  },
+  {
+    "id": "oncology-subgroup-004",
+    "title": "Dose timing prevents relapse in a small oncology subgroup",
+    "domain": "oncology",
+    "claim": {
+      "intent": "causal",
+      "text": "Dose timing prevents relapse in the biomarker-positive subgroup."
+    },
+    "evidence": {
+      "design": "quasi_experimental",
+      "hasComparator": true,
+      "temporalOrder": true,
+      "confounderStrategy": "propensity score weighting",
+      "effectSize": "hazard ratio 0.72",
+      "subgroups": [
+        {
+          "name": "biomarker-positive subgroup",
+          "claim": "dose timing prevents relapse",
+          "powered": false
+        }
+      ]
+    },
+    "conclusion": "Dose timing prevents relapse for biomarker-positive patients."
+  }
+]

causal-claim-validity-guard/package.json

@@ -0,0 +1,13 @@
+{
+  "name": "causal-claim-validity-guard",
+  "version": "1.0.0",
+  "description": "Dependency-free causal claim validity guard for AI research assistant review packets.",
+  "main": "src/index.js",
+  "scripts": {
+    "test": "node --test",
+    "demo": "node scripts/demo.js",
+    "video": "node scripts/render-demo-video.js",
+    "check": "node --check src/index.js && node --check scripts/demo.js"
+  },
+  "license": "MIT"
+}