# Correx — Catch-up for a ~2-month-old memory

**If your last memory of Correx is the epic-13/epic-14 era (mid-May 2026), read this.**

Back then the project was a *skeleton*: epics 0–14 had landed the module structure
(events → sessions → transitions → validation → approvals → artifacts → context →
tools → inference → kernel → infra → interfaces → router). It compiled and replayed,
but the orchestration loop was thin and mostly unproven against real model runs.

Two months and ~250 feature commits later, the architecture is the *same* (all 9 Hard
Invariants still hold; the event log is still the only source of truth), but nearly the
entire *behavioral* layer — how a session actually drives a model through real work —
was built and hardened by live QA. This document groups the major additions. It is a
map, not a changelog; the dated files in `docs/plans/` are the real changelog.

Work is no longer tracked as "epics." It's tracked as **plans** (`docs/plans/`) and a
**Vikunja backlog** (project_id 4).

---

## The single biggest correction: the TUI is now Go

The Kotlin TUI (Mosaic, then tamboui) was **retired**. The interactive terminal UI is
now a **Go / Bubble Tea** app at `apps/tui-go` — a WS client of the server. `apps/cli`
(Clikt, Kotlin) and `apps/server` (Ktor) are the only Gradle app modules; the old
`apps/desktop` / `apps/worker` stubs were deleted. If you remember tamboui, forget it.

## New whole subsystems (did not meaningfully exist at epic-14)

**Native task tracking (`core:tasks`).** A dependency-aware work graph: `task_decompose`
splits a goal into a DEPENDS_ON graph in one approval; tasks have claim gates
(dependency-hard-gate, cite-before-claim, duplicate-title guard), per-task history,
markdown export, a full REST surface, a `correx task` CLI, a TUI task board with
readiness, and **git-driven status** (a commit mention → IN_PROGRESS, a closing keyword
→ DONE, idempotent). The execution loop is now *tasked* — it replaced the old linear
role_pipeline.

**Plane-2 tool-call intent validation (`core:toolintent`).** An anti-hallucination /
safety layer that assesses every tool call *before* it runs and records
`ToolCallAssessedEvent`: path-containment, read-before-write, reference-must-exist,
write-scope adherence, stale-write, exec-interpreter and network-host rules, and a
per-session egress allowlist. This is the layer that stops an agent citing files it
never read or writing outside its declared scope.

**Compression pipeline (`infrastructure:compression`).** A staged, replay-safe context
compressor: level policy → fact sheet + strict allocation → tier summarizer → token
pruning + embedding relevance + ToMe merge → static-doc pruning (CLAUDE.md/AGENTS.md).
Distinct from the required/optional *bucket* rework in `core:context`.

**Staged verification & review gates.** Stage output passes a gate ladder instead of
being trusted: build gate, plan-compile gate, contract/execution gate, and a
semantic-review gate (`core:critique`, with structured `CritiqueFinding` + per-model
calibration). Per-gate retry budgets with progress-aware charging and hybrid salvage;
static-first reviewer framing; capability-gap reflection; brief echo-back gate.

**Research workflow.** `WebSearchTool` (local SearXNG), `WebFetchTool` (bounded fetch),
deterministic HTML→markdown extraction, a research workflow graph, batch source-fetch
approval, and dedicated `SourceFetched` / `LowQualityExtraction` events. On by default.

**Cross-session repo memory (L3 + repo-map + project profile).** `RepoMapIndexer`
(symbols for Kotlin, GDScript, C#/Godot-Mono, markdown headings), `RepoKnowledgeRetriever`
with recency fallback, L3 ANN retrieval (`in_memory` or `turbovec` sidecar) recorded as
environment observations, `ProjectMemoryService`/`Distiller`, and `ProjectProfile`
(per-repo standing context at `.correx/project.toml`) injected as L0. Note: this is
*repo-scoped* memory — the "cross-session memory" anti-feature (conversational recall)
is still deliberately out.

**Git run-branch transport (the "Gitea transport") — SHIPPED.** The server owns a Git
checkout; each run pushes to a run branch (`GitRunBranchTransport`, `RunBranchPushedEvent`);
`GitTaskSync`/`GitCommandCommitReader` drive task status from commits. "gitea" is just
the configured remote name; the transport is plain Git.

**Observability & replay tooling (Epic 15, largely shipped).** Event-stream inspector
(`correx events`, `/sessions/{id}/events`), session replay + determinism digest,
causation-graph DOT export, metrics as a replayable projection (`correx stats`),
event-sourced health checks (EventStore latency, llama-server liveness, disk watermark,
ROCm/VRAM probe), and correlation-structured MDC logging.

**Model lifecycle management (`[[models]]`).** Correx spawns/owns the llama-server
process: per-stage model selection, manual swap + pin, resource telemetry, VRAM gauge.
(The autonomous *residency scheduler* is still unbuilt — see below.)

**Workspace scoping & undo.** `WorkspaceResolver` trust pipeline + `allowed_workspace_roots`,
per-session workspace-scoped tools/policy, client→server workspace handshake, crash-safe
atomic file writes with pre/post-image captured to CAS (`FileWrittenEvent`), and a
`FileMutationReverser` undo primitive (server endpoint + CLI). Agents can also READ
outside `workspace_root` via an operator approval prompt (writes stay jailed).

**Approvals & grants.** Cross-session grant scopes (PROJECT/GLOBAL) + revoke,
grant-aware approval engine, risk rationale surfaced to the operator; approval gates now
block indefinitely instead of auto-rejecting on timeout, and steering actually affects
the run.

**Router interaction layer.** Beyond CHAT+STEERING: grounded system prompts, triage
directive (no bare refusals), structured **workflow proposals** from triage, a
**clarification-question loop** (analyst asks, operator answers, producer-exit rehydrate
on reconnect), **rubber-duck idea board** (capture/feed/promote to project profile), and
grounded **narration** (pinned narration model, latency/token metrics surfaced).

**Freestyle / execution-plan engine.** Two-phase planning→execution driver,
`ExecutionPlanCompiler` + `ExecutionPlanLockedEvent`, post-plan operator approval gate,
freestyle graph re-routing (deterministic override), soft-lock steering preemption,
plan grounding + positive-pattern mining + a stage-prompt audition rig.

**Decision journal (`core:journal`).** Decision-journal projection injected into stage
context, salience-aware compaction (`JournalCompactionService`, CAS-rendered).

**Personalization (`core:config`).** `OperatorProfile` + `ProfileLoader` bound at start
and surfaced into L0; propose-only `ProfileAdaptationService`.

**Native MCP host.** The server mounts external stdio MCP servers as first-class Correx
tools (inherit tier / receipt / replay). `codebase-memory-mcp` is installed and granted
per code-intel stage.

**Recovery loop.** Failed write-less stages route to recovery instead of futile retry;
tier-2 intent-holder arbiter; remaining-delta pinning; failure-ticket routing +
review-gate RECOVER + return-to-sender; structured package-404 recovery evidence;
stage-global repeated-failure loop breaker.

**Godot / game-dev support.** GDScript + C#/Godot-Mono symbol extraction in the repo
map, and a structural `.tscn`/`.tres` scene validator.

## Refactors & hardening you'll notice

- `DefaultSessionOrchestrator` god-class decomposed into per-concern extensions;
  `DomainEventMapper`'s god-`when` split per-domain. Detekt baseline ratcheted 120 → 90.
- Persistence hardened: sequences assigned atomically inside INSERT, reads serialized
  with the append transaction, slow WS clients no longer stall the kernel.
- Tool results bounded + framed, full output spilled to CAS with a `tool_output`
  retrieval tool; `glob`/`grep` search tools; web_fetch SSRF fix; interruptible shell
  timeouts with process-tree kill; shell allowlist validates every command position.
- Config: orchestration loop/threshold/budget constants moved to `[orchestration]`;
  operator-tunable sampling knobs (top_k/min_p/repeat_penalty) per stage.

## Still planned / deliberately NOT built (don't assume these exist)

- Full **remote always-on / thin-client** deployment topology. Its Git *transport*
  shipped (above); the hosting topology itself is not yet stood up.
- Full router **context isolation** (persistent conversation history, session-scoped
  boundaries). CHAT+STEERING works; the isolation layer is deferred.
- Autonomous GPU **residency scheduling** (lifecycle *is* built; idle-eviction policy
  is not).
- Still explicitly out: parallel agent execution, conversational cross-session memory,
  three-critic ensemble, fine-tuning, streaming inference.

## Where to look now

- `CLAUDE.md` — current session guide, Module Map, invariants.
- `docs/plans/` — the real changelog of intent since epic-14 (dated files).
- Vikunja project 4 — live backlog. `scripts/ctx.py <query>` — ranked file/symbol lookup.