graff — a fast agentic coding harness in Zig: multi-provider, MCP, workflows, DGM evolution loop, TS/Python SDKs
Architecture Decision Records
Settled decisions with their reasoning, so nobody (human or agent) has to re-derive or re-litigate them from scratch. Each record is one decision: the context that forced it, what was decided, and what it costs.
Start here. The index below gives you the rule in one line; open the record only when you need the evidence or the edge cases.
Index
| ADR | The rule |
|---|---|
| 0001 | Structured output is a final formatting step. Never constrain the agentic phase with a schema grammar, and do not use --output-schema unless a program consumes the result. |
| 0002 | xAI runs on the Responses wire by default (WS turns + on-socket previous_response_id). Compaction is the client summarizer, not xAI's blob endpoint. GRAFF_XAI_WIRE=chat opts out. |
| 0003 | Codegraff uses Responses + WS for GPT-5.6+ (incl. GPT-6 Astra / Codex gpt-5.6-*) and grok-4.6; Claude aliases use native Messages (0255); Gemini and other aliases stay on Chat Completions. |
| 0004 | Peer speech is pull: a one-line [peer] wake in history, bodies in the inbox ring; compact drops spent injects and never treats them as the human. |
| 0005 | Standing goal is one prefix line; the user-message essay injects on change only, never every N turns. |
| 0006 | Mid-session worktree switch is a real workspace tool; a skill cannot move file-tool cwd. |
| 0007 | Cursor/Claude/Grok/Codex plugins and MCP are read in place (Claude/Cursor cache via installed_plugins.json, Codex via config.toml PluginStore, never walked); skills stay on-demand; MCP stays consent-gated. |
| 0008 | Synthetic coding evals promote only external-verifier passes; model judges may tiebreak correctness, never decide it. |
| 0009 | GPT-5.6 OpenAI Platform marks the stable prefix explicitly; Codex and xAI stay on their supported keyed automatic-cache paths. 12h lifetime (opt-in): 0312. |
| 0010 | bash_output/agent_output wait_ms>0 blocks until exit (10h cap); do not poll every 30s. |
| 0011 | Prompt-cache max is on: stable catalog by default; /cache is the HUD; /btw rides the parent prefix; children share role-lane x-grok-conv-id / prompt_cache_key (not the root id). |
| 0012 | Fat tool results become tr_N handles; named --context-limit caps prefix bytes; --add-dir extra roots are PathConfine allow-lists, not cwd/skill/session sources. |
| 0013 | Directory listing is codedb list_dir (in-process BFS, gitignore, 10k cap), not a new always-on catalog tool. |
| 0014 | /resume restores the peer-channel byte cursor and inbox; it does not replay the room into history. |
| 0015 | Reply images require explicit UI support and ride a follow-up user message; otherwise yield_turn stops for the next prompt without completing work. |
| 0016 | Line REPL chrome is a WORKING block plus a bare ›; tool fan-out is a tree, never ✓ bash. |
| 0017 | /model and /models on both frontends rank signed-in plan seats above credits and metered keys (src/models_rank.zig). |
| 0018 | Last-turn cache hit % rides with ctx on the line-REPL meter and the TUI footer; /cache stays the posture HUD. |
| 0019 | Advertise only context / around / callpath / list_dir / status; hop verbs stay callable, not on the menu. |
| 0020 | Transcript shows decisions: one interpreted tool line, collapsed infra failures, compact WORKING; ↵ raw, /debug, and TUI-fold disclose the bytes explicitly. |
| 0021 | Transcript is the task, not the event bus: bookkeeping is silent, todos are WORKING, subagents are scouts. |
| 0022 | rlm (Alex Zhang spec-ptc + RLM, Zig) is the default loop. --old restores structured-only. Prime persist + subagent() only — no IPython. |
| 0023 | Codex check: take sidecar-vs-critical-path spawn prompts; reject V8 Code Mode, extra spawn tools, and parent-history fork. |
| 0024 | Steal short child briefs + sidecar spawn; print(read_file) returns the file; -p skips the shared-tree checkpoint (evals are sibling sandboxes); reject rlm-only catalog, grok heap, Harbor. |
| 0025 | Process Io stays Zig Threaded. spec-ptc is already the default loop (ADR 0022). Do not take ublk or switch main to std.Io.Uring. |
| 0026 | Root foreground bash auto-backgrounds after 120s (a shorter timeout may promote earlier); it is not killed. Subagents still kill at 120s (#93). |
| 0027 | Kimi Coding User-Agent is graff/<version>, not a spoofed kimi-code-cli token. X-Msh device fields follow kimi-code's shapes. Superseded by 0204. |
| 0028 | Codex HTTP/WS session_id is the prompt_cache_key (openai/codex ModelClient default), not a per-process random UUID. |
| 0029 | Loaded MCP tools are rlm host functions; persist return shapes on the load result, never the prefix; fat MCP results auto-slim; default -p connects .mcp.json (folded, not skipped). |
| 0030 | Superseded by 0140. Late showcase hid rlm on small turns; that gate is gone. |
| 0031 | xAI Responses splices hosted x_search onto tools turns. It is not a catalog function; GRAFF_XAI_X_SEARCH=0 opts out. |
| 0032 | graff acp streams thought / tool / text session/updates mid-turn. The native app is an ACP client; it does not need graff serve. |
| 0033 | Only the user retires a standing constraint: TTY /never picker (two confirms), ACP/rm, or an explicit override. The model cannot. |
| 0034 | JSON/serve image inputs are a typed URL/base64 union, validated atomically and preserved as native provider vision blocks; never flatten pixels into prompt text. |
| 0035 | First model call after a deferred MCP boot does not wait for the handshake; companion auto-connect is the same defer; native tools run now. |
| 0036 | Superseded by 0313. Graff launched Codex Computer Use through its signed sandbox wrapper. |
| 0037 | --experiment N / /experiment N pre-mints a child worktree pool; the root must spawn; pool trees are listed and delivered back, never auto-deleted. |
| 0038 | Same-process embed is libgraff + graff-core.wasm + createGraffAgent() (ACP core, echo turn). Live coding stays graff acp. |
| 0039 | Agent-authored local tools are project scripts under .graff/tools/; skills stay instructions. Runtime catalog extras, not schema.effectiveRootSpecs. |
| 0040 | Ordinary reads use native codedb / read_file; codedb-pro is extra search, not the default reader. |
| 0041 | The fullscreen TUI is an in-process ACP client: session/prompt in, session/update thought/tool/text out. No child graff acp. |
| 0042 | graff tui / TTY graff repl claim the alt-screen before keys/MCP/prompt; leftover boot happens inside the pager. |
| 0043 | Pi SWE A/B uses pi-xai on the SuperGrok seat; do not steal Pi's catalog or heap from the json-stream pass. |
| 0044 | -p and --json skip learn auto-init; the Pi SWE wall gap was a 38s graff-pinned copy, not their catalog. |
| 0045 | Codegraff glm-5.3-flash SWE: Pi 5/6 in 758s, graff 3/6 with three 300s timeouts; do not steal Pi's heap. |
| 0046 | Flash / Gemini send reasoning_effort=low (omit still thinks); lean -p shortens tool prose; -p streams. |
| 0047 | Codegraff SWE A/B is not GLM-only: Gemini graff 5/6 in 103s; DeepSeek flash still one-shots; do not steal Pi's catalog. |
| 0048 | Model HTTP calls lease a recoverable client generation; request-construction TLS failure rotates safely without deinitializing in-flight users. |
| 0049 | --resume SOURCE --branch DEST clones provider history and peer cursor state once; every later save belongs only to DEST. |
| 0050 | Reuse warmed TLS: MCP probe/initialized stay on the persistent HTTP client; WSS CA is scanned once per process; WS→SSE keeps the prewarmed pool; MCP HTTP accepts gzip. |
| 0051 | /teleport restores a snapshot tar onto another CLI backend; /snapshot gc keeps the newest n trees. |
| 0052 | Lean -p bounces a first-turn prose-only "done"; one user note naming file tools, then re-open. |
| 0053 | Retry short Codegraff follow-up flakes (2); opencode-codegraff A/B on the same seat. Auth/quota stay fail-fast. |
| 0054 | DeepSeek family default low sends thinking.type=disabled; /effort high still thinks. GLM stays low-only. |
| 0055 | Lean -p bash auto-backgrounds at 15s; interactive / --no-lean stay 120s (ADR 0026). |
| 0056 | Composer image chips sync on delete and reuse #N; clipboard_paste MIME/bytes wait until send. |
| 0057 | peer_message resolves exact title / saved-session base before opaque id or goal. |
| 0058 | Same unresolved compact_cut pin that does not shrink stops after two tries. |
| 0059 | /resume and /sessions list cwd then ~/.graff/sessions; home-origin resume keeps tools in the current cwd. Linked worktrees: 0155. |
| 0060 | The named-source nudge is per unanswered mention; identical user turns do not replay (#714). |
| 0061 | Heads-up text rides in the same response as the tool calls; a choice for the user is an ask_user call; a job exit the model already read never wakes it. |
| 0062 | A background job silent and unread for 2h is stopped with its command kept; /jobs keep pins one (retained at exit); every job has an ownership record graff servers can list and stop, verified by start identity (#199). |
| 0063 | Every cancel records its source; a turn cancelled with no recorded source is labelled a harness cancel, never a user interrupt, and the source lands in the trace (#728). |
| 0064 | Plain root finals with open current work get one reconciliation request; a remaining stop is explicit, not a promise of continued execution. |
| 0065 | Stop bounded lexical prose loops before delivery without user cancellation, transport retries, or completion nudges. |
| 0066 | Publication safeguards survive custom prompts; recaps cannot change ledger authority, and constraint writes refresh active prompts atomically. |
| 0067 | Recorded constraints are live ledger JSON in the root prefix; recap prose is not authority, and a write refreshes instructions in the same turn. |
| 0068 | Background-agent ids are a session ledger; an interrupted parent turn must not report them as never started (#753). |
| 0069 | Prompt-cache affinity is the git root (or a shared scratch seed), not the leaf cwd. |
| 0070 | The local Electron desktop renders browser pages directly, keeps coding in graff ACP, and hosts narrow SwiftUI panels through a native bridge. |
| 0071 | Desktop MCP controls embedded Chromium; coding stays in graff. The native macOS computer tool was removed (0209). |
| 0072 | GUI profiling is bounded and off by default; feedback exports contain allowlisted measurements with no automatic upload. |
| 0073 | One ACP stdout reader routes responses; shared review reads Git working trees without inferring edit authorship. |
| 0074 | Explicit desktop skills and validated themes live in the GUI; selected instructions travel over ACP. |
| 0075 | ACP presentation decoding is separate from session lifecycle; desktop performance uses bounded workload measurements and default Chromium acceleration. |
| 0076 | Verified local peer discovery, non-consuming history, explicit queued DMs and anonymous profiler slots. |
| 0077 | ACP shares the complete REPL catalog; desktop menus, tool disclosure and initial history rendering stay bounded. |
| 0078 | Desktop workspace terminals start lazily, preserve hidden shells and bound output through a trusted PTY bridge. |
| 0079 | Signed desktop updates download in the background and install only on explicit restart; one process owns each profile. |
| 0080 | Desktop projects are folders; preferences survive local UI origin changes, and new chats inherit the focused project's folder. |
| 0081 | Split positions remain stable as focus changes; shared controls and draggable separators keep navigation usable. |
| 0082 | Sub-agents publish bounded, independent activity snapshots for read-only ACP inspection without mixing parent transcripts. |
| 0083 | Meta / Muse Spark tool_choice is auto at the source; max effort folds to xhigh (#751). |
| 0084 | Native codedb context is --local (or refused before spawn) when repository policy or local_only forbids transmitting working data; no-retention hybrid is not no egress. |
| 0085 | /update installs a verified release for the next launch; this session keeps its original binary. |
| 0086 | Unsent desktop drafts and uploads belong to open chats and survive hidden panes; closing a chat disposes them. |
| 0087 | Bound syntax caches and live code rendering; project saved transcripts before sending them to the renderer and measure identical desktop workloads. |
| 0088 | Failed children return bounded partial evidence with error status intact, including an excerpt for workflow synthesis. |
| 0089 | Preserve standalone compaction windows across pruning and resume; opaque recovery uses the server or reports failure without discarding history. |
| 0090 | Local steering stays local; durable project constraints require explicit scope and exact current-user text, while legacy unscoped records are reviewable. |
| 0091 | Superseded by 0152 for persistent wait_ms; finite jobs still wait until exit (ADR 0010). |
| 0092 | Bare codedb context is --local; --hybrid / --semantic are opt-in remote rerank (and still refused under ADR 0084 policy). |
| 0093 | Project layout favors breadth under its caps; missing directories offer bounded sibling hints without changing confinement or ADR 0090 constraint policy. |
| 0094 | GUI Stop writes {id}.cancel in the activity dir; the child finishes failed even if the model returns. Not session/cancel. |
| 0095 | Live evals are gated PRs with no SPEC.md; score pass @ n=3 and list$ on passing reps only. |
| 0096 | Persist the desktop link destination outside origin-scoped storage; validate once and reveal the focused chat's Browser without navigating the app. |
| 0097 | Offline PTY probes get private clipboard commands per process; direct probe runs retain OS clipboard integration. |
| 0098 | Legacy listener discovery is read-only; stop authority requires verified ownership, port preflight checks both families, and unknown browser visibility protects listening jobs. |
| 0099 | A saved-session GET is a snapshot with unknown live status; the GUI must not infer the REPL finished. |
| 0100 | Non-draft PRs fail closed on CI/Verification/helper-only claims; artifact presence ACK is not ownership; recipe success is verified task success. PR-readiness and verified-completion parts superseded by 0250. |
| 0101 | GUI tests stay hidden by default; visible opt-in can overlap other apps, and native foreground checks require separate opt-in. |
| 0102 | Agents uses the workspace area, Tasks visibility is explicit and persisted, and timed-out cancellation retires the worker before session recovery. |
| 0103 | MCP Apps are private saved result views in isolated GUI/browser sandboxes; app tool calls require a future approval path. |
| 0104 | Requests merge only ready MCP tasks; publication and completion use fresh head evidence; claim transactions serialize handoffs. Publication head-evidence part superseded by 0250. |
| 0105 | Only an explicit identity-bound stop-suspect action may terminate an unrecorded legacy listener; automatic cleanup stays conservative. |
| 0106 | Desktop HTML explanations are private saved results in static, opaque sandboxes with bounded source and offscreen teardown. |
| 0107 | A page the model draws (render_html) is a private snapshot served under a CSP sandbox; the model picks the presentation, never the privilege. |
| 0108 | Browser page-info events invalidate older pending IPC snapshots; a loaded page must not revert to loading. |
| 0109 | Resume restores loaded tool selections and the same-workspace layout snapshot, without freezing current instructions or granting permissions. |
| 0110 | Project MCP entries opt in optional servers; inherited extras still require opt-in, and startup consent applies to both. |
| 0111 | Peer inbox owns complete bodies, reports and persists loss, and clears only after a complete read result is allocated. |
| 0112 | MCP wire names are escaped and bounded; raw server/tool identities control policy and dispatch. |
| 0113 | Direct AppKit clipboard failures need typed evidence; generic helper failures never imply Automation permission. |
| 0114 | Live terminal citations use per-stream display filters with independent reasoning state; structured JSON/ACP output stays unchanged. |
| 0116 | Summary turns gather bounded evidence; coding completion requirements apply to requested changes. |
| 0118 | File edits checkpoint the target Git worktree; unresolved paths retain the caller checkpoint. |
| 0119 | Superseded by 0313. Computer-use MCP requests carried caller-owned session and turn context. |
| 0120 | Superseded by 0250. Draft PRs cannot satisfy verified completion. A draft completes as a labeled, unverified handoff with no user command; ready PRs need passing current-head checks. |
| 0121 | Claims include repository identity; literal PR mutations compare the observed repository, PR number and branch, while unknown scopes stay conservative. |
| 0122 | Open chats use the expanded sidebar or collapsed top tabs, preserving drafts and groups; focused mode keeps a compact composer and accessible settings. |
| 0123 | Superseded by 0250. PR completion retains named current-head check observations locally; diagnostic receipts never replace fresh verification. |
| 0124 | Explicit reviews request a findings checkpoint every twenty calls without forcing completion or changing authority. |
| 0125 | Opt-in review deadlines use joined turn-owned watchers, preserve user cancellation, and cannot validate late results. |
| 0126 | Superseded by 0250. Observed failed checks survive resumes; non-draft publication waits for successful reruns and occupies its own tool batch. |
| 0127 | GUI titles require one explicit result and successful process exit; diagnostics never become chat names. |
| 0128 | The GUI context ring uses last-reported harness occupancy; missing usage stays unknown. |
| 0129 | graff mcp serve exposes bounded fresh CLI tasks over stdio; launch-time permissions and workspace stay outside tool arguments. |
| 0130 | MCP task apps negotiate presentation only; structured results and text fallback share the same bounded task execution. |
| 0131 | HTTP MCP shares bounded task execution; CLI and GUI installs register detected clients additively through a private local service. |
| 0132 | Desktop Touch ID uses matching signed keychain configuration; account choice is explicit and existing iCloud credentials need a fallback. |
| 0133 | Clipboard cleanup requires file ownership and released consumers; age alone never deletes active or saved attachments. |
| 0133 | Superseded by 0250. Proposed: non-draft publication reviews immutable source and observed checks; changed inputs invalidate earlier assessments. |
| 0134 | JSONL is the durable peer room; Accord Unix 0600 is live by default (GRAFF_ACCORD=0 opts out). |
| 0135 | Advertise one shell tool (run / output / kill); bash names stay dispatch aliases. Not a PTY. |
| 0136 | A queued follow-up or force-steer promotes a foreground shell; Esc still kills it. |
| 0137 | Desktop appearance tokens for render_html ride the turn, never the prefix or tool catalog; drawn HTML uses them unless the user named colors. |
| 0138 | Unselected split panes keep their transcript under a light wash; the focused pane stays the working surface. |
| 0139 | Retain a bounced answer only in the current turn, before unfinished-work reconciliation; never recover it from persisted history. |
| 0140 | rlm is on the catalog whenever it is available. No batch-size or compactAt gate. --old still hides it. |
| 0141 | The desktop session observer is a non-activating SwiftUI edge panel; cells are live ACP work, opt-in from Settings. |
| 0142 | Zigzag is not a frontend. TTY graff repl is TUI/; piped/CI uses a local scripted Model. Do not vendor zigzag. |
| 0143 | Packaged Codegraff.app is com.codegraff.app. dev.* identities are local rebuilds only. |
| 0144 | Claim conflicts ping the owner on Accord/JSONL; the model does not broker handoff in chat. |
| 0145 | Claim acquire/release/handoff replicate as replaceable Accord progress; the JSON ledger stays canonical. |
| 0146 | A second live session in the same Git checkout gets its own worktree; concurrent agents never share index.lock. |
| 0147 | Finish is not archive: park peer wakes until idle, paint the tally at the step boundary, refuse cleanup/fix-it children, cap live fan-out. |
| 0148 | After N same-prefix or incrementing read_file misses, refuse further guesses this turn and point at codedb list_dir. |
| 0145 | GPT-5.6 reasoning replays from local history: never send reasoning.context or reasoning.mode; max effort is the ladder ceiling (shown as Ultra); PTC items stay opaque history. |
| 0148 | A streamed provider "internal error" after output began is a transient 500: bounded backoff retry, never overflow. Overflow needs a size/length phrasing or code; the meter pins only on a real rejection. Reverses #1019. |
| 0149 | Ambient [peer] wakes are not a new task; [daddy] directives are explicit supervisor control. |
| 0150 | Child briefs are headed sections plus a harness environment header; the judge stays a bare prompt. |
| 0151 | Z.AI Coding Plan is a sub_login like Kimi/xAI: graff login zai uses ZCode's public CLI OAuth broker, then provisions a Graff-named API key onto /api/coding/paas/v4. |
| 0152 | Persistent shells snapshot immediately (wait_ms ignored) and stay on /jobs; do not poll. Finite jobs still wait until exit (ADR 0010). |
| 0153 | Task workspaces copy gitignored include files from the main checkout and run setup/run/archive scripts from .graff/workspace.toml. Finish is still not archive. |
| 0154 | Interactive parked shells yield the parent like subagents: 15s foreground wait, then the prompt is yours until the job-exit wake. |
| 0155 | Resume of a linked-worktree save re-enters that tree; $HOME origin stays history-only. |
| 0156 | Linux desktop uses system window decorations, a POSIX terminal, and a sandbox fallback when user namespaces or the setuid helper are unavailable. |
| 0157 | Tag releases upload the unsigned Linux .deb (and AppImage when the packager built one). macOS stays notarized; do not skip the Linux upload for lack of a signature. |
| 0158 | MiMo workers use local Pro/Flash defaults; live catalog and price checks still apply, and benchmark scores are never invented. |
| 0159 | Opening a model surface refreshes only the gateway catalog, with a short deadline and the existing snapshot as fallback. | | 0160 | Running model picks stay per chat and apply only at the next prompt boundary without cancelling the current response. | | 0161 | Default model preferences stay on the selected provider; explicit and saved choices win. | | 0162 | HTTP/2 requests exclusively lease active sessions; the process pool owns only one idle connection. | | 0163 | Restore and request admission share tool-result repairs while preserving typed blocks. | | 0164 | Task archive requires current commit evidence; live writers and failed teardown keep the checkout visible. | | 0167 | Dependent stages share a worktree; pipeline items stay isolated and retained edits are explicitly delivered. | | 0168 | Normal TUI tool approvals use frontend-owned typed requests and once-only responses. | | 0169 | Invocation tool limits reserve atomically across descendants; legacy per-turn root limits keep their meaning. | | 0170 | Workers retain owned conversation state; queue-only messages and explicit resume have distinct semantics. | | 0171 | Cost estimates use the actual provider route, preserve cache and long-context rates, and leave unknown tariffs unpriced. | | 0172 | Model guidance is composed once per request from the current model, with root-only delegation and stable repeated prefixes. |
| 0173 | Native and external schemas share admission order, which survives session save and restore. |
| 0174 | Deferred completion rejects pending work and preserves background verification exit status. | | 0175 | RLM speculates only leading read-only calls, then preserves statement order and stopped tool results. | | 0176 | A trailer deadline after valid completion returns buffered output; missing usage stays explicitly unknown. | | 0177 | Direct read-only async jobs own their lifetime, preserve order, and join before the next request. | | 0178 | Preflight every edit span in memory, then perform one verified replacement; an invalid later span leaves the file unchanged. |
| 0179 | Reserve durable JS-exact shell handles before spawning; stale handles never target new jobs. |
| 0180 | ACP permission decisions belong to the active client and request; cancellation never grants approval. |
| 0181 | Live ACP loads saved conversations in their selected workspace and replays history without rerunning tools. |
| 0182 | Connection-scoped ACP usage preserves unknown totals through a custom notification; network retries remain activity indicators. |
| 0183 | Ambiguous HTTP/2 failures return to the request retry policy so attempts and unknown usage remain observable. |
| 0184 | Directory scan limits count examined entries before filtering; truncated listings and suggestions remain explicitly partial. |
| 0185 | Empty-input, whitespace, and record-framing semantics come from the task contract, not global work instructions. |
| 0186 | Tool previews select whole diagnostic lines from original omitted ranges within byte and line budgets. |
| 0187 | Optional judgments use an independent gateway login; tokens and unsettled cost remain distinct in CLI and ACP usage. |
| 0188 | Streamed tool calls use explicit IDs; reused indexes keep incomplete predecessors invalid, and prose is not execution evidence. |
| 0189 | Buffered HTTP/2 posts cap body growth, use exclusive pooled leases with durable transport allocation, join deadlines, and never replay ambiguous sends. |
| 0190 | Catalog GETs use bounded HTTP/2 pages with joined deadlines, shared redirect limits, and credentials scoped to the original origin. |
| 0191 | ACP thought-level options follow the active model and share /effort state; changes received during a turn apply after that turn. |
| 0192 | MiMo exposes Off/On, preserves legacy positive settings as On, and uses the documented thinking control on each wire. |
| 0193 | Optional Jev selects only supported session effort at the next request boundary; arbitrary judgments are not exposed. |
| 0194 | Draft ACP child sessions stream live only with explicit opt-in; durable replay is required before default enablement. |
| 0194 | Optional native learning admits and promotes only with a fresh pinned formal baseline check bound to the evaluated binary; remote submission waits for a compatible signed receipt. |
| 0195 | Desktop browser uses embedded Chromium, web preview uses the paired extension, and CLI fetch uses built-in HTTP without a sidecar. |
| 0196 | Detached ACP workers stream through an opted-in Graff extension with connection-lifetime output ownership; draft child sessions remain foreground-only. |
| 0197 | Deferred MCP queues, joins, tool lookup, and catalog snapshots use the registry lock so concurrent requests consume and publish each connection once. |
| 0198 | New chats inherit the chosen project while ACP reports each worker checkout; generated worktrees are rooted at the main checkout. |
| 0199 | Generated worktree activity rolls up to the owning project in automatic suggestions; explicitly saved checkouts stay selectable. |
| 0200 | Desktop restart/reload confirms active-turn interruption and restores tab references from saved sessions in their workspaces. |
| 0201 | CLI beta updates require explicit opt-in, select the newest numeric release branch, verify pinned assets, and activate on next launch. |
| 0202 | ACP sessions adopt the client cwd, report the worktree as _meta["graff/worktree"] (null in a main checkout), and graff worktree exits non-zero when it refuses or does nothing. |
| 0203 | Other agents join the device rooms with graff peer list/send/inbox: same JSONL rooms and records, owned by the agent's process; a DM is held while the recipient's newer message is unread; drains read only new bytes. |
| 0204 | Kimi requests send X-Msh-Platform: graff and graff/<version> everywhere (OAuth and inference), never kimi_code_cli; a Kimi Code console key bills as plan quota. Supersedes 0027. |
| 0205 | By default a subagent streams its work onto the parent tool call as tool_call_update rows (resolved-model title, rolling log + _meta["graff/subagent"]); the draft child-session stream only when both sides opt in; GRAFF_ACP_SUBAGENT_PROGRESS=0 turns it off. |
| 0206 | ACP v2 draft shapes behind GRAFF_ACP_V2=1 plus a client protocolVersion >= 2; v1 stays the default and unchanged. Prompt is acknowledged with messageId on insertion, the outcome travels as state_update. |
| 0207 | Rejected: no Jev file retrieval (locate tool, Jev rerank after codedb context, or jevgrep). A full Jev scan found answer files best (80% in top 5 vs 38% for codedb context) but costs one request per file and grows with repo size; codedb stays the retrieval path. |
| 0208 | A mid-session instruction-file edit or date rollover is appended before the next prompt as a keyed <context> message (developer role on Responses, system on Chat Completions, user elsewhere), and the system prompt is left as is. Compaction drops those messages and folds the latest values into the new system prompt. |
| 0209 | The desktop app has no computer use: the computer tool, endpoint and menu toggle are removed; the native input bridge remains a test-only driver. Supersedes the computer half of 0071. |
| 0210 | Tag releases sign and notarize the macOS CLI tarballs on a macOS runner before anything is uploaded, gated on all five signing secrets; without them the job no-ops and docs/notarization.md is the fallback. SHA256SUMS is computed once from the uploaded bytes. The desktop DMG stays a local distribute.sh step. |
| 0211 | graff mcp add <name> resolves from the codegraff.com/mcp.json catalog, then the MCP registry only for a namespace owner matching the name. --everywhere writes the user-level file. Harness syncs that file through its registry as non-secret rows. Env values, headers and OAuth tokens stay on each device. Harness drives graff only over ACP (slash command, form elicitation, _meta["graff/mcp"] status). Supersedes the vault-item sync in #1371. |
| 0212 | A cold build is 16 s of single-core semantic analysis; codegen and link are nearly free. No redundant files to cut. Keep the default backend: /.codegraff/mcp-state.json-fllvm is 2x slower, -fincremental/--watch do not help on Zig 0.17-dev, and -fno-llvm -fno-lld exhausts memory. Iterate with -Dtest-filter (44 s → 13 s). |
| 0213 | Keep line-REPL paste framed through active turns; submit one draft on Enter, and stage or reject bounded image data URIs before text expansion. |
| 0214 | Mine live eval tasks from merged PRs, with graders validated red on the parent and green and stable on the merge, and a person approving each. Hill-climb on a fixed held-out split with measured noise: keep a change only when train beats the noise band and test improves. Model-guide advice enters as candidates, not edits. |
| 0215 | Headless roots (-p, --json, graff serve, piped stdin) wait for their own background work to report before a plain final ends the run. Servers do not count, a 10-minute heartbeat wakes the model, and interactive surfaces keep their idle wake. |
| 0216 | /loop is retired: /goal is the one autonomous run, and waiting for background work is how every run works (ADR 0215). Typing /loop prints a pointer to /goal and makes no model call. |
| 0217 | A plain follow-up typed while the root reply streams cuts that stream, drops the uncommitted partial and rebuilds the request with the follow-up (not for compaction, children, started async tools, or GPT-6 WebSocket steer). TUI Enter hands plain text to the running turn; /btw, commands and images still wait; ACP is unchanged. |
| 0218 | A finite root job started in the background writes its output to .graff/job-output/<id>/ with an exit receipt from its own shell, so it outlives a crashed graff. Loading the session re-attaches this session's unreported jobs under their old ids, reports what ended while graff was down, and sweeps other sessions' stale captures. Foreground commands, servers, subagent jobs and Windows keep pipes. |
| 0219 | Claude Opus 5.5, Sonnet 5.5 and Fable 5.1 are never forced to a tool, get drop_block thinking binding (with its beta header), take /effort as output_config.effort (left off at graff's default), and get 64K/128K max_tokens. Claude errors take the same retry-without ladder as other providers; a refusal ends the turn outside history. Default model claude-opus-5-5, ladder opus-5-5 → sonnet-5-5. |
| 0220 | On the Anthropic API, compaction's note and summary fork the conversation while its cache is warm. They use the same tools, system prompt and history, with the instruction appended, so they read the history instead of rewriting it. Otherwise the old shape runs without breakpoints. A turn-opening request keeps the TTL of the last gap inside a turn. 1-hour writes bill at 2x. 5.5-era models get graff's effort as shown; titles and recaps run at low. A second breakpoint marks where the previous request wrote. |
| 0221 | The ChatGPT plan's sign-in for open-source apps is its own opt-in chatgpt-new provider (dynamic registration, per-machine host id, RS256-verified ID token, the public Responses endpoint and WebSocket, billed flat-rate); Codex stays the primary ChatGPT route until OpenAI requires the new method. |
| 0222 | A follow-up typed while a GPT-6 reply streams over the Codex WebSocket is sent as response.steer: accepted, the reply continues or the steer rides the next chained request; refused, it waits for the next turn. The root turn leaves server compaction off while well below its threshold, because the backend will not steer those requests. |
| 0223 | Codex with a ChatGPT account id partitions the prompt cache by account, not repo: the system+tools prefix carries no cwd, so turn 1 in any repo reads the prefix another repo warmed. Children keep their role lanes on the account base; other providers keep the project key (ADR 0069). |
| 0224 | render_html, agent_message, install_agent_tool, read_tool_result, subagent_resume and schedule_task join native_fold.folded: listed by load_tool_schemas, auto-loaded on a confident call, no longer paid on every request. |
| 0225 | Every MCP load/search/select result says how large list results are slimmed (identity fields; comment lists become {n, latest_author}), so a fresh project does not code against dropped fields. A direct call's slimmed result keeps the full payload as a read_tool_result handle; rlm binds stay plain slim JSON. |
| 0226 | On the codex provider, graff's default medium effort is sent as the model catalog's default level, and the Responses body carries the catalog's text.verbosity (not on compaction or output-schema requests). Any other effort is sent as chosen. |
| 0227 | A spawned child's catalog gains the MCP tools its root loaded, with full schemas (worker_mcp.inherit into Agent.worker_tools, served first by toolsJson). Unloaded tools stay out; children still have no load tool. |
| 0228 | An MCP tool is a read when its server declares readOnlyHint: true (mcp.Tool.read_only). A read-only (informational) child may call those and inherits only those from its root; undeclared MCP tools stay refused. |
| 0229 | The Codex client's login no longer works, so every ChatGPT login name (chatgpt, codex, openai, gpt, oai) and the model picker run the chatgpt-new sign-in, and chatgpt-new precedes codex in the provider table. The codex provider stays for an existing Codex CLI auth.json. Replaces ADR 0221's "Codex first". |
| 0230 | Every session but --json connects MCP servers in the background (interactive after consent, --yolo, -p, ACP); no request waits for a handshake, finished starts join the next request, and debug diagnostics report connection results without normal startup chatter. ACP session/new waits at most 250 ms; /mcp lists without waiting. |
| 0231 | No call the task did not ask for: a named small MCP server (and subagents, when asked for) loads with the first request, with the slim-shape note; write_file refuses to replace an unread file unless replace: true and reports created/replaced and JSON validity; inherited child MCP tools are never deferred; a piped bracketed paste is one prompt; unwatched (-p, piped) sessions get no ask_user and no low-effort reasoning summaries. |
| 0232 | Sub-agents measured (subagents suite and its subagents-solo counterfactual, subagent_split.py) and brought to parity: write_file creates a new file's directory; unwatched sessions get no todo_write nudges; agent_output takes ids and spawn receipts name the running children; a fresh child starts with the user's prompts and its parent's live effort (/effort or Jev) unless pinned, and can ask Jev mid-run for its own; a read-only child's shell runs under macOS seatbelt instead of an allowlist; one subagent trace line per child; a script that computes a file writes it. |
| 0233 | No tool result the model already has: interactive roots ignore a model's shell timeout (the 15s park of ADR 0154 stands) and unattended roots floor it at 5s, so a timeout: 1000 habit no longer parks quick commands and ends the turn; todo_write answers the model with counts and the items graff kept, not the list it just sent (the UI still gets the full list). |
| 0234 | The shell tool names the OS its commands run on (macOS: BSD tools, sed -i ''). The codedb guard lets an in-place sed -i edit and a pipe-free whole-file read of files up to 16 KiB through; searches and bigger reads still go to codedb. |
| 0235 | MiMo thinks only at high and above: minimal/low/medium (graff's default) send thinking Off on the Chat and Responses wires; On, a worker pin, or Jev's high turn it on. Replaces ADR 0192's "positive values mean On" below high. |
| 0236 | rlm takes JSON array/object literals as arguments and binds (name = [...], bound names allowed inside); its splitters nest []/{}; each(arr, tool[, field]) passes plain items as is, picks field from objects (default: an MCP tool's first parameter) and names the fields it found; an unsupported statement lists the forms that work. |
| 0237 | DeepSeek's default effort (medium) sends reasoning_effort: low with thinking enabled; /effort low still turns thinking off (ADR 0054), and high and above are unchanged. |
| 0238 | An MCP call inside an rlm script binds the whole result; print() shows the slim view (each item of an each() bind cut on its own), project(x, field) reads any field (n/latest_author through a comment list's fold), and write_file saves the whole result; inside rlm, read_tool_result("tr_N") with no range binds a stored result whole. |
| 0239 | Heads-ups are one short line in the same response as their tool calls; a script that computes an answer is its own proof (no second derivation); read_file is required only before editing an existing file. |
| 0240 | A slim view names the whole value's fields (; fields: ... on rlm print and direct-call handle markers); the slim rule says to compute over results inside the same rlm script; an unbound host call or each() in rlm prints its result. |
| 0241 | On the Responses wire, prose tightens the stall budget only while its output item is open; response.output_item.done restores the full budget for the next item (WS and SSE alike). |
| 0242 | The shell tool's OS clause names python3's version, read at startup from where python3 on PATH resolves (never by running it); unknown versions leave the description unchanged. |
| 0243 | On the Responses wire for codex, chatgpt-new and openai, root turns send the project-instructions section and the layout as one developer input item ahead of the conversation, so the instructions are byte-identical across repos and cache on turn 1. |
| 0244 | Remember saved workspace roots locally; remote picker targets are workspace-qualified, and resume must enter the selected tree before restoring it. |
| 0245 | The fullscreen UI is maintained separately; graff tui launches installed graff-tui before engine startup, sibling first then PATH, without downloading. TTY graff repl uses the line REPL. Supersedes 0041, 0042 and the fullscreen portion of 0142. |
| 0246 | On an eligible model at the default effort, graff asks Jev for the turn's effort alongside the first request; the pick applies from the next request, holds for that turn, is never saved, and never overrides a user's effort. chatgpt-new GPT-6 models are eligible. |
| 0247 | A parked turn names the work it waits on: the standing block draws ↻ waiting on <work> — graff continues when it finishes while a job or agent that will wake the session runs, the yield prints only for a server, and a wake prints what finished before continuing. |
| 0248 | Commentary prose (the heads-up before a tool-call batch, which the server holds open until it releases the calls) counts as visible text but does not tighten the stall budget; final-answer prose and whitelisted tool-argument prose still do. Refines 0241. |
| 0249 | The work note no longer says a green public test is not the whole spec: it made the model write an extra verification script on every spec task without changing the pass rate. Spec tasks end at their own tests; the lean note is unchanged. Refines 0024. |
| 0250 | PR publication is not gated: no local-check, head-CI or claim-review preflight and no completion obligation; drafts complete like any task. Artifact claims and disclosure policy are unchanged. Supersedes 0120, 0123, 0126, 0133 and parts of 0100/0104. |
| 0251 | Tool results inline up to 64 KiB (was 16 KiB); effectiveThreshold still clamps to half the context window, so small windows are unchanged. The codedb small-read exemption follows the same number. |
| 0253 | When a ChatGPT request is rejected and the refresh cannot replace the token, an interactive root session opens the browser sign-in, waits up to three minutes and retries once; -p, piped, --json, ACP and sub-agents never do. One unfinished sign-in ends it for the process. |
| 0254 | Imported Claude history uses the configured graff provider and credentials; source models are metadata, and foreign tool results remain historical receipts. |
| 0262 | A queued follow-up ends a blocking action=output wait like Esc does (the job keeps running and still reports on exit); an ACP prompt arriving mid-turn raises that follow-up without cancelling the turn. Refines ADR 0010. |
| 0255 | Claude aliases on codegraff use the native Messages endpoint; isClaudeApi is the one predicate for the real Claude wire. |
| 0256 | Gemini models get a working note (chained shell steps, no read-backs, no pasted files, check computed answers) and may batch attempt_completion with a final check or write; the completion is recorded only if every batched call succeeded. |
| 0257 | A slimmed MCP comment list keeps the issue id its rows share ({issue, n, latest_author}), so parallel results name what they describe. |
| 0258 | On the Codegraff chat wire, Gemini root turns send the project instructions and layout as the conversation's first user message (ADR 0243's split), so the system prompt every request repeats no longer carries them. |
| 0259 | First-party Responses routes (direct API, Codegraff GPT, ChatGPT plan) compact only server-side: no client-summary fallback while the server arm is on. A compaction item's encrypted_content is metered at 16 bytes/token, not as text, so a blob-anchored history does not re-compact every step. |
| 0260 | GRAFF_CLEF_COMPACT=1 routes client-summary compactions through the gateway's server-side POST /v1/compact (Clef decision-model pruning, text verbatim); OpenAI-family server paths are untouched and any failure falls back to the summary. |
| 0261 | The client summary stays the compactor: GRAFF_CLEF_COMPACT defaults off (Clef rarely pruned and mostly fell back to the summary in measurement); first-party Responses routes use only the provider's own compaction. Supersedes 0260's default. |
| 0264 | A parked foreground job records its outcome in .graff/job-parked/<id>.json (exit code and unread tail, or how session end treated it), so a later process answers its handle instead of "unknown outcome". Completes ADR 0218's follow-up without moving parked jobs off pipes. |
| 0270 | A stdio MCP server whose connection closes goes back to dormant with its launch config and restarts on its next call; the failed call is never replayed, and after two restarts in a session its tools are withdrawn as before. |
| 0278 | An ACP client named t3-code… gets a profile: slash commands are the first prompt block, the client's cwd is never swapped for an auto-isolated tree, a model config option lists reachable models, and /model and /yolo are not advertised. |
| 0280 | Every configured MCP server has one status row (graff mcp status --json, /mcp); graff mcp reconnect / /mcp reconnect run a real handshake and refresh its catalog; graff mcp enable|disable live in `; the catalog cache keys on cwd + env, and server envoverlays graff's own. | | [0281](0281-anthropic-console-sign-in-reads-the-sdk-profile.md) | Anthropic Console sign-in: graff reads theuser_oauth profile Anthropic's CLI writes (ant auth login), in the SDK's precedence (API key wins), sends it as Bearer, and refreshes through ant auth print-credentials; graff login anthropicrunsant auth login. No claude.ai subscription login. | | [0282](0282-claude-system-breakpoint-closes-before-the-repo-context.md) | On Claude, the system prompt is two text blocks with the same bytes: the cache breakpoint closes the static instructions, before the project instructions and layout, so every repo shares the tools + instructions prefix. | | [0283](0283-agents-prepare-and-linked.md) | New task worktrees symlink the gitignored paths .agents/linkedlists from the main checkout and run.agents/preparewhen.graff/workspace.tomlnames no setup script. | | [0284](0284-output-limits-are-recovery-not-completion.md) | Output limits continue with bounded recovery; empty replies back off; one-shots expose a saved-session handle and classified result without claiming unknown costs or exactly-once replay. | | [0271](0271-gemini-interactions-continue-the-stored-interaction.md) | Direct Gemini (Interactions) requests are stored and continue the last Interaction withprevious_interaction_idplus only the new steps while a content hash proves graff's history extends it; any rewrite, model switch or rejected id falls back to a full replay; usage meters the whole prompt from the per-invocation counts. Tool choice isvalidated, minimalthinking maps tolow, thought summaries stream, and Gemini 3.1 Pro with tools uses its custom-tools variant. GRAFF_INTERACTIONS_STORE=0keeps it stateless. | | [0272](0272-compaction-never-summarizes-unread-tool-results.md) | A compaction never summarizes tool results the model has not read: the cut keeps the newest model turn and its results verbatim, and the pre-send gate sends a batch that dominates the context and compacts after the model reads it. Summaries copy exact values. Interactionsuser_inputsteps are turn boundaries. Gemini compacts by default at 80% capped at 300k tokens. | | [0285](0285-acp-reauth-is-route-specific.md) | Terminal ChatGPT auth rejection carries fixed route-specific recovery metadata: ACP v1-32000+error.data, v2 failed idle _meta["graff/reauth"]; graff login chatgpt-newrepairs the new store,codex loginthe legacy one. Retry and non-auth error behavior stay unchanged. | | [0252](0252-hosted-compaction-with-a-codegraff-login.md) | With a Codegraff login andGRAFF_CLEF_COMPACT=1(default-off per 0261),compact()` asks the gateway first: per-call keep/trim/drop decisions applied to graff's own history by call id, plus a spliced summary when pruning frees too little. Live-turn calls stay; a reply must check out and free a tenth of the context. Refused key or exhausted credits: local for the session; other failures: local for that compaction. |
| 0286 | run_task accepts bounded text context and preserves task metadata across the shared engine and ACP. |
| 0287 | Loopback inference receives request-local default deadlines; explicit limits and remote recovery budgets remain unchanged. |
| 0288 | Native subscription PKCE login is shared across CLI, REPL and ACP; subscription wire compatibility stays credential-source-aware. |
| 0289 | Preserve typed MCP results independently of display content, show resource references without fetching them and answer pings during shared waits. |
| 0290 | HTTP task calls wait for validated child and required preprocessing budgets plus reply cleanup; other requests keep their deadlines. |
| 0291 | Pin nanocompile and cache complete release build tasks with explicit inputs, tool resources, and a verified byte-identical restore before packaging. |
| 0292 | GPT-6.1 Sol uses a 500k subscription window on Codex and ChatGPT sign-in; smaller catalog windows still win, other models retain their conservative caps, and API maxima do not widen subscription defaults. | | 0293 | Restore pinned CI executables from optional object storage only after checking a reviewed SHA-256; unavailable artifacts retain the pinned-source fallback. | | 0294 | Only audited fixed-target/baseline-CPU release tasks opt into platform host identity; identical compiler/manifest/package snapshots avoid redundant native fetch preparation. |
| 0295 | Experimental Worker-native turns share the native chat step; JSPI supplies bounded host I/O, not a proxy or a second agent loop. |
| 0296 | Worker/DO tasks retain the agent loop and delegate Linux execution to remote sandboxes with explicit ownership, deletion and bounded leases. |
| 0297 | The fetch-only managed SDK reuses account relay/device tapes; prompt retries are explicit, durability limits are stated, and content-free OTLP export remains opt-in and observational. |
| 0298 | A graff peer send live wake is concurrent and bounded by one shared deadline; misses are reported and the durable room post still succeeds. |
| 0299 | fork_from explicitly snapshots current, project-local saved, or family-owned worker history into independent children; lightweight delegation stays the default and retained remains opt-in across subagents and workflows. |
| 0300 | Synthesis gets bounded evidence requests and a final report-only request; cancelled or exhausted workers are not restarted and failed stages retain prior evidence. |
| 0298 | A current unresolved recurrence reopens the canonical resolved issue; comments alone do not complete reporting, intentional closures remain respected, and final state is verified. |
| 0299 | On macOS tool commands' open launches apps without activating them (a -g shim first on the tool PATH); GRAFF_GUI_FOREGROUND=1 on a command is the explicit foreground opt-in. |
| 0300 | Shell commands that look like simulator work are bracketed by booted-device snapshots; devices a session booted are leased under ~/.codegraff/simulators/ and shut down when the last live leaseholder ends, never devices booted before. GRAFF_KEEP_SIMULATORS=1 opts out. |
| 0301 | Exhausted request retries leave a truthful failure boundary in history so an identical prompt can run after reconnecting, including after save/load; duplicate-host protection and bounded retries stay unchanged. | | 0302 | Refine the line REPL's terminal sinks: quiet status hierarchy, mode-first width priority and active-work emphasis, without native windows or changing the editor, engine or external fullscreen client. |
| 0303 | The line REPL renders inline emphasis and offers a temporary mouse/keyboard /workers inspector over the existing bounded ACP child feed, without replacing the editor or changing engine behavior. |
| 0304 | File tools allow canonical in-root symlinks, reject escaping or unresolved links, and retain lexical confinement and missing write targets; the check is not an atomic sandbox. |
| 0305 | A cancelled todo needs a short reason or the write is rejected whole; it stays listed with that reason, stops blocking completion and never counts as verified. A verification item can be cancelled after a newer user message or an answered ask_user. |
| 0306 | Boot and graff/models never wait on a catalog GET past a budget: cached catalogs activate now and refresh behind on detached workers whose only output is the disk cache; only uncached ones wait, together, up to 800ms. |
| 0307 | A session saves the provider's count of its compaction state, scoped to provider, model, size and digest; loading reapplies it before rebasing the meter, so a restart neither inflates the meter nor forces a compaction. |
| 0308 | A cheaper scout worker is an opt-in persona (model: <provider>/<model>, cross-provider only with consent and a login), not a default route; it buys accuracy on exploration-heavy work and costs more on small change tasks, so the refine loop decides per repository. |
| 0309 | Claude Agent runs the user's own claude over the SDK control protocol: graff's tools as an in-process MCP server with held calls, graff's history as the source of truth, never reading Claude Code's login. |
| 0310 | A terminal auth rejection names the seat that failed: sign-in text keeps "sign in again"; key and promoted-key texts say "API key was rejected" and never the signed-out phrases. Key seats carry {"kind":"api_key_rejected","provider":…} (v1 -32603 data, v2 _meta["graff/recovery"]); reauth_required is unchanged. |
| 0311 | Claude Agent refreshes a changed tool list with MCP tools/list_changed (served before anything else; fresh session if not re-read in 15 s) instead of removing and re-adding its server, which failed held calls. attempt_completion settles a task like a final answer: room mail waits for the next human prompt, addressed mail can still start a turn; yield_turn stays strict. A peer wake preloads peer_message. |
| 0312 | OpenAI Responses GPT-5.6+ can put a 12h explicit breakpoint on the stable prefix (GRAFF_OPENAI_CACHE_TTL=12h or openai_cache_ttl); the default stays 30m (ADR 0009 bytes) until a live probe confirms OpenAI accepts the field and keeps the entry. Usage parses cache writes by TTL. |
| 0313 | Graff does not load Codex's computer-use or unified-computer-use plugins; every MCP elicitation is declined. Supersedes 0036 and 0119. |
| 0314 | Computer use on macOS is nanocua, a signed app shipped beside graff and offered as one MCP server; it works inside one app in the background, and the app's panel, not graff, says what it may do: graff and Harness can read its state and turn things off, but turning anything on takes a person's click in its window. nanoui's copy is generated from codegraff's and keeps codegraff's license. |
| 0315 | Harness carries explicit command completion intent in ACP _meta["harness/command"]; literal slash prose bypasses dispatch and expansion, while legacy clients retain their syntax. |
| 0316 | Server-compaction replacements retain private exact-input checkpoints; rejected state restores only a matching window plus its later tail, within a bounded recovery budget. |
| 0317 | A provider or model switch expands opaque compaction state from its checkpoint instead of replaying ciphertext the new seat cannot decrypt. |
| 0302 | SSE idle watchdogs observe partial body-byte progress, while separate unfinished-event time and size bounds preserve recovery. |
When to write one
Write an ADR when a decision is load-bearing and non-obvious: it was reached through measurement, a debate, or a failure, and someone later would plausibly "fix" it back. Do not write ADRs for conventions the linter or tier 1 already enforces (those live in AGENTS.md).
How to add one
- Copy the template below into
docs/adr/NNNN-short-slug.md(next free number). - Add one row to the index above with the rule stated in one line.
- Keep it under a page. Evidence beats prose: link the eval, issue, or commit.
# NNNN. Title stating the decision
Status: accepted YYYY-MM-DD
## Context
What forced a decision, with the measurements or failures that framed it.
## Decision
What we do now, stated so a reader can comply without reading anything else.
## Consequences
What this costs, what it protects, and what would justify revisiting it.