ADR-0015: The .stet Topology — Versioned, Tiered Configuration Primitives

Extended by ADR-0021: the topology becomes dual-rail and gains a fourth primitive — Knowledge Bases (KBs). A KB's reviewable git-side binding is managed exactly like Agents/Skills/Verbs (declared, versioned, resolved, pinned across tiers); its payload — the queryable memory graph — rides the Dolt rail (ADR-0013), bound 1:N per tier. KB bindings resolve, pin, sign, and allow/deny across these same tiers, extending the .github-style dotfiles pattern from config to distributed, governable memory.

Status

Proposed / exploring. Captured during ideation on 2026-07-04; the topology and the set of primitives were decided in that session (marked DECIDED). Extends ADR-0005 (verbs) and ADR-0012 (skills) with a concrete storage/resolution model. Revisit for promotion after the core loop (SPEC-0001..0003) is standing.

Context and Problem Statement

ADR-0012 established that skills exist in three tiers (user / team / project). Stet has other configuration that wants the same treatment. We need one concrete, versioned, collaborative storage topology and resolution model for all of Stet's configuration primitives — not a bespoke scheme per primitive.

Decisions

DECIDED — A three-level .stet topology

Following the familiar $org/.github and $user/.github convention (also .gitlab), Stet defines three levels, each a git-versioned artifact:

Tier	Location	Kind
user	$USERNAME/.stet	a repository
org/team	$ORG_NAME/.stet	a repository
project	<owner>/<repo>/.stet/	a directory in the repo (ADR-0011)

The org/team tier is the concrete home for ADR-0012's "team" tier. The project tier is the same .stet/ directory that holds trajectories (ADR-0011).

DECIDED — Four primitives get this treatment

Agents (ADR-0016), Skills (ADR-0012), and Verbs (ADR-0005) are ALL defined, versioned, and resolved across the three levels. No primitive is special-cased.

Knowledge Bases (KBs) are the fourth primitive (added 2026-07-08; ADR-0021). A KB is managed exactly like the others — its binding (the source/address, ref pin, and signer policy) is a reviewable, versioned git-side definition resolved across the three tiers — while its payload, the queryable memory graph, lives on the Dolt rail (ADR-0013) and is bound 1:N per tier. Managing "my KB library" is therefore the same experience as managing agents and verbs: declare, version, pin, allow/deny.

DECIDED — Resolution: configurable precedence, most-specific-wins by default

At use time, Stet composes the three levels. On a name/key conflict a winner is chosen; otherwise the sets union (you inherit org and user definitions the project does not override). The precedence direction is a setting — the default is project → org → user (project most specific), but a user may configure the order to suit their workflow. Precedence is a soft preference and governs only unpinned definitions (see Enforcement).

DECIDED — Enforcement: higher tiers can pin definitions

A primitive definition at a higher tier may be marked non-overridable (pinned). A pinned definition cannot be overridden by any lower tier regardless of the precedence setting — the pin is a hard governance lock that trumps the soft precedence preference. It is expressed as a setting on the primitive (e.g. an agent that org policy mandates) and applies to Agents, Skills, and Verbs.

This turns the $ORG/.stet "blast radius" into a governance feature, not a risk: an org can mandate an agent/skill/verb across all its repos, and because pins are set through the recursion (a reviewed, voted PR to $ORG/.stet, ADR-0014) and are versioned, the enforcement itself is auditable provenance — you can prove what was mandated, by whom, when, and that it could not be locally overridden.

Pinning applies to KB bindings too, so an org can mandate or forbid a KB source across all its repos (an allow/deny governance lock on imported memory; ADR-0021).

DECIDED — Recursion: .stet repos are Stet projects

Because every level is a repo/dir, each is itself a Stet project: editing an agent, skill, verb, or KB binding is a dispatch you read, mark up, vote on, and stet, with trajectories captured (ADR-0011), distillation running (ADR-0012), and voting applied (ADR-0014). Stet improves Stet. Org-wide configuration changes therefore go through a reviewed, voted PR to $ORG/.stet — governance falls out of the core loop.

Why it fits

• Good, because it reuses a convention every developer already knows (.github), so the mental model is instant.
• Good, because it gives ADR-0012's abstract tiers a concrete, versioned, collaborative home and generalizes it to all primitives.
• Good, because the recursion means the configuration surface is governed and improved by Stet's own mechanics — no separate admin tool.

Open questions

• Merge semantics per primitive. Beyond precedence + pinning: when do sets union vs. override per-key, and per primitive? (relates to ADR-0012 "tier conflicts").
• Governance defaults. Whether the org tier requires reviewed+voted PRs by default, who may set/remove a pin, and how pin changes are surfaced.
• Discovery / bootstrapping. How Stet locates the .stet repos for a signed-in user and their orgs via the forge (ADR-0007), and what happens when they don't exist (offer to create).
• Conflict UX. How the composed, overridden configuration is surfaced so users can see which tier a given agent/skill/verb came from.

Consequences (tentative)

• Introduces a topology-aware resolver used by Agents/Skills/Verbs/KB bindings.
• Amends ADR-0005 (verbs) and ADR-0012 (skills) to resolve across this topology; adds the $ORG/.stet and $USER/.stet repos as first-class, Stet-managed projects.
• Ties governance of shared configuration to the review/vote loop (ADR-0006/0014).
• Adds a configurable precedence setting and a per-definition pin (non-overridable) attribute; pins are a hard lock that trumps precedence and become auditable provenance of what an org mandated.

More Information

Convention precedent: github.com/$org/.github, github.com/$user/.github. Primitives: Agents (ADR-0016), Skills (ADR-0012), Verbs (ADR-0005), Knowledge Bases (ADR-0021). Recursion substrate: ADR-0011 (trajectories), ADR-0013 (collaboration), ADR-0014 (voting).