save progress

docs/modules/aoc/README.md

@@ -0,0 +1,37 @@
+# AOC (Append-Only Contracts)
+
+**Status:** Implemented
+**Source:** `src/Aoc/`
+**Owner:** Platform Team
+
+## Purpose
+
+AOC provides compile-time enforcement of append-only contract rules during data ingestion. Uses Roslyn analyzers to prevent connectors from writing to fields that should only be computed by downstream merge/decisioning pipelines.
+
+## Components
+
+**Analyzers:**
+- `StellaOps.Aoc.Analyzers` - Roslyn DiagnosticAnalyzers (AOC0001, AOC0002, AOC0003)
+
+**Libraries:**
+- `StellaOps.Aoc` - Core abstractions (IAocGuard)
+- `StellaOps.Aoc.AspNetCore` - ASP.NET Core integration
+
+**CLI:**
+- `StellaOps.Aoc.Cli` - Manual validation tool
+
+## Key Concepts
+
+**Forbidden Fields** (ingestion-time writes forbidden):
+- `severity`, `cvss`, `cvss_vector` - Computed from CVSS + context
+- `effective_status`, `effective_range` - VEX consensus outcomes
+- `risk_score`, `reachability`, `asset_criticality` - Runtime analysis
+
+**Derived Fields:**
+- Any field prefixed with `effective_*` is treated as derived and forbidden
+
+## Related Documentation
+
+- Architecture: `./architecture.md`
+- Concelier: `../concelier/` (uses AOC for connectors)
+- Excititor: `../excititor/` (uses AOC for VEX ingestion)