spb/khaelor Public
KHAELOR — a terminal-native autonomous engineering agent powered by Anthropic.
TypeScript 82.9%
HTML 14.9%
CSS 1.1%
JavaScript 0.7%
1<!doctype html>2<!--3KHAELOR4File: website/public/docs/phases.html5Description: Docs — phase gates (understand → design → implement), native verification, and project memory (v2).6Author: Simon-Pierre Boucher7Contact: contact@spboucher.ai8-->9<html lang="en">10<head>11<meta charset="utf-8">12<meta name="viewport" content="width=device-width, initial-scale=1">13<title>Phase gates & verification — KHAELOR docs</title>14<meta name="description" content="Understand → design → implement as an enforced runtime mechanism: design artifacts, gate modes, native verification, and provenance-anchored project memory.">15<link rel="stylesheet" href="/styles.css">16<script>17(function(){try{var t=localStorage.getItem("khaelor-theme");if(!t&&window.matchMedia&&window.matchMedia("(prefers-color-scheme: light)").matches)t="light";if(t==="light")document.documentElement.setAttribute("data-theme","light");}catch(e){}})();18</script>19<script defer src="/site.js"></script>20</head>21<body>2223<header class="site-header"><div class="inner">24 <a class="wordmark" href="/"><span class="glyph">❯</span><span class="g-ember">KHAELOR</span></a>25 <nav>26 <a href="/docs/getting-started.html">Docs</a>27 <a href="/#install">Install</a>28 <button id="theme-toggle" type="button" aria-label="Toggle color theme">light</button>29 </nav>30</div></header>3132<main class="page"><div class="docs-layout">3334<aside class="sidebar">35 <div class="group"><div class="group-title">Start</div>36 <a href="/docs/getting-started.html">Getting started</a>37 <a href="/docs/cookbook.html">Cookbook</a>38 </div>39 <div class="group"><div class="group-title">Using KHAELOR</div>40 <a href="/docs/usage.html">The TUI</a>41 <a href="/docs/commands.html">Commands & keyboard</a>42 <a href="/docs/tools.html">Tools</a>43 <a href="/docs/sessions.html">Sessions</a>44 </div>45 <div class="group"><div class="group-title">Autonomy</div>46 <a href="/docs/phases.html">Phase gates</a>47 <a href="/docs/verification.html">Verification</a>48 <a href="/docs/worktrees.html">Parallel worktrees</a>49 <a href="/docs/daemon.html">The daemon</a>50 </div>51 <div class="group"><div class="group-title">Intelligence</div>52 <a href="/docs/repograph.html">Semantic index</a>53 <a href="/docs/memory.html">Project memory</a>54 <a href="/docs/context.html">Context engine</a>55 <a href="/docs/fork-replay.html">Fork · replay · sdiff</a>56 </div>57 <div class="group"><div class="group-title">Control</div>58 <a href="/docs/permissions.html">Permissions</a>59 <a href="/docs/configuration.html">Configuration</a>60 <a href="/docs/cli.html">CLI reference</a>61 </div>62 <div class="group"><div class="group-title">Internals</div>63 <a href="/docs/architecture.html">Architecture</a>64 <a href="/docs/events.html">The event model</a>65 <a href="/docs/theming.html">Theming & terminal</a>66 </div>67 <div class="group"><div class="group-title">Help</div>68 <a href="/docs/faq.html">FAQ & troubleshooting</a>69 </div>70</aside>7172<article class="content">7374<h1>Phase gates & verification</h1>75<p class="lead">“Understand first. Design second. Implement third.” is not a slogan in KHAELOR —76it is a mechanism of the tool runtime, enforced by the permission model.</p>7778<h2 id="phases">The three phases<a class="anchor" href="#phases">#</a></h2>79<p>Every gated session moves through three phases, shown live in the status bar ribbon:</p>80<pre class="term" data-no-copy><code> <span class="t-ember">◐ UNDERSTAND</span> <span class="t-dim">─ design ─ implement</span> read · grep · glob · symbols · refs · read-only bash81 <span class="t-dim">✓ understand ─</span> <span class="t-ember">◑ DESIGN</span> <span class="t-dim">─ implement</span> + write docs/design/*.md only82 <span class="t-dim">✓ understand ─ ✓ design ─</span> <span class="t-ember">● IMPLEMENT</span> write · edit · full bash unlocked</code></pre>83<p>If the agent tries to edit before its design is approved, the tool call fails with a structured84<code>PHASE_GATE_BLOCKED</code> error telling it to finalize its design first. That is prompt engineering85by architecture: the model learns the workflow because the runtime enforces it.</p>8687<h2 id="artifact">The design artifact<a class="anchor" href="#artifact">#</a></h2>88<p>The agent unlocks implementation by calling the <code>design</code> tool with a structured artifact:</p>89<table>90 <tr><th>Field</th><th>Meaning</th></tr>91 <tr><td><code>goal</code></td><td class="wrap">The need, restated in the agent's own words.</td></tr>92 <tr><td><code>files</code></td><td class="wrap">The files it plans to modify — the auto-approval threshold counts these.</td></tr>93 <tr><td><code>approach</code></td><td class="wrap">The technical plan, 5–15 lines.</td></tr>94 <tr><td><code>risks</code></td><td class="wrap">Identified risks; lines prefixed <code>out of scope:</code> become explicit non-goals.</td></tr>95 <tr><td><code>verification</code></td><td class="wrap">How the agent will prove the change works.</td></tr>96</table>97<p>The artifact is a durable event in the session log — every approved design is part of the98auditable history, including the ones the daemon records at night.</p>99100<h2 id="modes">Gate modes<a class="anchor" href="#modes">#</a></h2>101<pre><code>khaelor --gate strict # three phases, human approval of every design102khaelor --gate auto # self-approves designs touching ≤ 3 files (default)103khaelor --gate off # v1 behavior — no gate</code></pre>104<p>Configure the threshold in <code>.khaelor/config.json</code>:</p>105<pre><code>{106 "gate": { "mode": "auto", "autoApprove": { "maxFiles": 3 } }107}</code></pre>108<p><code>/phase</code> is the escape hatch: it shows the current phase and lets you force a transition —109always logged as a <code>user-override</code> event, never silent.</p>110111<h2 id="verify">Native verification<a class="anchor" href="#verify">#</a></h2>112<p>After each batch of edits, KHAELOR runs your project's checks itself — in parallel — and feeds113failures back to the model <em>before</em> handing back to you, in a bounded repair loop114(default 3 rounds, then an honest failure report). Checks are auto-detected from115<code>package.json</code>, <code>tsconfig.json</code>, <code>Cargo.toml</code>, or <code>pyproject.toml</code>,116and overridable:</p>117<pre><code>// .khaelor/verify.json118{119 "typecheck": { "cmd": "npx tsc --noEmit", "timeout": 60 },120 "test": { "cmd": "npx vitest run --changed", "timeout": 120 },121 "lint": { "cmd": "npx eslint --fix", "timeout": 30, "autofix": true },122 "policy": "after-each-edit-batch",123 "maxRepairLoops": 3124}</code></pre>125<pre class="term" data-no-copy><code> <span class="t-glow">⟳</span> <span class="t-b">verify</span> typecheck <span class="t-ok">✓</span> <span class="t-dim">1.2s</span> · tests <span class="t-err">✗</span> · lint <span class="t-ok">✓</span>126 <span class="t-dim">FAIL src/context/engine.test.ts — compaction preserves running processes</span>127 <span class="t-dim">KHAELOR is repairing the failure…</span>128 <span class="t-ok">✓ verified 5.3s</span></code></pre>129<p>Run the whole suite on demand with <code>/verify</code>. Every result is a durable130<code>verify.result</code> event: real commands, real exit codes, errors-first truncation.</p>131132<h2 id="memory">Project memory with provenance<a class="anchor" href="#memory">#</a></h2>133<p>When the agent discovers a durable fact — a convention, a build command, a pitfall — it persists134it with the <code>remember</code> tool into <code>.khaelor/MEMORY.md</code>: readable, git-versionable,135and injected into context at every session start. Each entry is anchored to the session and tool136call that produced it:</p>137<pre><code>## Conventions138- Errors flow through Result<T, KError>; never throw in src/core.139 <!-- khaelor: session=01J8… tool=toolu_01… confidence=high date=2026-08-10 --></code></pre>140<p><code>/memory</code> lists the entries with their provenance; low-confidence entries not re-confirmed141become purge candidates at the next <code>/compact</code>. You always know <em>why</em> the agent142believes something.</p>143144<div class="pager">145 <div><span class="label">Previous</span><a href="/docs/sessions.html">← Sessions</a></div>146 <div class="next"><span class="label">Next</span><a href="/docs/daemon.html">The daemon →</a></div>147</div>148149</article>150</div></main>151152<footer class="site-footer"><div class="inner">153 <span>KHAELOR — Simon-Pierre Boucher · <a href="mailto:contact@spboucher.ai">contact@spboucher.ai</a></span>154 <span>Anthropic-powered · terminal-native by design</span>155</div></footer>156157</body>158</html>159