@rune-kit/rune 2.13.0 → 2.14.0

package/skills/brainstorm/references/design-it-twice.md

@@ -0,0 +1,155 @@
+# Design-It-Twice Mode
+
+Force genuine architectural diversity when exploring alternative interfaces or module shapes. Spawns parallel subagents, each pinned to a *radically different* design constraint, then computes a diversity score before presenting results.
+
+## When to use
+
+| Situation | Use Design-It-Twice |
+|-----------|---------------------|
+| Multiple credible interface shapes for a deepening candidate (from `improve-architecture`) | ✅ |
+| User asked "what are the options for designing X?" | ✅ |
+| Ports vs no-ports decision is itself a design question | ✅ |
+| Cross-seam dependencies (remote-owned, true-external) where adapter choice matters | ✅ |
+| One obvious interface shape — translation of existing public functions | ❌ Skip; go directly to surgeon/fix |
+| Single-method utility | ❌ Skip; not enough surface to design twice |
+
+## The four standard constraints
+
+Each parallel subagent is pinned to exactly one constraint via the spawn prompt. The constraints are deliberately incompatible — that's where the diversity comes from.
+
+| ID | Constraint | What it produces |
+|----|------------|------------------|
+| `C1` | **Minimize interface** — aim for 1–3 entry points; maximize leverage per entry | Smallest interface; deep impl; few callers learn the surface |
+| `C2` | **Maximize flexibility** — support many use cases, plugin/extension surface | Wide interface; configurable; extension points |
+| `C3` | **Optimize common case** — make default trivial; rare cases pay cost | Tiny default; opt-in complexity for power users |
+| `C4` | **Ports & adapters** — design seams for cross-boundary swap | Explicit ports; multiple adapter slots |
+
+For most cases pick 3 of 4. Add C4 only when the dependency category (from `improve-architecture/references/deepening.md`) is `remote-owned` or `true-external`.
+
+## Subagent spawn template
+
+```
+You are designing an interface for: <module description>
+
+Current state:
+  files: <file list>
+  callers: <caller summary>
+  current_depth: <1-5>
+  dependency_category: <in-process | local-substitutable | remote-owned | true-external>
+  what_to_hide: <state, lifecycle, retry, error transformation>
+
+Constraint: <C1 | C2 | C3 | C4>
+  <constraint description from the table above>
+
+Output (YAML):
+  interface:
+    name: <DeepenedModuleName>
+    methods:
+      - signature: <method signature>
+        invariants: [<invariant 1>, <invariant 2>]
+        errors: [<error case 1>, <error case 2>]
+  usage_example: |
+    <code showing how a caller invokes the interface>
+  hides_behind_seam:
+    - <complexity 1 hidden inside the implementation>
+    - <complexity 2>
+  dependency_strategy:
+    category: <category>
+    adapters: [<adapter1>, <adapter2>]
+    seam_real: <true if adapters >= 2, false if 1 (downgrade to internal seam)>
+  tradeoffs:
+    leverage: <1-5 + 1-line justification>
+    flexibility: <1-5 + 1-line justification>
+    common_case_simplicity: <1-5 + 1-line justification>
+
+Vocabulary: use the controlled terms from rune:improve-architecture/references/language.md
+  (module, interface, seam, adapter, leverage, locality)
+  Do NOT use "boundary", "component", "service", or "layer" in narrative.
+
+Domain terms: <if CONTEXT.md present, list its glossary terms here so the design uses them>
+```
+
+## Diversity gate (machine-checked)
+
+After all subagents return, compute pairwise similarity over feature vectors:
+
+```
+feature_vector(design) = [
+  count(interface.methods),
+  count(distinct_return_types),
+  count(unique_adapter_kinds),
+  count(unique_dependencies),
+  paradigm_tag,           // "minimal" | "extensible" | "default-light" | "ports-adapters"
+  has_async_methods,      // bool → 0/1
+  has_streaming,          // bool → 0/1
+]
+```
+
+Diversity score:
+```
+similarity(d_i, d_j) = jaccard(feature_vector(d_i), feature_vector(d_j))
+diversity = 1 - mean(similarity(d_i, d_j) for all i < j)
+```
+
+| Diversity | Action |
+|-----------|--------|
+| ≥ 0.6 | Proceed to presentation |
+| 0.4 – 0.59 | Marginal; surface to user — "designs are similar in [shared trait]; want me to re-spawn with different constraints?" |
+| < 0.4 | Re-spawn with rotated constraints (e.g., swap C2 → C4); 1 retry max before giving up |
+
+`diversity_floor = 0.4` is conservative; tune in v0.7+ once usage telemetry exists.
+
+## Presentation order
+
+1. Each design alone (sequential, so user can absorb each in isolation)
+2. Comparison table contrasting designs by:
+   - **Depth** — leverage at the interface
+   - **Locality** — where change concentrates
+   - **Seam placement** — internal vs external; ports yes/no
+   - **Common-case trivial-ness** — how much work for the default path
+3. **Opinionated recommendation** — strongest design + concrete hedge condition for when to pick a different one
+4. **Hybrid synthesis (optional Step 4.5)** — if 2 designs have complementary strengths, propose a 4th synthesized option that combines them
+
+Skip the comparison table if N=2 (just 1 contrast, prose handles it).
+
+## "It depends" is BLOCKED
+
+The recommendation step requires a concrete recommendation with a hedge:
+
+✅ "Recommend C1 (minimize interface). Choose C3 (optimize common case) if you discover most callers only need the default path."
+
+❌ "It depends on your priorities."
+
+If you genuinely can't pick between two designs, propose the hybrid (Step 4.5) and recommend that as the default.
+
+## Hybrid synthesis (Step 4.5 — optional)
+
+When two designs have complementary strengths (e.g., C1's leverage + C4's seam discipline), propose a 4th option that combines them:
+
+```
+Option D (Hybrid C1 + C4):
+  - Interface: 3 methods (from C1's minimization)
+  - Adapters: HttpAdapter + InMemoryAdapter (from C4's port discipline)
+  - Pros: small surface AND testable across the seam
+  - Cons: more upfront design work; locks the port early
+```
+
+Hybrid synthesis is **opt-in**. If no two designs have clear complementary strengths, skip this step.
+
+## Cost note
+
+4 parallel opus subagents is the most expensive thing this skill does. Use Design-It-Twice mode only when `improve-architecture` flags a candidate worth deepening (multiple credible interfaces). Default Discovery mode is cheaper for ordinary brainstorming.
+
+## Output schema (chain_metadata)
+
+```yaml
+chain_metadata:
+  skill: "rune:brainstorm"
+  mode: "design-it-twice"
+  exports:
+    designs: [<yaml-per-design>]
+    diversity_score: 0-1
+    constraints_used: [C1, C2, C4]
+    recommendation: <design-id>
+    hybrid_proposed: <true|false>
+```

package/skills/context-pack/SKILL.md

@@ -4,7 +4,7 @@ description: "Creates structured handoff briefings between agents. Use when dele
 user-invocable: false
 metadata:
   author: runedev
-  version: "0.1.0"
+  version: "0.2.0"
   layer: L3
   model: haiku
   group: state
@@ -52,12 +52,13 @@ When a parent agent delegates work to a subagent, critical context gets lost —
 ## Workflow
 
 1. **COLLECT** — Gather context from the current conversation:
-   - Task description and user intent
+   - Task description and user intent (verb-led behavioral phrasing)
    - Decisions already made (and WHY)
    - Constraints and hard-stops
    - Failed attempts (what NOT to do)
    - Files already read or modified
    - Current progress state
+   - **Type Surface** — types / function signatures / contracts that callers cross. These are the durable spine of the brief.
 
 2. **COMPRESS** — Reduce to essential information:
    - Strip conversational noise
@@ -65,46 +66,74 @@ When a parent agent delegates work to a subagent, critical context gets lost —
    - Prioritize by relevance to the delegated task
    - Target: <500 tokens for simple tasks, <1500 tokens for complex
 
-3. **STRUCTURE** — Format as a context packet (see Output Format)
+3. **STRUCTURE** — Format as a context packet (v2 — see Output Format and [references/brief-template.md](references/brief-template.md))
 
 4. **VALIDATE** — Check packet completeness:
    - Does it include the task goal?
    - Does it include constraints that could cause failure?
    - Does it include what was already tried?
+   - Does it include `### Out of scope`? (mandatory)
+   - Does it include `### Type Surface` (mandatory if task >= 300 tokens)?
    - Is it small enough for the target agent's context budget?
 
-## Output Format
+5. **PHASE 4.5 — SMELL TESTS** — Run mechanical regex gates before emit. See [references/durability-rules.md](references/durability-rules.md).
+
+   | Regex | Tier | Reason |
+   |-------|------|--------|
+   | `\b\S+\.[a-z]{1,4}:\d+\b` | BLOCK | file:line reference (e.g., `login.ts:42`) — line numbers go stale |
+   | `^- \S*[\\/]\S+\.(ts\|js\|py\|go\|rs\|java)\b` outside `### Files Touched` | BLOCK | Path-only bullet in narrative |
+   | `\b(line \|on line )\d+\b` | BLOCK | "line 42" / "on line 100" |
+   | `\b(src\|lib\|app)/\S+` in narrative paragraphs | WARN | Path mention; verify it belongs in Files Touched section |
+
+   <HARD-GATE>
+   Any BLOCK-tier match → DO NOT emit. Rewrite the offending lines to use type/function/module names.
+   Missing `### Out of scope` section → DO NOT emit (completion-gate rejects).
+   Missing `### Type Surface` for tasks >= 300 tokens → DO NOT emit.
+   </HARD-GATE>
+
+6. **EMIT** — Send the validated packet to the receiving agent.
+
+## Output Format (v2)
 
 ```markdown
 ## Context Packet
 
-**Task**: [One-line description of what the subagent must do]
-**Parent**: [Which skill/agent is delegating]
-**Scope**: [Specific files, modules, or boundaries]
+**Task**: [One-line behavioral description, verb-led]
+**Parent**: [delegating skill]
+**Scope**: [type names / module names — NOT file paths]
 
 ### Decisions Made
-- [Decision 1]: [choice] — because [reason]
-- [Decision 2]: [choice] — because [reason]
+- [Decision]: chose [X] over [Y] because [reason]
 
 ### Constraints
-- MUST: [requirement 1]
-- MUST NOT: [prohibition 1]
-- BLOCKED BY: [dependency, if any]
+- MUST: [behavioral assertion]
+- MUST NOT: [behavioral prohibition]
+- BLOCKED BY: [contract dependency, not file path]
 
 ### Already Tried
-- [Approach that failed] — [why it failed]
+- [approach] — [observable failure mode]
 
-### Files Touched
-- `path/to/file.ts` — [what was done / what needs doing]
+### Type Surface (durable)
+- `TypeName { field: type }` — [what it represents]
+- `Module.method(input: T): Result<O, E>` — [contract]
 
-### Success Criteria
-- [ ] [Verifiable criterion 1]
-- [ ] [Verifiable criterion 2]
+### Files Touched (locator-only, may rename)
+- `path/to/file.ts` (TypeName, Module.method) — [behavioral hint]
+
+### Acceptance Criteria
+- [ ] [verb-led testable statement starting with: accepts, rejects, produces, notifies, persists, retries, times-out, validates, returns, dispatches, redirects, throws, logs, increments, decrements, retrieves, emits, caches, invalidates, authenticates]
+- [ ] ...
+
+### Out of scope
+- [Thing the receiver should NOT do]
+- (or "(none)" if explicitly empty)
 
 ### Progress
-- [What's done so far, if partial handoff]
+- [partial state if mid-handoff — omit if fresh start]
 ```
 
+Full template + worked examples: [references/brief-template.md](references/brief-template.md).
+
 ## Returns
 
 | Field | Type | Description |
@@ -116,32 +145,46 @@ When a parent agent delegates work to a subagent, critical context gets lost —
 
 ## Constraints
 
-1. MUST include task goal and success criteria — subagent needs to know when it's done
+1. MUST include task goal and acceptance criteria — subagent needs to know when it's done
 2. MUST include failed attempts — prevents subagent from repeating mistakes
 3. MUST include hard-stop constraints — prevents constraint violations in delegated work
 4. MUST NOT exceed 2000 tokens — context packets that are too large defeat the purpose
-5. MUST NOT include full file contents — use file paths and summaries instead
+5. MUST NOT include full file contents — use type names + summaries instead
 6. MUST NOT fabricate context — only include information from the actual conversation
+7. MUST emit `### Out of scope` section — empty `(none)` allowed, missing section is rejected by completion-gate
+8. MUST emit `### Type Surface` section for tasks >= 300 tokens — durable contract spine
+9. MUST pass all BLOCK-tier smell tests — no file:line references, no "line N", no narrative path-only bullets
+10. MUST use behavior verbs in Acceptance Criteria — shape verbs ("is defined", "has property") rejected
 
 ## Sharp Edges
 
 | Failure Mode | Severity | Mitigation |
 |---|---|---|
-| Packet too large (>2000 tokens) | HIGH | Compress aggressively — file paths not contents, decisions not discussions |
+| Packet too large (>2000 tokens) | HIGH | Compress aggressively — type names not file contents, decisions not discussions |
 | Missing constraint causes subagent violation | CRITICAL | Always scan for MUST/MUST NOT in parent conversation |
 | Stale context from prior session included | MEDIUM | Cross-check session-bridge state with current files |
 | Over-constraining subagent with parent's approach | MEDIUM | Include constraints and goals, not implementation approach (unless approach is the constraint) |
+| File:line references in packet (rotting briefs) | CRITICAL | Phase 4.5 BLOCK gate — regex `\b\S+\.[a-z]{1,4}:\d+\b` catches them; rewrite to type/function names |
+| Narrative paragraphs with bare paths (`src/auth/`) | MEDIUM | WARN tier — surface and rewrite or move to Files Touched table |
+| Missing Type Surface section for non-trivial task | HIGH | Mandatory for tasks >= 300 tokens; the durable spine is what survives file moves |
+| Missing Out of scope section | HIGH | Always required (even "(none)"); completion-gate rejects briefs without it |
+| Acceptance Criteria using shape verbs ("is defined", "has property") | MEDIUM | Rewrite to behavior verbs from the whitelist |
 
 ## Self-Validation
 
 ```
 SELF-VALIDATION (run before emitting output):
-- [ ] Packet includes a clear task goal
-- [ ] Packet includes success criteria (verifiable, not vague)
+- [ ] Packet includes a clear task goal (verb-led)
+- [ ] Packet includes acceptance criteria (verb-led, testable, not vague)
 - [ ] All MUST/MUST NOT constraints from parent are present
 - [ ] Failed attempts are listed (if any exist)
 - [ ] Token estimate is under 2000
-- [ ] No full file contents embedded (paths only)
+- [ ] No full file contents embedded (type names + paths only)
+- [ ] No file:line references anywhere (regex check)
+- [ ] No bare-path narrative bullets outside Files Touched
+- [ ] ### Out of scope section present (even if "(none)")
+- [ ] ### Type Surface section present (if task >= 300 tokens)
+- [ ] Files Touched entries include (TypeName, function) annotations
 IF ANY check fails → fix before reporting done. Do NOT defer to completion-gate.
 ```
 

package/skills/context-pack/evals.md

@@ -0,0 +1,122 @@
+# Eval Scenarios — `context-pack` skill
+
+## Eval: E01 — happy-path good packet emits cleanly
+
+### Prompt
+Cook calls context-pack to hand off a feature: "Add device_id field to login flow." Decisions: track at login, optional field. Constraints: preserve backward compat, don't touch rate limits.
+
+### Expected Reasoning
+Agent emits a v2-format packet with all required sections (Task / Parent / Scope / Decisions / Constraints / Type Surface / Files Touched / Acceptance Criteria / Out of scope). Acceptance criteria use behavior verbs. Type Surface lists `LoginInput`, `AuthService.authenticate`, `Session`. Files Touched annotated with type names.
+
+### Must Include
+- `### Type Surface (durable)` section with at least 2 type entries
+- `### Out of scope` section (even if "(none)")
+- All ACs start with whitelisted behavior verbs
+- Files Touched entries include `(TypeName, function)` annotations
+
+### Must NOT
+- Reference file:line (e.g., `login.ts:42`)
+- Use shape verbs ("should be defined", "has property")
+- Skip Out of scope section
+
+### Category
+happy-path
+
+---
+
+## Eval: E02 — file:line BLOCK violation caught
+
+### Prompt
+A draft packet contains: "Modify the function at `src/auth/login.ts:42` to handle the new field."
+
+### Expected Reasoning
+Agent runs the smell-test regex `\b\S+\.[a-z]{1,4}:\d+\b` and matches `login.ts:42`. BLOCK tier. Refuses to emit. Rewrites the prose to use type/function names: "Modify `AuthService.authenticate` to handle the new field."
+
+### Must Include
+- Smell-test BLOCK verdict surfaced
+- Specific regex match cited
+- Rewrite suggestion that uses behavioral language
+
+### Must NOT
+- Emit the packet with the file:line still present
+- "Just this once" exception language
+
+### Category
+adversarial
+
+---
+
+## Eval: E03 — narrative path WARN handling
+
+### Prompt
+A draft packet contains a narrative paragraph: "The work is centered around `src/auth/`, particularly the login flow."
+
+### Expected Reasoning
+Agent matches narrative path regex (WARN tier). Surfaces the warning, asks: is this narrative the right section? If it belongs in `### Files Touched`, move it; if it stays in narrative, rewrite to a type/module name.
+
+### Must Include
+- WARN verdict (not BLOCK — narrative paths are softer)
+- Suggestion to either move or rewrite
+- No automatic emission until resolved
+
+### Must NOT
+- BLOCK on a WARN-tier match
+- Auto-rewrite without surfacing
+
+### Category
+edge-case
+
+---
+
+## Eval: E04 — missing Out of scope section
+
+### Prompt
+A draft packet has all sections except Out of scope.
+
+### Expected Reasoning
+Agent recognizes mandatory section. Either prompts the parent for the out-of-scope list, OR explicitly emits `### Out of scope\n- (none)` if the parent confirms there's nothing to exclude. Never silently omits.
+
+### Must Include
+- Either an Out of scope section (potentially empty with explicit "(none)")
+- OR a request back to parent for the exclusion list
+- Reference to Phase 4.5 / `completion-gate` rejection rule
+
+### Must NOT
+- Emit the packet without Out of scope
+- Auto-fill with assumed exclusions
+
+### Category
+adversarial
+
+---
+
+## Eval: E05 — Type Surface optional for short task
+
+### Prompt
+A simple bug fix handoff: "Fix typo in error message — '404 Note Found' → '404 Not Found'." Task body is ~80 tokens.
+
+### Expected Reasoning
+Agent recognizes that the task is below the 300-token threshold where Type Surface becomes mandatory. Emits a packet without Type Surface, but still includes Out of scope and behavioral ACs.
+
+### Must Include
+- Out of scope section (mandatory regardless of task size)
+- AC with behavior verb (e.g., "Returns the corrected error message on 404")
+- Note in packet header that Type Surface is omitted because task is below threshold
+
+### Must NOT
+- Force a Type Surface section for a one-line text fix
+- Skip Out of scope (still mandatory)
+
+### Category
+edge-case
+
+---
+
+## Eval Coverage
+
+| Category | Count | Status |
+|---|---|---|
+| happy-path | 1 | ✅ E01 |
+| edge-case | 2 | ✅ E03, E05 |
+| adversarial | 2 | ✅ E02, E04 |
+| **Total** | **5** | **✅ above minimum (4)** |

package/skills/context-pack/references/brief-template.md

@@ -0,0 +1,121 @@
+# Brief Template (v2)
+
+Use this verbatim. Receivers expect every section. Sections marked optional may be omitted only if there's nothing to record (not because the writer didn't bother).
+
+```markdown
+## Context Packet
+
+**Task**: [One-line behavioral description, verb-led: "Add rate limiting to login route"]
+**Parent**: [delegating skill — e.g., cook]
+**Scope**: [type names / module names — NOT file paths]
+
+### Decisions Made
+- [Decision]: chose [X] over [Y] because [reason]
+- ...
+
+### Constraints
+- MUST: [behavioral assertion — "preserve existing 1hr rate-limit window"]
+- MUST NOT: [behavioral prohibition — "modify the audit log writer"]
+- BLOCKED BY: [contract dependency — "the auth.token-refresh contract finalized in PR #42"]
+
+### Already Tried
+- [Approach] — [observable failure mode]
+
+### Type Surface (durable)
+- `TypeName { field: type; field: type }` — what it represents
+- `Module.method(input: T): Result<O, E>` — the contract
+- `ErrorEnum = "case_a" | "case_b"` — what callers switch on
+
+### Files Touched (locator-only, may rename)
+- `path/to/file.ts` (TypeName, Module.method) — [behavioral hint]
+- ...
+
+### Acceptance Criteria
+- [ ] [Verb-led testable statement — "Rejects login attempts with 429 after 5 failures within 1 hour"]
+- [ ] ...
+
+### Out of scope
+- [Thing the receiver should NOT do]
+- [Adjacent feature that might seem related but is separate]
+- (or "(none)" if nothing to exclude)
+
+### Progress
+- [What's done so far, if partial handoff — omit if fresh start]
+```
+
+## Behavioral verb whitelist
+
+Every Acceptance Criterion must start with one of these:
+
+```
+accepts          dispatches      logs              redirects        retrieves
+rejects          throws          increments        retries           returns
+produces         times-out       decrements        notifies          validates
+persists         emits           caches            invalidates       authenticates
+```
+
+Verbs not on the whitelist may still be valid; check whether the criterion describes *observable behavior* (good) or *shape* ("is defined", "has property", "exists") — shape verbs are banned.
+
+## Worked example
+
+### ✅ Good packet
+
+```markdown
+## Context Packet
+
+**Task**: Add device tracking to login flow
+**Parent**: cook
+**Scope**: AuthService, LoginInput, sessions table
+
+### Decisions Made
+- Track device_id at login: chose passing through to session storage over hashing in-app, because compliance requires preserving raw values for audit window
+- Optional field: chose nullable rather than required, because mobile clients prior to v3.2 don't send it
+
+### Constraints
+- MUST: preserve backward-compatible login for clients without device_id
+- MUST NOT: change rate-limit window (currently 1hr)
+
+### Already Tried
+- Storing in JWT claims — rejected because tokens grow past mobile size limit
+
+### Type Surface (durable)
+- `LoginInput { email: string; password: string; device_id?: string }` — payload accepted by login route
+- `AuthService.authenticate(input: LoginInput): Result<Session, AuthError>` — primary contract
+- `Session { user_id: string; created_at: Date; device_id: string | null }` — issued on success
+
+### Files Touched (locator-only, may rename)
+- `src/auth/login.ts` (LoginInput, AuthService.authenticate) — route handler
+- `src/db/migrations/sessions.sql` (sessions table) — schema
+
+### Acceptance Criteria
+- [ ] Persists device_id to sessions table when login succeeds and device_id is provided
+- [ ] Persists null when device_id is absent
+- [ ] Returns AuthError 'invalid_credentials' on bad password (existing behavior unchanged)
+
+### Out of scope
+- Changing rate-limit window
+- Updating mobile client SDKs
+- Audit log writer
+```
+
+### ❌ Bad packet (would fail smell tests)
+
+```markdown
+## Context Packet
+
+**Task**: fix the login
+
+**Files**: src/auth/login.ts:42, src/types.ts:18
+
+The function around line 100 has a bug. Add a device field. See `src/handlers/`.
+```
+
+Failures:
+- No section structure
+- File:line references (`login.ts:42`)
+- "line 100" — line-number reference
+- "around line" — narrative path
+- No Type Surface
+- No Out of scope
+- No Acceptance Criteria with behavior verbs
+- Vague task description ("fix the login")

package/skills/context-pack/references/durability-rules.md

@@ -0,0 +1,109 @@
+# Durability Rules — Why Briefs Rot, How to Stop It
+
+A subagent receives a context packet. A day later, after a refactor, that packet's file paths point to renamed files, line numbers point to shifted code, and "the function in `src/auth/login.ts:42`" no longer exists. The subagent burns tokens grepping to recover or — worse — generates hallucinated edits matching the stale brief.
+
+The fix is to write briefs that describe **types and contracts**, which survive moves, instead of **paths and line numbers**, which don't.
+
+## The 5 rules
+
+### 1. Behavioral over procedural
+
+Describe what the system *does*, not *where* the code lives.
+
+| ❌ Bad | ✅ Good |
+|--------|---------|
+| "Open `src/handlers/login.ts` and modify line 42" | "When a login fails 5 times, the rate limiter should reject the next attempt with a 429 response and a `Retry-After` header" |
+| "Add the field to the type at `src/types.ts:18`" | "The `LoginInput` type should accept an optional `device_id: string`" |
+| "Refactor the function around line 150 in `main.ts`" | "Extract the password-hashing path into its own module so it can be tested independently" |
+
+### 2. Type names over file paths in narrative
+
+When you must reference code in narrative prose, refer to **type names, function names, or contracts** — not file paths.
+
+| ❌ Bad | ✅ Good |
+|--------|---------|
+| "Update the function in `src/auth/`" | "Update the `authenticate` method on `AuthService`" |
+| "Modify `src/db/migrations/0042.sql`" | "The new migration should add a `device_id` column to the `sessions` table, nullable, with a default of `NULL`" |
+
+File paths may appear in a clearly-marked `### Files Touched` table — never in narrative prose.
+
+### 3. Type Surface section
+
+Add a `### Type Surface` section listing the contracts that *won't* change even if files do. This is the durable spine of the brief.
+
+```markdown
+### Type Surface (durable)
+- `LoginInput { email: string; password: string; device_id?: string }` — payload accepted by the login route
+- `AuthService.authenticate(input: LoginInput): Result<Session, AuthError>` — primary contract
+- `AuthError = "invalid_credentials" | "rate_limited" | "account_locked"` — error union the caller switches on
+```
+
+If a file gets renamed but `AuthService.authenticate` keeps its shape, the brief still applies. If the contract changes, the brief is invalidated — that's a feature, not a bug.
+
+### 4. Out of scope is mandatory
+
+Every brief includes `### Out of scope`. Receivers expand into adjacent work without this anchor. Empty list is fine *if explicitly empty* (`### Out of scope\n- (none)`); missing section is rejected by completion-gate.
+
+```markdown
+### Out of scope
+- Changing the rate-limit window (currently 1 hour — keep it)
+- Touching the audit log writer (separate ticket)
+- Anything in `src/billing/` — different domain
+```
+
+### 5. Behavioral verbs in acceptance criteria
+
+Each acceptance criterion must start with a verb from the whitelist:
+
+```
+accepts, rejects, produces, notifies, persists, retries, times-out, validates,
+returns, dispatches, redirects, throws, logs, increments, decrements, retrieves
+```
+
+Banned verb-less constructs ("the field should be present", "the type is exported") describe shape, not behavior.
+
+| ❌ Bad | ✅ Good |
+|--------|---------|
+| "The new field should exist" | "Persists the device_id when login succeeds" |
+| "An error type should be defined" | "Returns AuthError 'rate_limited' when 5 failures occur within 1 hour" |
+
+## Smell tests (mechanical regex gates)
+
+`context-pack` Phase 4.5 runs these regex against the packet body before emit. Any BLOCK-tier hit fails the gate.
+
+| Regex | Tier | Reason |
+|-------|------|--------|
+| `\b\S+\.[a-z]{1,4}:\d+\b` | BLOCK | file:line reference (e.g., `login.ts:42`) — line numbers go stale |
+| `^- \S*[\\/]\S+\.(ts\|js\|py\|go\|rs\|java)\b` (in non-`Files Touched` sections) | BLOCK | Path-only bullet in narrative |
+| `\b(line \|on line )\d+\b` | BLOCK | "line 42" / "on line 100" |
+| `\b(src\|lib\|app)/\S+` (in narrative paragraphs) | WARN | Path mention; check if it's in the right section |
+
+Whitelist for `### Files Touched` table — paths there must include the type/function name in parens for durability:
+
+```
+- `src/auth/login.ts` (LoginInput, AuthService.authenticate) — the route handler
+```
+
+Without the parens annotation, even the table entry is too brittle.
+
+## When durability rules can be relaxed
+
+Two narrow exceptions:
+
+1. **Single-cycle short tasks** (<300 tokens, <3 files) — the brief lives only as long as one cycle, and the receiving agent will execute immediately. Type Surface section becomes optional.
+2. **Bug-fix briefs with concrete repro** — sometimes the bug *is* on a specific line of a specific file as it exists right now. In that case, paths may appear in narrative IF accompanied by the type/function name. Example: *"In `AuthService.authenticate` (currently `src/auth/service.ts`), the comparison uses `<` instead of `<=`."*
+
+The rules above are defaults; the exceptions are explicit and rare. When in doubt, follow the rules.
+
+## Self-check before emit
+
+```
+[ ] Every narrative reference uses type/function names, not file paths
+[ ] Type Surface section lists contracts that won't change with file moves
+[ ] Out of scope section exists (even if "(none)")
+[ ] Every Acceptance Criterion starts with a behavior verb
+[ ] No file:line references appear anywhere
+[ ] Files Touched table entries have (Type, function) annotations
+```
+
+If any check fails, fix before the receiving agent gets the packet. A stale brief is worse than no brief at all.