@rune-kit/rune 2.14.0 → 2.16.0

package/skills/ba/references/synthesis-mode.md

@@ -0,0 +1,105 @@
+# Synthesis Mode (Chat → Requirements Without Re-Interview)
+
+When the conversation already contains rich context — user described the feature in detail, pasted a spec, or worked through requirements iteratively — running the 5 Questions again wastes attention and breaks rapport. Synthesis mode extracts the Requirements Document from existing context, then **confirms** rather than re-interviewing.
+
+> Re-asking what the user already told you is the second-most expensive bug after wrong requirements. The first is wrong requirements shipped correctly.
+
+## When to use synthesis (skip the 5 Questions)
+
+Trigger synthesis instead of elicitation if ANY of:
+
+| Signal | Threshold |
+|--------|-----------|
+| User pasted a spec / PRD / brief | Any document > 200 words describing the feature |
+| Conversation has > 1000 words discussing this feature | Sufficient context already gathered |
+| User said "I already explained — just write the spec" / "synthesize" / "build the requirements" | Explicit synthesis request |
+| Session is a continuation — prior session captured most answers in `.rune/features/<name>/requirements.md` | Re-elicitation would duplicate |
+| Issue tracker / external ticket has filled-in template (problem, user story, acceptance criteria) | Source already structured |
+
+If NONE match → fall back to standard elicitation (Step 2 — 5 Questions).
+
+## Synthesis workflow
+
+### Step S1 — Sweep context
+
+Pull from in this order:
+1. The current conversation (every message from user, in order)
+2. Pasted documents (spec, PRD, ticket body)
+3. `.rune/features/<feature>/requirements.md` if continuation
+4. Codebase signals (only if needed for inference — `package.json`, `README.md`)
+
+### Step S2 — Extract answers to the 5 dimensions
+
+Map existing context onto the same 5 dimensions used in elicitation:
+
+| Dimension | Where to look |
+|-----------|---------------|
+| **WHO** (user, technical level, surrounding workflow) | "users who...", personas, role mentions |
+| **WHAT** (specific outcome, definition of done) | Acceptance criteria, "should", "must", success metrics |
+| **WHY** (problem, consequence of not building) | "because", "to avoid", problem statement, motivation |
+| **BOUNDARIES** (out of scope) | "not", "won't", "later", "v2", "future" |
+| **CONSTRAINTS** (tech, perf, security, deadline) | Tech stack mentions, perf targets, deadlines, integrations |
+
+For each dimension, mark **filled** | **partial** | **gap**.
+
+### Step S3 — Identify ONLY the gaps
+
+If all 5 dimensions are **filled** or **partial-but-acceptable** → skip directly to Step S4. No questions.
+
+If 1-2 dimensions are **gap** → ask ONLY those questions, single round, multiple-choice format. Never ask all 5 over again.
+
+If 3+ dimensions are **gap** → synthesis context wasn't actually rich; fall back to standard elicitation (Step 2).
+
+### Step S4 — Draft Requirements Document
+
+Use the standard Requirements Document format (same as elicitation output). For every dimension, cite the source:
+
+```markdown
+### Who
+[Synthesized statement]
+
+> _Source: user message at [timestamp/turn], "..."_
+```
+
+Citations are mandatory in synthesis mode — they let the user verify nothing was misread or invented.
+
+### Step S5 — Confirm, don't re-elicit
+
+Present the Requirements Document with this exact framing:
+
+> "I synthesized requirements from our conversation. **Read each section** — if anything is wrong or missing, tell me which line. If it's correct, say 'go' and I'll lock it for plan."
+
+Wait for explicit confirmation. Do NOT auto-proceed to plan handoff.
+
+User responses:
+- `"go"` / `"locked"` / `"correct"` → emit Requirements Document, hand off to plan
+- `"section X is wrong"` → revise that section only, re-confirm
+- `"add Y"` / `"actually..."` → treat as additional gap; ask multiple-choice if specific, otherwise add to Open Questions
+
+## Anti-patterns
+
+| Anti-pattern | Why it fails |
+|--------------|--------------|
+| Running 5 Questions after user pasted a 500-word spec | Burns trust — user already gave you the answers |
+| Synthesizing without citations | User can't verify; one misread becomes a downstream bug |
+| Auto-proceeding to plan after synthesis without confirmation | Synthesis is interpretation, not transcription. Confirmation prevents drift. |
+| Asking all 5 questions even when 4 dimensions are filled | Defeats the purpose. Ask 1, not 5. |
+| Treating "looks fine" as confirmation | Need explicit "go" or "locked" — vague approval = ambiguous handoff |
+
+## Integration with Step 1 (Intake & Classify)
+
+After classifying requirement type, branch:
+
+```
+Feature Request | Greenfield | Integration:
+  → Check synthesis triggers
+    → All filled (S2): synthesize + confirm (S4-S5)
+    → Partial (1-2 gaps): synthesize + targeted questions (S3-S5)
+    → Mostly empty (3+ gaps): fall back to standard elicitation (Step 2)
+Bug Fix:
+  → Skip BA entirely
+Refactor:
+  → Light BA (synthesis usually fits)
+```
+
+Synthesis mode is **opt-in via context detection**, not via user flag — the trigger is "rich context exists", not "user asked for it". The user shouldn't have to know which mode is active.

package/skills/brainstorm/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: brainstorm
-description: Creative ideation and solution exploration. Generates multiple approaches with trade-offs, uses structured frameworks (SCAMPER, First Principles), and hands off to plan for structuring.
+description: "Creative ideation and solution exploration. Generates multiple approaches with trade-offs, uses structured frameworks (SCAMPER, First Principles), and hands off to plan for structuring."
 metadata:
   author: runedev
   version: "0.6.0"

package/skills/browser-pilot/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: browser-pilot
-description: Playwright browser automation. Navigates URLs, takes screenshots, checks accessibility tree, interacts with UI elements, and reports findings.
+description: "Playwright browser automation. Navigates URLs, takes screenshots, checks accessibility tree, interacts with UI elements, and reports findings."
 metadata:
   author: runedev
   version: "0.2.0"

package/skills/completion-gate/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: completion-gate
-description: "Validates agent claims against evidence trail. Catches 'done' without proof, 'tests pass' without output, 'fixed' without verification. Called by cook and team at workflow end."
+description: "Validates agent claims against evidence trail. Use when verifying an agent has actually done what it claims — auto-fires at workflow end. Catches 'done' without proof, 'tests pass' without output, 'fixed' without verification. Called by cook and team."
 user-invocable: false
 metadata:
   author: runedev

package/skills/constraint-check/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: constraint-check
-description: "Meta-validator for HARD-GATEs. Verifies that skills' mandatory constraints were followed during a workflow. Called by cook, team, and audit to audit discipline compliance."
+description: "Meta-validator for HARD-GATEs. Use when auditing whether a skill's mandatory constraints were actually followed during a workflow (not just claimed). Called by cook, team, and audit for discipline compliance."
 user-invocable: false
 metadata:
   author: runedev

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.2.0"
   layer: L3
   model: haiku
   group: state
   tools: "Read, Glob, Grep"
+  emit: context.preview, output.density.set
 ---
 
 # 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
 
@@ -101,9 +103,11 @@ Emit recommendation to the calling orchestrator:
 
 Identify the next safe boundary (end of current loop iteration, end of current file being processed) and flag it.
 
+**Auto-activate Caveman Output Mode** (see `references/caveman-mode.md`) — emit `output.density.set` with `mode=caveman, scope=session, source=context-orange`. Reduces output token cost ~75% with no information loss; persists until /compact returns context to GREEN. Manual override (`/caveman` or "stop caveman") always wins.
+
 ### Step 5 — If RED
 
-Immediately trigger state save via `rune:session-bridge` (Save Mode) before any compaction occurs.
+Immediately trigger state save via `rune:session-bridge` (Save Mode) before any compaction occurs. If caveman mode was not already active from ORANGE, emit `output.density.set` with `mode=caveman, scope=session, source=context-red` now.
 
 Pass to session-bridge:
 - Current task and phase description
@@ -375,11 +379,117 @@ When Context Budget Warning fires, append to Context Health report:
 - **Recommendation**: Disable [server] to save ~[N]k tokens
 ```
 
+## Output Density Mode (Caveman)
+<MUST-READ path="references/caveman-mode.md" trigger="when context reaches ORANGE/RED OR user says 'caveman'/'be brief'/'less tokens'"/>
+
+Caveman is a terse output mode that strips filler, articles, hedging, and pleasantries while preserving full technical accuracy. ~75% output token reduction with no information loss when applied per the rules in `references/caveman-mode.md`.
+
+### Activation triggers
+
+| Trigger | Source | Persistence |
+|---------|--------|-------------|
+| Context health = ORANGE or RED | Auto from Step 4-5 above | Until `/compact` returns to GREEN |
+| User says "caveman" / "/caveman" / "be brief" / "less tokens" | Explicit user signal | Until "stop caveman" / "normal mode" |
+| Per-workstream override (e.g., `team` worker exceeds output budget) | Per-workstream scope | Scoped to that workstream only |
+
+Auto-activation emits `output.density.set` signal carrying `{mode: caveman, scope, source}`. Orchestrators (cook, team, rescue) honor the signal for the duration of their session.
+
+### Auto-clarity exceptions (revert ONE response, then resume)
+
+- Security warnings (data loss, credential exposure)
+- Confirmations of irreversible actions (`rm -rf`, force-push, drop table, prod deploy)
+- Multi-step sequences where fragment ordering risks misreading
+- User says "explain" / "clarify" / repeats the same question
+- Root-cause diagnosis where cause-and-effect chains need grammatical structure
+
+### Anti-pattern
+
+Caveman in the FIRST response of a task. The user can't calibrate severity from a single output yet — verbose first response is fine. Caveman starts on response 2+.
+
+## 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 +504,12 @@ 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) |
+| Caveman activated in first response of a task | MEDIUM | First response = user calibration baseline. Verbose first; caveman from response 2+ (see `references/caveman-mode.md`) |
+| Caveman compresses code blocks or error messages | CRITICAL | Caveman strips filler ONLY. Code, errors, paths, technical terms stay verbatim. Compression of those = wrong fix |
+| Caveman drift back to verbose mid-session | MEDIUM | Once activated, persists every response until explicit deactivation. Drift defeats the token savings |
+| Caveman during destructive-action confirmation | HIGH | Auto-clarity exception: revert ONE response for security/irreversible-action confirmations, then resume |
 
 ## Done When
 
@@ -402,6 +518,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/caveman-mode.md

@@ -0,0 +1,107 @@
+# Caveman Output Mode
+
+A terse output mode that strips filler, articles, and pleasantries while preserving full technical accuracy. Reduces output token cost by ~75% with no information loss when applied correctly.
+
+> "All technical substance stays. Only fluff dies."
+
+## When to activate
+
+| Trigger | Source | Persistence |
+|---------|--------|-------------|
+| User says "caveman", "caveman mode", "be brief", "less tokens" | Explicit user signal | Until user says "stop caveman" / "normal mode" |
+| Context health = ORANGE or RED | Auto from `context-engine` Step 4-5 | Until context returns to GREEN after compaction |
+| Output budget exceeded for a workstream (e.g., team parallel worker) | Per-workstream override | Scoped to that workstream |
+
+Once active, **every response stays in caveman mode** until explicit deactivation. No drift back to verbose mid-session.
+
+## What dies
+
+- Articles: `a`, `an`, `the`
+- Filler: `just`, `really`, `basically`, `actually`, `simply`, `essentially`, `you can see that`
+- Pleasantries: `Sure!`, `Certainly`, `Of course`, `Happy to help`, `Great question`, `Let me`
+- Hedging: `I think`, `it seems`, `probably`, `might want to consider`
+- Connective bloat: `In order to`, `with regard to`, `at this point in time`
+- Restating the user's question
+
+## What stays (untouched)
+
+- Code blocks — exact, unmodified
+- Error messages — quoted verbatim
+- Technical terms — full names, no abbreviation if ambiguous
+- File paths and identifiers
+- Numbers, units, version strings
+
+## Techniques allowed
+
+| Technique | Example |
+|-----------|---------|
+| Sentence fragments | `Fixed.` instead of `I have fixed it.` |
+| Short synonyms | `big` not `extensive`, `use` not `utilize` |
+| Common abbreviations | `DB`, `auth`, `config`, `req`/`res`, `fn`, `impl`, `repo`, `env` |
+| Arrow notation for causality | `null input → crash at line 42 → fix: validate before parse` |
+| Skeleton pattern | `[thing] [action] [reason]. [next step].` |
+| Bullet over paragraph | List 3 things instead of writing a paragraph about them |
+
+## Auto-clarity exceptions (revert temporarily)
+
+Drop caveman for ONE response, then resume. Triggers:
+
+| Situation | Why revert |
+|-----------|------------|
+| Security warning (data loss, credential exposure, destructive command) | Fragments risk underweighting severity |
+| Confirming an irreversible action (`rm -rf`, force-push, drop table, deploy to prod) | User must understand what they're approving |
+| Multi-step sequence where order matters | Fragment ordering can be misread |
+| User says "explain" / "clarify" / repeats the same question | They want more, not less |
+| Diagnosis of a hard bug — root cause needs grammatical structure to be unambiguous | Cause-and-effect chains break in fragments |
+
+## Token savings (calibration)
+
+| Mode | Sample output for "explain X" | Tokens |
+|------|-------------------------------|--------|
+| Verbose | `Sure! So basically, the X function is responsible for handling the case where...` | ~80 |
+| Caveman | `X handles [case]. Fails on [edge]. Fix: [action].` | ~20 |
+
+Expect 60-80% reduction on conversational responses. Code/docs/error messages are unaffected (they were already pure information).
+
+## Examples
+
+### Verbose
+> Sure! So I've taken a look at the auth middleware and it seems like the issue might be that the token validation function is being called before the token is actually parsed. Basically what's happening is that we're trying to validate something that doesn't exist yet, which is causing the null reference error you're seeing.
+
+### Caveman
+> Auth middleware: `validate(token)` called before parse → null ref. Fix: parse first, then validate.
+
+### Verbose
+> Great question! Let me explain how this works. The retry logic is implemented using exponential backoff, which means that each retry waits longer than the previous one.
+
+### Caveman
+> Retry uses exponential backoff. Each attempt waits longer than last.
+
+### Caveman with security exception
+> Caveman normally — but for this one: **Warning**: `git push --force` will overwrite the remote `main` branch. This destroys any commits other developers have pushed in the meantime. Confirm explicitly before I run it.
+> 
+> [next response resumes caveman]
+
+## Integration with context-engine
+
+Auto-activation flow (Step 4 ORANGE / Step 5 RED):
+
+```
+1. context-engine detects ORANGE/RED
+2. Emit advisory: "Context [X]%. Activating caveman output mode."
+3. Set session flag: caveman_active = true
+4. All subsequent responses honor caveman rules
+5. On /compact + return to GREEN: emit "Caveman mode released" — back to normal
+```
+
+Manual override always wins: if user says "/caveman" while GREEN, activate; if user says "stop caveman" while RED, respect it (but emit warning that context is critical).
+
+## Anti-patterns
+
+| Anti-pattern | Why it fails |
+|--------------|--------------|
+| Compressing code or error messages | Information loss → wrong fix |
+| Using rare abbreviations the user might not know | Saves tokens, costs comprehension |
+| Caveman during security/destructive confirmation | User skips reading because format signals "low importance" |
+| Drifting back to verbose after a few turns | Mode must persist — drift defeats the purpose |
+| Caveman in the FIRST response of a task | User can't calibrate severity from the first output yet — verbose first response is fine |

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.2.0"
+  version: "0.3.0"
   layer: L3
   model: haiku
   group: state
@@ -134,6 +134,24 @@ When a parent agent delegates work to a subagent, critical context gets lost —
 
 Full template + worked examples: [references/brief-template.md](references/brief-template.md).
 
+## Variant: Agent Brief (Async / Durable Handoff)
+<MUST-READ path="references/agent-brief.md" trigger="when handing off to an AFK agent, an issue tracker queue, autopilot, or any receiver that may execute hours/days later"/>
+
+The standard packet (above) is for **immediate** sub-agent dispatch in the same session. When the handoff target is async — issue tracker, scheduled cron agent, `rune:autopilot` (Pro) for multi-session work, or any receiver that may execute hours or days later — switch to the **agent brief** variant.
+
+Agent brief adds two durability principles on top of the standard packet:
+
+1. **Durability over precision** — describe interfaces, types, and behavioral contracts. NEVER reference line numbers in narrative. File paths only in `### Files Touched` (locator-only, may rename).
+2. **Behavioral, not procedural** — describe WHAT the system should do, not HOW to implement it. The async agent will explore the codebase fresh.
+
+Additional BLOCK-tier checks for agent briefs (on top of the standard smell tests):
+- `**Category:**` line present (`bug` / `enhancement` / `refactor`)
+- Both `**Current behavior:**` and `**Desired behavior:**` sections present
+- Acceptance criteria are independently testable (each pass/fail alone)
+- `**Key interfaces:**` names types/functions, not file paths
+
+Full template + worked examples: [references/agent-brief.md](references/agent-brief.md).
+
 ## Returns
 
 | Field | Type | Description |
@@ -169,6 +187,9 @@ Full template + worked examples: [references/brief-template.md](references/brief
 | 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 |
+| Async handoff (issue tracker / autopilot / scheduled run) emitted as standard packet | HIGH | Switch to agent-brief variant (`references/agent-brief.md`) — standard packet rots when receiver runs hours/days later. Brief adds durability rules: behavioral not procedural, no line numbers in narrative |
+| Agent brief with file:line references in narrative ("change `auth.ts:42`") | CRITICAL | Brief BLOCK gate — line numbers go stale on first edit. Reference type names, function signatures, contracts instead. File paths only in `### Files Touched` |
+| Agent brief without `**Current behavior:**` AND `**Desired behavior:**` split | HIGH | Brief BLOCK gate — without the delta explicit, async agent cannot verify when work is done |
 
 ## Self-Validation