epoch

Author: solatis

.config/wt.toml

@@ -0,0 +1,12 @@
+# Koan project worktree hooks
+# Docs: https://worktrunk.dev/hook/
+
+[post-create]
+deps = "uv sync --dev"
+
+[post-start]
+copy = "wt step copy-ignored"
+
+[pre-merge]
+check = "uv run ruff check ."
+test = "uv run pytest"

.github/workflows/ci.yml

@@ -0,0 +1,28 @@
+name: CI
+
+on:
+  push:
+    branches: ["main"]
+  pull_request:
+  workflow_dispatch:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v4
+
+      - name: Install dependencies
+        run: uv sync --dev
+
+      - name: Run tests
+        run: uv run pytest

.gitignore

@@ -1,4 +1,14 @@
-node_modules/
-dist/
 .pi/
 .DS_Store
+
+.claude/
+plans/
+.env
+.env.*
+*.log
+
+# Frontend build output (committed source lives in frontend/src/)
+koan/web/static/app/
+frontend/node_modules/
+frontend/dist/
+__pycache__/

.koan/memory/.gitignore

@@ -0,0 +1,2 @@
+.index/
+summary.md

.koan/memory/0001-persistent-orchestrator-over-per-phase-cli.md

@@ -0,0 +1,8 @@
+---
+title: Persistent orchestrator over per-phase CLI spawning
+type: decision
+created: '2026-04-16T07:13:41Z'
+modified: '2026-04-16T07:13:41Z'
+---
+
+This entry documents the orchestrator spawn architecture decision in koan's workflow engine (`koan/driver.py`). On 2026-04-02, Leon redesigned the system to replace per-phase CLI process spawning with a single long-lived orchestrator process running the entire workflow in one continuous session. Previously, each planning phase spawned a fresh `claude`, `codex`, or `gemini` CLI process; a separate `workflow-orchestrator` subagent was then spawned to present the user with a phase-selection decision after each phase completed. Leon's rationale: per-phase spawning caused compounding context loss (each new process re-derived what the previous had explored), and the workflow-orchestrator role was architecturally wasteful -- "a process-boot just to ask a question." Two alternatives were explicitly rejected: (1) API-based conversation (driver calling the LLM API directly) -- would have bypassed the runner abstraction handling model selection, MCP config, output streaming, and thinking mode; (2) context injection into fresh processes per phase -- cheaper but fails to provide a persistent reasoning chain and does not eliminate the workflow-orchestrator overhead. The redesign landed in `koan/driver.py` as a single `spawn_subagent()` call awaiting the orchestrator's exit, and added `koan_set_phase` as the new phase-transition tool replacing the two-tool `koan_propose_workflow` / `koan_set_next_phase` dance.

.koan/memory/0002-step-first-workflow-pattern-boot-prompt-is.md

@@ -0,0 +1,8 @@
+---
+title: Step-first workflow pattern -- boot prompt is exactly one sentence
+type: decision
+created: '2026-04-16T07:13:50Z'
+modified: '2026-04-16T07:13:50Z'
+---
+
+The step-first workflow pattern governs how all LLM subagent CLI processes in koan receive task instructions. On 2026-02-10, Leon established this as a load-bearing architectural invariant in the koan initial design (documented in `docs/architecture.md` as Invariant 2 and enforced in `koan/web/mcp_endpoint.py`). The rule: every subagent's boot prompt is exactly one sentence -- role identity plus "Call koan_complete_step to receive your instructions." Task details, phase guidance, and tool lists arrive exclusively as the return value of the first `koan_complete_step` MCP call. The pattern was motivated by a failure mode observed with haiku-class (weaker) models: complex task instructions in the boot prompt caused these models to produce text output on the first turn and exit without ever entering the tool-calling loop. Three reinforcement mechanisms make the pattern robust across model capability levels: primacy (boot prompt is the LLM's very first message), recency (`format_step()` in `koan/phases/format_step.py` always appends "WHEN DONE: Call koan_complete_step..." last), and muscle memory (by step 2 the LLM has called the tool multiple times, locking in the pattern).

.koan/memory/0003-server-authoritative-projection-via-json-patch.md

@@ -0,0 +1,8 @@
+---
+title: Server-authoritative projection via JSON Patch over symmetric dual fold
+type: decision
+created: '2026-04-16T07:13:57Z'
+modified: '2026-04-16T07:13:57Z'
+---
+
+The koan projection system maintains frontend-visible workflow state for the browser dashboard, served via Server-Sent Events from `koan/projections.py`. On 2026-03-29, Leon decided to replace a dual fold architecture with a server-authoritative JSON Patch model. The prior design maintained two independent fold implementations -- one in Python (`koan/projections.py`) and one in TypeScript (`frontend/src/sse/connect.ts`) -- required to produce identical projections from the same event sequence. Two production bugs traced directly to these folds diverging: fragmented thinking cards in the activity feed, and scout events appearing incorrectly in the primary agent's conversation feed. Leon's decision: Python computes the fold and the RFC 6902 JSON Patch diff after each event; the browser applies patches mechanically via `fast-json-patch` with no fold logic, no event interpretation, and no business rules. Simultaneously, Leon adopted camelCase for all wire-format keys so patches apply directly to the Zustand store without a field-renaming layer. The correctness guarantee is now structural: one fold in one place.

.koan/memory/0004-file-boundary-invariant-llms-write-markdown.md

@@ -0,0 +1,8 @@
+---
+title: File boundary invariant -- LLMs write markdown, driver writes JSON
+type: decision
+created: '2026-04-16T07:14:03Z'
+modified: '2026-04-16T07:14:03Z'
+---
+
+The file boundary invariant is a load-bearing architectural constraint in koan governing file ownership across the system's actors. On 2026-02-10, Leon established this rule in the koan initial design (documented in `docs/architecture.md` as Invariant 1). The rule: LLM subagents write markdown files only; the koan driver (`koan/driver.py`) reads and writes JSON state files exclusively; tool code in `koan/web/mcp_endpoint.py` bridges both worlds by writing JSON state (for the driver) and templated markdown status files (for LLMs) in the same operation. Leon's stated rationale: if an LLM writes a JSON file, schema drift and parse errors in the payload become runtime failures in the deterministic driver, while markdown is forgiving. The invariant is enforced structurally -- planning-role subagents have write access scoped to the run directory (`~/.koan/runs/<id>/`) but no mechanism to produce JSON state files, and the driver reads JSON state files and exit codes only, never parsing markdown.

.koan/memory/0005-phase-trust-model-plan-review-as-designated.md

@@ -0,0 +1,10 @@
+---
+title: Phase trust model -- plan-review as designated adversarial verifier
+type: decision
+created: '2026-04-16T07:35:13Z'
+modified: '2026-04-16T07:35:13Z'
+related:
+- 0001-persistent-orchestrator-over-per-phase-cli.md
+---
+
+The plan workflow's phase trust architecture in koan (`docs/phase-trust.md`, `koan/lib/workflows.py`) was designed around an asymmetric verification model. On 2026-02-10, Leon formalized this as part of the initial koan design: phases in the plan pipeline (intake, plan-spec, execute) were built to trust each other's outputs without re-verification; only plan-review was designated as the adversarial verifier. Leon documented the rationale in `docs/phase-trust.md`: cross-phase re-verification is the "intrinsic self-correction" anti-pattern -- research shows the same LLM re-checking its own prior work is more likely to change correct conclusions to incorrect ones than the reverse. Leon gave plan-review the CRITIC role: it uses the actual codebase as an external tool to check every file path, function name, signature, and type claim in `plan.md` against reality. Leon also decided that plan-review would be advisory only -- it reports findings with severity classification and may suggest looping back to plan-spec for critical or major issues, but it does not modify `plan.md` itself.

.koan/memory/0006-directory-as-contract-taskjson-over-cli-flags-for.md

@@ -0,0 +1,10 @@
+---
+title: Directory-as-contract -- task.json over CLI flags for subagent configuration
+type: decision
+created: '2026-04-16T07:35:24Z'
+modified: '2026-04-16T07:35:24Z'
+related:
+- 0004-file-boundary-invariant-llms-write-markdown.md
+---
+
+The subagent configuration mechanism in koan (`koan/subagent.py`, `docs/subagents.md`) was redesigned on 2026-02-10 when Leon replaced a 9-CLI-flag approach with a task.json file convention, later documented as Invariant 6 (Directory-as-contract) in `docs/architecture.md`. The previous design passed task configuration as 9 CLI arguments; Leon replaced it after identifying four problems: (1) the flat flag namespace caused naming collisions (`--koan-role` vs `--koan-scout-role`); (2) role-specific fields mixed with common fields without structure; (3) `--koan-retry-context` needed to carry multi-paragraph summaries exceeding practical CLI limits; (4) after a crash, reconstructing what a subagent had been asked required parsing process arguments from system logs. Leon adopted the convention that the driver would write `task.json` atomically (tmp + `os.rename()`) to the subagent directory before spawn. The subagent discovers its MCP endpoint by reading `mcp_url` from that file. No structured configuration flows through CLI flags, environment variables, or other process-level channels. Leon designated `task.json` as write-once by the parent before spawn and read-once by the parent at agent registration, never modified afterward.