@rune-kit/rune 2.13.0 → 2.15.0

package/skills/context-engine/SKILL.md

@@ -4,11 +4,12 @@ description: "Context window management. Auto-triggered when context is filling
 user-invocable: false
 metadata:
   author: runedev
-  version: "1.0.0"
+  version: "1.1.0"
   layer: L3
   model: haiku
   group: state
   tools: "Read, Glob, Grep"
+  emit: context.preview
 ---
 
 # context-engine
@@ -49,6 +50,7 @@ Context-engine also manages **behavioral mode injection** via `contexts/` direct
 - `rescue` (L1): between refactoring sessions for state persistence
 - `context-pack` (L3): when packaging context for sub-agent handoff
 - `session-bridge` (L3): coordinates with context-engine for compaction timing
+- `adversary` (L2): (oracle-mode) emit `context.preview` before bundle build to gate token cost
 
 ## Execution
 
@@ -375,11 +377,90 @@ When Context Budget Warning fires, append to Context Health report:
 - **Recommendation**: Disable [server] to save ~[N]k tokens
 ```
 
+## Mode: preview (v1.1.0)
+
+Pre-flight cost check for expensive escalations. Caller (`adversary` oracle-mode, `team` workstream spawn, `review` multi-file, `audit` cross-pack) MUST emit `context.preview` BEFORE building the bundle, so context-engine can estimate token cost and gate the dispatch against a per-caller threshold.
+
+### Why
+
+Without preview, callers learn about budget overruns AFTER the bundle is built and dispatched — too late to prune. `team` parallel workstreams especially can blow $20 of Opus tokens in a single session if context bundles are unchecked.
+
+### Token Estimation (no tokenizer dep)
+
+```
+estimated_tokens = total_chars × 0.25
+```
+
+Char count includes the `[SYSTEM]` line, `[USER]` line, and all `### File N:` blocks per `references/preview-gate.md`. The 0.25 ratio is calibrated for English code/markdown — overestimates Japanese/Chinese, underestimates highly-repetitive content. Both error directions are safe (overestimate → over-cautious block; underestimate → caller still hits dispatch-time hard cap).
+
+### Threshold Defaults (per caller)
+
+| Caller | warn-at (tokens) | block-at (tokens) |
+|--------|------------------|-------------------|
+| `adversary` oracle-mode | 50k | 100k |
+| `team` parallel workstream (per worker) | 30k | 80k |
+| `review` multi-file | 40k | 100k |
+| `audit` cross-pack | 60k | 120k |
+
+Caller passes its identity in the preview request; context-engine resolves to the correct threshold.
+
+### Action Enum
+
+`context.preview` payload includes a single `action` field:
+
+| Action | Meaning | Caller behavior |
+|--------|---------|-----------------|
+| `proceed` | Under warn threshold | Continue without warning |
+| `warn` | Between warn and block | Log warning to user, continue |
+| `block` | At or over block threshold | Abort dispatch, emit caller-specific failure (e.g. `oracle.failed` reason=`context_budget_exceeded`) |
+
+### Signal Payload Schema
+
+```yaml
+context.preview:
+  caller: adversary | team | review | audit
+  estimated_tokens: <int>
+  file_count: <int>
+  top_5_files_by_size:
+    - { path: <string>, chars: <int> }
+  threshold:
+    warn_at: <int>
+    block_at: <int>
+  action: proceed | warn | block
+```
+
+### Step P1 — Receive request
+
+Caller invokes context-engine with: caller-id, file list (paths + char counts), prompt char count.
+
+### Step P2 — Estimate
+
+Sum total chars, multiply by 0.25, identify top 5 files by size.
+
+### Step P3 — Resolve threshold
+
+Look up caller in threshold table (defaults above; override via `RUNE_CONTEXT_THRESHOLDS_<CALLER>` env var).
+
+### Step P4 — Determine action
+
+```
+if estimated_tokens >= block_at: action = block
+elif estimated_tokens >= warn_at: action = warn
+else: action = proceed
+```
+
+### Step P5 — Emit
+
+Emit `context.preview` with full payload. Caller decides whether to proceed.
+
+See `references/preview-gate.md` for tunable points and integration with each caller.
+
 ## Constraints
 
 1. MUST preserve context fidelity — no summarizing away critical details
 2. MUST flag context conflicts between skills — never silently pick one
 3. MUST NOT inject stale context from previous sessions without marking it as historical
+4. (preview) MUST emit `context.preview` BEFORE bundle-building begins (not after) — late emission defeats the gate purpose
 
 ## Sharp Edges
 
@@ -394,6 +475,8 @@ Known failure modes for this skill. Check these before declaring done.
 | Not activating large-file adjustment on Python/Java codebases | MEDIUM | Track Read calls returning >500 lines; if ≥3 occur, switch to adjusted (0.8x) thresholds for the session |
 | Mid-loop compaction breaks tool_use/tool_result pair | CRITICAL | Always keep tool pairs together — splitting causes orphaned results and context corruption |
 | Mid-loop compaction without flushing state first | HIGH | session-bridge + neural-memory MUST run before compaction — losing unsaved decisions is worse than hitting context limit |
+| (preview) Caller bundles before requesting preview | HIGH | Constraint 4 enforces order; reject preview-after-build calls with explicit error |
+| (preview) Estimated tokens off by 2x for non-English content | LOW | Document calibration in `references/preview-gate.md`; safe both directions (block-too-eager or block-too-late but hard cap at dispatch saves us) |
 
 ## Done When
 
@@ -402,6 +485,7 @@ Known failure modes for this skill. Check these before declaring done.
 - Appropriate advisory emitted matching health level (no advisory for GREEN)
 - If RED: session-bridge called and confirmed saved before compaction signal
 - Context Health Report emitted with tool count, status, and recommendation
+- (preview-mode) `context.preview` emitted with `action` ∈ `proceed | warn | block` BEFORE caller builds its bundle
 
 ## Cost Profile
 

package/skills/context-engine/references/preview-gate.md

@@ -0,0 +1,139 @@
+# Context Preview Gate
+
+## Purpose
+
+Pre-flight cost check for expensive escalations. Before any caller bundles a large context for dispatch (oracle-mode second-opinion, parallel workstream spawn, multi-file review, cross-pack audit), `context-engine` emits `context.preview` with a token-cost estimate and an action recommendation. The caller decides whether to proceed, warn, or abort.
+
+## Why
+
+Without a preview gate:
+- Callers learn about budget overruns only after dispatch — too late to prune
+- `team` parallel workstreams can blow $20 of Opus tokens silently
+- Users have no way to enforce per-call cost ceilings
+
+With the preview gate:
+- Costs are visible at decision time, not bill time
+- Per-caller thresholds enforce different budgets per use case
+- Hard `block` action prevents accidental runaway
+
+## Token Estimation
+
+```
+estimated_tokens = total_chars × 0.25
+```
+
+Where `total_chars` includes:
+- The bundle's `[SYSTEM]` line
+- The `[USER]` problem statement
+- Every `### File N: <path>` header
+- Every file body (post-truncation, post-redaction)
+
+The `0.25` ratio is calibrated for English code/markdown:
+
+| Content type | Calibration |
+|--------------|-------------|
+| English code (TypeScript/Python/JS) | accurate ±10% |
+| English markdown / docs | accurate ±5% |
+| Japanese / Chinese / Korean | underestimates by 30-50% |
+| Highly-repetitive (lots of imports) | overestimates by 20-30% |
+
+Both error directions are safe:
+- Overestimate → over-cautious block, caller can manually override
+- Underestimate → caller still hits the dispatch-time hard cap (e.g. adversary's 100k token limit) and aborts with `oracle.failed`
+
+## Threshold Defaults
+
+| Caller | warn-at | block-at | Rationale |
+|--------|---------|----------|-----------|
+| `adversary` oracle-mode | 50,000 | 100,000 | Single-shot diagnosis; 100k matches second-model context budget |
+| `team` parallel workstream (per worker) | 30,000 | 80,000 | Per-worker; total may be 5x if 5 workers spawn |
+| `review` multi-file | 40,000 | 100,000 | Code review benefits from breadth; cap protects opus budget |
+| `audit` cross-pack | 60,000 | 120,000 | Audit is intentionally broad; raised cap reflects intent |
+
+### Override
+
+Set environment variables to override per-caller thresholds:
+
+```
+RUNE_CONTEXT_THRESHOLDS_ADVERSARY=warn:60000,block:120000
+RUNE_CONTEXT_THRESHOLDS_TEAM=warn:40000,block:100000
+RUNE_CONTEXT_THRESHOLDS_REVIEW=warn:50000,block:130000
+RUNE_CONTEXT_THRESHOLDS_AUDIT=warn:80000,block:150000
+```
+
+## Action Decision
+
+```
+if estimated_tokens >= block_at:
+    action = "block"
+elif estimated_tokens >= warn_at:
+    action = "warn"
+else:
+    action = "proceed"
+```
+
+## Caller Integration
+
+### `adversary` oracle-mode
+
+```
+Phase 0 (pre-bundle): emit context.preview { caller: adversary, files: [...], prompt: "..." }
+  context-engine returns { action: "proceed" }     → continue with bundle build
+  context-engine returns { action: "warn" }        → log warning, continue
+  context-engine returns { action: "block" }       → abort, emit oracle.failed reason=context_budget_exceeded
+```
+
+### `team` parallel workstream
+
+```
+Phase 2 ASSIGN (per worker): emit context.preview { caller: team, files: [...] }
+  proceed → spawn worker
+  warn    → log warning, spawn worker
+  block   → reduce worker scope or split into 2 smaller workers
+```
+
+### `review` multi-file
+
+```
+Entry step: emit context.preview { caller: review, files: [...] }
+  proceed → run review
+  warn    → log warning, run review
+  block   → ask user to narrow file scope (e.g. specific subdirectory)
+```
+
+### `audit` cross-pack
+
+```
+Entry step: emit context.preview { caller: audit, files: [...] }
+  proceed → run audit
+  warn    → log warning, run audit
+  block   → reduce audit scope (e.g. one pack at a time)
+```
+
+## Signal Payload
+
+```yaml
+context.preview:
+  caller: adversary | team | review | audit
+  estimated_tokens: 73000
+  file_count: 8
+  top_5_files_by_size:
+    - { path: "src/auth/login.ts", chars: 12400 }
+    - { path: "src/middleware/auth.ts", chars: 9800 }
+    - { path: "src/services/session.ts", chars: 8200 }
+    - { path: "tests/auth.test.ts", chars: 6100 }
+    - { path: "src/types/user.ts", chars: 4500 }
+  threshold:
+    warn_at: 50000
+    block_at: 100000
+  action: warn
+```
+
+## Failure Modes
+
+| Symptom | Reason | Mitigation |
+|---------|--------|------------|
+| Caller bundles before preview | Caller didn't follow contract | context-engine rejects late preview requests with explicit error |
+| Estimate way off for non-English content | Tokenizer ratio assumes English | Document limitation; safe both directions due to dispatch-time hard cap |
+| Block action ignored by caller | Caller bug | Each caller's Done When MUST verify `action != block` before dispatch |
+| Threshold env-var malformed | User typo | context-engine logs warning, falls back to default |

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")