diff --git a/.gitea/ISSUE_TEMPLATE.md b/.gitea/ISSUE_TEMPLATE.md
new file mode 100644
index 0000000..a97b7b3
--- /dev/null
+++ b/.gitea/ISSUE_TEMPLATE.md
@@ -0,0 +1,15 @@
+## Problem
+
+What is broken or missing, and the evidence for it.
+
+## Scope
+
+The intended change, bounded to what one reviewed pull request can carry.
+
+## Acceptance Criteria
+
+- Observable completion criteria, each checkable on the candidate revision.
+
+## Dependencies
+
+Issues that must complete first, if any.
diff --git a/.gitea/PULL_REQUEST_TEMPLATE.md b/.gitea/PULL_REQUEST_TEMPLATE.md
new file mode 100644
index 0000000..68218fe
--- /dev/null
+++ b/.gitea/PULL_REQUEST_TEMPLATE.md
@@ -0,0 +1,57 @@
+## Summary
+
+<!-- Keep prose brief. Add the smallest useful diagram, diff-sketch, tree,
+pseudocode, or code block when it makes the change faster to understand. Use
+the project's domain language. -->
+
+## Evidence
+
+- **Before:** the screenshot, output, symptom, or failing test run.
+- **After:** the screenshot, output, corrected behavior, or passing test run.
+
+<!-- For a bug fix, name the confirmed root cause or successful hypothesis.
+Merge evidence stays here; it is not a docs/evidence/ record (see
+docs/agents/standards.md). -->
+
+### Checks run
+
+- `the exact command already run` — observed result.
+
+## Documentation disposition
+
+updated / not_required / deferred / blocked — which one, and why in one line.
+
+<!-- Definitions and the recording rule live in docs/agents/standards.md;
+/cleanup blocks the merge without one. -->
+
+## Merge Danger
+
+**Door:** one-way or two-way — why the change is or is not cheap to reverse.
+
+**Blast Radius:** the affected subsystem, consumers, or behavior.
+
+**Rollback:** the exact rollback path, including any state it cannot restore.
+
+## Reviewer prerequisites
+
+- Required runtime, services, credentials or profiles, operating system,
+  fixtures, clean-state conditions, duration, and meaningful cost; or `None`.
+
+## Manual Test Plan
+
+<!-- Include only behavior that automated evidence cannot prove. -->
+
+1. [ ] **Action:** the exact reviewer action, command, route, control label,
+   field value, or UI interaction. Put every command in a copyable fenced block.
+
+   **Expected:** the observable evidence that the step passed, and any
+   condition that requires the reviewer to stop.
+
+## Post-Merge Cleanup
+
+```sh
+git switch main
+git pull --ff-only origin main
+git branch -d ISSUE-<number>
+git push origin --delete ISSUE-<number>
+```
diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 0000000..ab03976
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,37 @@
+## Agent skills
+
+### Issue tracker
+
+Gitea issues, driven by the `gitea-issues` helpers.
+See `docs/agents/issue-tracker.md`.
+
+### Domain docs
+
+single layout: CONTEXT.md and ADRs live per `docs/agents/domain.md`.
+
+### Work queue
+
+Priority lives in the `type/roadmap` issue's ordered queue; see `docs/agents/queue.md`.
+
+### Working standards
+
+Docs and tests are first-class artifacts; the tracker is the queue, repository
+documents the durable memory. Read the issue's epic and related issues
+before planning; build test-first at the spec's pre-agreed seams; record each
+change's documentation disposition and the evidence behind its merge; commands
+presented as runnable must be ready to run as written. See
+`docs/agents/standards.md`.
+
+### Focused checks
+
+`python3 -m unittest discover -s tests -v`
+
+Run on the exact current head during implementation and review follow-ups;
+any later change makes this evidence stale.
+
+### Epic gate
+
+`python3 -m unittest discover -s tests -v`
+
+The complete gate, reserved for final epic acceptance — run once on the exact
+integrated commit.
diff --git a/docs/agents/domain.md b/docs/agents/domain.md
new file mode 100644
index 0000000..03d3484
--- /dev/null
+++ b/docs/agents/domain.md
@@ -0,0 +1,56 @@
+# Domain Docs
+
+How the engineering skills should consume this repo's domain documentation when exploring the codebase.
+
+## Before exploring, read these
+
+- **`CONTEXT.md`** at the repo root, or
+- **`CONTEXT-MAP.md`** at the repo root if it exists: it points at one `CONTEXT.md` per context. Read each one relevant to the topic.
+- **`docs/authoritative/adr/`**: read ADRs that touch the area you're about to work in. In multi-context repos, also check `src/<context>/docs/authoritative/adr/` for context-scoped decisions. The rest of `docs/authoritative/` holds current product design, contracts, and constraints.
+- **`docs/evidence/`**: curated observations that inform a foundational design decision. Read a record when you need to understand or challenge the decision it supports; it informs that decision but never overrides the authoritative document. Its `README.md` sets what qualifies.
+- **`docs/historical/`**: superseded designs, archived handoffs, and development records, including one issue's retained work under `docs/historical/issue-notes/<issue-number>/`. Read these to understand how the project arrived at its current state — never as current behavior.
+
+If any of these files don't exist, **proceed silently**. Don't flag their absence; don't suggest creating them upfront. The `/domain-modeling` skill (reached via `/grill-with-docs` and `/improve-codebase-architecture`) creates them lazily when terms or decisions actually get resolved; `/cleanup`-bound work moves superseded context into `docs/historical/` per `docs/agents/standards.md`.
+
+## File structure
+
+Single-context repo (most repos):
+
+```
+/
+├── CONTEXT.md
+├── docs/
+│   ├── authoritative/adr/
+│   │   ├── 0001-event-sourced-orders.md
+│   │   └── 0002-postgres-for-write-model.md
+│   ├── evidence/                      ← foundational design evidence
+│   └── historical/issue-notes/186/    ← one issue's retained records
+└── src/
+```
+
+Multi-context repo (presence of `CONTEXT-MAP.md` at the root):
+
+```
+/
+├── CONTEXT-MAP.md
+├── docs/authoritative/adr/            ← system-wide decisions
+└── src/
+    ├── ordering/
+    │   ├── CONTEXT.md
+    │   └── docs/authoritative/adr/    ← context-specific decisions
+    └── billing/
+        ├── CONTEXT.md
+        └── docs/authoritative/adr/
+```
+
+## Use the glossary's vocabulary
+
+When your output names a domain concept (in an issue title, a refactor proposal, a hypothesis, a test name), use the term as defined in `CONTEXT.md`. Don't drift to synonyms the glossary explicitly avoids.
+
+If the concept you need isn't in the glossary yet, that's a signal: either you're inventing language the project doesn't use (reconsider) or there's a real gap (note it for `/domain-modeling`).
+
+## Flag ADR conflicts
+
+If your output contradicts an existing ADR, surface it explicitly rather than silently overriding:
+
+> _Contradicts ADR-0007 (event-sourced orders), but worth reopening because…_
diff --git a/docs/agents/issue-board.toml b/docs/agents/issue-board.toml
new file mode 100644
index 0000000..13a47bf
--- /dev/null
+++ b/docs/agents/issue-board.toml
@@ -0,0 +1,2 @@
+[status_board]
+project_id = 12
diff --git a/docs/agents/issue-tracker.md b/docs/agents/issue-tracker.md
new file mode 100644
index 0000000..54ad582
--- /dev/null
+++ b/docs/agents/issue-tracker.md
@@ -0,0 +1,135 @@
+# Issue tracker: Gitea
+
+Issues, specs, and pull requests for this repo live on its Gitea host. Use the
+deterministic helpers from the `gitea-issues` skill for every operation — never
+hand-write API calls. Resolve `<gitea-issues>` from the installed skill path.
+
+## Conventions
+
+- **Read an issue**: `python <gitea-issues>/scripts/gitea.py issue read --issue <number> --comments`
+- **Rename an issue**: `issue update-title --issue <number> --title "New title"` (optionally `--expected-title "Old title"` or `--expected-content-version <version>`)
+- **List issues**: `python <gitea-issues>/scripts/gitea.py issue list --state open` (add `--label` / `--exclude-label` filters, `--output json` for structure)
+- **Create an issue**: `issue create --title "..." --body-file - --label status/ready-for-agent` with the body on standard input, using the `## Problem` / `## Scope` / `## Acceptance Criteria` structure
+- **Comment**: `issue comment --issue <number> --body "..."`
+- **Change status**: `issue set-status --issue <number> --status status/<role>`
+- **Edit classification**: `issue edit-labels --issue <number> --add <label> --remove <label>` (repeat either flag; omit either when unused)
+- **Start implementation**: `issue start --issue <number>` — creates the `ISSUE-<number>` branch in a dedicated worktree and prints the path every later command must use
+- **Close reviewed work**: `pr cleanup` merges the reviewed pull request and reconciles the issue; `issue close --status status/done` closes an explicitly authorized resolved decision, and `--status status/wontfix` closes declined non-implementation work with a short marker-backed explanation
+- **Clean up a merged worktree**: `issue remove-worktree --issue <number> --pull <number>` — fast-forwards local `main` to the fetched remote tip (stopping with resolution commands before any deletion when it cannot) and removes the worktree and its branch
+
+Repository identity comes from the `origin` remote or the resolved credentials;
+the helpers never need a token pasted into chat.
+
+`issue update-title` sends a title-only edit with Gitea's preflight
+`content_version` check and verifies a fresh readback. Gitea does not provide
+an atomic title compare-and-swap, so a concurrent edit can still race. The
+command directs a check of the actual owning roadmap or epic entry and reports
+child `Parent:` lines that need separate guarded repair. Its own `Parent:` line
+is only a hint; preserve entry order and checkboxes.
+
+Read-only commands (`issue list`, `queue roadmap|inspect|next`, `epic
+next-ready`/`start-next` selection) reuse unchanged reads through a
+conditional cache that never touches mutation preflights or read-after-write
+verification. Disable it with `GITEA_READ_CACHE=off`, inspect it with
+`read-cache status`, and clear it with `read-cache clear`; see the skill's
+`references/read-cache.md` for the freshness contract.
+
+## Label vocabulary
+
+Status labels are the agent-writeable source of truth. When a status Project is
+configured in `docs/agents/issue-board.toml`, successful lifecycle commands
+request card reconciliation through `issue-project-board`. The board displays
+status and prerequisites; the roadmap remains the priority source:
+
+`status/needs-triage`, `status/needs-info`, `status/ready-for-agent`,
+`status/ready-for-human`, `status/in-progress`, `status/review`,
+`status/done`, `status/wontfix`, plus `priority/P0` as an exceptional interrupt
+indicator. Type labels (`type/epic`, `type/feature`, `type/bug`, …) and area
+labels classify work. Install missing names idempotently with
+`labels setup --dry-run` then `labels setup`; existing labels are preserved.
+`board/archived` is a non-status label for a closed `status/done` or
+`status/wontfix` issue kept searchable outside the status board. Initial board
+migration and later selected archival require reviewed previews in
+`issue-project-board`; ordinary closure still adds a Done or Won't Fix card.
+`board/finalizing` marks an in-progress epic whose listed children are closed
+`status/done` while final gates are checked. Other in-progress epics appear in
+Active Epics; individual work stays in In Progress. Existing eight-column
+boards use the reviewed `issue-project-board` migration.
+See `docs/agents/triage-labels.md` for the triage-role mapping and
+`docs/agents/queue.md` for the roadmap contract.
+
+`issue edit-labels` changes only named existing non-status labels, preserving
+unrelated labels. It validates every requested name before writing, adds before
+removing, and verifies the requested result with a fresh read. A satisfied
+replay writes nothing. Use `issue set-status` for `status/*` transitions.
+Writes are incremental: after a write or verification failure, reconcile with
+`issue read` before retrying. Changing `type/epic` does not create child order,
+blocking edges, or roadmap placement; use their separate helper operations.
+
+## The repository work queue
+
+Exactly one open issue labelled `type/roadmap` holds the
+`## Work Queue In Priority Order` section that defines repository priority;
+epics order children the same way. Each list entry uses `- [ ] #123 Title` or
+`- [x] #123 Title`; checkboxes display closed `status/done` progress and do
+not change workflow state. `queue inspect` reports disagreements. Convert
+numbered lists only through reviewed `checklist preview` and guarded
+`checklist apply`. Dependencies gate execution; they never define priority.
+
+- **Inspect**: `queue inspect` (health, skipped entries, tree-invariant violations, selected leaf)
+- **Read placement state**: `queue roadmap` (top-level order and content version)
+- **Select read-only**: `queue next`
+- **Maintain**: `queue init` (idempotent), `queue insert --issue <n> --position <p> --expected-content-version <v>`, `queue reorder`, `queue link-children preview` / `apply --confirm` (direct-child blocking edges)
+- **Move to `independent` mode**: the reviewed edge migration — `migration preview --history --write-plan <file>`, `migration freeze`, `migration apply --plan <file>`, `migration readiness`, then a reviewed configuration commit (see the gitea-issues `references/repository-queue.md`)
+
+Only top-level delivery epics and explicitly standalone issues
+(`--allow-standalone`) enter the roadmap. When the user has not stated a
+priority, new work enters at the default position from the gitea-issues
+queue-placement contract — the highest its dependencies allow — and an
+explicit statement always wins. The queue tree carries one
+invariant — every open issue except the roadmap itself sits on exactly one
+priority list and blocks that parent — specified in full in the gitea-issues
+`references/repository-queue.md` reference. Inserting an open entry — epic or
+standalone — links it as blocking the roadmap, so the Gitea UI **Blocks**
+section links each level to the root; the roadmap never takes dependency
+edges beyond its direct children (its queue entries). `queue link-children`
+repairs missing direct-child edges.
+
+## Pull requests as a triage surface
+
+**PRs as a request surface: no.** _(Set to `yes` if this repo treats external
+PRs as feature requests; `/triage` reads this flag.)_
+
+When set to `yes`, external PRs run through the same status labels as issues:
+read them with `issue read --issue <number> --comments`, label with
+`issue set-status`, and triage contributor PRs (not owner/maintainer work)
+through `/triage`.
+
+## When a skill says "publish to the issue tracker"
+
+Create a Gitea issue with `issue create`, then place it explicitly: group
+implementation work under a delivery epic (children linked with
+`epic add-dependency --parent <epic> --child <child>`, the legacy alias of
+`prerequisite add --issue <epic> --requires <child>`, and ordered in the epic's
+`## Child Issues In Priority Order` section) and insert only the epic — or an
+explicitly standalone issue — into the roadmap with `queue insert`. Creation
+and placement stay two separate, reconcilable operations; when the user gave
+no priority, apply the default-placement rule from that contract and say so
+with the proposal, and publish unqueued only when placement is genuinely
+unresolved.
+
+## When a skill says "fetch the relevant ticket"
+
+Run `issue read --issue <number> --comments`.
+
+## Wayfinding operations
+
+Used by `/wayfinder`. The **map** is a single issue labelled `wayfinder:map`;
+its **child tickets** are plain issues that block the map.
+
+- **Map**: `issue create --title "..." --label wayfinder:map` holding the Notes / Decisions-so-far / Fog body.
+- **Child ticket**: an issue labelled `wayfinder:<type>` (`research`/`prototype`/`grilling`/`task`) with `Part of #<map>` at the top of its body, linked to the map with `prerequisite add --issue <map> --requires <n>` (the map waits for each ticket).
+- **Blocking**: Gitea dependency links — the map is blocked by every child. `issue read` reports open blockers, which are the live gate.
+- **Frontier query**: `issue list --state open --label wayfinder:map`-scoped children (list open issues, keep those mentioning `Part of #<map>`), drop any with an open blocker or `status/in-progress`; first in map order wins.
+- **Claim**: move the ticket to `status/in-progress` with `issue set-status`.
+- **Resolve**: `issue comment --issue <n> --body "<answer>"`, then use `issue close --issue <n> --status status/done --comment "Decision accepted; see the resolution comment."` for an explicitly authorized accepted decision; use `status/wontfix` for declined work and `pr cleanup` for PR-backed implementation. Gist the decision into the map's Decisions-so-far.
diff --git a/docs/agents/issue-workflow.toml b/docs/agents/issue-workflow.toml
new file mode 100644
index 0000000..0c1b8b8
--- /dev/null
+++ b/docs/agents/issue-workflow.toml
@@ -0,0 +1,8 @@
+# The relationship mode and the one authoritative priority source, read by the
+# gitea-issues helpers from the default branch. Change it only through a
+# reviewed commit: activation, rollback, and source changes are migrations.
+relationship_mode = "legacy"
+
+[priority_source]
+kind = "roadmap"
+issue = 2
diff --git a/docs/agents/queue.md b/docs/agents/queue.md
new file mode 100644
index 0000000..bdaf2ed
--- /dev/null
+++ b/docs/agents/queue.md
@@ -0,0 +1,104 @@
+# Work Queue
+
+How this repository decides what is next. The contract in one paragraph: exactly
+one open issue labelled `type/roadmap` carries a `## Work Queue In Priority
+Order` section; that order — with epic `## Child Issues In Priority Order`
+sections beneath it — is repository priority. Dependency links gate execution;
+status labels gate readiness. Neither ever overrides the written order. The
+queue tree carries one invariant — every open issue except the roadmap itself
+sits on exactly one priority list and blocks that parent — specified in full
+in the gitea-issues `references/repository-queue.md` reference. Every open
+direct child of the roadmap — epic or standalone entry — blocks the roadmap,
+one edge per direct child and never edges to the whole backlog, so the Gitea
+UI **Blocks** section links each level of the tree to the root.
+
+Priority lists use `- [ ] #123 Title` and `- [x] #123 Title`. Physical order
+sets priority; the checkbox is a progress display. A checked entry represents
+a closed issue with `status/done`, including an epic accepted and closed
+separately. `status/wontfix` and historical closed issues without
+`status/done` stay unchecked. `queue inspect` reports disagreements; clicks
+never change readiness, closure, or prerequisites. Convert numbered lists
+through reviewed `checklist preview` and guarded `checklist apply`.
+
+## Reading the queue
+
+- **Health and explanations**: `queue inspect` — status counts, skipped
+  entries, unqueued ready work, tree-invariant violations, structural
+  anomalies.
+- **Placement and reconciliation**: `queue roadmap` — targeted top-level order
+  and current `content_version`, without dependency scans.
+- **What is next**: `queue next` — read-only selection of the highest-priority
+  executable leaf, with every higher-ranked skip explained.
+
+Both are read-only. Inspecting never claims anything; claim separately with
+`issue start --issue <number>`, which creates the `ISSUE-<number>` worktree and
+moves the issue to `status/in-progress`.
+
+## Changing the queue
+
+Queue edits are explicit mutations, never side effects of other work:
+
+- `queue init` — create the canonical roadmap if absent (idempotent).
+- `queue insert --issue <n> --position <p> --expected-content-version <v>` —
+  add a top-level epic, or a standalone issue with `--allow-standalone`.
+  Inserting an open entry — epic or standalone — also links it as blocking
+  the roadmap (reported separately from the body write).
+- `queue reorder --issue <n> ... --expected-content-version <v>` — rewrite the
+  top-level order, naming every current entry exactly once.
+- `queue link-children preview` / `apply --confirm` — classify and repair the
+  direct-child blocking edges to the roadmap (read-only preview; confirmed
+  apply creates exactly the missing edges, streaming `[queue]` progress
+  milestones with the terminal summary and exit status authoritative).
+
+Mutations send the optimistic-locking `content_version` printed by `queue roadmap`.
+On any ambiguous result, re-run `queue roadmap` and reconcile before retrying;
+never blindly re-run a mutation.
+
+## Adopting existing epics
+
+Epics created before this contract may carry legacy child-order sections.
+`epic migrate-children preview` inventories them read-only and classifies each
+open epic; the owner confirms each proposed migration, and
+`epic migrate-children apply --epic <n> --expected-content-version <v>`
+rewrites one epic at a time under the queue contract's rules. Ambiguous epics
+go back to the owner with their diagnostics. The gitea-issues
+`references/repository-queue.md` reference documents the full contract.
+
+## Moving to independent mode
+
+In `legacy` mode, which this document describes, a native edge may mean
+containment, navigation, or a prerequisite. A repository moves to
+`independent` mode — edges mean prerequisites only — through a reviewed
+migration, never a setup rerun: `migration preview --history --write-plan <file>` classifies every
+edge read-only, the owner reviews the plan, `migration freeze` makes every
+roadmap-driven helper fail closed, `migration apply --plan <file>` removes
+only the projection edges the evidence proves and writes each placed
+issue's `Parent:` line, `migration readiness` confirms nothing blocks, and a
+reviewed commit of `relationship_mode = "independent"` activates it. The
+gitea-issues `references/repository-queue.md` reference documents recovery
+and rollback.
+
+## Who enters the roadmap
+
+Only two kinds of issue: a top-level delivery epic, and an explicitly
+standalone actionable issue. Epic children never enter the roadmap — they stay
+in the epic's child-priority list plus dependency links, under the
+queue-tree invariant stated above.
+
+## Default placement for new issues
+
+Newly published work with no priority statement from the user enters at the
+default position — the highest its dependencies allow, per the default rule
+in the gitea-issues `references/create-and-organize.md` queue-placement
+contract; an explicit statement from the user always wins. Creation and
+placement remain two explicit, reconcilable operations either way, and
+genuinely unresolved placement still publishes unqueued and stays visible
+under "Unqueued ready work".
+
+## After reviewed work merges
+
+`pr cleanup` merges reviewed work and reconciles its issue. Continuation then
+recommends exactly one follow-up, in order: newly unblocked dependents, the
+current epic's next executable child, the roadmap's next executable leaf, or an
+explicit blocked/empty result. Recommendations only — starting the next issue
+needs its own authorization.
diff --git a/docs/agents/standards.md b/docs/agents/standards.md
new file mode 100644
index 0000000..8823d65
--- /dev/null
+++ b/docs/agents/standards.md
@@ -0,0 +1,146 @@
+# Working Standards
+
+The philosophies every session in this repository works under. The
+`## Agent skills` block in the agent instructions carries the one-line rules;
+this document is the authority behind them and is safe to extend per repo.
+
+## Documentation and tests are first-class artifacts
+
+Code may be replaced, but durable decisions, behavior, and lessons must remain
+recoverable from focused documentation and verification artifacts. A future
+agent with no conversation history should be able to determine:
+
+- what the system currently does;
+- which behavior is only proposed, not implemented;
+- why important architectural decisions were made, and which observations
+  informed the foundational ones (`docs/evidence/`);
+- how to verify implemented behavior;
+- which earlier approaches are retained only for context (`docs/historical/`).
+
+## Documents versus the issue tracker
+
+The issue tracker is the queue for actionable work and holds the transient
+working context of one change; repository documents are the durable memory. A
+closed issue thread is not a supported reference for current behavior. When an
+issue resolves a term or a decision, record it in `CONTEXT.md` or an ADR
+rather than leaving it only in the thread; an idea too valuable to lose and
+not actionable enough to be an issue belongs in the domain documents, not in
+an issue comment.
+
+Before addressing an issue, read the issue with its comments, every other
+issue in its epic, and the issues in related epics. Confirm scope, boundaries,
+and dependencies before planning.
+
+## Writing current-truth documents
+
+`CONTEXT.md` and the ADRs describe what the system does, in present tense, as
+a contract — not a narrative of the change that produced them.
+
+- Test every sentence carrying an issue reference by deleting the number: if
+  the sentence stays true, the reference was decoration and goes; if it stops
+  making sense, rewrite it as a statement of current behavior. ADRs keep
+  their references — they are decision records.
+- ADRs are immutable. Never rewrite a decided ADR; mark it superseded and
+  record the replacement decision in a new ADR that links back.
+- State uncertainty explicitly, and label proposed behavior as proposed.
+- When verified behavior lands, reconcile `CONTEXT.md` and the ADRs in the
+  same iteration. Never document behavior that does not exist yet.
+
+## Historical records
+
+`docs/historical/` holds superseded designs, archived handoffs, and
+development records. Use it to understand how the project arrived at its
+current state; never treat it as current behavior. When reconciling
+documents after verified behavior lands, move superseded context that still
+explains decisions or discarded alternatives to `docs/historical/` rather
+than deleting it. Decisions themselves supersede through the ADR mechanism,
+not by moving.
+
+## Design evidence and issue history
+
+Choose a record's destination by its purpose, not its format, rigor, or size:
+
+- `docs/evidence/` holds only curated observations that materially inform a
+  named foundational product-design decision and stay useful after the
+  implementation issue is forgotten. Its `README.md` carries the admission
+  rule, examples, and a lightweight record shape.
+- `docs/historical/issue-notes/<issue-number>/` holds durable records of one
+  issue's work — test runs, review findings, debugging chronology, shakedown
+  or replay reports, handoffs — created only when worth retaining.
+- The pull request or issue holds issue-specific verification that needs no
+  repository archive.
+
+The ADR or authoritative document keeps the decision and its concise
+rationale and may link supporting evidence. Evidence never declares current
+behavior, and issue notes are history, never current truth. A routine change
+needs no new document, directory, or evidence record; an ADR link alone does
+not make verification qualify as evidence.
+
+## Documentation disposition
+
+The implementing session records one documentation disposition on the issue
+or pull request before completion — in an issue comment on trackers without a
+pull-request template. On Gitea, `/cleanup` blocks the merge without one.
+
+`CONTEXT.md` and ADRs are created lazily (see `docs/agents/domain.md`): a
+change that resolves no new term or decision records `not_required` rather
+than forcing a document into existence.
+
+- **updated** — verified behavior was reconciled into `CONTEXT.md` and the
+  ADRs as present-tense contracts;
+- **not_required** — the change made no durable behavioral or architectural
+  difference; say why in one line;
+- **deferred** — documentation work remains; normal completion waits unless
+  the owner explicitly accepts the deferral;
+- **blocked** — documentation cannot be reconciled because implementation or
+  verification evidence is insufficient.
+
+## Build discipline
+
+Tests are part of the specification. Write the failing test first at the
+spec's pre-agreed seams and make it green with the minimal change — red
+before green, one seam, one test per cycle. Test-after is reserved for glue
+and wiring, UI verified by a manual test plan, and throwaway prototypes.
+
+## Verification cadence
+
+During implementation and review follow-ups, run the focused checks for the
+changed areas and their immediate contracts or consumers, on the exact
+current head. A later code, test, configuration, or documentation change
+invalidates the affected evidence and requires those checks again.
+
+Reserve the complete gate declared as the epic gate for the final integrated
+epic commit, before epic acceptance and closure. Existing successful CI
+satisfies it only when bound to that exact commit. Run a repository-wide
+suite earlier only when explicitly requested, when a failure cannot be
+localized, or when a change to shared test infrastructure, root
+configuration, or a foundational contract has an unbounded blast radius — and
+state the reason before starting it.
+
+Do not delete, weaken, skip, or consolidate tests solely to reduce runtime.
+Pruning is legitimate only with evidence that the coverage is obsolete or
+redundant, the behavior preserved at the lowest faithful layer, and the
+verification documentation updated.
+When automated coverage is not practical for an enduring contract, record a
+repeatable manual procedure and its expected result beside that contract.
+
+## Merge evidence
+
+Every pull request carries the evidence that caused it to be merged, recorded
+before the merge: screenshots for a visible interface, brief command output
+for command-line behavior, the focused checks that passed and the exact head
+they ran against when the effect is not observable through any interface.
+Attribute a reported observation to whoever made it rather than presenting it
+as independently verified, and never attach evidence that was not examined.
+An unrecorded verification did not happen. Merge evidence lives on the pull
+request (or under `docs/historical/issue-notes/<issue-number>/` when worth
+retaining); it is not a `docs/evidence/` record.
+
+## Commands given to the user
+
+A command presented as runnable must be ready to run as written — no
+unresolved placeholder such as `/absolute/path/to/...`, `<your-token>`, or an
+unassigned `$VALUE`. When a value cannot be known while drafting, give the
+exact command that discovers it, then the command that consumes it, and say
+how to substitute the result. Use the repository's documented shell where it
+declares one; otherwise prefer POSIX-compatible syntax.
diff --git a/docs/evidence/README.md b/docs/evidence/README.md
new file mode 100644
index 0000000..e3388a8
--- /dev/null
+++ b/docs/evidence/README.md
@@ -0,0 +1,104 @@
+# Design Evidence
+
+This directory holds curated observations and analyses that materially inform
+a named, **foundational** product-design decision: a durable choice about
+product behavior, architecture, boundaries, core methodology, or a constraint
+that shapes the product across individual implementation issues.
+
+It is not an archive. Most changes add nothing here, and completing an issue
+never requires an entry.
+
+## Admission
+
+Ask: **would a future maintainer need this record to understand, challenge, or
+revisit a foundational product choice after forgetting the implementation
+issue?** If the record's value is only establishing that one change passed its
+checks, or describing how work proceeded, it belongs with the issue instead.
+
+A qualifying record explains:
+
+- which foundational decision or documented design question it informs;
+- what observations bear on the alternatives or constraints, and how;
+- why those observations stay useful beyond the issue that produced them.
+
+Purpose decides, not format, rigor, or size. A rigorous measurement, a passing
+test suite, or a link to an ADR does not qualify a record on its own, and an
+ADR is never created just to give routine verification somewhere to point.
+
+## Where material goes
+
+| Material | Destination |
+| --- | --- |
+| Current product design, contracts, and constraints | `docs/authoritative/`, per `docs/agents/domain.md` |
+| A decision and its concise rationale, including meaningful trade-offs | `docs/authoritative/adr/` |
+| Curated observations materially informing a foundational design choice | `docs/evidence/` |
+| Durable records of one issue's work: test runs, review findings, debugging chronology, shakedown or replay reports, handoffs | `docs/historical/issue-notes/<issue-number>/` |
+| Issue-specific verification that needs no repository archive | the pull request or issue body and comments |
+
+`<issue-number>` is the tracker's issue number: issue 186's retained records
+live below `docs/historical/issue-notes/186/`. Create that directory only when
+something is worth retaining.
+
+The ADR or authoritative document keeps the "why"; it links here when a
+supporting record helps. Evidence informs a decision — it never declares
+current behavior or silently overrides the authoritative document. Issue notes
+are history, never current truth.
+
+## Examples
+
+Qualifies:
+
+- An evaluation of methodology alternatives behind the product's durable
+  grading contract or experimental design.
+- A data-quality study that establishes a foundational dataset-selection or
+  exclusion policy.
+- Accuracy, latency, and resource measurements that explain a core
+  model-serving architecture choice.
+- A failed experiment or contradictory observation that materially informs such
+  a decision, or explains why a serious alternative was rejected.
+
+Does not qualify:
+
+- "Issue 186 passed 260 tests", CI output, coverage summaries, or merge receipts.
+- One patch's replay results, admission or qualification receipts, debugging
+  logs, an implementation chronology, or an agent handoff.
+- A benchmark run, literature collection, or research note with no demonstrated
+  connection to a foundational product-design decision.
+
+Mixed purpose: when issue work reveals a foundational insight, leave the
+original verification and history where they are, and write a focused
+synthesis here that states the design implication and links to those sources.
+Do not promote the whole issue diary or duplicate its raw artifacts.
+
+## Record shape
+
+Keep only the provenance that helps someone assess the design implication.
+Name files by topic or decision (`serving-latency-trade-offs.md`), not by issue
+or test run. There is no required schema; a record usually covers:
+
+```md
+# Serving latency trade-offs
+
+Informs: the model-serving architecture (link the ADR or design document).
+Date and identities: 2026-03-02; code a1b2c3d, dataset v4, model m-7.
+
+## Observations
+
+What was measured or seen, how, and from which source. Keep large raw
+artifacts in their artifact store and reference them by stable location and
+hash.
+
+## Interpretation
+
+What the observations suggest for the alternatives, kept separate from the
+observations themselves. Include counterevidence.
+
+## Limitations and implications
+
+What the evidence cannot show, and what it means for the design.
+```
+
+When a later decision changes the picture, add a linked correction or
+superseding analysis rather than rewriting the old result, so its historical
+qualifications stay visible. Records need not endorse the currently accepted
+choice, but each must stay meaningfully connected to a foundational decision.