Concepts & Glossary
Stet borrows its vocabulary from proofreading and publishing. These are the terms that show up throughout the docs.
The review loop
Stet / to stet — the proofreader's mark (Latin, "let it stand") written in the margin to approve a change. In the app, approving a hunk is "stetting" it.
Galley — the thing being read and marked up: a file, a diff, or a rendered document. (From the galley proofs an editor marks up before print.)
Margin — where comments, reactions, and suggestions live, anchored to a location in the galley.
Markup — the human's feedback: comments, emoji verbs, spoken notes, and strike-through/scribble suggestions. See ADR-0006.
Verb — an emoji (or comment type) that is a command, not decoration: 🐛 investigate, 🎨 refactor-ugly, ❓ explain, 🔥 delete. Each binds to a workflow. See ADR-0005.
Brief — the structured, compiled output of a submitted review. One review compiles to one brief → one pull request. See ADR-0006.
Tour / narration — the AI-authored walkthrough of a PR: an ordered set of stops, each with a location, a "why," and a risk flag. Drives the canvas in reading order. See ADR-0008.
Agents & dispatch
Dispatch — sending a compiled brief to a local agent, which does the work and opens a pull request.
Harness — the mechanism that runs a coding agent (OpenHands, Crush, Pi). See ADR-0004.
Agent — a named, versioned, configured actor: a harness + model + persona + attached skills + handled verbs + guardrails. Distinct from the harness. See ADR-0016.
Runtime / sandbox — the isolated local environment for one dispatch: a fresh
container/VM with its own worktree and a branch-scoped, revocable credential. Apple
container or Docker. See ADR-0003.
Forge — a code host: GitHub or Gitea. Provides identity, pull requests, and the baseline social surface. See ADR-0007.
Learning & provenance
Trajectory — the full, versioned record of how a change was made (brief, reasoning, tool calls, diffs, cost), committed inside the repo as the branch's final commit and reviewable like any file. See ADR-0011.
Distillation — mining trajectories + feedback + outcomes into reusable skills, each proposed as a reviewed PR and injected into future dispatches. See ADR-0012.
Skill — a reusable, versioned capability (often distilled) that makes agents better at a given project or task.
Redaction gate — a deterministic, bundled secret-scanner + redaction step that runs before any trajectory is committed. See ADR-0011.
Social & governance
Vote / consensus — humans and agents vote on hunks, skills, and trajectories. Human consensus and agent consensus are shown separately: humans decide, agents advise. Agent votes carry auditable rationale. See ADR-0014.
Collaboration store — where rich markup, threads, and votes live: an embedded, versioned Dolt database that syncs via the forge or a self-hosted instance. See ADR-0013.
The .stet topology
Primitive — one of the three versioned configuration artifacts: Agents, Skills, Verbs. See ADR-0015.
Topology — three versioned levels where primitives live: $USER/.stet (repo),
$ORG/.stet (repo), and a project's .stet/ directory — following the .github
convention.
Tier — one level of the topology (user, org, or project).
Precedence — the direction in which tiers override one another when they conflict. Most-specific-wins by default; the direction is a user setting.
Pin / enforcement — marking a definition at a higher tier non-overridable. A hard governance lock that beats precedence — mandated, auditable config.
Import — a .stet building on another .stet repo, turning the topology into a
dependency graph. Pinned to a ref (a lockfile). See ADR-0017.
Signed ref / allowed signer — the trust primitive for imports: downstream policy can require the pinned commit be GPG-signed by an approved identity. See ADR-0017.
Config provenance — tracing an effective agent/skill/verb back through tiers, imports, and pins to the reviewed change that produced it.