epic-12: after epic audit and init commit

docs/decisions/adr-0003-compression-strategy.md

@@ -0,0 +1,103 @@
+---
+name: "Adr 0003 Compression Strategy"
+description: "Rule‑based compression, no summariser model for v1"
+depth: 2
+links: ["../index.md", "../architecture/context-layers.md"]
+---
+
+# ADR 0003: adopt rule‑based compression with structured decision points; defer model‑based summarisation
+
+**status:** accepted  
+**date:** 07.05.2026 (May) 
+**deciders:** Kami
+
+---
+
+## context
+
+Correx must feed large volumes of tool output, conversation history, artifacts, and event streams into limited local model context windows. Raw accumulation destroys performance, especially for smaller models. We need a compression strategy that:
+
+* is deterministic and replay‑safe
+* does not itself require a large or separate model (for v1)
+* preserves decision‑critical context, not just surface summaries
+* works across multiple data sources (tools, chat, artifacts, events)
+
+## decision
+
+We adopt a **100% rule‑based compression system** for v1. No summariser model will be used for compression, even as an option.
+
+The four data sources will be handled as follows:
+
+### 1. tool output – RTK‑style pipeline
+
+All shell and tool command output is compressed using a configurable pipeline:
+
+1. **smart filter** – strip comments, whitespace, and known boilerplate
+2. **group** – aggregate similar items (e.g., files by directory, errors by type)
+3. **deduplicate** – collapse repeated identical lines with occurrence counts (`Error: timeout (×14)`)
+4. **truncate** – keep first N and last M lines; discard middle unless marked critical
+
+On command failure, the full unfiltered output is saved to disk and only a pointer path is included in the compressed receipt. The model may request the raw log if needed.
+
+User‑defined tools can declare their own compression patterns (regex + fallback) directly in the tool definition, not in a global config. This ties compression ownership to the tool.
+
+### 2. conversation history – manual compaction with micro‑compaction
+
+For Router ↔ User conversations:
+
+* the last N messages are kept verbatim (configurable; default N = 6)
+* **micro‑compaction** at ~60‑70% context pressure silently clears old tool outputs, keeping conversation intact
+* **manual compaction** (like `/compact`) at logical breakpoints summarises older conversation into a brief paragraph, preserving action items and user intent
+* users may **pin individual messages** to prevent their removal during compaction
+
+No automatic summarisation of conversation will occur; compaction is only triggered explicitly or when token pressure requires micro‑compaction.
+
+### 3. artifacts – chunking + summary field
+
+Large artifacts (e.g., plans) are broken into chunks; only the current step ± 1 neighbor is kept in context. Remaining chunks are stored on disk with a file pointer left in the artifact.
+
+All artifacts must include a `summary` field as part of their canonical schema. Non‑chunkable artifacts use this summary directly in context packs.
+
+### 4. event history → L2 – structured decision points
+
+L2 (compressed session memory) is built not by summarising events but by harvesting structured fields from existing validated artifacts and approval events:
+
+* `summary` from the artifact → what was done
+* `rationale` from the artifact (optional) → why it was done
+* user steering text from approval events → human guidance
+* stage outcome (success/failure/retry) → final status
+
+These are assembled into a lightweight `DecisionPoint` record per completed stage. No model‑based summarisation is performed; the process is purely rule‑based and deterministic.
+
+Older decision points eventually graduate to L3 project memory when the L2 token cap is exceeded.
+
+### 5. no tiny summariser model
+
+We explicitly postpone any model‑based compression beyond v1. Even v2 will re‑evaluate only if rule‑based compression proves insufficient, and then only for specific narrow tasks.
+
+## consequences
+
+**positive:**
+
+* full determinism and replayability for all compression steps
+* zero additional inference cost for compression
+* tool output compressed dramatically (≥90% reduction on typical dev commands)
+* conversation compaction is user‑controlled, preventing silent loss of important instructions
+* decision points capture the *why*, not just the *what*, allowing later stages to reason about past choices
+* architecture scales with more sophisticated compression later without changing contracts
+
+**negative:**
+
+* rule‑based extraction may miss decision nuances when models omit the `rationale` field (mitigated by prompt design and user steering)
+* manual compaction requires user awareness; if never used, conversation history may still grow until micro‑compaction kicks in
+* per‑tool regex patterns require tool authors to think about summarisation, adding a small authoring burden (mitigated by sensible defaults and fallback truncation)
+
+## alternatives considered
+
+* **dedicated tiny summariser model** – would improve compression quality but introduces nondeterminism, increased system complexity, and higher resource usage. Rejected for v1.
+* **only truncation** – simplest but loses too much critical information. Rejected.
+* **full context window without compression** – impossible for local models with limited context (≤32k tokens) and long‑running sessions. Rejected.
+
+## status
+
+This decision defines the v1 compression architecture. It may be revisited in a future ADR if empirical data shows rule‑based compression is insufficient for critical decision‑making.