spb/khaelor Public

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