pi-htn

Layer 1Command Surface (Extension Layer)

The extension entry point src/index.ts registers a single /htn command and dispatches to subcommands. It is intentionally thin: it parses input (e.g. intent=bug body=… into a world-state object), wires the correct engine path, and reports a one-line run notice. Tab completion is data-driven from src/commands/complete.ts — it autocompletes subcommands, setting keys, and stored domain names.

• /htn author <name> — read the session trace, ask the big model for N candidate domains, gate each, save the best passing one.
• /htn run <name> [input] — compile a stored domain and execute it; reports mode (live / dry-run / live: <tools>).
• /htn watch <pr> [domain] — heal a PR's CI until merge-ready.
• /htn settings — panel persisting model endpoint, default domain, heal rounds, poll interval to ~/.pi-htn/config.json.
• /htn list — list stored domains.

Figure 2 — The dispatcher routes; each subcommand owns its own engine wiring.

Layer 2Authoring Pipeline

Authoring is rare and runs on the big model. The Recorder parses the active session JSONL (an id/parentId tree) and extracts the ordered tool calls. The Author turns that trace into a prompt that asks the model to extract reusable structure — which steps are conditional, the branch predicates, observed failures — not just replay the literal trace. It requests N=3 candidate YAML domains.

Every candidate passes through the Validator, the reliability gate: for each synthetic world state it runs findPlan (decomposition only, no operators fire) and requires a non-empty plan. Best-of-N keeps the best passing candidate; the symbolic validator is the hard gate, and scoring only ranks among passers. The winner is written by the DomainStore to ~/.pi-htn/domains/<name>.yaml.

Figure 3 — A successful trace becomes a reusable, validated YAML domain. The gate is symbolic, not statistical.

Layer 3Compile + Plan Engine

The Compiler walks the YAML task tree and builds the plain-object structure GamePlanHTN's Domain constructor understands. Conditions compile through the Predicate DSL ({eq:[k,v]}, {has:k}, {not:…}); effects compile to PlanAndExecute state writes. Crucially, the compiled planning operator is a no-op that reports success so decomposition completes — real side-effects run later, in the Executor (this is "execution mode B"). Because GamePlanHTN's PrimitiveTask drops unknown fields, the Executor recovers the tool binding by task name.

The engine seeds every referenced world-state key before init() so planning-mode state lookups resolve, then Domain.findPlan produces a plan with symbolic backtracking. GamePlanHTN is vendored under vendor/gameplanhtn/ and used purely as the planner/backtracker.

Figure 4 — YAML data is compiled to a vendored GamePlanHTN domain and decomposed. Operators plan as no-ops.

Layer 4Execution Runtime

The Executor is pi-htn's own async loop (GamePlanHTN's operators are synchronous). It calls findPlan, switches the context out of planning mode so setState mutates the real world state, then runs each primitive: if the operator carries a prompt, the SmallModel fills arguments (mode B); the ToolRegistry invokes the bound tool. exec.ts binds one tool per name — an exec: block becomes a real shell-backed tool via the injected pi.exec() runner; tools without one fall back to a safe dry-run echo, so mixed live/dry-run domains work.

Effects are applied literal-first, then $result.* overrides with real tool output. A non-zero exit throws: the loop increments a replan counter and re-enters findPlan; after maxReplans (default 5) the circuit breaker aborts. Every step is appended to a Checkpoint JSONL linked to the session-tree node.

Figure 5 — Replay loop. A throwing tool trips a replan; the just-tried rung is excluded by its *_tried guard so the planner climbs the ladder.

Layer 5PR Watcher + Self-Learning

The watcher (src/watcher/, also runnable standalone via bin/pi-htn-watch.ts) polls gh pr checks and collapses per-check rows into a single state: any failure → red, else any pending → pending, else green. On red it classifies a failure_class (informed by the playbook prior), runs one heal round through executeDomain with the pr-ci ladder, then re-checks gh as the verifier. The set of already-tried strategy ids is carried forward as tried_<id>, so across rounds the HTN excludes spent rungs and climbs the ladder — genuine cross-round backtracking. When every rung is exhausted it escalates.

The Playbook (~/.pi-htn/playbook.jsonl) is the self-learning memory: it records (repo, pr, failureClass, strategy, ok) per attempt and computes a Laplace-smoothed success rate per strategy, so the watcher can try the historically-most-successful rung first.

Figure 6 — Poll → classify → heal → re-check, with gh as the verifier and the playbook as durable memory.

Cross-subsystem flows

Two end-to-end paths tie the subsystems together: the author→run lifecycle (how a domain is born and replayed) and the heal loop (how structural backtracking converges).

▸ verify ................ ✗ still red
↩ backtrack ............. just-tried rung excluded by *_tried guard
▸ planner ............... decomposes to the NEXT rung      (alternate-branch backtrack)
▸ verify ................ ✓ GREEN  → report

The three configured domains

pi-htn ships three worked domains in demo/, plus a generic built-in ladder at src/domains/pr-ci.yaml. Each is pure YAML data — the same engine runs all of them. They share one reliability recipe: let the small model try the narrow, creative patch first; let the HTN structurally backtrack to a deterministic, guaranteed-converging safety net.

repair (select, until fixed)
 ├─ m-rerun   if failure_class=flaky → apply-rerun → verify
 ├─ m-lint    generic lint/format pass → verify
 └─ m-revert  revert the offending change → verify   (terminal)
report          one-sentence PR comment

repair (select, until fixed)
 ├─ m-guard   apply the 4B model's emitted guard line     → verify
 ├─ m-dedupe  deterministic strip-then-append (known-good) → verify
 └─ m-revert  rewrite from canonical template (guaranteed) → verify
report          one-sentence PR comment via gh

heal (select, until healthy)
 ├─ m-apply    apply model's proposed image (tool: kset)      → verify rollout
 └─ m-restore  restore last-known-good image (tool: krestore) → verify rollout
report           model writes an incident note; report.sh annotates the deploy

Architectural decisions

Fact-check verification

Claims in this document were verified against the pi-htn source tree on 2026-06-19. Summary below.

One claim was corrected in place (pr-doctor's terminal rung). No claims were silently passed.