Architecture decision records

ADRs preserve why a decision was ratified. accepted means ratified, not necessarily implemented or still current. Superseded records remain in place; later ADRs link back to the decision they amend or replace. Read the current architecture for the implemented system; the archive below identifies decisions whose former implementation or scope is historical.

Conventions

• Put current setup, commands, configuration, and implementation state in the owning app or package README. ADRs keep the decision, evidence, alternatives, and consequences.
• Link amendments and superseding decisions in the status paragraph. Historical implementation details stay explicitly historical rather than claiming to describe the running system.
• When a decision retires guidance that agents or users read, add the retired phrasing to retired-claims.json. pnpm docs:check then fails wherever live code, skills or guides still repeat it.
• Link ADRs by stable filename, not by number alone. Accepted ADRs are never renumbered, except once to end the four historical collisions below.
• Allocate the next unused number after checking fetched main. pnpm docs:check and pnpm check:landing reject duplicate numbers.

Renumbered records

Until 2026-10-17 numbers 0098, 0189, 0191 and 0207 each named two records. VUH-2396 moved one of each pair to a new number: a proposed record gave way to an accepted one, otherwise the later one moved, and the less-cited one when both landed in the same commit. Links and citations written before then may use the former number; this table resolves them.

The other record of each pair keeps its number: ADR 0098 (user-session shares), ADR 0189 (Linear echoes), ADR 0191 (work tracking) and ADR 0207 (native delivery).

Diagrams

ADR 0210 records the separation of native goals, explicit session assignments and current activity.

Diagrams are Mermaid in the Markdown that owns the subject, so they render on GitHub and in Linear and change in the same commit as the code. The architecture keeps the system map, the message-to-turn flow and the fleet flow; subsystem diagrams live in their package or app README. The former tldraw sources and JPG exports were removed on 2026-10-06; git history keeps them.

ADR 0215 records exclusive body-resource leases for parallel conversations belonging to one Clankie.

ADR 0216 moves agent roles and project policy into owner settings, with lossless persona migration and per-agent membership rules.

ADR 0217 supersedes ADR 0216's fleet tool gate: admitted fleet members reach verified connected accounts through clankie_tools and clankie_call, with an owner kill switch.

ADR 0218 lets native harness seats drive a selected conversation, preserving room grants and delivery receipts across handover, and routes worker reports to their persisted lead.

ADR 0220 adds one presence operator operation, a desktop tool for his own expressions, and hero pixel art in branding/pet/; the desktop pet itself lives in the private app.

ADR 0221 prioritizes real E2E, integration and golden coverage for new work; existing unit-test pruning remains a separate reviewed effort.

• 0222 — Discord setup has one shared definition

• 0225 — Minecraft keeps playing with one driver

• 0226 — One tracker tool surface

ADR 0214's VUH-1678 amendment supersedes ADR 0218's Linear routing extension: verified rule-passing webhooks wake one ordinary configured chat, global-default by default, and retire the separate Linear inbox protocol. Clankie can set the non-secret target and rules.

• 0227 — Discord connects a server with a role

• 0228 — Quick actions are skills, and tidy keeps results

• 0232 — Hosted Connections use the body broker

• 0229 — Room handoffs are visible parallel threads

• 0230 — Fleet responsibility is owner settings

• 0233 — Activity shares own their media scope

• 0234 — Games share one extension contract

• 0235 — Worker catalog refresh keeps the original controller

• 0236 — Clankie owns the skills he ships

• 0237 — Hosted bodies update themselves to official releases

• 0238 — Hosted Claude workers trust their own workspace

• 0239 — Worker harnesses sign in with their own logins

• 0240 — Changes land directly on main

• 0241 — One official Discord bot serves every Clankie

• 0242 — Every Clankie has a mailbox we run

• 0243 — Linear GraphQL is the tracker escape hatch

• 0244 — Machines join Clankie at an access level

• 0247 — Narrow checks have one command

• 0249 — Simulator leases answer promptly and name their holders

• 0251 — Discord servers have owners; rooms can grant skills

• 0252 — Household legacy authors need owner-confirmed ID bindings

• 0253 — Owner confirmation needs an isolated authority (proposed)

• 0255 — A lent screen keeps consent and stops on its host

• 0256 — Lent input needs native drain proof

• 0257 — A lowered local runtime keeps an OS boundary

• 0258 — Evidence lives in the evidence store

• 0260 — Usage meters come from each harness's own CLI

• 0261 — Hires go where capacity would otherwise go unused

• 0262 — Prime Agent's operator seat is a resident daemon session

• 0263 — One autonomy dial over the decision leaves

• 0264 — Projects on Auto replace goals

• 0265 — Routines are recurring jobs with a run fence

• 0266 — Landing gates keep isolation and load less

Archived decisions

Archived means superseded or retired for the scope named below. These records retain their stable paths and historical rationale; archiving does not delete an ADR or change the surviving constraints explicitly noted in its status. The links in this table follow each record's current-status paragraph and the superseding decisions.

Archived scopes within continuing records

These ADRs retain a live boundary or an unimplemented proposal. Only the named scope is archived; readers should follow the successor for its implementation.

• 0246 — Worker questions use native hook answers

• 0248 — Owner settings use one revision-fenced API

• 0267 — Skins share one public animation spec

• 0268: Account-owned device revocation survives a sleeping body — VUH-2121 / VUH-2215.

• 0269: Browser pairing binds an account session to one device — VUH-2122.

• 0270: Auto rounds measure outcomes and name drift — VUH-2255.

• 0271: The lead seat restarts fresh in its own pane — VUH-2274.

• 0272: A hosted body runs model-directed work as a separate uid — VUH-2320 (Proposed).

• 0273: The fleet room is a durable, owner-only coordination record — VUH-2184.

• 0279: Fleet counts come from the host roster — VUH-2448.

• 0280: Automatic tidy requires positive work proof — VUH-2462; amended for home and repository containers (VUH-2926) and moved, not copied, evidence (VUH-2932).

• 0281 — Paired devices read a shipping projection

• 0282: Settings can save trust with autonomy — VUH-2525.

• 0284: A service restart pauses one Pi room turn — VUH-2574 (bounded prototype).

• 0285: Hosted presence has no idle clock — VUH-2575.

• 0286: One body holds Clankie at a time — VUH-2577.

• 0287: A standing reviewer gates every landing — VUH-2616. Amends ADR 0240.

• 0288: A device call is a voice body of the same session — VUH-2682. Extends ADR 0057 and ADR 0215.

• 0289: A call through the gateway is a sealed stream — VUH-2761. Amends ADR 0173; extends ADR 0288.

• 0290: App switch metrics are bounded device reports — VUH-2558.

• 0291: A room thinks in one loop — VUH-2796 (Proposed). Would amend ADR 0229 for Pi text rooms.

• 0292: Onboarding opens an explicit local seat — VUH-2784. Extends ADR 0152 and ADR 0248.

• 0293: A seat is sized by its work, not its window — VUH-2820 (Accepted). Extends ADR 0271.

• 0294: Owner activity glimpses follow live presence — VUH-2819.

• 0295: A self-hosted bot admits its own Activity viewers — VUH-2833. Extends ADR 0233.

• 0296: Hired workers run under an OS profile that keeps the owner's credentials — VUH-2592.

• 0298: Linked repos are read-only sources, never owners — LOCAL-VUH-41. Extends ADR 0270.

• 0299: The owner's app gives the verdict on finished work — LOCAL-VUH-58. Extends ADR 0226 and ADR 0245.