@reddb-io/red-skills-dev 2.75.2

package/skills/engineering/tdd/SKILL.md

@@ -0,0 +1,96 @@
+---
+name: tdd
+description: Test-driven development with a red → green loop. Use when user wants to build features or fix bugs using TDD, mentions "red-green", wants integration tests, or asks for test-first development.
+---
+
+# Test-Driven Development
+
+<what-to-do>
+
+**Loop rule: red before green, one slice at a time, tests only at pre-agreed seams.** One failing test, the minimum code to pass it, nothing more; repeat until every listed behaviour is covered.
+
+The loop has no prescribed steps — pick the next uncovered behaviour, write one failing test, write the minimum code to pass it, check the cycle checklist, move on.
+
+### Seams
+
+A **seam** is the public boundary you test at. Agree on seams before writing the first test — no test at an unconfirmed seam. Each seam carries one behaviour per cycle.
+
+### Hard rules — do not break these
+
+- ❌ Do **not** write all tests first then all implementation ("horizontal slicing"). This produces tests of *imagined* behaviour, not *actual* behaviour. See `<supporting-info>` for why.
+- ❌ Do **not** write more code than the current test requires. No speculative features, no anticipating the next test.
+- ❌ Do **not** test private methods or mock internal collaborators. Tests must go through the public interface.
+- ❌ Do **not** verify behaviour through external means (querying the database directly when an API exists, etc.).
+- ❌ Do **not** write tautological assertions — expected values must come from an independent source of truth (a literal, a worked example, the spec), not by recomputing the same way the code does. `expect(add(a, b)).toBe(a + b)` always passes and can never catch a bug.
+- ✅ **Do** confirm seams before writing the first test — no test at an unconfirmed seam.
+- ✅ **Do** check each cycle against the per-cycle checklist before moving to the next test.
+- ✅ **Do** keep tests focused on observable behaviour through public interfaces.
+- ✅ **Do** use the project's domain vocabulary in test names and interface design.
+
+### Per-cycle checklist
+
+Before declaring a cycle done, confirm every box:
+
+```
+[ ] A reader can tell what the system does from this test alone — not how it does it
+[ ] The test reaches the system only through its public interface
+[ ] This test would still pass if the internal implementation were replaced entirely
+[ ] No code was added beyond what this test required
+[ ] No features were anticipated beyond the current test
+[ ] Expected values come from a literal, worked example, or spec — not recomputed the way the code computes them
+```
+
+If any box is unchecked, the cycle isn't done — fix it before moving on.
+
+Once all tests are GREEN, refactoring is a separate concern — run `/code-review` on the branch to clean up.
+
+</what-to-do>
+
+<supporting-info>
+
+## Philosophy
+
+**Core principle**: Tests verify behaviour through public interfaces, not implementation details. Code can change entirely; tests shouldn't.
+
+**Good tests** are integration-style: they exercise real code paths through public APIs. They describe *what* the system does, not *how*. A good test reads like a specification — *"user can checkout with valid cart"* tells you exactly what capability exists. These tests survive refactors because they don't care about internal structure.
+
+**Implementation-coupled tests** are the first bad-test pattern: they mock internal collaborators, test private methods, or verify through external means (like querying a database directly instead of using the interface). The warning sign: your test breaks when you refactor, but behaviour hasn't changed.
+
+**Tautological tests** are the second bad-test pattern: a test whose assertion is recomputed the way the code computes it passes by construction and proves nothing. `expect(add(a, b)).toBe(a + b)` will always pass regardless of what `add` does — the assertion restates the implementation instead of verifying it against an independent expected value. Expected values must come from a literal, a worked example, or the spec.
+
+See [tests.md](tests.md) for examples of both anti-patterns, [mocking.md](mocking.md) for mocking guidelines, [interface-design.md](interface-design.md) for designing for testability.
+
+## Seams
+
+A **seam** is the public boundary you test at: the interface where you observe behaviour without reaching inside the implementation. Tests live at seams, never against internals.
+
+Confirming seams before the first test is how testing effort lands on critical paths and complex logic — not on every edge case. One seam, one test, one implementation per cycle.
+
+## Why horizontal slicing is forbidden
+
+Treating RED as "write all tests" and GREEN as "write all code" produces **crap tests**:
+
+- Tests written in bulk test *imagined* behaviour, not *actual* behaviour
+- You end up testing the *shape* of things (data structures, signatures) rather than user-facing behaviour
+- Tests become insensitive to real changes — they pass when behaviour breaks, fail when behaviour is fine
+- You outrun your headlights, committing to test structure before understanding the implementation
+
+```
+WRONG (horizontal):
+  RED:   test1, test2, test3, test4, test5
+  GREEN: impl1, impl2, impl3, impl4, impl5
+
+RIGHT (vertical):
+  RED→GREEN: test1→impl1
+  RED→GREEN: test2→impl2
+  RED→GREEN: test3→impl3
+  …
+```
+
+Each test responds to what you learned from the previous cycle. Because you just wrote the code, you know exactly what behaviour matters and how to verify it.
+
+## Planning aids
+
+When listing behaviours, also identify opportunities for [deep modules](deep-modules.md) (small interface, deep implementation) and design interfaces for [testability](interface-design.md). These choices are easier to make before any code exists.
+
+</supporting-info>

package/skills/engineering/tdd/deep-modules.md

@@ -0,0 +1,33 @@
+# Deep Modules
+
+From "A Philosophy of Software Design":
+
+**Deep module** = small interface + lots of implementation
+
+```
+┌─────────────────────┐
+│   Small Interface   │  ← Few methods, simple params
+├─────────────────────┤
+│                     │
+│                     │
+│  Deep Implementation│  ← Complex logic hidden
+│                     │
+│                     │
+└─────────────────────┘
+```
+
+**Shallow module** = large interface + little implementation (avoid)
+
+```
+┌─────────────────────────────────┐
+│       Large Interface           │  ← Many methods, complex params
+├─────────────────────────────────┤
+│  Thin Implementation            │  ← Just passes through
+└─────────────────────────────────┘
+```
+
+When designing interfaces, ask:
+
+- Can I reduce the number of methods?
+- Can I simplify the parameters?
+- Can I hide more complexity inside?

package/skills/engineering/tdd/interface-design.md

@@ -0,0 +1,31 @@
+# Interface Design for Testability
+
+Good interfaces make testing natural:
+
+1. **Accept dependencies, don't create them**
+
+   ```typescript
+   // Testable
+   function processOrder(order, paymentGateway) {}
+
+   // Hard to test
+   function processOrder(order) {
+     const gateway = new StripeGateway();
+   }
+   ```
+
+2. **Return results, don't produce side effects**
+
+   ```typescript
+   // Testable
+   function calculateDiscount(cart): Discount {}
+
+   // Hard to test
+   function applyDiscount(cart): void {
+     cart.total -= discount;
+   }
+   ```
+
+3. **Small surface area**
+   - Fewer methods = fewer tests needed
+   - Fewer params = simpler test setup

package/skills/engineering/tdd/mocking.md

@@ -0,0 +1,59 @@
+# When to Mock
+
+Mock at **system boundaries** only:
+
+- External APIs (payment, email, etc.)
+- Databases (sometimes - prefer test DB)
+- Time/randomness
+- File system (sometimes)
+
+Don't mock:
+
+- Your own classes/modules
+- Internal collaborators
+- Anything you control
+
+## Designing for Mockability
+
+At system boundaries, design interfaces that are easy to mock:
+
+**1. Use dependency injection**
+
+Pass external dependencies in rather than creating them internally:
+
+```typescript
+// Easy to mock
+function processPayment(order, paymentClient) {
+  return paymentClient.charge(order.total);
+}
+
+// Hard to mock
+function processPayment(order) {
+  const client = new StripeClient(process.env.STRIPE_KEY);
+  return client.charge(order.total);
+}
+```
+
+**2. Prefer SDK-style interfaces over generic fetchers**
+
+Create specific functions for each external operation instead of one generic function with conditional logic:
+
+```typescript
+// GOOD: Each function is independently mockable
+const api = {
+  getUser: (id) => fetch(`/users/${id}`),
+  getOrders: (userId) => fetch(`/users/${userId}/orders`),
+  createOrder: (data) => fetch('/orders', { method: 'POST', body: data }),
+};
+
+// BAD: Mocking requires conditional logic inside the mock
+const api = {
+  fetch: (endpoint, options) => fetch(endpoint, options),
+};
+```
+
+The SDK approach means:
+- Each mock returns one specific shape
+- No conditional logic in test setup
+- Easier to see which endpoints a test exercises
+- Type safety per endpoint

package/skills/engineering/tdd/tests.md

@@ -0,0 +1,85 @@
+# Good and Bad Tests
+
+## Good Tests
+
+**Integration-style**: Test through real interfaces, not mocks of internal parts.
+
+```typescript
+// GOOD: Tests observable behavior
+test("user can checkout with valid cart", async () => {
+  const cart = createCart();
+  cart.add(product);
+  const result = await checkout(cart, paymentMethod);
+  expect(result.status).toBe("confirmed");
+});
+```
+
+Characteristics:
+
+- Tests behavior users/callers care about
+- Uses public API only
+- Survives internal refactors
+- Describes WHAT, not HOW
+- One logical assertion per test
+
+## Bad Tests
+
+**Implementation-detail tests**: Coupled to internal structure.
+
+```typescript
+// BAD: Tests implementation details
+test("checkout calls paymentService.process", async () => {
+  const mockPayment = jest.mock(paymentService);
+  await checkout(cart, payment);
+  expect(mockPayment.process).toHaveBeenCalledWith(cart.total);
+});
+```
+
+Red flags:
+
+- Mocking internal collaborators
+- Testing private methods
+- Asserting on call counts/order
+- Test breaks when refactoring without behavior change
+- Test name describes HOW not WHAT
+- Verifying through external means instead of interface
+
+```typescript
+// BAD: Bypasses interface to verify
+test("createUser saves to database", async () => {
+  await createUser({ name: "Alice" });
+  const row = await db.query("SELECT * FROM users WHERE name = ?", ["Alice"]);
+  expect(row).toBeDefined();
+});
+
+// GOOD: Verifies through interface
+test("createUser makes user retrievable", async () => {
+  const user = await createUser({ name: "Alice" });
+  const retrieved = await getUser(user.id);
+  expect(retrieved.name).toBe("Alice");
+});
+```
+
+## Tautological Tests
+
+**Tautological assertion**: expected value recomputed the way the code computes it — passes by construction and proves nothing.
+
+```typescript
+// BAD: tautological — assertion mirrors the implementation
+test("add returns the sum", () => {
+  const a = 3;
+  const b = 4;
+  expect(add(a, b)).toBe(a + b); // always true regardless of what add does
+});
+
+// GOOD: expected value from an independent source of truth
+test("add returns the sum", () => {
+  expect(add(3, 4)).toBe(7); // 7 is a literal from a worked example
+});
+```
+
+Red flags:
+
+- Expected value is computed using the same operator/function as the implementation
+- Swapping the implementation for any expression that satisfies the same type would still pass
+- The test can never catch an off-by-one or wrong-operator bug

package/skills/engineering/to-spec/SKILL.md

@@ -0,0 +1,104 @@
+---
+name: to-spec
+description: Turn the current conversation context into a Spec and publish it to the project issue tracker. Use when user wants to create a Spec from the current context.
+---
+
+**Synthesize the current conversation into a Spec and publish it — no interview, no implementation.** Just synthesize what you already know from the conversation.
+
+The issue tracker and triage label vocabulary should have been provided to you — run `/red-setup` if not.
+
+<what-to-do>
+
+## Process
+
+1. Explore the repo to understand the current state of the codebase, if you haven't already. Use the project's domain glossary vocabulary throughout the Spec, and respect any ADRs in the area you're touching.
+
+2. Sketch out the testing seams for the feature. Prefer existing, high-level seams over new low-level ones. If new seams are needed, propose them at the highest point that can exercise the behavior.
+
+Check with the user that these seams match their expectations.
+
+**Capture every HITL call** made during the conversation that led to this Spec — testing seam choices, module shape choices, trade-offs the user took a side on, alternatives they rejected, constraints they imposed. These go into the `Human Decisions` section of the template. Do not silently fold them into `Implementation Decisions` — once `/to-tickets` slices this Spec and `/afk` picks up the children, the human's calls become indistinguishable from agent inference unless they are flagged here.
+
+3. **Cascade gate — run before publishing.** AFK workers branch from `origin/{base}` and cannot see the primary checkout's working-tree edits, so never publish while docs are unlanded.
+
+   a. `git fetch origin`, then compare the `.red/` docs (`.red/CONTEXT.md`, `.red/CONTEXT-MAP.md`, `.red/contexts/**`, `.red/adr/**`) between the primary working tree and `origin/{base}` (base resolved lock > pin > main). "Landed" means reachable from `origin/{base}`, not merely present on disk — origin-first comparison, mirroring the `/review-adrs` convention.
+   b. **On mismatch:** run the doc-landing procedure from the `/start` end-of-session finalizer (canonized by ADR 0092) first, then continue to step 4.
+   c. **If landing is impossible** (no network, no push access): abort — never publish while docs are unlanded. State clearly which files must be landed and stop.
+
+4. Write the Spec using the template below, then publish it to the project issue tracker.
+
+   **Labels on publish:** apply `type:spec` and `needs-slicing`. **Do not apply `ready-for-agent` to a Spec — a Spec is not an implementable unit; `/to-tickets` must slice it first.** `/afk` hard-filters anything tagged `type:spec` so an accidental `ready-for-agent` will be ignored, but the right pre-condition is to not set it in the first place.
+
+   The next step after publish is `/to-tickets` (manual or scheduled) which consumes `needs-slicing` Specs, generates child issues with `spec:{N}` + `ready-for-agent`, and removes `needs-slicing` from the parent.
+
+</what-to-do>
+
+<supporting-info>
+
+<spec-template>
+
+## Problem Statement
+
+The problem that the user is facing, from the user's perspective.
+
+## Solution
+
+The solution to the problem, from the user's perspective.
+
+## User Stories
+
+A LONG, numbered list of user stories. Each user story should be in the format of:
+
+1. As an <actor>, I want a <feature>, so that <benefit>
+
+<user-story-example>
+1. As a mobile bank customer, I want to see balance on my accounts, so that I can make better informed decisions about my spending
+</user-story-example>
+
+This list of user stories should be extremely extensive and cover all aspects of the feature.
+
+## Human Decisions
+
+Calls the human made during the conversation that produced this Spec. These are load-bearing — they reflect judgement that the agent could not have inferred on its own and must survive into the slicing + implementation phases. One bullet per decision, in this shape:
+
+- **Decision:** what was decided
+- **Why:** the reason the human gave
+- **Alternatives considered:** options that were rejected and why (omit if not applicable)
+
+If a decision is genuinely just agent inference, it does not belong here — put it in `Implementation Decisions` instead.
+
+## Implementation Decisions
+
+A list of implementation decisions that were made. This can include:
+
+- The modules that will be built/modified
+- The interfaces of those modules that will be modified
+- Technical clarifications from the developer
+- Architectural decisions
+- Schema changes
+- API contracts
+- Specific interactions
+
+Do NOT include specific file paths or code snippets. They may end up being outdated very quickly.
+
+Exception: if a prototype produced a snippet that encodes a decision more precisely than prose can (state machine, reducer, schema, type shape), inline it within the relevant decision and note briefly that it came from a prototype. Trim to the decision-rich parts — not a working demo, just the important bits.
+
+## Testing Decisions
+
+A list of testing decisions that were made. Include:
+
+- A description of what makes a good test (only test external behavior, not implementation details)
+- Which seams or modules will be tested
+- Prior art for the tests (i.e. similar types of tests in the codebase)
+
+## Out of Scope
+
+A description of the things that are out of scope for this Spec.
+
+## Further Notes
+
+Any further notes about the feature.
+
+</spec-template>
+
+</supporting-info>

package/skills/engineering/to-tickets/SKILL.md

@@ -0,0 +1,158 @@
+---
+name: to-tickets
+description: Break a plan or Spec into independently-grabbable Tickets on the project issue tracker using tracer-bullet vertical slices. Use when user wants to convert a plan into Tickets, create implementation Tickets, or break down work into Tickets.
+---
+
+# To Tickets
+
+**Break a plan into independently-grabbable vertical slices and publish them to the issue tracker.**
+
+The issue tracker and triage label vocabulary should have been provided to you — if not, ask the user to run `/red-setup` and stop.
+
+<what-to-do>
+
+### Step 1 — Gather context
+
+Work from whatever is already in the conversation context. If the user passes an issue reference (issue number, URL, or path) as an argument, fetch it from the issue tracker and read its **full body and all comments** before continuing.
+
+### Step 2 — Explore the codebase (only if you haven't already)
+
+Skip if the current conversation already explored. Otherwise: read enough to understand the current state. Issue titles and descriptions **must** use the project's domain glossary vocabulary. Respect ADRs in the area you're touching.
+
+### Step 3 — Draft vertical slices
+
+Break the plan into **tracer-bullet** issues. Each slice cuts end-to-end through every layer.
+
+Apply the rules in `<supporting-info>` literally. The cardinal one: **vertical, not horizontal.**
+
+Mark each slice with its routing class:
+
+(i) **AFK** — mergeable without human decision
+(ii) **HITL** — requires an architecture call or human judgment (design review, external access)
+
+Prefer AFK over HITL wherever possible.
+
+**File disjunction check — serialize entangled slices.** After assigning routing classes, inspect every pair of parallel slices (those with no `req:N` edge between them) for file-set overlap. Two slices are *entangled* when they both write to the same file(s). Entangled concurrent slices produce a merge conflict that no runtime resolves — the conflict is inherent, not recoverable. Serialize them: add a `req:N` dependency edge from the later slice to the earlier one so only one is `ready-for-agent` at a time. Parallel slots belong exclusively to *file-disjoint* slices that touch non-overlapping file sets. This is the canonical serialization mechanism; the AFK fleet width is calibrated from the resulting disjunction structure (see `/afk fleet` docs).
+
+### Step 4 — Quiz the user (mandatory — do not skip)
+
+Present the proposed breakdown as a numbered list. For each slice show:
+
+- **Title** — short descriptive name
+- **Type** — HITL / AFK
+- **Blocked by** — which other slices (if any) must complete first
+- **User stories covered** — which user stories this addresses (if the source has them)
+
+Then ask, **explicitly**:
+
+- Does the granularity feel right? (too coarse / too fine)
+- Are the dependency relationships correct?
+- Should any slices be merged or split further?
+- Are the correct slices marked HITL vs AFK?
+
+**Iterate until the user approves the breakdown.** Do not advance to Step 5 on silence or implicit approval.
+
+### Step 5 — Cascade gate
+
+**Verify referenced `.red/` docs are landed on `origin/{base}` before publishing** — AFK workers branch from `origin/{base}` and cannot see the primary checkout's working-tree edits, so never publish while docs are unlanded.
+
+1. `git fetch origin`, then compare the `.red/` docs (`.red/CONTEXT.md`, `.red/CONTEXT-MAP.md`, `.red/contexts/**`, `.red/adr/**`) between the primary working tree and `origin/{base}` (base resolved lock > pin > main). "Landed" means reachable from `origin/{base}`, not merely present on disk — origin-first comparison, mirroring the `/review-adrs` convention.
+2. **On mismatch:** run the doc-landing procedure from the `/start` end-of-session finalizer (canonized by ADR 0092) first, then continue to Step 6.
+3. **If landing is impossible** (no network, no push access): abort — never publish while docs are unlanded. State clearly which files must be landed and stop.
+
+### Step 6 — Publish in dependency order
+
+For each approved slice, publish a new issue. Use the issue template in `<supporting-info>`.
+
+- Publish in **dependency order** (blockers first) so you can reference real issue identifiers in each "Blocked by" field
+- Tag only currently-unblocked AFK slices with the canonical `ready-for-agent` triage label (mapped string from `/red-setup`).
+- If an AFK slice has open blockers, publish it as `blocked:dependency` + one `req:N` label **per blocker** (NOT `ready-for-human` — a dependency-blocked slice is healthy and must never page a human). Also create the tracker-native blocked-by relationship for each blocker using `/red-setup` issue-tracker-github *Dependency & hierarchy operations*. The native blocked-by relationship is the human surface; req:N labels remain the machine truth for `/afk` close cascade, boot sweep, and gate census. Keep the strict `## Blocked by` task list in the body as the ADR 0094 AFK boot-sweep fallback and human-facing mirror. `req:N` labels are created on demand (`gh label create req:<n>` if missing). `/afk` auto-promotes the issue to `ready-for-agent` the moment its last dependency closes (event-driven close cascade, with the boot sweep as a safety net). See `/red-setup` triage-labels *Dependency Edges* and ADR 0094.
+  - **`req:N` targets must be executable slices, never a Spec** (authoritative statement + rationale in Hard rules below). Before creating each `req:N` label, check the target with `gh issue view N --json labels`: if #N carries `type:spec`, **refuse the edge** and re-point it at the Spec's concrete executable slice(s) instead (the child issues carrying `spec:N`); when the Spec has no slices yet, first create the concrete slice the dependent actually waits on, then point `req:N` at that slice.
+- If a slice is HITL, publish it as `ready-for-human`. Do **not** include a literal `## Blocked by` section unless it should be auto-promoted to AFK after blockers close; use `## Current blocker` / `## Human decision needed` for gates, measurements, and decisions where closing a referenced issue is not enough to make the slice delegable.
+- If the parent is a Spec (carries `type:spec` + `needs-slicing`), tag every child with `spec:{N}` referencing the parent and create the tracker-native sub-issue relationship from the parent Spec to the child Ticket using `/red-setup` issue-tracker-github *Dependency & hierarchy operations*. The native sub-issue relationship is the human surface; `spec:{N}` remains the label contract. After all slices are published, remove `needs-slicing` from the parent Spec. Never remove `type:spec` — it is a permanent type marker. Never apply `ready-for-agent` to the parent Spec itself.
+
+### Hard rules — do not break these
+
+- ❌ Do **not** mark two slices as parallelizable when they write to the same file(s) — that is a file-entanglement merge conflict waiting to happen at landing. Add `req:N` edges to serialize them instead; file-disjoint slices run in parallel, entangled ones run serial.
+- ❌ Do **not** publish until the user explicitly approved the breakdown in Step 4
+- ❌ Do **not** modify or close any parent issue
+- ❌ Do **not** create horizontal-slice issues ("the schema layer", "the API layer", "the UI layer")
+- ❌ Do **not** invent label strings — use the mapping from `/red-setup`
+- ❌ Do **not** create a `req:N` edge whose target #N is a `type:spec` — dependency edges must point at executable slices. A Spec closes only after a manual bookkeeping step long after its substance ships (#907/#928: 46/46 children closed, Specs still open), so a `req:<Spec>` edge strands the dependent in `blocked:dependency` forever. Re-point at the Spec's `spec:N` children, or, when the Spec has no slices yet, first create the concrete slice the dependent waits on and point `req:N` at that.
+- ❌ Do **not** "clean up" controlled redundancy between native tracker edges and labels/body text. Do not clean up either side: native sub-issue relationship and native blocked-by relationship edges are for humans; req:N labels remain the machine truth; the `## Blocked by` body fallback stays for compatibility.
+- ❌ Do **not** inline file paths or code snippets in issue bodies — they go stale. The one exception is in `<supporting-info>` (decision-rich prototype output)
+- ✅ **Do** publish in dependency order so "Blocked by" fields point at real issue IDs
+- ✅ **Do** prefer many thin slices over few thick ones
+
+</what-to-do>
+
+<supporting-info>
+
+## Vertical-slice rules
+
+<vertical-slice-rules>
+- Each slice delivers a narrow but COMPLETE path through every layer (schema, API, UI, tests)
+- A completed slice is demoable or verifiable on its own
+- Prefer many thin slices over few thick ones
+- Parallel slices must be file-disjoint; file-overlapping slices get `req:N` serialization edges so they run serial, not concurrent
+</vertical-slice-rules>
+
+A horizontal slice ("build the schema for all tables") cannot be demoed and cannot be merged independently — it produces issues that block each other unnecessarily and tests imagined behaviour.
+
+## Issue body template
+
+<issue-template>
+## Parent
+
+A reference to the parent Spec on the issue tracker, written as a literal `Spec #N` line (if the source was an existing Spec, otherwise omit this section). The `/afk` pin-reader parses this exact `Spec #N` form to inherit the parent's `branch:` pin — keep the word `Spec` and the `#N` reference literal.
+
+## What to build
+
+A concise description of this vertical slice. Describe the end-to-end behaviour, not layer-by-layer implementation.
+
+Avoid specific file paths or code snippets — they go stale fast. **Exception**: if a prototype produced a snippet that encodes a decision more precisely than prose can (state machine, reducer, schema, type shape), inline it here and note briefly that it came from a prototype. Trim to the decision-rich parts — not a working demo, just the important bits.
+
+## Acceptance criteria
+
+- [ ] Criterion 1
+- [ ] Criterion 2
+- [ ] Criterion 3
+
+## Blocked by
+
+- [ ] #123
+- [ ] #456
+
+Format: one GitHub task-list tracking entry per blocker, `- [ ] #N`. This is not GitHub's issue-dependencies widget. Its job is the ADR 0094 body fallback: the `/afk` boot sweep parses this exact section to auto-promote issues whose blockers have all closed, and humans still get a readable mirror in the issue body. Keep the heading literal (`## Blocked by`, capitalised, no extra punctuation) and the format strict.
+
+This section is the body fallback required by ADR 0094. When the tracker supports native edges, publish the native blocked-by relationship too; keep this section anyway so older paths and audits retain the same source shape.
+
+Omit the section entirely (do not write "None") if the slice has no blockers.
+
+For a human gate, use this shape instead:
+
+```markdown
+## Current blocker
+
+<!-- red:blocker-state v1 -->
+status: blocked
+kind: decision
+ref: #123
+summary: The dependency closed, but the measurement did not prove the required win.
+next: Human must decide whether to stop, redesign, or continue anyway.
+<!-- /red:blocker-state -->
+```
+
+</issue-template>
+
+## Wide refactors — expand → migrate → contract
+
+**When a change is blast-radius-wide** (a rename, signature change, or API move touching dozens of call sites), a single vertical slice cannot both stay small and stay mergeable. Slice it as an **expand–contract** chain instead — three (or more) Tickets that each merge green on their own:
+
+1. **Expand.** Introduce the new form *alongside* the old one — new function/flag/label/type added, old one untouched and still authoritative. Nothing calls the new form yet. This Ticket merges without changing any behaviour.
+2. **Migrate.** Move call sites onto the new form, in one Ticket per independently-verifiable batch (by package, by layer, or by directory). Each batch merges green because the old form still exists as a fallback. Many thin migration Tickets beat one giant one — a failed batch never blocks the others.
+3. **Contract.** Once every call site is migrated, remove the old form in a final Ticket. This is the only Ticket that deletes the old vocabulary, and it is `blocked:dependency` on all the migration Tickets (one `req:N` per batch).
+
+**Big-bang exception.** Some flips must NOT expand–contract — when the two forms cannot coexist (a single atomic label/flag rename with no transition window, e.g. ADR 0093's vocabulary flip), slice it as one Ticket that changes definition + call sites + tests together, and say so explicitly in the Ticket body so a reviewer does not expect a fallback. Prefer expand–contract; reach for big-bang only when coexistence is genuinely impossible or the maintainer decided against a transition window.
+
+</supporting-info>