Add collaborative ethics consent guard

collaborative-ethics-consent-guard/README.md

@@ -0,0 +1,57 @@
+# Collaborative Ethics and Consent Guard
+
+This module adds a focused collaborative ethics-and-consent export guard for the Real-Time Collaborative Editor in issue `#12`.
+
+Collaborative manuscripts can accumulate edits, comments, translations, and locked-section changes across many users. Before export, the editor needs a deterministic gate that checks whether ethics and consent content is safe to publish and whether private reviewer or participant details are still embedded in collaborative state.
+
+## Scope
+
+- Checks human-subjects manuscripts for ethics approval identifiers.
+- Flags expired approvals and missing exemption rationale.
+- Checks vulnerable-population review evidence.
+- Checks consent statement presence and waiver rationale.
+- Compares consent scope against the requested export scope.
+- Checks required translated-consent coverage.
+- Flags pending edits in locked ethics/consent sections without approved override.
+- Flags stale ethics-section review after collaborative edits.
+- Holds exports with private ethics comments or participant-like identifiers.
+- Produces JSON, Markdown, SVG, and MP4 reviewer artifacts.
+- Uses synthetic data only.
+- Uses no external APIs, private manuscripts, real participant data, credentials, payment systems, or network calls.
+
+## Requirement Map
+
+| Issue #12 capability | Implementation |
+| --- | --- |
+| Real-time collaboration | Reviews collaborative comments, pending edits, locks, and section state before export. |
+| Change tracking and suggestions | Detects pending ethics edits and unresolved ethics comments. |
+| Rich scientific manuscript export | Guards ethics/consent statements before manuscript export. |
+| Version history and autosave | Checks review freshness after collaborative changes. |
+| Inline comments and review sidebar | Blocks private reviewer notes and participant-like identifiers from public export. |
+| Publication-ready formatting | Confirms consent scope, translated-consent coverage, and ethics approval metadata. |
+
+## Run
+
+```bash
+npm test
+npm run demo
+npm run video
+npm run check
+```
+
+Demo artifacts are written to `reports/`:
+
+- `summary.json`
+- `reviewer-packet.md`
+- `summary.svg`
+- `demo.mp4`
+
+## Decisions
+
+- `RELEASE`: ethics, consent, comments, and export scope are publication-ready.
+- `REVIEW`: missing or stale evidence can be repaired before export.
+- `HOLD`: missing approval/consent, expired approval, private comment leakage, or participant identifiers block export.
+
+## AI Assistance Disclosure
+
+Implemented with Codex assistance and locally verified with deterministic tests and generated artifacts.

collaborative-ethics-consent-guard/data/sample_editor_packets.json

@@ -0,0 +1,162 @@
+[
+  {
+    "id": "release-clean-consent",
+    "title": "Clean collaborative consent export",
+    "reviewDate": "2026-08-15",
+    "manuscript": {
+      "domain": "public health",
+      "humanSubjects": true,
+      "participantGroups": ["adults"]
+    },
+    "ethics": {
+      "approvalId": "IRB-2026-114",
+      "expiryDate": "2027-01-31",
+      "vulnerablePopulationReview": false
+    },
+    "consent": {
+      "required": true,
+      "statementPresent": true,
+      "scope": "journal publication",
+      "requiredLanguages": ["English", "Spanish"],
+      "presentLanguages": ["English", "Spanish"]
+    },
+    "collaborativeState": {
+      "lastEthicsReviewAt": "2026-08-01",
+      "ethicsSection": {
+        "locked": true,
+        "pendingEdits": false
+      }
+    },
+    "comments": [
+      {
+        "id": "c1",
+        "section": "methods ethics",
+        "private": false,
+        "exportVisible": false,
+        "resolved": true,
+        "text": "Consent statement reviewed."
+      }
+    ],
+    "exportTarget": {
+      "releaseScope": "journal publication"
+    }
+  },
+  {
+    "id": "review-stale-vulnerable",
+    "title": "Vulnerable population review needs refresh",
+    "reviewDate": "2026-08-15",
+    "manuscript": {
+      "domain": "education research",
+      "humanSubjects": true,
+      "participantGroups": ["children"]
+    },
+    "ethics": {
+      "approvalId": "REC-2025-09",
+      "expiryDate": "2026-12-01",
+      "vulnerablePopulationReview": false
+    },
+    "consent": {
+      "required": true,
+      "statementPresent": true,
+      "scope": "conference abstract",
+      "requiredLanguages": ["English", "French"],
+      "presentLanguages": ["English"]
+    },
+    "collaborativeState": {
+      "lastEthicsReviewAt": "2025-11-01",
+      "ethicsSection": {
+        "locked": true,
+        "pendingEdits": true,
+        "approvedOverride": true
+      }
+    },
+    "comments": [
+      {
+        "id": "c2",
+        "section": "ethics statement",
+        "private": false,
+        "exportVisible": false,
+        "resolved": false,
+        "text": "Need French consent upload confirmation."
+      }
+    ],
+    "exportTarget": {
+      "releaseScope": "conference abstract"
+    }
+  },
+  {
+    "id": "hold-missing-approval",
+    "title": "Human-subjects packet without approval",
+    "reviewDate": "2026-08-15",
+    "manuscript": {
+      "domain": "clinical methods",
+      "humanSubjects": true,
+      "participantGroups": ["adults"]
+    },
+    "ethics": {
+      "approvalId": "",
+      "exempt": false
+    },
+    "consent": {
+      "required": true,
+      "statementPresent": false,
+      "scope": "journal publication",
+      "requiredLanguages": ["English"],
+      "presentLanguages": []
+    },
+    "collaborativeState": {
+      "lastEthicsReviewAt": "2026-08-01",
+      "ethicsSection": {
+        "locked": true,
+        "pendingEdits": false
+      }
+    },
+    "comments": [],
+    "exportTarget": {
+      "releaseScope": "journal publication"
+    }
+  },
+  {
+    "id": "hold-private-comment-leak",
+    "title": "Private participant details leaking through comments",
+    "reviewDate": "2026-08-15",
+    "manuscript": {
+      "domain": "behavioral science",
+      "humanSubjects": true,
+      "participantGroups": ["adults"]
+    },
+    "ethics": {
+      "approvalId": "IRB-2026-202",
+      "expiryDate": "2027-03-01",
+      "vulnerablePopulationReview": false
+    },
+    "consent": {
+      "required": true,
+      "statementPresent": true,
+      "scope": "journal publication",
+      "requiredLanguages": ["English"],
+      "presentLanguages": ["English"]
+    },
+    "collaborativeState": {
+      "lastEthicsReviewAt": "2026-07-20",
+      "ethicsSection": {
+        "locked": true,
+        "pendingEdits": true,
+        "approvedOverride": false
+      }
+    },
+    "comments": [
+      {
+        "id": "c3",
+        "section": "ethics statement",
+        "private": true,
+        "exportVisible": true,
+        "resolved": false,
+        "text": "participant 104 withdrew after DOB: 02/04/1999 note."
+      }
+    ],
+    "exportTarget": {
+      "releaseScope": "journal publication"
+    }
+  }
+]

collaborative-ethics-consent-guard/package.json

@@ -0,0 +1,13 @@
+{
+  "name": "collaborative-ethics-consent-guard",
+  "version": "1.0.0",
+  "description": "Dependency-free ethics and consent export guard for collaborative research manuscripts.",
+  "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 && node --check scripts/render-demo-video.js"
+  },
+  "license": "MIT"
+}

collaborative-ethics-consent-guard/reports/reviewer-packet.md

@@ -0,0 +1,62 @@
+# Collaborative Ethics and Consent Export Review
+
+Generated: 2026-08-15T21:08:58.890Z
+
+## Decision Counts
+
+- RELEASE: 1
+- REVIEW: 1
+- HOLD: 2
+
+## Packet Reviews
+
+### Clean collaborative consent export
+Decision: RELEASE
+Confidence: 0.96
+Human subjects: true
+Comments checked: 1
+Reviewer note: public health: ethics, consent, comments, and export scope are publication-ready.
+
+### Vulnerable population review needs refresh
+Decision: REVIEW
+Confidence: 0.31
+Human subjects: true
+Comments checked: 1
+Reviewer note: education research: REVIEW before export because the manuscript includes vulnerable participant groups without documented enhanced ethics review.
+- MAJOR VULNERABLE_POPULATION_REVIEW_MISSING: The manuscript includes vulnerable participant groups without documented enhanced ethics review.
+  Remediation: Add vulnerable-population review evidence and consent safeguards before publication export.
+- MAJOR TRANSLATED_CONSENT_COVERAGE_MISSING: Required consent-language coverage is missing for one or more participant groups.
+  Remediation: Add translated consent evidence or justify why those participant groups are not included in the export.
+- MAJOR STALE_ETHICS_REVIEW: The last ethics-section review is older than the configured freshness window.
+  Remediation: Refresh ethics reviewer signoff after the latest collaborative edits.
+- MINOR UNRESOLVED_ETHICS_COMMENT: An ethics-section comment remains unresolved at export time.
+  Remediation: Resolve or explicitly defer the ethics comment before publication export.
+
+### Human-subjects packet without approval
+Decision: HOLD
+Confidence: 0.11
+Human subjects: true
+Comments checked: 0
+Reviewer note: clinical methods: HOLD before export because the manuscript involves human subjects but lacks an ethics approval identifier.
+- CRITICAL MISSING_ETHICS_APPROVAL_ID: The manuscript involves human subjects but lacks an ethics approval identifier.
+  Remediation: Add the IRB/REC approval identifier or mark the study as exempt with supporting rationale.
+- CRITICAL MISSING_CONSENT_STATEMENT: Consent is required but no consent statement is present in the collaborative manuscript.
+  Remediation: Add a consent statement or documented waiver before export.
+- MAJOR TRANSLATED_CONSENT_COVERAGE_MISSING: Required consent-language coverage is missing for one or more participant groups.
+  Remediation: Add translated consent evidence or justify why those participant groups are not included in the export.
+
+### Private participant details leaking through comments
+Decision: HOLD
+Confidence: 0.1
+Human subjects: true
+Comments checked: 1
+Reviewer note: behavioral science: HOLD before export because a locked ethics or consent section has pending collaborative edits without approved override.
+- MAJOR LOCKED_ETHICS_SECTION_HAS_PENDING_EDITS: A locked ethics or consent section has pending collaborative edits without approved override.
+  Remediation: Route pending edits through the section owner or ethics reviewer before export.
+- CRITICAL PRIVATE_ETHICS_COMMENT_VISIBLE_IN_EXPORT: A private ethics or reviewer comment is marked visible in the export packet.
+  Remediation: Redact or remove private comments before creating the public manuscript export.
+- CRITICAL PARTICIPANT_IDENTIFIER_IN_COMMENT: A collaborative comment appears to contain a participant, subject, patient, MRN, or DOB marker.
+  Remediation: Redact participant identifiers and regenerate reviewer-safe comments before export.
+- MINOR UNRESOLVED_ETHICS_COMMENT: An ethics-section comment remains unresolved at export time.
+  Remediation: Resolve or explicitly defer the ethics comment before publication export.
+