Update README with honest results, clean structure, paper reference

README.md

@@ -4,7 +4,51 @@ tags:
 ---
 # Oracle-Credit-Compute (OCC) Stack
 
-A minimal, open-source research prototype for **agentic compute allocation** where agents earn and spend non-transferable, decaying credits based on verified marginal impact.
+**Compute is not neutral.** In multi-agent debate, giving an adversarial agent equal speaking turns causes accuracy to collapse from 73.3% to 56.7% — worse than single-round voting. The mechanism is volume amplification, not persuasion: honest agents retain their positions 84% of the time but get outvoted.
+
+OCC is a mechanism-design layer that treats agent compute as a scarce, earned, auditable privilege. Agents earn non-transferable, decaying, capability-scoped credits based on verified marginal impact.
+
+**Paper:** `reports/occ_paper.md`  
+**Design doc:** `design.md`  
+**Literature review:** `reports/literature_review.md`
+
+---
+
+## Key Results
+
+### Debate Collapse (Real LLM — Qwen3-Coder-30B on H200)
+
+| Condition | Accuracy | Δ |
+|-----------|:--------:|:---:|
+| 1-round baseline | **73.3%** | — |
+| 3-round debate (with adversary) | **56.7%** | −16.7pp |
+| Judge voting | **73.3%** | recovered |
+| Confidence-weighted voting | **73.3%** | recovered |
+| Equal-token (cap adversary volume) | **70.0%** | −3.3pp |
+
+**Root cause:** Volume amplification (H1 ✅). Not persuasion (H4 ❌, 84% retention). Not skill-dependent (H6 ❌, weak adversary still collapses).
+
+### Simulated Benchmarks
+
+| Benchmark | Baseline | OCC | Savings |
+|----------|:--------:|:---:|:-------:|
+| Code (pass@1, iso-accuracy) | 0.78 | 0.78 | 52.3% compute |
+| Debate (adversarial) | 0.56 | 0.76 | +20pp accuracy |
+| Retrieval QA | 0.79 | 0.71 | 33% retrievals (accuracy lags) |
+
+### Anti-Gaming
+
+10 attack vectors tested, all contained: credit farming, collusion, oracle spoofing, verbosity gaming, confidence manipulation, strategic abstention, identity laundering, sybil agents, sandbagging, griefing.
+
+### Honest Limitations
+
+- OCC ≈ random gating at moderate budgets (doesn't beat simple baselines in median case)
+- GRPO training produced no improvement at 0.5B scale
+- Single seed for mechanism isolation (CI ±16pp)
+- Simulated benchmarks for code/QA (not real LLM agents)
+- HumanEval result is adaptive retry, not OCC credit allocation
+
+---
 
 ## Quickstart
 
@@ -14,21 +58,23 @@ cd occ-stack
 pip install -r requirements.txt
 
 # Simulated benchmarks (CPU)
-python benchmarks/benchmark_code.py              # Code compute allocation
-python benchmarks/benchmark_retrieval_qa.py    # Retrieval QA
-python benchmarks/benchmark_debate_v2.py         # Multi-agent debate
+python benchmarks/benchmark_code.py
+python benchmarks/benchmark_debate_v2.py
+python benchmarks/benchmark_retrieval_qa.py
 
-# Ablations + anti-gaming (CPU, ~5 min)
+# Ablations + anti-gaming (CPU)
 python eval_runner.py
 
-# Real LLM benchmark (GPU, requires T4+)
-python jobs/run_real_llm_standalone_v7.py
-
 # Unit tests
 python tests/test_oracle.py
 python tests/test_ledger.py
+
+# Debate collapse analysis
+python jobs/analyze_collapse.py reports/debate_collapse_mechanism_results.json
 ```
 
+---
+
 ## Architecture
 
 ```
@@ -47,67 +93,42 @@ python tests/test_ledger.py
                    └─────────────────┘
 ```
 
-## Key Results (Simulated)
+## Components
 
-- **52.3% compute reduction at iso-accuracy** on code benchmark (OCC tiered escalation vs fixed budget)
-- **76% accuracy with 40% adversarial agents** in debate (OCC credit-filtering vs 56% naive confidence voting)
-- **All anti-gaming attacks contained:** hidden-test gaming, collusion, over-abstention, spam
+| Component | File | Description |
+|-----------|------|-------------|
+| Impact Oracle | `oracle/oracle.py` | Multi-mode scoring (code, QA, debate) with cost-adjusted rewards |
+| Credit Ledger | `ledger/ledger.py` | Non-transferable, decaying, capability-scoped credits with audit trail |
+| Resource Broker | `broker/broker.py` | Capability-based access control (allow/deny/downgrade/escalate) |
+| GRPO Hook | `rl/grpo_hook.py` | TRL-compatible reward function for learned allocation |
+| Reward | `rl/reward.py` | Cost-adjusted reward with anti-gaming penalties |
 
-## Status
+## Formal Definition
 
-| Component | Status |
-|-----------|--------|
-| Impact Oracle | ✅ Working |
-| Credit Ledger | ✅ Working |
-| Resource Broker | ✅ Working |
-| GRPO/RL Hook | ✅ Factory ready |
-| Simulated benchmarks | ✅ Complete |
-| Ablations (10 conditions) | ✅ Complete |
-| Anti-gaming tests | ✅ Complete |
-| Real LLM benchmark | 🔄 V7 in progress |
-| GRPO training | 🔄 Not yet run |
+Full formal definition with 10 system invariants, ledger event schema, threat model, and when-to-use guidance in [`design.md`](design.md).
 
 ## Repo Structure
 
 ```
 occ/
-  oracle/          # ImpactOracle — rule-based scoring
-  ledger/          # CreditLedger — non-transferable, decaying credits
-  broker/          # ResourceBroker — capability-based access control
-  rl/              # RewardHook, OfflineComparator — TRL GRPO integration
-  benchmarks/      # 3 benchmark scripts + real LLM variants
+  oracle/          # ImpactOracle
+  ledger/          # CreditLedger
+  broker/          # ResourceBroker
+  rl/              # GRPO hook + reward function
+  benchmarks/      # 3 benchmark scripts
+  jobs/            # GPU job scripts + analysis
   tests/           # Unit tests
-  reports/         # Reports, results, blog post
-  jobs/            # Self-contained GPU job scripts
+  reports/         # Paper, reports, literature review, blog post
+  design.md        # Formal system definition
 ```
 
 ## Citation
 
 ```bibtex
 @misc{occ2026,
-  title={Oracle-Credit-Compute: A Minimal Stack for Agentic Compute Allocation},
+  title={Compute Is Not Neutral: Mechanism Analysis of Adversarial Debate Collapse and the OCC Stack},
   author={narcolepticchicken},
   year={2026},
   url={https://huggingface.co/narcolepticchicken/occ-stack}
 }
 ```
-
-<!-- ml-intern-provenance -->
-## Generated by ML Intern
-
-This model repository was generated by [ML Intern](https://github.com/huggingface/ml-intern), an agent for machine learning research and development on the Hugging Face Hub.
-
-- Try ML Intern: https://smolagents-ml-intern.hf.space
-- Source code: https://github.com/huggingface/ml-intern
-
-## Usage
-
-```python
-from transformers import AutoModelForCausalLM, AutoTokenizer
-
-model_id = 'narcolepticchicken/occ-stack'
-tokenizer = AutoTokenizer.from_pretrained(model_id)
-model = AutoModelForCausalLM.from_pretrained(model_id)
-```
-
-For non-causal architectures, replace `AutoModelForCausalLM` with the appropriate `AutoModel` class.