Glossary

Glossary

The project's vocabulary. Two families: the parts of the loop kstrl is built as, then the names things have in the code. Where a term is planned rather than shipped, its tracker item is named.

The loop

Set point: the state the loop steers toward, written down before work starts. In kstrl: the acceptance criteria on each user story, the policy envelope on each merge, and the floor on test quality.

Sensor: anything that measures the work independently of the agent that did it. In kstrl: mechanical verification, the code reviewer, the security reviewer, contract tests, the approved-fixtures oracle, and calibration (the sensor pointed at the other sensors). The only sensor the agent can influence is the one it is not allowed to be: its own report.

Measurement versus claim: a claim is what the agent says about its work (the passes flag, the completion marker, a self-critique). A measurement is what a sensor reads from the diff. Claims are rendered; measurements gate.

Finding (the error signal): the typed record every sensor emits when the work misses the set point: phase, category, severity, location, explanation, suggestion. An empty findings list means every sensor ran and found nothing, because a sensor that did not run leaves a finding saying so (see infrastructure_error, phase_skipped).

Controller: the harness code that turns findings into the next action: retry with a structured context, halt, merge, or demote the factory's own autonomy. It runs outside the agent's reach.

Actuator: the thing that changes the world: the engineer agent, and after the release stage (R8.7), the deploy driver.

Feedforward (Phase 0): context computed from the tree and handed to the agent before it acts: module map, public interfaces, import graph, conventions. No model call, no token cost.

Disturbance: change the loop did not command: model nondeterminism, transport failures, a base branch that moved, a concurrent human commit. Named so it can be kept apart from real signal; an infrastructure failure is never counted as a lesson.

Retry context: the parsed failures, review findings and contract failures handed to the agent on its next attempt. R10.2 makes it level-triggered: current failures in full, earlier findings that were not re-measured listed separately, resolved ones omitted.

Advisory first: the rule for any gate whose threshold is unknown. Ship it measuring and reporting without blocking; graduate it to blocking once the operator has read its output on real runs. The number arrives from running, never from guessing.

Dampener (R10.6): a stored baseline of finding counts in version control plus a check on every pull request reporting what the branch made worse, so the measured properties cannot regress while the loop improves them.

Flow control (R10.7): the daemon admits no new work while a kstrl-authored pull request is already open, because the reviewer is the slowest part of the system and the loop must not outrun it. Manual runs bypass it.

Safe mode (R10.4): one question with one answer: is the factory in a degraded state, and why. Backed by the existing fail-closed paths (autonomy clamped, queue paused, control directory untrusted, an adversarial phase skipped).

On the loop: where the operator stands. The system runs itself; the operator watches, intervenes on exception, and adjusts behaviour between runs. Contrast in the loop (a required step) and out of the loop (absent).

Names in the code

Adversarial budget (max_adversarial_calls): shared cap on LLM calls across the reviewer, security and distiller phases. R10.5 makes hard mode halt the component when the cap is reached rather than merge it unreviewed; advisory mode records a phase_skipped finding and continues.

Architect: the LLM role that red-teams a spec and decomposes it into a component DAG with per-component PRDs. Halts on blocker-severity spec issues (see SpecBlocker).

Autonomy ladder (R8.2, shipped): graded autonomy levels L1-L4 (supervised, gated merge, enveloped auto-merge, deploy). Promotion requires evidence plus a recorded human acknowledgement; demotion is automatic, one level per trigger, with a cooldown. The permission bundle is derived from the level at every run start and can only withhold, never grant.

Calibration: the truth signal for adversarial roles. Planted-bug fixtures measure each role's detection rate against a saved baseline; prompt changes must show their delta (H2).

Component: the unit of factory work: one node in the manifest DAG, built in its own worktree, gated through all phases, shipped as its own PR by default.

Contract testing (Phase 3): mechanical cross-component integration tests run on merged tier branches; failures are attributed to the most recently merged component, which is reset and re-run.

Control directory (R8.9, shipped): the factory's own state (autonomy level, spend ledger, pause marker, inbox, processed intake ids), kept under the XDG state home outside the repository so the agent cannot edit its own governor.

Dark factory: the name of the R8 cycle's target: a software factory that plans, builds, tests and ships without a human reviewing each change, within an explicit policy envelope, with the human on the loop for exceptions. Explicitly not zero humans; see Vision and Philosophy.

Distiller (knowledge distiller): the LLM role that writes durable facts about the artifact to disk before the PR merges, so later components inherit verified knowledge rather than re-deriving it.

E6 checkpoint: the optional human gate before PR merge (pause_before_pr_merge). Named for its item in the original adversarial roadmap. An explicit setting survives every autonomy level (#195).

EARS: Easy Approach to Requirements Syntax, the acceptance-criteria format the architect demands in generated PRDs.

Events substrate: .kstrl/runs/<run_id>/events.jsonl, the typed, schema-versioned event stream every UI projects. "The filesystem is the event bus."

Evolution journal (.kstrl/evolution.jsonl): append-only record of every component outcome, error signature, cost and finding summary; the data source for ks evolve proposals and for health trending (R8.4).

Exception inbox (R8.3, shipped): one surface for everything awaiting a human decision: policy exceptions, merge gates, halted runs, budget overruns, demotion notices, calibration drift, adequacy blocks. Snooze returns an item; an open-item cap is consulted before new work is admitted.

Fixtures oracle: approved input/output pairs held outside the agent-writable tree, executed sandboxed. The one adequacy layer whose ground truth the engineer cannot rewrite.

Golden patterns (R10.8): an operator-authored file describing what a good change looks like in this repository, injected beside the knowledge prefix.

Hard mode: review or security configuration where findings at or above a threshold block the pipeline, versus advisory mode, which records but does not block.

H1-H4: the binding process rules: no self-review, calibration on prompt change, prompt version and snapshot move together, state tested versus assumed. See Contributing.

infrastructure_error: the finding that distinguishes "the reviewer never ran" (timeout, parse failure) from "the reviewer ran and found nothing". In hard mode it counts as failure; absence of findings must be earned.

Knowledge facts: durable, per-component markdown facts written by the distiller and injected into later engineer runs (three-tier retrieval: core, dependency, sibling). Their uptake is measured as a lower bound.

ks sense (R10.1, shipped): the command that runs the mechanical sensors against any tree, with no PRD, branch, worktree or agent spend. The first thing the R10 cycle built, because a sensor that only runs inside a factory run cannot be tuned or trusted cheaply.

Manifest (scripts/kstrl/manifest.json): the component DAG with per-component state, PR pointers and run metadata; the factory's resumable source of truth. Records the policy hash the run was held to.

Memory file (R10.9): a versioned file of standing operator feedback (scope exclusions, known false positives, reviewer corrections) loaded into the agent's context last, after the retry context. R10.10 lets a pull-request comment append to it.

MERGE_PENDING: component state when a PR merge timed out; blocks dependent scheduling and re-polls on resume rather than assuming success.

No-progress breaker: circuit breaker that halts a component after N engineer iterations with an unchanged diff hash and unchanged test signature. It detects zero change; a convergence check that detects insufficient change is R10.12, gated on evidence.

phase_skipped: the finding recorded when an adversarial phase was deliberately skipped (budget, mode). Together with infrastructure_error it is what makes an empty findings list a safe success signal.

Policy envelope (R8.1, shipped): the declarative [policy] block (deny paths, blast-radius caps, dependency and licence rules, secret patterns) enforced mechanically on diffs and lockfiles, plus a non-overridable set of enforcement paths that halt at every autonomy level.

PRD: per-component product requirements document (user stories plus acceptance criteria): the contract the reviewer verdicts against, and the set point the loop steers toward.

Roadmap item IDs (A-H, R0-R10): short tracker identifiers used like ticket numbers in issues, PRs and commits. The first cycle numbered items A1-H5, the second R0-R7, the dark-factory cycle R8.x, continuous learning R9, and the control-loop cycle R10.x. The prefix only says which tracker owns the item; see Roadmap.

Self-critique block: the ## Self-Critique section the engineer must emit each iteration; its shape is mechanically verified. A claim, not a measurement.

Set-point agreement (R10.3): the check that a story marked passes: true by the engineer was independently marked pass by the reviewer. Advisory first; in blocking mode the harness reverts the flag so the record agrees with the sensor.

SpecBlocker: a blocker-severity spec issue found by the architect. The run halts with exit code 2 and no override flag; the spec gets fixed, not the gate.

SpecKit: a spec-driven development artifact set; ks decompose accepts a SpecKit directory (spec.md plus optional plan.md, tasks.md).

Tier: a topological layer of the component DAG; contract testing merges and tests tier by tier.

Work queue (R8.6, shipped): the maildir-style .kstrl/queue/ that ks serve drains one item per cycle, with leases, a reaper, exponential backoff, a daily budget, a poison breaker and an inbox cap consulted before admission. GitHub issues carrying a label are the remote inbox; polling only, no webhooks.

Worktree: the isolated git workspace each component builds in, cut from origin/<base>, locked per host, and cleaned up (or kept on failure for forensics).