@diottodev/runic 1.0.0 → 1.1.0

package/engineering/grill-with-docs/commands/cs-grill-with-docs.md

@@ -0,0 +1,100 @@
+---
+name: "cs-grill-with-docs"
+description: "/cs:grill-with-docs <path-to-plan> — Start a docs-anchored grilling session. Pre-flights CONTEXT.md + docs/adr/ linters, then interrogates the plan one decision at a time, updating glossary + writing ADRs inline as they crystallise."
+---
+
+# /cs:grill-with-docs — Docs-Anchored Plan Interrogation
+
+**Command:** `/cs:grill-with-docs <path-to-plan>`
+
+The `cs-grill-with-docs` persona pre-flights the project's documented language and decisions, then walks the plan one branch at a time — challenging fuzzy terms against `CONTEXT.md`, surfacing code-vs-glossary contradictions, and writing ADRs only when the 3-criteria gate is met.
+
+## When to Run
+
+- Stress-testing a plan that touches an established codebase with documented language
+- Onboarding a new feature into an existing bounded context
+- Resolving ambiguity introduced by drift between glossary and code
+- Pre-mortem on an architectural decision before it lands
+
+## When NOT to Run (use `/cs:grill-me` instead)
+
+- The repo has no `CONTEXT.md` and no `docs/adr/` and you don't want to seed them
+- You want a plan-only grill in a vacuum (the docs anchor would add no signal)
+- The plan is exploratory / pre-language-decision
+
+## The Six Forcing-Question Patterns (Docs-Anchored)
+
+1. **Glossary conflict:** "CONTEXT.md defines '{term}' as X. You just used it to mean Y. Which is it — or are these two concepts?"
+2. **ADR contradiction:** "ADR-{nnnn} locked in {choice}. Your plan implies {opposite}. Are we superseding, or did the plan drift?"
+3. **Undefined term:** "You said '{term}'. CONTEXT.md doesn't define it. Do you mean {candidate-1}, {candidate-2}, or something new?"
+4. **Code vs claim:** "Your code says X. You just said Y. Which is current state — and which are we changing?"
+5. **ADR 3-criteria gate:** "This decision is reversible in an afternoon. Why does it need an ADR? If 'it doesn't' — skip it."
+6. **Boundary check:** "Which bounded context owns this concept? If two contexts both touch it, what's the contract between them?"
+
+## Discipline
+
+- **Pre-flight the linters first.** Never grill without the docs-state snapshot.
+- **One question per turn.** Never bundle.
+- **Recommended answer attached.** Every question carries a position + rationale.
+- **Codebase + docs before speculation.** `grep` / `Read` / lint resolves before asking.
+- **CONTEXT.md edited inline.** No deferred glossary batches.
+- **ADR 3-criteria gate.** Hard-to-reverse + surprising + real-trade-off. All three or skip.
+
+## Workflow
+
+```bash
+# 1. Pre-flight — snapshot the docs state
+python ../skills/grill-with-docs/scripts/context_md_linter.py CONTEXT.md
+python ../skills/grill-with-docs/scripts/adr_scanner.py docs/adr/
+python ../skills/grill-with-docs/scripts/glossary_code_consistency.py \
+  --context CONTEXT.md --code src/
+
+# 2. Read the plan
+#    Use the linter findings as opening question seeds.
+
+# 3. Walk one question at a time:
+#    Persona asks Q1 with recommendation (anchored to docs/code).
+#    User answers.
+#    Apply edits inline if the answer changes the glossary or warrants an ADR.
+
+# 4. Re-lint after any structural CONTEXT.md edit:
+python ../skills/grill-with-docs/scripts/context_md_linter.py CONTEXT.md
+
+# 5. Re-scan after any new ADR:
+python ../skills/grill-with-docs/scripts/adr_scanner.py docs/adr/
+
+# 6. At close — final consistency sweep:
+python ../skills/grill-with-docs/scripts/glossary_code_consistency.py \
+  --context CONTEXT.md --code src/
+```
+
+## When to Stop
+
+- Every branch has an answer, AND
+- Final lint state is clean (context_md_linter + adr_scanner both PASS), AND
+- No new fuzzy terms surfaced in the last 3 turns
+
+Produce a "glossary changes + ADRs + open items" summary at close.
+
+## Output Format
+
+```
+Q[i]/[total] (anchor: CONTEXT.md§Language | ADR-0003 | code:src/orders/cancel.ts:42 | plan:L18):
+
+[question]
+
+Recommended: [position] because [rationale grounded in the anchor]
+```
+
+## Related
+
+- Agent: [`cs-grill-with-docs`](../agents/cs-grill-with-docs.md)
+- Skill: [`grill-with-docs`](../skills/grill-with-docs/SKILL.md)
+- Format specs: [ADR-FORMAT](../skills/grill-with-docs/ADR-FORMAT.md), [CONTEXT-FORMAT](../skills/grill-with-docs/CONTEXT-FORMAT.md)
+- Sibling skill: `/cs:grill-me` (plan-only grill)
+- Adjacent: `/cs:caveman`, `/cs:handoff`, `/cs:write-a-skill`
+
+---
+
+**Version:** 1.0.0
+**Derived:** Matt Pocock's grill-with-docs (MIT) + this repo's wrapper

package/engineering/grill-with-docs/skills/grill-with-docs/ADR-FORMAT.md

@@ -0,0 +1,53 @@
+<!--
+Derived from Matt Pocock's grill-with-docs:
+https://github.com/mattpocock/skills/tree/main/skills/engineering/grill-with-docs/ADR-FORMAT.md
+MIT License © 2026 Matt Pocock. Reproduced verbatim under MIT.
+-->
+
+# ADR Format
+
+ADRs live in `docs/adr/` and use sequential numbering: `0001-slug.md`, `0002-slug.md`, etc.
+
+Create the `docs/adr/` directory lazily — only when the first ADR is needed.
+
+## Template
+
+```md
+# {Short title of the decision}
+
+{1-3 sentences: what's the context, what did we decide, and why.}
+```
+
+That's it. An ADR can be a single paragraph. The value is in recording *that* a decision was made and *why* — not in filling out sections.
+
+## Optional sections
+
+Only include these when they add genuine value. Most ADRs won't need them.
+
+- **Status** frontmatter (`proposed | accepted | deprecated | superseded by ADR-NNNN`) — useful when decisions are revisited
+- **Considered Options** — only when the rejected alternatives are worth remembering
+- **Consequences** — only when non-obvious downstream effects need to be called out
+
+## Numbering
+
+Scan `docs/adr/` for the highest existing number and increment by one.
+
+## When to offer an ADR
+
+All three of these must be true:
+
+1. **Hard to reverse** — the cost of changing your mind later is meaningful
+2. **Surprising without context** — a future reader will look at the code and wonder "why on earth did they do it this way?"
+3. **The result of a real trade-off** — there were genuine alternatives and you picked one for specific reasons
+
+If a decision is easy to reverse, skip it — you'll just reverse it. If it's not surprising, nobody will wonder why. If there was no real alternative, there's nothing to record beyond "we did the obvious thing."
+
+### What qualifies
+
+- **Architectural shape.** "We're using a monorepo." "The write model is event-sourced, the read model is projected into Postgres."
+- **Integration patterns between contexts.** "Ordering and Billing communicate via domain events, not synchronous HTTP."
+- **Technology choices that carry lock-in.** Database, message bus, auth provider, deployment target. Not every library — just the ones that would take a quarter to swap out.
+- **Boundary and scope decisions.** "Customer data is owned by the Customer context; other contexts reference it by ID only." The explicit no-s are as valuable as the yes-s.
+- **Deliberate deviations from the obvious path.** "We're using manual SQL instead of an ORM because X." Anything where a reasonable reader would assume the opposite. These stop the next engineer from "fixing" something that was deliberate.
+- **Constraints not visible in the code.** "We can't use AWS because of compliance requirements." "Response times must be under 200ms because of the partner API contract."
+- **Rejected alternatives when the rejection is non-obvious.** If you considered GraphQL and picked REST for subtle reasons, record it — otherwise someone will suggest GraphQL again in six months.

package/engineering/grill-with-docs/skills/grill-with-docs/CONTEXT-FORMAT.md

@@ -0,0 +1,83 @@
+<!--
+Derived from Matt Pocock's grill-with-docs:
+https://github.com/mattpocock/skills/tree/main/skills/engineering/grill-with-docs/CONTEXT-FORMAT.md
+MIT License © 2026 Matt Pocock. Reproduced verbatim under MIT.
+-->
+
+# CONTEXT.md Format
+
+## Structure
+
+```md
+# {Context Name}
+
+{One or two sentence description of what this context is and why it exists.}
+
+## Language
+
+**Order**:
+{A concise description of the term}
+_Avoid_: Purchase, transaction
+
+**Invoice**:
+A request for payment sent to a customer after delivery.
+_Avoid_: Bill, payment request
+
+**Customer**:
+A person or organization that places orders.
+_Avoid_: Client, buyer, account
+
+## Relationships
+
+- An **Order** produces one or more **Invoices**
+- An **Invoice** belongs to exactly one **Customer**
+
+## Example dialogue
+
+> **Dev:** "When a **Customer** places an **Order**, do we create the **Invoice** immediately?"
+> **Domain expert:** "No — an **Invoice** is only generated once a **Fulfillment** is confirmed."
+
+## Flagged ambiguities
+
+- "account" was used to mean both **Customer** and **User** — resolved: these are distinct concepts.
+```
+
+## Rules
+
+- **Be opinionated.** When multiple words exist for the same concept, pick the best one and list the others as aliases to avoid.
+- **Flag conflicts explicitly.** If a term is used ambiguously, call it out in "Flagged ambiguities" with a clear resolution.
+- **Keep definitions tight.** One sentence max. Define what it IS, not what it does.
+- **Show relationships.** Use bold term names and express cardinality where obvious.
+- **Only include terms specific to this project's context.** General programming concepts (timeouts, error types, utility patterns) don't belong even if the project uses them extensively. Before adding a term, ask: is this a concept unique to this context, or a general programming concept? Only the former belongs.
+- **Group terms under subheadings** when natural clusters emerge. If all terms belong to a single cohesive area, a flat list is fine.
+- **Write an example dialogue.** A conversation between a dev and a domain expert that demonstrates how the terms interact naturally and clarifies boundaries between related concepts.
+
+## Single vs multi-context repos
+
+**Single context (most repos):** One `CONTEXT.md` at the repo root.
+
+**Multiple contexts:** A `CONTEXT-MAP.md` at the repo root lists the contexts, where they live, and how they relate to each other:
+
+```md
+# Context Map
+
+## Contexts
+
+- [Ordering](./src/ordering/CONTEXT.md) — receives and tracks customer orders
+- [Billing](./src/billing/CONTEXT.md) — generates invoices and processes payments
+- [Fulfillment](./src/fulfillment/CONTEXT.md) — manages warehouse picking and shipping
+
+## Relationships
+
+- **Ordering → Fulfillment**: Ordering emits `OrderPlaced` events; Fulfillment consumes them to start picking
+- **Fulfillment → Billing**: Fulfillment emits `ShipmentDispatched` events; Billing consumes them to generate invoices
+- **Ordering ↔ Billing**: Shared types for `CustomerId` and `Money`
+```
+
+The skill infers which structure applies:
+
+- If `CONTEXT-MAP.md` exists, read it to find contexts
+- If only a root `CONTEXT.md` exists, single context
+- If neither exists, create a root `CONTEXT.md` lazily when the first term is resolved
+
+When multiple contexts exist, infer which one the current topic relates to. If unclear, ask.

package/engineering/grill-with-docs/skills/grill-with-docs/SKILL.md

@@ -0,0 +1,143 @@
+---
+name: grill-with-docs
+description: Docs-anchored grilling session — challenges a plan against the project's existing language (CONTEXT.md) and recorded decisions (docs/adr/), and updates those files inline as terminology and decisions crystallise. Use when user wants to stress-test a plan against documented domain language, or mentions "grill with docs".
+license: MIT
+metadata:
+  derived_from: "https://github.com/mattpocock/skills/tree/main/skills/engineering/grill-with-docs"
+  original_author: "Matt Pocock (@mattpocock)"
+  original_license: MIT
+  voice: "Matt Pocock — relentless, one-at-a-time, codebase-and-docs-first, ADRs only when 3 criteria are met"
+  version: 1.0.0
+---
+
+# Grill with Docs
+
+> Derived from [Matt Pocock's grill-with-docs](https://github.com/mattpocock/skills/tree/main/skills/engineering/grill-with-docs) (MIT, © 2026 Matt Pocock). Matt's interview discipline + docs-anchored grilling rules preserved verbatim under MIT. Additions in this repo: 3 stdlib validators (CONTEXT.md linter, ADR scanner, glossary↔code consistency check), 3 in-depth references each citing 7+ authoritative sources, `cs-grill-with-docs` agent, `/cs:grill-with-docs` command. See [Wrapper additions](#wrapper-additions) below.
+
+<what-to-do>
+
+Interview me relentlessly about every aspect of this plan until we reach a shared understanding. Walk down each branch of the design tree, resolving dependencies between decisions one-by-one. For each question, provide your recommended answer.
+
+Ask the questions one at a time, waiting for feedback on each question before continuing.
+
+If a question can be answered by exploring the codebase, explore the codebase instead.
+
+</what-to-do>
+
+<supporting-info>
+
+## Domain awareness
+
+During codebase exploration, also look for existing documentation:
+
+### File structure
+
+Most repos have a single context:
+
+```
+/
+├── CONTEXT.md
+├── docs/
+│   └── adr/
+│       ├── 0001-event-sourced-orders.md
+│       └── 0002-postgres-for-write-model.md
+└── src/
+```
+
+If a `CONTEXT-MAP.md` exists at the root, the repo has multiple contexts. The map points to where each one lives:
+
+```
+/
+├── CONTEXT-MAP.md
+├── docs/
+│   └── adr/                          ← system-wide decisions
+├── src/
+│   ├── ordering/
+│   │   ├── CONTEXT.md
+│   │   └── docs/adr/                 ← context-specific decisions
+│   └── billing/
+│       ├── CONTEXT.md
+│       └── docs/adr/
+```
+
+Create files lazily — only when you have something to write. If no `CONTEXT.md` exists, create one when the first term is resolved. If no `docs/adr/` exists, create it when the first ADR is needed.
+
+## During the session
+
+### Challenge against the glossary
+
+When the user uses a term that conflicts with the existing language in `CONTEXT.md`, call it out immediately. "Your glossary defines 'cancellation' as X, but you seem to mean Y — which is it?"
+
+### Sharpen fuzzy language
+
+When the user uses vague or overloaded terms, propose a precise canonical term. "You're saying 'account' — do you mean the Customer or the User? Those are different things."
+
+### Discuss concrete scenarios
+
+When domain relationships are being discussed, stress-test them with specific scenarios. Invent scenarios that probe edge cases and force the user to be precise about the boundaries between concepts.
+
+### Cross-reference with code
+
+When the user states how something works, check whether the code agrees. If you find a contradiction, surface it: "Your code cancels entire Orders, but you just said partial cancellation is possible — which is right?"
+
+### Update CONTEXT.md inline
+
+When a term is resolved, update `CONTEXT.md` right there. Don't batch these up — capture them as they happen. Use the format in [CONTEXT-FORMAT.md](./CONTEXT-FORMAT.md).
+
+`CONTEXT.md` should be totally devoid of implementation details. Do not treat `CONTEXT.md` as a spec, a scratch pad, or a repository for implementation decisions. It is a glossary and nothing else.
+
+### Offer ADRs sparingly
+
+Only offer to create an ADR when all three are true:
+
+1. **Hard to reverse** — the cost of changing your mind later is meaningful
+2. **Surprising without context** — a future reader will wonder "why did they do it this way?"
+3. **The result of a real trade-off** — there were genuine alternatives and you picked one for specific reasons
+
+If any of the three is missing, skip the ADR. Use the format in [ADR-FORMAT.md](./ADR-FORMAT.md).
+
+</supporting-info>
+
+## Wrapper Additions
+
+The additions below are **not** part of Matt's upstream skill. They operationalize the upstream's rules into deterministic, stdlib-only validators that pair naturally with the interview loop.
+
+### Workflow (with wrapper tools)
+
+1. **Pre-flight (before the first question):**
+   - Run `scripts/context_md_linter.py CONTEXT.md` if a `CONTEXT.md` exists — confirms the glossary is well-formed before grilling against it.
+   - Run `scripts/adr_scanner.py docs/adr/` if `docs/adr/` exists — surfaces numbering gaps, malformed ADRs, status-frontmatter inconsistencies.
+   - Run `scripts/glossary_code_consistency.py --context CONTEXT.md --code src/` — flags defined-but-unused terms (dead glossary) and code-only common nouns that may need definitions. Use these flags as opening grill questions.
+
+2. **During the session (Matt's rules apply):**
+   - One question per turn, walking depth-first.
+   - When a term is sharpened: edit `CONTEXT.md` immediately; re-run `context_md_linter.py` if the edit is structural.
+   - When an ADR is warranted: write it under `docs/adr/`; re-run `adr_scanner.py` to confirm numbering.
+
+3. **Closing:**
+   - Final `glossary_code_consistency.py` run to confirm no new orphan terms were introduced.
+   - Summarize: terms added/refined, ADRs written, scenarios discussed, open items.
+
+### Tools (stdlib-only)
+
+| Tool | One-line role |
+|---|---|
+| `scripts/context_md_linter.py` | Validate `CONTEXT.md` against the CONTEXT-FORMAT.md structure. PASS/WARN/FAIL per rule. |
+| `scripts/adr_scanner.py` | Walk `docs/adr/`, check `NNNN-slug.md` pattern, numbering integrity, body completeness. |
+| `scripts/glossary_code_consistency.py` | Cross-reference bold terms in `CONTEXT.md` against codebase usage. Flag dead glossary + code-only common nouns. |
+
+### References (citations behind each rule)
+
+- [`references/ubiquitous_language.md`](references/ubiquitous_language.md) — why a glossary belongs in source control (Evans, Vernon, Khononov, Wlaschin, Brandolini, Avram & Marinescu, Fowler)
+- [`references/adr_practice.md`](references/adr_practice.md) — when an ADR earns its keep (Nygard, Tyree & Akerman, Zimmermann Y-statements, MADR, ThoughtWorks Radar, adr-tools, Backstage)
+- [`references/context_md_as_artifact.md`](references/context_md_as_artifact.md) — CONTEXT.md as living artifact (Khononov on language drift, Kernighan on naming, BoundedContext bliki, Confluent on data contracts, Brandolini on EventStorming glossary)
+
+### Companion
+
+- Agent: `cs-grill-with-docs` (see `../../agents/cs-grill-with-docs.md`)
+- Command: `/cs:grill-with-docs` (see `../../commands/cs-grill-with-docs.md`)
+
+---
+
+**Version:** 1.0.0
+**Derived:** Matt Pocock's grill-with-docs (MIT) + this repo's wrapper

package/engineering/grill-with-docs/skills/grill-with-docs/references/adr_practice.md

@@ -0,0 +1,111 @@
+# ADR Practice — When Does a Decision Earn an ADR?
+
+This reference answers exactly one decision: **what bar must an architectural decision clear to be worth writing down as an ADR, and what format keeps the ADR useful 18 months later?**
+
+Pair with `scripts/adr_scanner.py` for filename + numbering + structural validation.
+
+## The Core Claim
+
+ADRs are not a compliance ritual. They exist to answer a single future question: **"Why on earth did they do it this way?"** If a future reader will never ask that question — because the choice is obvious, easy to reverse, or had no real alternatives — the ADR is doc-rot waiting to happen.
+
+The matt-pocock 3-criteria gate (preserved verbatim in `ADR-FORMAT.md`) is the strict version of this principle:
+
+1. **Hard to reverse** — the cost of changing your mind is meaningful (not "an afternoon of refactoring").
+2. **Surprising without context** — a future reader will look at the code and wonder why.
+3. **Result of a real trade-off** — there were genuine alternatives and you picked one for specific reasons.
+
+**All three must be true.** Two-out-of-three is not enough. If a decision was hard to reverse but obvious and uncontested (e.g., "we used HTTPS"), no ADR. If it was a real trade-off but easy to reverse (e.g., "we used React Query over SWR"), no ADR.
+
+## What Earns an ADR (Examples)
+
+- **Architectural shape.** "Write model is event-sourced, read model is projected into Postgres." Hard-to-reverse + surprising + real-trade-off.
+- **Integration patterns between contexts.** "Ordering and Billing communicate via domain events, not synchronous HTTP." Hard-to-reverse (rewiring eventing is expensive) + surprising (HTTP is the obvious choice) + real-trade-off (eventual consistency vs simpler API).
+- **Technology choices with lock-in.** Database engine, message bus, auth provider. Not "we picked Lodash" — those swap in an afternoon.
+- **Boundary and scope decisions.** "Customer data is owned by the Customer context; other contexts reference by ID only." The explicit no-s are as valuable as the yes-s.
+- **Deliberate deviations from the obvious path.** "We use manual SQL instead of an ORM because X." Stops the next engineer from "fixing" something deliberate.
+- **Constraints not visible in code.** "Can't use AWS due to compliance." "Response times must be <200ms due to partner API contract."
+- **Rejected alternatives with non-obvious rejections.** "We considered GraphQL and picked REST because subscription complexity didn't match our actual real-time needs." Otherwise someone will suggest GraphQL again in 6 months.
+
+## What Does NOT Earn an ADR
+
+- **Library choices.** Lodash vs Ramda, axios vs ky, dayjs vs date-fns — these swap in an afternoon. Comment in code if you must.
+- **Style guide decisions.** "We use Prettier" — record in `package.json`, not an ADR.
+- **Defaults you didn't deviate from.** "We use the framework's recommended router." No trade-off, no ADR.
+- **Decisions that are easy to reverse.** If the future-you can undo it in a day, future-you doesn't need the why.
+- **Decisions where the alternative was never seriously considered.** No real trade-off → no ADR.
+
+## Format Discipline
+
+ADRs are markdown files at `docs/adr/NNNN-slug.md`, numbered sequentially.
+
+**Default format (minimum viable):**
+
+```md
+# {Short title of the decision}
+
+{1-3 sentences: what's the context, what did we decide, and why.}
+```
+
+An ADR can be a single paragraph. The value is in recording *that* a decision was made and *why* — not in filling out sections.
+
+**Optional sections (only when they add genuine value):**
+
+- **Status frontmatter** (`proposed | accepted | deprecated | superseded by ADR-NNNN`) — useful when decisions are revisited.
+- **Considered Options** — only when rejected alternatives are worth remembering.
+- **Consequences** — only when non-obvious downstream effects need to be called out.
+
+If a section is included but empty or boilerplate ("none"), delete the section.
+
+## Numbering Discipline
+
+- Sequential, zero-padded to 4 digits: `0001`, `0002`, ..., `9999`.
+- No gaps. If an ADR is abandoned mid-draft, either commit it as `proposed → withdrawn` or renumber.
+- Slug is short, kebab-case, intent-revealing: `0042-event-sourced-orders.md`, not `0042-adr.md` or `0042-decision-about-events.md`.
+
+`scripts/adr_scanner.py` enforces the pattern and surfaces gaps.
+
+## Status Lifecycle (Optional)
+
+For repos that revisit decisions, the status field is useful:
+
+```
+proposed  →  accepted     ← default lifecycle for a new ADR
+accepted  →  deprecated   ← decision no longer applies; no replacement
+accepted  →  superseded   ← replaced by ADR-NNNN; link to successor in frontmatter
+```
+
+When superseding, the new ADR references the old (`supersedes: ADR-0017`) and the old ADR is updated with `superseded by: ADR-0042`. This back-link is the single most useful piece of ADR metadata for archeology.
+
+## Anti-Patterns
+
+- **The ADR factory.** Writing an ADR for every PR. Within a year, you have 200 ADRs and no one reads any. The 3-criteria gate is the firewall.
+- **The proposal that never accepts.** ADR sits in `proposed` for months. Either accept it (do it) or withdraw it (delete the file or mark withdrawn).
+- **The TOC-only ADR.** Filled-in section headers but no actual content. Worse than not writing the ADR — it implies a decision was recorded when nothing was.
+- **The future-tense ADR.** "We will use X." ADRs are records, not plans. Write in past tense ("We chose X because ...") so it reads correctly 2 years later.
+- **The unanchored ADR.** ADR with no link to the PR/issue/discussion that drove it. The "why" loses fidelity over time without the source thread.
+
+## Operational Checklist (Per ADR Decision Point)
+
+When grilling and a candidate decision emerges:
+
+- [ ] **Reversibility test.** "If we change our mind in 6 months, what's the cost?" If "an afternoon" → skip the ADR.
+- [ ] **Surprise test.** "Will a future engineer look at this and wonder why?" If no → skip.
+- [ ] **Trade-off test.** "What alternatives did we seriously consider, and why did each lose?" If none → skip.
+- [ ] **All three pass.** Write the ADR. Use the minimum format. Re-run `scripts/adr_scanner.py` to confirm numbering.
+- [ ] **Frontmatter status.** Only add `status` if revisiting is expected. Default is "implicit accepted".
+
+## Citations (7 sources)
+
+1. **Michael Nygard, "Documenting Architecture Decisions" (cognitect.com, November 2011).** The original ADR essay. Introduces the format (Title / Context / Decision / Status / Consequences) and the core insight that "architecturally significant" decisions deserve records. Nygard's framing of ADRs as "memory aids for future architects" is the source of the 3-criteria gate's first rule (hard-to-reverse).
+
+2. **Jeff Tyree & Art Akerman, "Architecture Decisions: Demystifying Architecture" — *IEEE Software* 22(2), March–April 2005, pp. 19–27.** Pre-dates Nygard. Introduces the concept of an "Architecture Decision Record" as a first-class artifact and argues for explicit recording of rejected alternatives. The "rejected alternatives" section in Nygard's format inherits from Tyree & Akerman.
+
+3. **Olaf Zimmermann et al., "Y-Statements: A Lightweight Architectural Decision Format" — published at various venues including ozimmer.ch.** Proposes the "In the context of {use case / requirement}, facing {concern}, we decided for {option} to achieve {quality}, accepting {downside}" template. Used widely as a compact alternative to the full Nygard format.
+
+4. **MADR (Markdown Architectural Decision Records) — adr.github.io/madr.** Open-source template maintained by a community of practitioners. Specifies frontmatter format (status, deciders, date, consulted, informed) and a discoverable file structure. Useful when ADRs need machine-readable metadata for indexing.
+
+5. **ThoughtWorks Technology Radar — thoughtworks.com/radar.** Has covered "Lightweight Architecture Decision Records" since Vol. 18 (2018) in the Techniques quadrant, with periodic upgrades to "Adopt". TW's "use ADRs sparingly" guidance aligns with the 3-criteria gate.
+
+6. **Joel Parker Henderson, adr-tools (github.com/npryce/adr-tools).** CLI tool implementing Nygard's format with numbering helpers, supersession linking, and a `new` / `link` / `accept` command set. Establishes the de-facto convention of `0001-slug.md` filenames and `docs/adr/` directory location.
+
+7. **Spotify Backstage — backstage.io.** Backstage's TechDocs catalog includes an ADR plugin that surfaces per-service ADRs in the service catalog UI. Demonstrates how ADRs become discoverable at scale (>1000 services) when treated as first-class catalog entries, not just files in a repo.

package/engineering/grill-with-docs/skills/grill-with-docs/references/context_md_as_artifact.md

@@ -0,0 +1,105 @@
+# CONTEXT.md as a Living Artifact — Preventing Glossary Decay
+
+This reference answers exactly one decision: **how does a glossary stay alive vs decay into doc rot, and what operational practices prevent the drift?**
+
+Pair with `scripts/glossary_code_consistency.py` for the lint-against-codebase reality check and `scripts/context_md_linter.py` for structural validation.
+
+## The Core Claim
+
+Every glossary decays by default. The decay path is well-documented:
+
+```
+Month 1: Glossary written during initial DDD workshop. Terms are precise.
+Month 3: New feature ships. Two new domain terms used in code, neither added to glossary.
+Month 6: A term in the glossary is renamed in code. Glossary still has old name.
+Month 9: New engineer joins. Reads glossary. Asks "what's a 'Booking'?" — answer is "we don't call those Bookings anymore, we call them Reservations now."
+Month 12: Glossary is officially declared stale. Engineers stop reading it. Drift becomes invisible.
+```
+
+The decay is not preventable by good intentions. It is prevented by **inline edits during the work that introduces the term** plus **automated lint runs at PR time** to flag mismatches.
+
+## Three Forces That Drive Drift
+
+1. **Language pressure from outside the bounded context.** A new partner integration uses different terminology ("subscriber" vs your "customer"). Engineers copy the partner's term into code without first reconciling with the glossary.
+2. **Refactor pressure inside the bounded context.** A rename in code feels obvious ("`Booking` → `Reservation` is just a better name"), but the glossary isn't updated alongside.
+3. **Convergence pressure between teams.** Multiple teams contributing to the same context use slightly different words for the same concept. Without a glossary as referee, all variants end up in code.
+
+`scripts/glossary_code_consistency.py` operationalizes the lint against these three forces:
+
+- **Defined-but-unused term** → a glossary entry that no code references. Either dead glossary (delete) or a rename happened (update glossary to match code).
+- **Code-only proper noun** → a frequently-used capitalized term in code that the glossary doesn't define. Either generic (ignore) or domain (add to glossary now).
+
+## Five Practices That Keep CONTEXT.md Alive
+
+1. **Edit inline during the work.** Never batch glossary updates. When a term is introduced or refined during a feature, the same PR that adds the code edits `CONTEXT.md`. Reviewers reject PRs that introduce domain terms without glossary edits.
+2. **Lint at PR time.** Run `scripts/context_md_linter.py` and `scripts/glossary_code_consistency.py` in CI. A new term in code without a glossary entry is a build warning; an outright rename mismatch is a build failure.
+3. **Per-context glossaries, not one mega-glossary.** Multi-context repos use `CONTEXT-MAP.md` to point at per-context `CONTEXT.md` files. Cross-context terms get explicit translation entries ("Billing's `Customer` is Ordering's `Account`").
+4. **Pruning passes.** Quarterly, run `glossary_code_consistency.py` and review the dead-glossary report. Delete entries that no code uses. Keeping dead entries dilutes signal.
+5. **One sentence per definition.** If a definition runs to a paragraph, the term is hiding two concepts. Split or sharpen. Long definitions are correlated with imprecise terms.
+
+## How CONTEXT.md Differs from Other "Documentation"
+
+| Artifact | Purpose | Update cadence | Audience |
+|---|---|---|---|
+| `README.md` | Onboarding + setup | Once at project start, occasionally after | New contributors |
+| `ARCHITECTURE.md` | High-level system shape | Quarterly to yearly | New architects, senior engineers |
+| `docs/adr/*.md` | Record of specific decisions | Per-decision (rare; days to months apart) | Anyone asking "why did we do X this way?" |
+| **`CONTEXT.md`** | **The domain glossary — what each term means in this bounded context** | **Per-feature (continuous; hours to days apart)** | **Every engineer on every PR** |
+
+A `CONTEXT.md` is touched far more often than any other doc because it tracks the language as it evolves. If yours hasn't been edited in 6 months, it's almost certainly drifting.
+
+## Single vs Multi-Context Repos
+
+**Single context (most repos):** One `CONTEXT.md` at the repo root. All terms in scope.
+
+**Multiple contexts:** A `CONTEXT-MAP.md` at the repo root lists the contexts and their relationships. Each bounded context has its own `CONTEXT.md` (and its own `docs/adr/` for context-specific decisions). Shared terms appear in both with cross-references.
+
+```
+/
+├── CONTEXT-MAP.md         ← lists contexts + relationships
+├── docs/adr/              ← system-wide ADRs
+└── src/
+    ├── ordering/
+    │   ├── CONTEXT.md     ← ordering-context glossary
+    │   └── docs/adr/      ← ordering-context ADRs
+    └── billing/
+        ├── CONTEXT.md
+        └── docs/adr/
+```
+
+When a term spans contexts, define it in each `CONTEXT.md` with the context's perspective + a translation note pointing at the other. Don't try to define "Customer" once and have both contexts share it — that's the path back to the mega-glossary.
+
+## Anti-Patterns
+
+- **The spec masquerading as a glossary.** `CONTEXT.md` includes implementation details, sequence diagrams, API responses. It is a glossary, not a spec. Move spec content elsewhere.
+- **The wiki masquerading as a glossary.** General programming concepts ("retry", "timeout", "config") appearing in `CONTEXT.md`. They are not domain-specific. Remove.
+- **The glossary that defines without forbidding.** Each term needs `_Avoid_: <aliases>` to push back on drift. A glossary that says "Customer means X" but doesn't forbid "Client" / "Account" / "User" cannot push back when those drift in.
+- **The frozen glossary.** No commits in 6+ months. Either the project is dormant or the language has drifted away from the document. Re-grill.
+- **The orphan glossary.** Sits in a repo but no CI/PR process references it. It will decay within two quarters.
+
+## Operational Checklist
+
+When grilling against `CONTEXT.md`:
+
+- [ ] Lint structure: `python scripts/context_md_linter.py CONTEXT.md`
+- [ ] Lint vs code: `python scripts/glossary_code_consistency.py --context CONTEXT.md --code src/`
+- [ ] For each "defined but unused": ask "dead term, or rename happened?"
+- [ ] For each "code-only proper noun": ask "domain term that needs definition, or generic?"
+- [ ] For each new term introduced during the grill: edit `CONTEXT.md` *now*, not "later"
+- [ ] Multi-context repo: verify the right `CONTEXT.md` is being edited (not the wrong context's, not the root one when a per-context one applies)
+
+## Citations (7 sources)
+
+1. **Vladimir Khononov, *Learning Domain-Driven Design* (O'Reilly, 2021).** Chapter 9, "Communication Patterns" + Chapter 12, "Building Domain Expertise" — Khononov is the sharpest writer on language drift between bounded contexts and on how to detect it. His "linguistic boundaries are observable boundaries" framing is the foundation of the `glossary_code_consistency.py` check.
+
+2. **Brian Kernighan & Rob Pike, *The Practice of Programming* (Addison-Wesley, 1999).** Chapter 1, "Style" — the section on naming. Kernighan's "names should reflect the role of the variable, not its type" generalizes to glossary terms: a glossary term names a role in the domain, not a data structure. Kernighan-style naming discipline is what keeps `CONTEXT.md` precise.
+
+3. **Martin Fowler, "BoundedContext" — martinfowler.com bliki (2014, updated).** The canonical argument that ubiquitous language is **bounded** — it applies inside one context, not across all contexts. The justification for per-context `CONTEXT.md` files. https://martinfowler.com/bliki/BoundedContext.html
+
+4. **Martin Fowler, "UbiquitousLanguage" — martinfowler.com bliki.** Companion entry to BoundedContext. Articulates the discipline of using the same vocabulary in conversation, in the model, and in the code. The justification for editing `CONTEXT.md` inline alongside code changes, not as separate doc work. https://martinfowler.com/bliki/UbiquitousLanguage.html
+
+5. **Confluent Schema Registry / Data Contracts community — confluent.io/blog/data-contracts.** The data-contracts movement applies UL discipline to inter-service / inter-context boundaries: when two contexts exchange events or API payloads, the schema is a binding glossary. Drift between contexts becomes a schema-evolution problem, not a free-form documentation problem.
+
+6. **Alberto Brandolini, *Introducing EventStorming* (Leanpub, ongoing).** Chapter on "Pivotal Events" + the convergence-workshop chapter. Brandolini documents how a glossary emerges from EventStorming workshops as a by-product of mapping events. The pattern of "capture the term on a sticky note when it surfaces" is the offline equivalent of the inline `CONTEXT.md` edit discipline.
+
+7. **Eric Evans, *Domain-Driven Design: Tackling Complexity in the Heart of Software* (Addison-Wesley, 2003).** Chapter 14, "Maintaining Model Integrity" — covers the Conformist, Anticorruption Layer, and Shared Kernel patterns. Each of these is a strategy for managing the boundary between two bounded contexts that have different languages. Justifies the multi-context `CONTEXT-MAP.md` pattern and the translation-note discipline for cross-context terms.