Phase gates & verification

“Understand first. Design second. Implement third.” is not a slogan in KHAELOR — it is a mechanism of the tool runtime, enforced by the permission model.

The three phases#

Every gated session moves through three phases, shown live in the status bar ribbon:

 ◐ UNDERSTAND ─ design ─ implement     read · grep · glob · symbols · refs · read-only bash
 ✓ understand ─ ◑ DESIGN ─ implement     + write docs/design/*.md only
 ✓ understand ─ ✓ design ─ ● IMPLEMENT   write · edit · full bash unlocked

If the agent tries to edit before its design is approved, the tool call fails with a structured PHASE_GATE_BLOCKED error telling it to finalize its design first. That is prompt engineering by architecture: the model learns the workflow because the runtime enforces it.

The design artifact#

The agent unlocks implementation by calling the design tool with a structured artifact:

The artifact is a durable event in the session log — every approved design is part of the auditable history, including the ones the daemon records at night.

Gate modes#

khaelor --gate strict    # three phases, human approval of every design
khaelor --gate auto      # self-approves designs touching ≤ 3 files (default)
khaelor --gate off       # v1 behavior — no gate

Configure the threshold in .khaelor/config.json:

{
  "gate": { "mode": "auto", "autoApprove": { "maxFiles": 3 } }
}

/phase is the escape hatch: it shows the current phase and lets you force a transition — always logged as a user-override event, never silent.

Native verification#

After each batch of edits, KHAELOR runs your project's checks itself — in parallel — and feeds failures back to the model before handing back to you, in a bounded repair loop (default 3 rounds, then an honest failure report). Checks are auto-detected from package.json, tsconfig.json, Cargo.toml, or pyproject.toml, and overridable:

// .khaelor/verify.json
{
  "typecheck": { "cmd": "npx tsc --noEmit", "timeout": 60 },
  "test":      { "cmd": "npx vitest run --changed", "timeout": 120 },
  "lint":      { "cmd": "npx eslint --fix", "timeout": 30, "autofix": true },
  "policy": "after-each-edit-batch",
  "maxRepairLoops": 3
}

 ⟳ verify   typecheck ✓ 1.2s · tests ✗ · lint ✓
   FAIL src/context/engine.test.ts — compaction preserves running processes
 KHAELOR is repairing the failure…
 ✓ verified 5.3s

Run the whole suite on demand with /verify. Every result is a durable verify.result event: real commands, real exit codes, errors-first truncation.

Project memory with provenance#

When the agent discovers a durable fact — a convention, a build command, a pitfall — it persists it with the remember tool into .khaelor/MEMORY.md: readable, git-versionable, and injected into context at every session start. Each entry is anchored to the session and tool call that produced it:

## Conventions
- Errors flow through Result<T, KError>; never throw in src/core.
  <!-- khaelor: session=01J8… tool=toolu_01… confidence=high date=2026-08-10 -->

/memory lists the entries with their provenance; low-confidence entries not re-confirmed become purge candidates at the next /compact. You always know why the agent believes something.