Prd 1 agentforge monigarr

.gitattributes

@@ -4,10 +4,23 @@
 # Exclude dev-only infrastructure from release archives and Composer installs.
 # GitHub uses these rules when generating source downloads for tagged releases.
 # Keep anything needed to install, configure, or run OpenEMR.
+# Hosts that build from a git export (e.g. Railway) honor export-ignore too.
 .github/                       export-ignore
 .phpstan/                      export-ignore
 ci/                            export-ignore
-docker/                        export-ignore
+# docker/: do not export-ignore the whole tree — Git omits children from archives and
+# never applies -export-ignore under an excluded parent. List sibling dirs only; keep
+# docker/agentforge-railway/ in archives for Dockerfile-based deploys (e.g. Railway).
+# If a new top-level directory is added under docker/, add export-ignore here unless it
+# must appear in git-archive build contexts.
+docker/README.md               export-ignore
+docker/development-easy/       export-ignore
+docker/development-easy-light/ export-ignore
+docker/development-easy-redis/ export-ignore
+docker/development-insane/     export-ignore
+docker/from-source/            export-ignore
+docker/library/                export-ignore
+docker/production/             export-ignore
 tests/                         export-ignore
 tools/                         export-ignore
 .gitattributes                 export-ignore

.gitignore

@@ -24,6 +24,8 @@ ccdaservice/node_modules
 .buildpath
 .project
 .settings
+PRD_Week1_AgentForge.jpeg
+PRD_Week1_AgentForge.md
 
 # testing
 .phpunit.result.cache

ARCHITECTURE.md

@@ -0,0 +1,183 @@
+# Clinical CoPilot — Week 2 ARCHITECTURE
+
+## 0. Executive Summary
+
+Week 2 extends the PRD 1 Clinical CoPilot into a multimodal, multi-agent system capable of ingesting clinical documents, extracting structured facts, retrieving guideline evidence, and producing fully grounded outputs.
+
+This is an **extension of PRD 1 — not a replacement**.
+
+The system preserves PRD 1 guarantees:
+- Verification-first output
+- Bounded tool access
+- Session-based trust model
+- Full observability via AgentTelemetry
+
+New capabilities:
+- Multimodal document ingestion (lab PDF, intake form)
+- Supervisor + worker multi-agent routing
+- Eval-driven CI gating
+
+---
+
+## 1. Architecture Position
+
+- OpenEMR remains system of record
+- PRD 1 orchestrator remains core authority
+- PRD 2 multi-agent layer is an extension on top
+- AI remains untrusted reasoning layer
+- Verification remains mandatory gate
+- Eval CI is production gate
+
+---
+
+## 2. Design Principles (M.O.M / M.I.L.E)
+
+- Intelligence-led extraction (never blind OCR trust)
+- Extraction is treated as **untrusted input**
+- Minimal expansion of surface area
+- Brownfield-safe (no OpenEMR core modification)
+- Observability-first (trace everything)
+- Eval-driven development (CI enforced)
+
+---
+
+## 3. System Overview
+
+User → OpenEMR UI → Controller  
+→ PRD1 Orchestrator Core  
+→ Supervisor Agent (extension)  
+→ Worker 1 (Extractor)  
+→ Worker 2 (Evidence Retriever)  
+→ Verification Gate  
+→ UI Response  
+
+---
+
+## 4. Multi-Agent Position (Critical Clarification)
+
+PRD 2 multi-agent architecture is:
+
+> A constrained, inspectable routing layer built on top of the PRD 1 orchestrator — not a replacement.
+
+- Supervisor = routing logic only
+- Workers = bounded responsibilities
+- All actions remain observable and verifiable
+
+No agent has:
+- direct DB access
+- write authority
+- uncontrolled autonomy
+
+---
+
+## 5. Tool Layer (Updated)
+
+| Tool | Role | Boundary |
+|------|------|----------|
+| attach_and_extract | document ingestion | server-controlled |
+| retrieve_guidelines | RAG retrieval | read-only |
+| get_patient_context | OpenEMR data | bounded |
+
+### Write Boundary Clarification
+
+`attach_and_extract`:
+- executes server-side only
+- persists data through controlled pipelines
+- model does NOT write to DB
+- model cannot modify records
+
+---
+
+## 6. Extraction Model (Critical Update)
+
+Extraction pipeline:
+
+Document → VLM → Structured JSON → Validation → Verification → Persist
+
+### Rule:
+> Extraction output is **not truth**. It is untrusted input until:
+- schema validated
+- citation linked to source
+- verified by system
+
+---
+
+## 7. Verification (Extended)
+
+Verification now applies to:
+1. OpenEMR structured data
+2. Extracted document data
+3. Retrieved guideline evidence
+
+Requirements:
+- every claim must have citation
+- patient facts ≠ guideline evidence
+- unsupported claims removed
+
+---
+
+## 8. Observability (Reconciled)
+
+PRD 1:
+- AgentTelemetry (LangFuse)
+
+PRD 2:
+- adds LangChain
+
+### Final Position:
+
+> LangChain is orchestration  
+> AgentTelemetry remains the system of record for observability
+
+All logs must include:
+- tool sequence
+- latency per step
+- token usage
+- cost estimate
+- eval result
+
+No PHI in logs
+
+---
+
+## 9. Eval Strategy (Critical)
+
+- 50-case golden dataset
+- boolean rubrics only
+- CI blocks regression >5%
+
+Eval is:
+> not testing — it is a production gate
+
+---
+
+## 10. Failure Modes
+
+| Failure | Behavior |
+|--------|----------|
+| OCR hallucination | drop or flag |
+| missing data | explicit uncertainty |
+| tool failure | partial response |
+| verification failure | remove claim |
+
+---
+
+## 11. Brownfield Constraints
+
+- OpenEMR is immutable source of truth
+- No modification of core
+- Module-only extension
+- Follow CONTRIBUTING.md + README strictly
+
+---
+
+## 12. Forward Path
+
+- critic agent
+- additional document types
+- improved retrieval
+
+---
+
+## Document Control
+Version: 2.1

ARCHITECTURE_RISKS.md

@@ -0,0 +1,58 @@
+# PRD 2 Architecture Risks
+
+## 1. Multi-Agent Complexity
+
+Risk:
+- Supervisor becomes opaque
+
+Mitigation:
+- log all routing decisions
+- limit agent scope
+- enforce deterministic flow
+
+---
+
+## 2. Extraction Risk (Critical)
+
+Risk:
+- system generates false structured data
+
+Mitigation:
+- treat extraction as untrusted input
+- require schema validation
+- require citation linkage
+
+---
+
+## 3. Write Boundary Risk
+
+Risk:
+- ingestion tool writes incorrect data
+
+Mitigation:
+- server-controlled persistence only
+- model cannot write directly
+- validation before storage
+
+---
+
+## 4. Observability Drift
+
+Risk:
+- losing PRD 1 traceability
+
+Mitigation:
+- AgentTelemetry remains source of truth
+- LangChain only for orchestration
+
+---
+
+## 5. Eval Failure Risk
+
+Risk:
+- regressions pass unnoticed
+
+Mitigation:
+- CI blocking gate
+- 50-case dataset
+- strict boolean scoring

AUDIT.md

@@ -0,0 +1,55 @@
+# Clinical CoPilot — AUDIT (Week 2 Addendum)
+
+## New Risk Areas
+
+### Document Processing
+- OCR inaccuracies
+- confabulated fields
+- extracted data treated as truth (critical risk)
+
+### Multi-Agent Complexity
+- routing errors
+- hidden reasoning
+- supervisor becoming black box
+
+### RAG Risks
+- irrelevant evidence
+- outdated guidelines
+
+---
+
+## New Mitigations
+
+- extraction treated as untrusted input
+- strict schema validation
+- citation enforcement
+- supervisor decisions logged
+- reranking enforced
+- verification extended to extracted data
+
+---
+
+## Compliance Notes
+- documents = PHI
+- no storage in logs
+- no external leakage
+
+---
+
+## New Findings
+
+| ID | Severity | Finding |
+|----|----------|--------|
+| W2-F1 | High | OCR hallucination risk |
+| W2-F2 | High | missing citation in extraction |
+| W2-F3 | Medium | RAG drift |
+| W2-F2 | High | extraction treated as truth risk |
+| W2-F4 | High | multi-agent opacity risk |
+
+---
+
+## Integration Impact
+
+- extend verification layer to extracted data
+- extend observability to multi-agent flows
+- enforce auditability of routing decisions