# KHAELOR v2 — implementation notes (0.2.0) The seven v2 work streams plus the "Terminal Cinema" TUI upgrade, as shipped. Every number below is enforced by `npm run check` (typecheck · eslint · vitest · header check). ## §1 Phase gates — `src/phases/` - Events: `phase.entered` / `phase.artifact` / `phase.approved` / `phase.rejected` (durable catalog, `src/session/events.ts`). - `PhaseService` sits AROUND the kernel: the Tool Runtime (`src/agent/executor.ts`) consults `checkToolCall` between capability mapping and permission evaluation; blocked calls fail with structured `PHASE_GATE_BLOCKED` repair prose. - Per-phase policy (`src/phases/gate.ts`): understand = read + read-only bash whitelist; design = + `docs/design/*.md`; implement = everything. `.khaelor/MEMORY.md` writable in every phase. - The model unlocks implement via the `design` tool (`src/tools/design.ts`). - Modes: `--gate strict|auto|off`, config `gate.autoApprove.maxFiles` (default 3). The doc's `maxRiskLevel` is not implemented — risks are free text; file count is the auto-approval criterion. - TUI: phase ribbon in the status bar, design panel (`src/tui/components/design-panel.ts`), strict-mode approval via the selector (Esc = reject; silence is never approval), `/phase` override. ## §4 Native verification — `src/verify/` - `.khaelor/verify.json` or auto-detection (package.json scripts / tsconfig / Cargo.toml / pyproject). - `VerifyRunner` runs checks in parallel (autofix checks last, serially) through the Workspace seam; each check is a durable `verify.result` with real exit codes and errors-first truncation. - Policy `after-each-edit-batch` (default) triggers in the executor after a successful write/edit batch. Failing results are folded into the conversation as user-visible input (the model repairs them) with a bounded loop: `maxRepairLoops` (default 3) failures per user turn, then honest stop. - `before-final-answer` maps onto the existing VerificationGate nudge flow; `/verify` runs on demand. ## §2 Fork / replay / sdiff — `src/session/fork.ts`, `sdiff.ts`, `src/cli/replay.ts` - `.meta.json` lineage (`parent`, `forkPoint`, `replayOf`). - `/fork` lists natural checkpoints (user turns, approved designs, compactions), copies the JSONL prefix (sessionIds rewritten, seq/payloads byte-preserved) and opens the fork. - `/replay` re-runs the user turns headless inside a throwaway worktree (`--sandbox` semantics built-in). - `/sdiff` folds two logs into turns/tool-calls/files/tokens/verify-failures/outcome. ## §5 Project memory — `src/memory/`, `src/tools/remember.ts` - `.khaelor/MEMORY.md`, entries anchored `` (the tool_use id is the event anchor). `memory.written` durable event. - Injected as a project-instruction tier at engine assembly; `/memory` lists with provenance; low-confidence entries surface as purge candidates. ## §3 RepoGraph — `src/repograph/` - Dependency-free heuristic extractor (TS/JS/Python): symbols, doc comments, imports. tree-sitter is the documented upgrade path — the service interface will not change. - Incremental by mtime, lazy debounced refresh, in-memory graph; `symbols` and `refs` (callers/callees/importers) tools; `skeleton()` produces signature-level file views for the context engine (wired for future compaction use). ## §6 Parallel worktrees — `src/tasks/`, `src/cli/subtasks.ts` - `subtask.created` / `subtask.completed` durable events with REAL git diff stats. - Children run a full headless engine in `.khaelor/worktrees/` on branch `khaelor/`: own JSONL (meta.parent → orchestrator), non-interactive permissions (asks deny), gates + verify on. - `/spawn`, `/tasks`, `/merge` (supervised `--no-ff`; conflicts abort cleanly). ## §7 Daemon — `src/daemon/`, bin `khaelord` - Scheduler (cron parser + heartbeat tick), event-sourced `GoalStore` (`.khaelor/daemon/goals/.json` + `.events.jsonl`), `BudgetGuard` (hard daily/per-goal USD ceilings from a persisted ledger; costs only priced when `pricing` is configured — never invented), `ApprovalQueue` (persisted; suspended run costs zero), `ChannelRouter` (webhook + command adapters), control socket (`status/goals/approvals/approve/deny/stop`), `khaelor` TUI `/goals` view. - Goal runs = throwaway worktree + headless engine + gates + verify; escalation notify / draft-pr (branch left for review) / auto-merge-if-verified. LLM heartbeat triage is not implemented — the goal `check` command is the cheap tier; an injectable seam exists. ## TUI v2 — "Terminal Cinema" - Khaelis palette (obsidian + magma: ember #FF6B35 → glow #FFB86B, teal #2DD4BF) as the default dark theme; OKLCH gradient interpolation (`src/tui/theme/gradient.ts`), `ember` named gradient. - Cockpit status bar: phase ribbon + `▰▱` context gauge (≥110 cols) + cost; verify strip, design panel, braille sparkline widgets; splash (`--splash`, gradient sweep, skippable); `MotionController` (six sanctioned effects, tick-driven, motion-off aware); `--doctor-tui`. ## Website (www.khaelor.sh) - Full Khaelis redesign, v2 landing (cockpit demo, feature grid, daemon section, design-panel mock), new docs: `phases.html`, `daemon.html`; sessions/commands updated; installer artifact 0.2.0.