H·AI·K·U Glossary

Quick reference for all H·AI·K·U terminology and concepts.

B

BackpressureSee in paper: Quality enforcement via hooks that block the agent from proceeding until standards are met, rather than relying on agent compliance.
BoltSee in paper: One cycle through a stage's hat sequence for a unit. If completion criteria are not met, another bolt runs. Derived from the unit's `iterations[]` history on its frontmatter — the workflow cursor reads the last entry to decide which hat is next.

C

Completion CriteriaSee in paper: Verifiable conditions that define when a unit is done. Expressed as checkboxes in unit markdown. Quality gates enforce machine-verifiable criteria; adversarial review enforces the rest.

D

DAG: Directed acyclic graph ordering units within a stage by their dependencies.

F

FB-as-Unit: The fix-loop's structural rule: a feedback finding (FB) IS the unit-of-work for the fix-loop hats. Fixers populate the FB body with diagnosis (root cause, proposed action, references) via `haiku_feedback_write`; flagged units stay read-only via `haiku_unit_read`. The fix-loop hat chain progresses via `haiku_feedback_advance_hat` (mirror of the unit equivalent); the workflow engine auto-closes the FB when the last hat advances and applies `targets.invalidates` to the targeted unit's approvals — the cursor's next tick re-runs whatever roles got invalidated. Implementation contract in `plugin/studios/ARCHITECTURE.md` §6.
Feedback Classification: The first hat in a stage's `fix_hats:` chain reads each newly-filed FB body and calls `haiku_feedback_set_targets` to record which unit (if any) the finding targets and which approval roles to invalidate on closure. Targets are immutable once set. Cross-stage misfilings get relocated via `haiku_feedback_move` (which renumbers the FB and moves any sidecar attachment); after that, routing flows purely by file location — a finding sitting in `stages/<earlier>/feedback/` rewinds the cursor to that stage's fix loop on the next tick. The directory IS the classification — no `upstream_stage` hint needed.
Feedback-Assessor: A terminal fix-hat that independently verifies whether a prior fix resolves the named feedback. Cannot self-certify — the producer hat that made the fix is a different hat — which is the whole point of the isolation. Decides closure, keeps the finding open, or rejects as invalid. Defined as `hats/feedback-assessor.md` in any stage that opts into `fix_hats`.
Fix Hats: Ordered subset of a stage's hats, declared as `fix_hats:` in STAGE.md, dispatched directly against an open feedback finding instead of synthesizing a new unit. Eliminates the rework drift of feedback → unit → execute. The feedback body *is* the scope. Typically `[<producer>, feedback-assessor]`.
Fix Loop: Mechanism that dispatches a stage's `fix_hats` against each pending feedback finding (one at a time), with a three-bolt cap per finding before escalation. Same mechanics exist at the studio level for intent-completion review.
Forward-only Lifecycle: Architectural rule: units (and FBs) move only `pending → active → completed`. There are no reverse transitions — no unwind, no reset. Once a unit is active or completed, downstream work has been informed by it; mutating it would silently invalidate that work. Stage revisits create new pending units that build on completed work; they never modify completed units. The MCP tools enforce this at write time (`haiku_unit_write` accepts only pending; `haiku_unit_set` blocks non-workflow engine field writes on active/completed; `haiku_unit_delete` is pending-only). Implementation contract in `plugin/studios/ARCHITECTURE.md` §1.3.
Frontmatter-is-workflow-engine-only: Architectural rule: frontmatter on workflow-managed files (units, feedback, intent) is reserved for the workflow engine. Agents may write FM when authoring (the elaborator drafts a unit's `inputs:`) but MUST NOT *interpret* FM for any mechanical purpose. DAG validity, schema, cross-references, lifecycle, and the workflow cursor's read-only signals (`iterations[]`, `started_at`, `approvals.*`, `reviews.*`, `discovery.*`) are workflow-engine responsibilities, validated at write time inside the MCP tools. Reviewer hats and verifier hats validate body content only. The `haiku_unit_read` and `haiku_feedback_read` MCP tools enforce this by returning `{title, body}` only — no FM exposed. Implementation contract in `plugin/studios/ARCHITECTURE.md` §1.1.

H

Hat: A behavioral role scoped to a stage. Each hat runs in a fresh agent context with instructions loaded from `stages/{stage}/hats/{hat}.md`.

I

IntentSee in paper: The top-level initiative being pursued. Contains units organized by stages. Stored at `.haiku/intents/{slug}/intent.md`.
Intent-Completion Review: Studio-level adversarial review that runs once, after every stage's gate passes, before the intent is marked complete. Agents live at `plugin/studios/{studio}/intent-review-agents/` (not per-stage) and include delivery-readiness lenses (the integrated app runs; CI is green *and meaningful* — the work's declared quality gates are actually run by the pipeline, not a no-op that exits zero — and the PR conversation is resolved on the delivery PR). Findings log at intent scope and run through a studio-level fix loop via `plugin/studios/{studio}/fix-hats/`. Catches cross-stage inconsistencies that per-stage reviewers miss by construction. Cross-stage findings are always surfaced to the human; the layer explicitly forbids auto-revisiting stages. Enabled by default; opt out per intent with `intent_completion_review: false`. The finding rate per intent is the measurement surface: if it trends down over time, stage-level specs and reviews have gotten sharper upstream.

P

Persistence Adapter: Backend that handles how work is stored and delivered. Implementations: git (branches, commits, pull requests) and filesystem (local directories).
Plan-Do-Verify: Hat-sequence pattern: every stage's `hats:` list MUST be at least three roles forming a plan → do → verify chain. Hat-to-hat handoff must be a meaningful baton (the rally-race test). Hat names MUST be distinct from the lifecycle's phase names (`elaborate`, `execute`, `review`, `gate`/`approve`, `merge`) so cursor traces and prompts stay unambiguous. The per-unit sequence is plan-do-verify roles only — adversarial review is NOT an in-loop hat; it runs at the stage level as a review agent plus the fix loop (see `plugin/studios/ARCHITECTURE.md` §3.5). Implementation contract in `plugin/studios/ARCHITECTURE.md` §3.

Q

Quality GateSee in paper: A machine-verifiable check (test, lint, typecheck, build, grep) enforced at advance_hat time. Declared as an executable `{name, command, dir?}` entry in unit frontmatter; commands must scope to the full stage artifact directory, not only the unit's declared inputs. Blocks the hat from advancing until the gate returns exit 0.

R

Review Agent: A specialized adversarial agent that evaluates stage output against a specific mandate (e.g., correctness, security, accessibility). Defined per-stage in `review-agents/{name}.md`. Agents can declare `applies_to:` (a list of file globs) to scope themselves to matching output kinds — e.g. a web accessibility agent only runs when the stage produces HTML/TSX/JSX. Stages can include review agents from other stages via `review-agents-include`.
Review Gate: A checkpoint between stages that controls advancement. Types: `auto` (advance when quality gates pass — no human involved), `ask` (open local review UI for human approval — signal is the MCP response), `external` (block until an external review system like GitHub/GitLab approves — signal detected primarily by branch merge detection, with URL-based CLI probing as fallback), `await` (block until an external event outside the review process occurs — e.g., customer response, contract signature). Compound gates like `[external, ask]` let the human choose between paths.

S

Spec Review: The engine-built `spec` reviewer that runs first in every stage's review track. Universal hard gate: every intent has a spec, every stage produces something the intent scoped, so the gate fires on every stage with no per-studio mandate file and no opt-out. It verifies that the completed units collectively delivered exactly what the intent scoped — no scope creep, no missed criteria, no cross-unit drift. Findings filed by spec routing through the fix loop unblock the rest of the review track (configured agents and the human gate).
Stage: A lifecycle phase within a studio. Contains hat definitions, review gate, input/output contracts, and unit type constraints.
Studio: A named lifecycle template mapping the four-phase model to domain-specific stages. Defines stage order, persistence type, and delivery mechanism.

U

UnitSee in paper: A discrete piece of work within an intent, scoped to a single stage. Has verifiable completion criteria and dependency relationships forming a DAG.

W

Workflow Cursor: The pure-TypeScript decision function that drives every `haiku_run_next` call. Reads on-disk frontmatter (intent.md, every unit.md, every feedback.md) plus studio config and returns one next action — `start_unit_hat`, `dispatch_review`, `merge_stage`, etc. No LLM in the workflow-position decision; no in-memory state across ticks. Walks three tracks in priority order: drift sweep, open feedback, intent track. Implementation in `packages/haiku/src/orchestrator/workflow/cursor.ts`; semantics documented in `plugin/studios/ARCHITECTURE.md` §5.

Read the full H·AI·K·U paper