Add ECC Harness: phd_research_os/AGENTS.md

phd_research_os/AGENTS.md

@@ -0,0 +1,102 @@
+# PhD Research OS — Agent Registry & Contracts
+
+> **WAKE-UP INSTRUCTION**: This file defines every agent role, its contract,
+> its boundaries, and how companion agents relate to the core brain.
+
+## Agent Hierarchy
+
+```
+Human Researcher (Provenance Level 1)
+  │
+  ├── Research OS Brain (Level 5 — core agents.py)
+  │     ├── Researcher Agent        → claim extraction
+  │     ├── Epistemic Classifier    → Fact/Interpretation/Hypothesis/Conflict
+  │     ├── Confidence Scorer       → formula-based scoring
+  │     ├── Verifier Agent          → contradiction detection
+  │     ├── Query Planner           → question decomposition
+  │     └── Decision Generator      → research action proposals
+  │
+  └── Companion Agents (Level 5 — spawned via agent_os.py)
+        ├── DataQualityAuditor      → audit extraction quality, flag drift
+        ├── PromptOptimizer         → improve system prompts via A/B testing
+        ├── DomainExpander          → generate training data for new STEM fields
+        ├── CalibrationAnalyst      → analyze Brier scores, recommend adjustments
+        ├── CitationChaser          → find papers that cite/contradict current claims
+        └── [Custom]                → user-defined agents via factory
+```
+
+## Core Agent Contracts (agents.py)
+
+### Researcher Agent
+- **Input**: Raw scientific text (1 page)
+- **Output**: `{"claims": [ClaimObject, ...]}`
+- **Constraint**: Epistemic tags conservative. Prefer "Interpretation" when uncertain.
+- **Provenance**: Level 5. Claims must be human-reviewed before canonical status.
+
+### Epistemic Classifier
+- **Input**: Single scientific statement
+- **Output**: `{"epistemic_tag": str, "reasoning": str, "confidence_in_classification": float}`
+- **Constraint**: 4-class only. No intermediate tags.
+
+### Confidence Scorer
+- **Input**: Claim text + journal + study type + tier
+- **Output**: `{"confidence": float, ...factor_breakdown...}`
+- **Constraint**: MUST use fixed-point formula. No free-form scoring.
+
+### Verifier Agent
+- **Input**: Claim pair (A, B)
+- **Output**: `{"conflict_detected": bool, "conflict_type": str, "hypothesis_confidence": "low", ...}`
+- **INVARIANT**: `hypothesis_confidence` is ALWAYS `"low"`. Hardcoded. Never changes.
+
+### Query Planner
+- **Input**: Broad research question
+- **Output**: `{"sub_queries": [str, ...], "reasoning": str}`
+- **Constraint**: 2–4 sub-queries. Each independently searchable.
+
+### Decision Generator
+- **Input**: Goal + gaps + low-confidence claims
+- **Output**: DecisionObject with information gain
+- **Constraint**: `expected_information_gain = uncertainty × impact`
+
+## Companion Agent Contract (agent_os.py)
+
+Every companion agent MUST:
+
+1. **Declare its purpose** at spawn time (immutable after creation)
+2. **Operate within boundaries** — cannot directly modify claims, sources, or goals
+3. **Produce proposals** — all output is a `Proposal` object requiring human approval
+4. **Log every action** — audit trail in `agent_audit_log` table
+5. **Run the ECC lifecycle** — preflight → plan → execute → postflight
+6. **Respect iteration budgets** — max 1 retry for patches, max 3 for architecture changes
+7. **Surface uncertainty** — if confidence < 0.5 on any decision, escalate to human
+8. **Self-terminate** — if task exceeds time budget by 50%, auto-halt (Kill Heuristic)
+
+### Companion Agent Types
+
+| Agent Type | Purpose | Improves Research OS By |
+|-----------|---------|------------------------|
+| `DataQualityAuditor` | Audit claim extraction quality over time | Catching drift, hallucination creep |
+| `PromptOptimizer` | A/B test system prompts against golden dataset | Improving extraction recall/precision |
+| `DomainExpander` | Generate training examples for new STEM fields | Expanding model capability |
+| `CalibrationAnalyst` | Analyze confidence calibration (Brier scores) | Reducing overconfidence |
+| `CitationChaser` | Find papers citing/contradicting current claims | Enriching knowledge base |
+| `SynthesisWriter` | Draft thesis sections from claim clusters | Phase 10 feature |
+| `custom` | User-defined purpose and prompt | Any improvement task |
+
+### Proposal Schema
+
+```json
+{
+  "proposal_id": "PROP_XXXXXXXX",
+  "agent_id": "COMP_XXXXXXXX",
+  "proposal_type": "prompt_change | training_data | confidence_adjustment | new_claim | architecture_change",
+  "description": "Human-readable description of what this proposes",
+  "changes": { ... },
+  "evidence": "Why this change should be made",
+  "estimated_impact": { "metric": "extraction_recall", "expected_delta": 0.05 },
+  "risk_assessment": "low | medium | high",
+  "reversible": true,
+  "status": "proposed | approved | rejected | applied",
+  "created_at": "ISO8601"
+}
+```