# `/kk:model` — archaeology reading method

How phase 3 reads domain source. The method exists because unordered reading produces a term inventory; ordered reading produces the facts a kit needs — what is enforced, what merely declared, and what silently assumed.

## Scope — model in service of the decision

The forcing question from intake bounds the read. Start from the entry points the question names (the feature's handlers, the ticket's modules) and follow references outward only while they bear on the question. A file the decision never touches is out of scope no matter how interesting — breadth is the ocean-boiling failure the forcing question exists to prevent. If mid-read the question turns out to stress a module outside the original scope, widen deliberately and say so; never widen by drift.

## Reading order — state → time → invariants

Three passes over the scoped source, each asking one kind of question. Keep them separate: mixing them is how a reader confirms structure while missing behavior.

1. **State.** What are the domain's states and transitions — and which are **actually enforced** versus merely declared? A status enum declares states; only the code that guards a transition enforces one. Record where each state lives (field, constant, collection) and, for every declared rule, whether any code path enforces it. Declared-but-unenforced is a finding, not a detail — it is traps-page material.
2. **Time.** Where does time enter the lifecycle? Timestamps, expiries, schedules, auto-transitions, background sweeps. For each: what fires it, and what it mutates. Time-driven mutations are where states drift out from under readers — a transition no user action triggers is exactly the kind of fact no single file reveals.
3. **Invariants.** What does the system silently assume? Uniqueness, cardinality, ordering, non-overlap, "exactly one result". For each assumption: is it enforced at the write path, or merely expected at the read path? Focus on the assumptions the forcing question stresses. This pass seeds phase 5's open-question checklist — an assumption noticed here and confirmed nowhere is a question, not a fact.

## Two-clock discipline

Every fact recorded from archaeology sits on one of two clocks, and the working notes say which:

- **Code clock** — what the code verifiably does. Citable to a file or symbol (never a line number); `/kk:review-architecture` can re-check it mechanically.
- **Business clock** — what the business *means*. Never derivable from code alone: code establishes code-clock facts only. Intent reverse-engineered from code — "this limit exists, so the business must want it" — is a **presumption**, recorded as `proposed` until a human with domain authority ratifies it (F3). The presumption is honest; presenting it as settled intent is the failure.

A code fact never ratifies a business intent. When the two clocks disagree — the code does X, a stated rule says Y — that disagreement is a divergence for the traps page and usually a decision-queue question, not something to reconcile silently in either direction.

# `/kk:model` — kit output contract

The **domain-reference kit** is the only durable artifact `/kk:model` produces. This file is the authoritative format for it (design §3). The drafting phase (process phase 4) writes to this contract; the conventions-bind-author self-check (phase 6) grades the produced pages against it.

The contract is deliberately small: **two durable pages per bounded context, plus one conventions index per home.** Everything else a modelling run might be tempted to emit — scoped diagrams, delta models, ERDs, logical/physical model pages — is disposable and is *not* produced (see §Kit-scope pushback).

The example fragments below use a **library-lending** domain purely to show shape. They are illustrations, not a template to clone — a real kit's terms come from the archaeology, never from this file.

---

## The two pages

Per bounded context, produce exactly two pages that live side by side in the home:

| Page | File | Carries | Audience |
| --- | --- | --- | --- |
| Glossary | `<context>.md` | the concepts, their bindings to code, and the business rules | product (definitions) + engineering (bindings) |
| Divergences & traps | `<context>-traps.md` | only facts **no single file reveals** — code-vs-rule divergences and cross-file hazards | engineering |

The two are one composite artifact: the glossary's rules table points at the traps page's `D#`/`P#` entries, so the pages are authored, reviewed, and re-verified together. `/kk:review-architecture` accepts either page's path and auto-discovers the sibling.

---

## Glossary page — `<context>.md`

### 1. Summary + one conceptual-altitude diagram

A short prose summary of the context, then **exactly one** diagram at **conceptual altitude**: entities, the relationships between them, and only the **load-bearing** attributes — the shape of the domain, not a field dump. Text-based (Mermaid or equivalent) so it diffs and re-verifies.

One diagram, not many. A field-level ERD is a schema mirror (see §Kit-scope pushback) and is wrong by default — the code is the schema reference.

```mermaid
erDiagram
    PATRON ||--o{ LOAN : holds
    TITLE  ||--o{ LOAN : "lent as"
    TITLE  ||--o{ HOLD : "reserved via"
```

*(Load-bearing shape only — a `Loan` belongs to one `Patron` and one `Title`; a `Hold` queues against a `Title`. No `created_at`, no surrogate keys, no field dump.)*

### 2. Business rules — numbered table with provenance banner

Fold the domain's rules into a compact numbered table (`L1…Ln`). Head it with a **provenance banner** stating that any rule reverse-engineered from code is a **presumption of intent, `proposed` until a human ratifies it** (F3 — code establishes code-clock facts only; intent derived from code is a presumption). Each rule's *enforcement pointer* (where the rule lives in code) is a binding the reviewer can check; the rule's *intent-truth* is exactly what stays `proposed`.

> **Provenance:** Rules below are reverse-engineered from code unless a source is cited. Reverse-engineered rules are **presumptions of intent — `proposed` until ratified by a product owner.** Code confirms what the code does, never what the business meant.

| # | Rule | Status | Enforced at |
| --- | --- | --- | --- |
| L1 | A patron may hold at most 5 concurrent loans. | proposed | `loans/policy.go` `maxConcurrent` |
| L2 | A title with an active hold queue cannot be renewed. | proposed | see traps `D2` — declared, not enforced |

### 3. Per-term entries — dual-audience fields

One entry per concept. Every entry carries these fields (omit a field only when genuinely empty):

- **Definition** — for product; the **business clock**. What the concept *means* to the business.
- **Bindings** — for engineering; the **code clock**. Where the concept lives: directory, collection/constant, field, symbol. **Cite file or symbol — never line numbers** (lines rot before they are read).
- **Status** — one marker (see below).
- **Aliases** — other names the same concept goes by.
- **Not to be confused with** — the near-neighbor concept it is routinely conflated with.
- **Notes** — anything else load-bearing. A note citing a ticket **must state what retires it** (see ticket-note discipline).

```markdown
### Hold

- **Definition:** A patron's reservation of a title that is currently on loan; grants borrowing priority when the title returns.
- **Bindings:** `holds/` · collection `holds` · `Hold.QueuePosition` · `holds/queue.go`
- **Status:** canonical
- **Aliases:** reservation (UI), queue entry (legacy code)
- **Not to be confused with:** Loan (a Hold has no due date and confers no possession).
- **Notes:** Priority tie-break is undecided — see decision queue RQ-3.
```

*(This entry is shown as `canonical` only because the library domain it illustrates has been through ratification. A first greenfield run has no ratification, so every reverse-engineered term defaults to `proposed` — see §4. Do not copy the `canonical` marker from this format illustration.)*

### 4. Status markers

Exactly one per term:

| Marker | Meaning |
| --- | --- |
| `canonical` | Ratified by a human with authority over the domain. |
| `proposed` | Author's best reading; awaiting ratification. **Default for anything reverse-engineered from code.** |
| `undecided` | The domain itself has not settled this; belongs in the decision queue. |
| `deprecated-alias` | A name kept for recognition; points at the canonical term. |
| `overloaded` | One name carrying two meanings; the entry disambiguates them. |

`/kk:model` **never flips `proposed → canonical` on its own** — that requires a recorded human decision (out of scope until `decide`, M2.1). In brownfield mode, existing markers are never changed unilaterally.

### 5. Derived-from footer

End the page with a **Derived-from footer** listing **every path a recorded domain fact derives from** — no line numbers, files and symbols only. This is what makes each binding re-checkable at its source and what `/kk:review-architecture` re-verifies for freshness.

```markdown
---
**Derived-from:** `loans/policy.go` · `holds/queue.go` · `titles/catalog.go` · `holds/` · ticket LIB-214
```

### Ticket-note retirement discipline

Any note that cites a ticket (`"pending LIB-214"`) **states the condition that retires the note** — what ships, what decision lands, what makes the note obsolete. A durable page accumulating live ticket references rots as those tickets ship: the note lingers, asserting a condition that is no longer true. If you cannot state what retires it, it is not a durable note — it belongs in the decision queue.

### Term-count guideline

**Typically 10–20 terms for a first greenfield slice — a guideline, not a requirement.** The real count is set by the **forcing question** (model only what the decision needs), the **mode** (a brownfield delta may touch two terms), and **feature scope**. A run that emits 40 terms for a three-term decision has boiled the ocean; a run that emits three for a domain the decision spans has under-modelled. Let the decision, not the number, set the count.

---

## Divergences & traps page — `<context>-traps.md`

Records **only facts no single file reveals** — the value a reader cannot get by opening one file:

- **`D#` — divergences.** Where the code diverges from a stated rule (a declared rule that nothing enforces; an enforced behavior no rule describes).
- **`P#` — cross-file hazards.** Traps that only appear when two or more files are read together (a single-result lookup over data written without a uniqueness guarantee; a silent default in one module that another module relies on).

Rules:

- **Stable numbering.** `D#`/`P#` numbers are permanent; a retired entry's number is **never reused** (so cross-references from the glossary rules table stay valid).
- **Never a schema mirror.** The code is the schema reference. A page that restates field lists or table structures is wrong by default — it drifts the moment the schema changes and adds no fact the code doesn't already carry.
- **Self-limiting staleness.** Each entry describes a divergence that *should be fixed*. When the divergence is fixed, **delete the entry in that same PR.** An entry outlives its divergence only if someone forgets — so the entry names the fix that kills it.

```markdown
### D2 — Renewal-during-hold rule declared but unenforced

Rule L2 says a title with an active hold queue cannot be renewed. `loans/renew.go`
checks due dates and loan caps but never consults `holds`. The rule is intent; the
code does not implement it.

**Retires when:** `renew.go` gains a hold-queue check, or L2 is withdrawn.
```

---

## Conventions index — once per home (`index.md`)

Written **once per home, not per context.** The **home** is the durable-docs root the kit pages live in (e.g. `docs/architecture/`, or a knowledge repo's domain-reference directory); every `<context>.md` / `<context>-traps.md` pair in that home reads under one shared contract. The index declares, so no kit page has to restate them:

- the per-term entry fields (Definition / Bindings / Status / Aliases / Not to be confused with / Notes);
- the status markers and their meanings;
- the **two-clock rule** — Definitions track the business clock; Bindings track the code clock; a code fact never ratifies a business intent;
- the citation rules — file or symbol, **never line numbers**;
- the freshness model (below).

If the home already has an `index.md`, do not rewrite it — the current context's pages conform to the existing index. Only a new home gets a new index.

---

## Freshness banner

Every produced page (glossary and traps) carries a banner stating both facts:

> **Freshness:** This page is `proposed` until reviewed by a human other than its author — it is **not** self-certified (F7). Check staleness by re-running `/kk:review-architecture` against the Derived-from anchors at consumption time; freshness is a skill run, not a standing promise.

The two halves matter independently: (a) **no self-certification** — the author marking their own page "verified/trusted" is exactly the failure this guards against; (b) the freshness mechanism is a **re-verification run**, not a maintenance social contract (cross-repo reviewer obligations were field-falsified — near-zero adoption).

---

## Homes-resolution precedence

The skill is **home-agnostic** and resolves where to write in this order:

1. **Brownfield** — wherever the existing kit already lives. Never relocate it.
2. **A user-declared home** — covers cross-repo domains kept in a dedicated knowledge repo. Use it as given.
3. **Default** — propose `docs/architecture/` as the single-repo default home (kit pages as `<context>.md` / `<context>-traps.md` directly in it) **and confirm with the user before writing.**

The org picks the home; the skill asks, never assumes.

---

## Kit-scope pushback — everything else is disposable

The kit is the *only* durable artifact. Scoped diagrams, delta models, ERDs, and standing logical/physical model pages are **drawn per-feature inside design docs and thrown away** — they are not kit pages.

When asked to produce one as a durable artifact, **push back before complying**: name the maintenance cost (a standing physical/ERD page is a copy of the schema that is wrong by default and drifts every migration), and offer the durable alternative (the conceptual-altitude glossary diagram) or a disposable per-feature diagram inside the relevant design doc. Comply only after the user has heard the cost — do not silently emit a durable schema mirror.

---

## Conventions-bind-author self-check (phase 6)

Before surfacing, grade the produced pages against this contract — the author obeys the kit's own conventions (F6):

- [ ] Every intent claim reverse-engineered from code is `proposed`, not `canonical`.
- [ ] No line numbers anywhere — citations are file or symbol only.
- [ ] Derived-from footer present and lists **every** path a recorded fact derives from (a file that contributed no domain fact — e.g. a bare `go.mod` — is not required).
- [ ] **Exactly one** diagram on the glossary page, at conceptual altitude.
- [ ] Traps page contains **no schema mirror**; every entry names what retires it.
- [ ] Every ticket-citing note states its retirement condition.
- [ ] Provenance banner present on the rules table; freshness banner on both pages.
- [ ] Status markers present and justified; no unilateral `proposed → canonical` flip.

# `/kk:model` — production workflow

The authoritative seven-phase workflow. SKILL.md carries the one-line phase summary; this file carries the full procedure. Phases run **strictly in order** — each phase exists to prevent a recorded field failure (the F-numbers cited below; each guard file opens with its failure), and reordering re-creates the failure the order prevents.

Phases 1–2 touch no domain code. Phase 3 is the single point where domain source is read — the content-read step appears exactly once, there. Phases 4–7 work from what phases 2–3 harvested; they re-open sources to check claims, never to widen scope.

## Phase 1 — Scope intake

Establish three things, in conversation with the user where the request leaves them open:

1. **The bounded context.** The domain slice being modelled — one kit (glossary + traps pair) serves one context. If the request spans several contexts, pick the one the forcing question lives in and say so.
2. **The forcing question.** The feature, ticket, or decision that makes modelling worth doing *now*. It bounds everything downstream: what archaeology reads, how many terms the glossary carries, which questions reach the decision queue. Model in service of the decision — a run with no forcing question boils the ocean, and an ocean-boiling model is sophistication nobody asked for. If the user names none, ask for one before proceeding.
3. **The mode.**
   - **Greenfield** — no kit exists for this context. Produce the initial two pages (+ the conventions index if the home has none), per [kit-contract.md](kit-contract.md).
   - **Brownfield** — an existing kit is found (check the homes in [kit-contract.md](kit-contract.md) §Homes-resolution precedence) or pointed at. Follow §Brownfield intake below.

### Brownfield intake

The existing kit is the **baseline**; the run updates it, never replaces it.

1. **Read the kit in full first** — glossary page, traps page, and the home's conventions index — before phase 2 runs. This is baseline-loading, not domain reading; phase 3 remains the run's only domain-source read. A delta computed against a half-read baseline is a rewrite wearing a delta's name.
2. **Every change is a delta.** The baseline's structure is the frame: entries the drift does not touch stay as they are, `D#`/`P#` numbers are never reset or reused, and the home's conventions index is never rewritten — the updated pages conform to it. If the baseline conflicts with [kit-contract.md](kit-contract.md), raise the conflict with the user; do not silently reformat.
3. **Status markers are never flipped unilaterally.** In particular, discovering that code **now enforces** a `proposed` rule updates the rule's *enforcement pointer*, not its status — enforcement is a code-clock fact, and `canonical` records a human ratification no code change can substitute for (F3). `proposed → canonical` requires a recorded human decision, out of this skill's scope.

Close intake with the capy knowledge search per [shared-capy-knowledge-protocol.md](shared-capy-knowledge-protocol.md): query `kk:arch-decisions` and `kk:project-conventions` for prior modelling decisions and conventions in this area. Empty results are normal; contradicting results are raised with the user before proceeding.

## Phase 2 — Requirements-harvesting gate (F1)

Run [shared-requirements-harvesting.md](shared-requirements-harvesting.md) in full before any modelling:

- Enumerate every ticket, issue, spec, or document the request names, plus **one hop** of references out from each.
- Read them and **quote the actual asks verbatim** into the working notes, attributed to their source (ticket id, author, stakeholder). Paraphrase is where an invented brief creeps back in.
- Fabricated input only as a labeled last resort when a search has confirmed no real input exists — labeled at the point of use, naming the real input that would replace it.

The quoted asks are the spine the rest of the run hangs on: archaeology reads what the asks stress, the kit models what the asks need, and the decision queue routes what the asks leave open.

## Phase 3 — Archaeology

Read the domain source per [archaeology.md](archaeology.md): the **state → time → invariants** order, under **two-clock discipline** (code-clock facts are verifiable and citable; intent derived from code is a presumption that stays `proposed`), scoped by the forcing question. This is the run's only subject-matter reading step.

Working notes from this phase record, for every fact: the file/symbol it derives from (no line numbers), and which clock it sits on.

## Phase 4 — Draft the kit

Draft per [kit-contract.md](kit-contract.md) — it is the complete format authority:

- Resolve the **home** first, per the contract's precedence (brownfield location → user-declared home → propose `docs/architecture/` and **confirm before writing**).
- Produce the glossary page and the divergences/traps page; add the conventions index only if the home has none.
- Anything beyond the two pages (durable ERDs, standing model pages) triggers the contract's **kit-scope pushback** — name the maintenance cost before complying.

## Phase 5 — Verify (F4)

Two distinct passes, per [shared-open-question-pass.md](shared-open-question-pass.md):

1. **Confirm-pass** — re-check every drafted claim against its cited source. Catches drift and staleness; cannot catch omissions.
2. **Open-question pass** — re-walk the same sources asking **new questions**, with the confirm-pass results out of view: cardinalities, single-result lookups, unchecked writes, silent defaults, time and ordering. Anything surfaced that is not already a written claim is a finding — record it as a new claim, a traps entry, or a decision-queue question. Never discard it.

## Phase 6 — Conventions-bind-author self-check (F6)

Grade the produced pages against the checklist in [kit-contract.md](kit-contract.md) §Conventions-bind-author self-check — the author obeys the kit's own declared conventions (status markers justified, no line numbers, Derived-from complete, exactly one diagram, no schema mirror, ticket notes carry retirement conditions, both banners present). Fix violations before surfacing; a kit that breaks its own contract is not done.

## Phase 7 — Surface & close (F5, F2)

1. **Present the decision queue.** Each entry (RQ) is one **precise, decidable question** tagged with the **role** that can decide it — product owner, developer, stakeholder, customer — plus the person or ticket if known, and what the answer unblocks. Precise-and-decidable is the bar: a role holder reading the RQ can answer it in a sentence.

   > **RQ-1** — Does a hold expire if the patron never collects, and after how many days? — **Decider:** product owner — **Unblocks:** rule L4, term `Hold`.

   The queue is presented inline, and **appended to the active feature's `docs/feat/wip/<feature>/design.md` under an "Open Questions" heading when that feature directory exists** (inline-only otherwise).
2. **Apply the contact-ratio guard** per [shared-contact-ratio-guard.md](shared-contact-ratio-guard.md): if this run brings the artifact-to-stakeholder-contact ratio to N:0, state plainly that the next unit of progress is a conversation, name the role (and person/ticket if known), and route the decision queue to them instead of producing more.
3. **Brownfield only — fact-flip propagation** per [shared-fact-flip-propagation.md](shared-fact-flip-propagation.md): any recorded fact this run contradicted is fixed at **every** occurrence across the workspace in this same session, not just where it was noticed. The usual shapes of a contradicted fact in a kit update:
   - **A stale binding** — the symbol a kit entry cites was renamed or moved. Fix every page that asserts the old name: entry Bindings, traps-page prose, the rules table — a rename fixed in the glossary but still asserted on the traps page is F2 verbatim.
   - **A vanished enforcement** — code a rule's pointer cites no longer exists. Correct the pointer (declared-not-enforced, or a new `D#`), drop the path from the Derived-from footer, and route the question of whether the removal was deliberate to the decision queue — never silently drop the rule.
   - **A met retirement condition** — the divergence a traps entry describes has been fixed. Delete the entry in this update (self-limiting staleness), never reuse its number, and update the rule row that pointed at it.
4. **Index the rationale.** Per [shared-capy-knowledge-protocol.md](shared-capy-knowledge-protocol.md), index non-obvious modelling rationale (why a term was scoped this way, why a status is `undecided`) to `kk:arch-decisions`. Skip anything self-evident from the kit pages themselves.

---
name: model
description: |
  Produce or update a domain-reference kit — the durable glossary + divergences/traps pages for a bounded context. Use for domain modelling, information architecture, building a domain glossary or domain model, mapping domain concepts to code (bindings), or surfacing the decidable questions stakeholders must close before design. Runs upstream of feature /kk:design as the first producer of the architecture flow, and emits artifacts /kk:review-architecture verifies. Triggers: "model the domain", "build a glossary", "domain reference", "bounded context", "what are the concepts here". NOT for behavioral code review or writing a feature design doc.
---

# Domain Modelling — the steady-state kit

**Goal: produce a provenance-clean domain-reference kit and, above all, a decision queue of precise, role-tagged questions a human can close.** The queue is the primary output — artifact count and model sophistication are explicitly not the metric.

`/kk:model` is the first **producer** of the architecture flow: it runs at information-architecture altitude (what the domain's concepts are, where they bind to code, and which questions about them only a human can close), upstream of feature `/kk:design` and never called by it. It writes files and interacts with you mid-flow — it is a main-session skill, not a read-only reviewer.

## Conventions

- **Capy knowledge base** — read [shared-capy-knowledge-protocol.md](shared-capy-knowledge-protocol.md); searched at intake (`kk:arch-decisions`, `kk:project-conventions`), indexed at close.
- **Shared producer guards** — four workflow guards, each citing the field failure it prevents. Load all four before acting:
  - [shared-requirements-harvesting.md](shared-requirements-harvesting.md) — quote the real asks before modelling (F1).
  - [shared-open-question-pass.md](shared-open-question-pass.md) — verification asks new questions, not just re-confirms (F4).
  - [shared-fact-flip-propagation.md](shared-fact-flip-propagation.md) — a contradicted fact is fixed everywhere in-session (F2).
  - [shared-contact-ratio-guard.md](shared-contact-ratio-guard.md) — at N:0 artifacts-to-contacts, the next step is a conversation (F5).
- **Profiles are not consulted** — `/kk:model` is language-agnostic in M2; archaeology reads code directly. Profile enrichment is deferred (design §8).

## Workflow

**Mandatory order — instructions before subject matter.** The flow is strictly sequential. Do **not** read code to model it, draft any kit page, or engage the domain beyond a mode-detecting directory/keyword scan until every instruction file is loaded: this SKILL.md, the process file [model-process.md](model-process.md), the reading method [archaeology.md](archaeology.md), the output contract [kit-contract.md](kit-contract.md), all four shared guards above, and the shared capy protocol. This ordering is load-bearing: with domain code in context before the contracts load, the model emits plausible terms and skips the methodology that makes them trustworthy.

1. **Load instructions.** Read [model-process.md](model-process.md) (the detailed seven-phase workflow), [archaeology.md](archaeology.md), [kit-contract.md](kit-contract.md), all four shared guards — [shared-requirements-harvesting.md](shared-requirements-harvesting.md), [shared-open-question-pass.md](shared-open-question-pass.md), [shared-fact-flip-propagation.md](shared-fact-flip-propagation.md), [shared-contact-ratio-guard.md](shared-contact-ratio-guard.md) — and [shared-capy-knowledge-protocol.md](shared-capy-knowledge-protocol.md). Minimal early scope — a directory listing or a keyword scan of the request — is permitted only to drive mode detection.
2. **Execute the seven phases** per [model-process.md](model-process.md):
   1. **Scope intake** — establish the bounded context, the **forcing question** (the feature/ticket that bounds what is worth modelling), and the **mode** (greenfield: no kit exists → produce the two pages; brownfield: an existing kit is read in full first and all changes are deltas, status markers never flipped unilaterally). Run the capy knowledge search.
   2. **Requirements-harvesting gate** *(guard, F1)* — read every linked ticket + one hop; quote the actual asks into working notes before any modelling.
   3. **Archaeology** — read code **state → time → invariants** per [archaeology.md](archaeology.md); two-clock discipline (code-clock facts verifiable, intent stays `proposed`).
   4. **Draft the kit** per [kit-contract.md](kit-contract.md) — glossary page + divergences/traps page (+ conventions index if the home has none).
   5. **Verify** — at least one confirm-pass **plus at least one open-question pass** *(guard, F4)*.
   6. **Self-check** — conventions-bind-author lint: the produced pages obey the kit's own declared conventions.
   7. **Surface & close** — present the **decision queue** (each RQ precise, decidable, role-tagged); apply the **contact-ratio guard** *(F5)*; in brownfield, **fact-flip propagation** *(F2)* on any contradicted recorded fact; index non-obvious rationale to `kk:arch-decisions`.

## Required Outputs

- [ ] The two durable kit pages (glossary + traps) for the context, provenance-clean, per [kit-contract.md](kit-contract.md) (+ conventions index if the home lacked one).
- [ ] The **decision queue** — precise, decidable, role-tagged questions — presented inline and appended to the active feature's `docs/feat/wip/<feature>/design.md` under an **Open Questions** heading when that directory exists.
- [ ] Contact-ratio guard applied; brownfield fact-flips propagated across the workspace.
- [ ] Non-obvious modelling rationale indexed to `kk:arch-decisions`.