@rune-kit/rune 2.2.6 → 2.3.0

package/skills/cook/references/deviation-rules.md

@@ -0,0 +1,19 @@
+# Deviation Rules — When Implementation Diverges from Plan
+
+When implementation diverges from the approved plan, classify the deviation and act accordingly.
+
+## Rule Table
+
+| Rule | Scope | Action | Example |
+|------|-------|--------|---------|
+| R1: Bug fix | Code doesn't work as planned | Auto-fix, continue | Test fails due to typo, missing import |
+| R2: Security fix | Vulnerability discovered | Auto-fix, continue | SQL injection, XSS, hardcoded secret |
+| R3: Blocking fix | Can't proceed without change | Auto-fix, continue | Missing dependency, wrong API signature |
+| R4: Architectural change | Different approach than planned | **ASK user first** | New database table, changed API contract, different library |
+
+## Guidance
+
+**R1-R3**: Security primitives and correctness fixes are NOT features — fix silently.
+
+**R4**: If you catch yourself thinking "this is a better way" — STOP and ask.
+The plan was approved for a reason. Architectural deviations require explicit user consent before proceeding.

package/skills/cook/references/error-recovery.md

@@ -0,0 +1,37 @@
+# Error Recovery — Phase Failure Handling
+
+What to do when each phase fails, plus repair operators to use before escalating.
+
+## Phase Failure Table
+
+| Phase | If this fails... | Do this... |
+|-------|-----------------|------------|
+| 1 UNDERSTAND | scout finds nothing relevant | Proceed with plan, note limited context |
+| 2 PLAN | Task too complex | Break into smaller tasks, consider `rune:team` |
+| 3 TEST | Can't write tests (no test framework) | Skip TDD, write tests after implementation |
+| 4 IMPLEMENT | Fix hits repeated bugs | `rune:debug` (max 3 loops) → re-plan → if still blocked → **Approach Pivot Gate** → `rune:brainstorm(rescue)` |
+| 5a PREFLIGHT | Logic issues found | Fix → re-run preflight |
+| 5b SENTINEL | Security CRITICAL found | Fix immediately → re-run (mandatory) |
+| 5c REVIEW | Code quality issues | Fix CRITICAL/HIGH → re-review (max 2 loops) |
+| 6 VERIFY | Build/lint/type fails | Fix → re-run verification |
+
+## Repair Operators (before escalation)
+
+When a task fails during Phase 4 (IMPLEMENT), apply these operators in order before escalating.
+
+| Operator | When | Action |
+|----------|------|--------|
+| **RETRY** | Transient failure (network, timeout, flaky test) | Re-run same approach, max 2 attempts |
+| **DECOMPOSE** | Task too complex, partial progress | Split into 2-3 smaller tasks, continue |
+| **PRUNE** | Approach fundamentally wrong | Remove failed code, try different approach from plan |
+
+## Retry Budget
+
+**2 repair attempts per task.**
+
+After 2 failures → escalate:
+- Same error both times → `debug` for root cause
+- Different errors → `plan` to redesign the task
+- All approaches exhausted → `brainstorm(rescue)` for alternative category
+
+Do NOT ask user until repair budget is spent.

package/skills/cook/references/exit-conditions.md

@@ -0,0 +1,31 @@
+# Exit Conditions — Autonomous Loop Caps
+
+Every cook invocation inside `team` or autonomous workflows MUST respect these exit conditions.
+These caps prevent runaway loops and force escalation before context exhaustion.
+
+## Hard Caps
+
+```
+MAX_DEBUG_LOOPS:   3 per error area (already enforced in Phase 4)
+MAX_QUALITY_LOOPS: 2 re-runs of Phase 5 (fix→recheck cycle)
+MAX_REPLAN:        1 re-plan per cook session (Phase 4 re-plan check)
+MAX_PIVOT:         1 approach pivot per cook session (Approach Pivot Gate)
+MAX_FIXES:         30 per session (hard cap — fix's WTF-likelihood self-regulation)
+WTF_THRESHOLD:     20% quality decay risk → STOP fixing, commit progress, re-assess
+TIMEOUT_SIGNAL:    If context-watch reports ORANGE, wrap up current phase and checkpoint
+```
+
+## Escalation Chain
+
+```
+debug-fix (3x) → re-plan (1x) → approach pivot via brainstorm rescue (1x) → THEN escalate to user
+```
+
+Never surrender before exhausting the pivot. Never spin indefinitely.
+
+## Triggered State
+
+If any exit condition triggers without resolution:
+- Cook emits `BLOCKED` status with full details (phase, blocker, what was tried)
+- Execution stops
+- User must make a decision before cook can resume

package/skills/cook/references/loop-detection.md

@@ -0,0 +1,39 @@
+# Hash-Based Loop Detection — Content-Aware Stuck Detection
+
+The Analysis Paralysis Guard (5-read counter in SKILL.md) catches obvious paralysis.
+This catches **same-input-same-output loops** — where the agent keeps calling the same tool
+with the same arguments and getting the same result, making zero progress.
+
+Source: goclaw (832★) — SHA256-based loop detection distinguishes true stuck loops from productive retries.
+
+## Detection Logic
+
+Track mentally (no actual SHA256 required):
+
+```
+For each tool call, track:
+  argsHash = fingerprint(tool_name + arguments)
+  resultHash = fingerprint(result content)
+
+IF same argsHash AND same resultHash seen before:
+  consecutive_identical += 1
+ELSE:
+  consecutive_identical = 0
+
+Thresholds:
+  3 identical calls → WARN: "Loop detected — same tool, same args, same result 3x. Change approach."
+  5 identical calls → FORCE STOP: "True stuck loop. Must try different tool or different arguments."
+```
+
+## Key Distinction
+
+Retry-with-different-result is **NOT** a loop (e.g., re-running tests after a fix).
+Only same-input-AND-same-output counts.
+
+## Common Loop Patterns
+
+| Pattern | Looks Like | Actually |
+|---------|-----------|----------|
+| Re-reading same file after failed edit | `Read(file.ts)` → same content 3x | Agent forgot what it read — act on existing knowledge |
+| Re-running same failing test without code change | `Bash(npm test)` → same failure 3x | No code was changed between runs — fix first, then test |
+| Grepping same pattern across different paths | `Grep("pattern", src/)` → `Grep("pattern", lib/)` → same 0 results | Pattern doesn't exist — change search terms |

package/skills/cook/references/mid-run-signals.md

@@ -0,0 +1,31 @@
+# Mid-Run Signal Detection — Two-Stage Intent Classification
+
+When user sends a message DURING cook execution (mid-phase), classify intent before acting.
+Source: goclaw (832★) — two-stage intent classification prevents expensive LLM calls for simple signals.
+
+## Stage 1 — Keyword Fast-Path
+
+No LLM reasoning needed. Applies when message is <60 chars.
+
+| Pattern | Intent | Action |
+|---------|--------|--------|
+| "stop", "cancel", "dừng", "abort" | `Cancel` | Save progress → emit Cook Report with status BLOCKED → stop |
+| "status", "tiến độ", "progress", "where are you" | `StatusQuery` | Reply with current phase + task + % estimate → resume |
+| "wait", "pause", "đợi" | `Pause` | Create `.rune/.continue-here.md` → WIP commit → stop |
+| "skip this", "bỏ qua", "next" | `Steer` | Skip current task → proceed to next task/phase |
+
+## Stage 2 — Context Classification
+
+Applies when NO keyword match AND message is >60 chars.
+
+| Intent | Signal | Action |
+|--------|--------|--------|
+| `Steer` | Modifies scope but keeps goal ("actually use Redis instead of Memcached") | Update plan inline, note deviation in Cook Report |
+| `NewTask` | Unrelated to current work ("also fix the login page") | Log to `.rune/backlog.md`, continue current task. Announce: "Noted for later — staying on current task." |
+| `Clarification` | Answers a question cook asked, or provides missing context | Absorb into current phase context, resume |
+
+## Priority Rule
+
+Cancel and Pause are **safety signals** — they take absolute priority over all other classifications.
+If ambiguous between Cancel and Steer → ask: "Did you mean stop, or change approach?"
+Never queue user messages — process immediately.

package/skills/cook/references/output-format.md

@@ -0,0 +1,40 @@
+# Cook Report — Output Format
+
+Full format for the Cook Report emitted at the end of every cook session.
+Also defines the NEXUS Deliverables table format used when cook is invoked by `team`.
+
+## Cook Report Format
+
+```
+## Cook Report: [Task Name]
+- **Status**: DONE | DONE_WITH_CONCERNS | NEEDS_CONTEXT | BLOCKED
+- **Phases**: [list of completed phases]
+- **Files Changed**: [count] ([list])
+- **Tests**: [passed]/[total] ([coverage]%)
+- **Quality**: preflight [PASS/WARN] | sentinel [PASS/WARN] | review [PASS/WARN]
+- **Commit**: [hash] — [message]
+
+### Deliverables (NEXUS response — when invoked by team)
+| # | Deliverable | Status | Evidence |
+|---|-------------|--------|----------|
+| 1 | [from handoff] | DELIVERED | [file path or test output quote] |
+| 2 | [from handoff] | DELIVERED | [file path or test output quote] |
+| 3 | [from handoff] | PARTIAL | [what's missing and why] |
+
+### Concerns (if DONE_WITH_CONCERNS)
+- [concern]: [impact assessment] — [suggested remediation]
+
+### Decisions Made
+- [decision]: [rationale]
+
+### Session State
+- Saved to .rune/decisions.md
+- Saved to .rune/progress.md
+```
+
+## Usage Rules
+
+- When cook is invoked **standalone** (not by team): Deliverables table is optional
+- When cook is invoked by **team** with a NEXUS Handoff: Deliverables table is **MANDATORY** — team uses it to track acceptance criteria across streams
+- Cook Report MUST contain actual commit hash, not placeholder
+- Self-Validation must pass before emitting the report

package/skills/cook/references/pack-detection.md

@@ -0,0 +1,82 @@
+# L4 Pack Detection — Signal → Pack Mapping
+
+This file defines the full signal-to-pack mapping used in Phase 1.5 (DOMAIN CONTEXT).
+When a signal in the codebase or task description matches a row below, load the corresponding pack.
+
+## Split Pack Protocol (context-efficient)
+
+- `Read` the matching PACK.md index (~60-80 lines) — contains triggers, skill table, connections, workflows
+- Match the task to the specific skill name in the index's Skills Included table
+- `Read` only the matching skill file(s) from `skills/` subdirectory (e.g., `extensions/backend/skills/auth.md`)
+- Load max 2-3 skill files per invocation — not all skills in the pack
+- Pack-level constraints (from index's Connections and Sharp Edges sections) always apply
+
+## Monolith Pack Protocol (legacy)
+
+If no `format: split` in PACK.md frontmatter, read the full PACK.md and extract the matching `### skill-name` section.
+
+## Signal → Pack Table
+
+| Signal in Codebase or Task | Pack | File |
+|---|---|---|
+| `*.tsx`, `*.svelte`, `*.vue`, Tailwind, CSS modules | `@rune/ui` | `extensions/ui/PACK.md` |
+| Express/Fastify/NestJS routes, API endpoints | `@rune/backend` | `extensions/backend/PACK.md` |
+| Dockerfile, `.github/workflows/`, Terraform | `@rune/devops` | `extensions/devops/PACK.md` |
+| `react-native`, `expo`, `flutter`, `ios/`, `android/` | `@rune/mobile` | `extensions/mobile/PACK.md` |
+| Auth, OWASP, secrets, PCI/HIPAA markers | `@rune/security` | `extensions/security/PACK.md` |
+| Trading, charts, market data, `decimal.js` | `@rune/trading` | `extensions/trading/PACK.md` |
+| Multi-tenant, billing, `stripe`, subscription | `@rune/saas` | `extensions/saas/PACK.md` |
+| Cart, checkout, inventory, Shopify | `@rune/ecommerce` | `extensions/ecommerce/PACK.md` |
+| `openai`, `anthropic`, embeddings, RAG, LLM | `@rune/ai-ml` | `extensions/ai-ml/PACK.md` |
+| `three`, `pixi`, `phaser`, `*.glsl`, game loop | `@rune/gamedev` | `extensions/gamedev/PACK.md` |
+| CMS, blog, MDX, `i18next`, SEO | `@rune/content` | `extensions/content/PACK.md` |
+| Analytics, tracking, A/B test, funnel | `@rune/analytics` | `extensions/analytics/PACK.md` |
+| Chrome extension, `manifest.json`, service worker, content script | `@rune/chrome-ext` | `extensions/chrome-ext/PACK.md` |
+| PRD, roadmap, KPI, release notes, `.rune/business/` | `@rune-pro/product` | `extensions/pro-product/PACK.md` |
+| Sales outreach, pipeline, call prep, competitive intel | `@rune-pro/sales` | `extensions/pro-sales/PACK.md` |
+| Data science, SQL, dashboard, statistical testing, ETL | `@rune-pro/data-science` | `extensions/pro-data-science/PACK.md` |
+| Support ticket, KB article, escalation, SLA, FAQ | `@rune-pro/support` | `extensions/pro-support/PACK.md` |
+| Budget, expense, revenue forecast, P&L, cash flow, runway | `@rune-pro/finance` | `extensions/pro-finance/PACK.md` |
+| Contract, NDA, compliance, GDPR, IP, legal incident | `@rune-pro/legal` | `extensions/pro-legal/PACK.md` |
+| JD, resume, interview, hiring, onboarding, compensation, HR policy | `@rune-pro/hr` | `extensions/pro-hr/PACK.md` |
+| Enterprise search, cross-system, knowledge graph, federated query | `@rune-pro/enterprise-search` | `extensions/pro-enterprise-search/PACK.md` |
+| Zalo Mini App, ZMP, `zalo-mini-app`, ZNS, Zalo OA | `@rune/zalo` | `extensions/zalo/PACK.md` |
+
+## After Match Found
+
+If ≥1 pack matches:
+- Use `Read` to load the matching PACK.md (index if split, full if monolith)
+- For split packs: identify the relevant skill from the index table, then `Read` only that skill file from `skills/` subdirectory
+- For monolith packs: extract the relevant `### skill-name` section from the PACK.md body
+- Apply pack constraints alongside cook's own constraints for the rest of the workflow
+- Announce: "Loaded @rune/[pack] → [skill-name] (split)" or "Loaded @rune/[pack] → [skill-name] (full)"
+
+If 0 packs match: skip silently, proceed to Phase 2.
+
+## Workflow Command Detection
+
+After a pack is matched, check if the user's request maps to a named workflow in the pack's Workflows table.
+
+**Detection rules:**
+1. Explicit command: user types `/rune <pack> <workflow>` (e.g., `/rune finance monthly-close`)
+2. Implicit match: task description contains workflow trigger keywords from the Workflows table
+3. Single-skill shortcut: `/rune <pack> <skill>` routes directly to one skill
+
+**If a workflow matches:**
+1. Read the Workflows section of the matched PACK.md
+2. Extract the skill sequence (e.g., `expense-analysis → financial-reporting → cash-flow-optimization`)
+3. Execute skills in order — each skill's output feeds the next as context
+4. Thread state via `.rune/<pack>/` artifacts (each skill reads previous skill's output file)
+
+**If no workflow matches:**
+- Fall back to single-skill detection (match task to best skill from the Skills table)
+- This is the current default behavior
+
+**Workflow examples:**
+| Command | Pack | Workflow | Skill Sequence |
+|---------|------|----------|----------------|
+| `/rune finance monthly-close` | finance | monthly-close | expense-analysis → financial-reporting → cash-flow |
+| `/rune hr full-cycle` | hr | full-cycle | jd-writer → resume-screener → interview-planner → scorecard |
+| `/rune search "query"` | enterprise-search | search | query-planner → source-connector → result-merger → permission-guard |
+| `/rune sales prep` | sales | prep | account-research → call-preparation → competitive-intel |
+| `/rune product feature` | product | feature | feature-spec → roadmap → metrics-tracking |

package/skills/cook/references/pause-resume-template.md

@@ -0,0 +1,38 @@
+# Pause/Resume Template — Formal Mid-Phase Handoff
+
+This file defines the `.continue-here.md` format used when cook must pause mid-phase
+(context limit, user break, session end before phase completes).
+
+## When to Use
+
+When cook cannot complete the current phase in one session:
+- Context limit approaching (context-watch ORANGE)
+- User explicitly requests a break ("pause", "đợi", "wait")
+- Session end is forced before phase completes
+
+## `.rune/.continue-here.md` Format
+
+```markdown
+## Continue Here
+- **Phase**: [current phase number and name]
+- **Task**: [current task within phase — e.g., "Task 3 of 5"]
+- **Completed**: [list of tasks done this session]
+- **Remaining**: [list of tasks not yet started]
+- **Decisions**: [any decisions made this session]
+- **Blockers**: [if any — what's stuck and why]
+- **WIP Files**: [files modified but not yet committed]
+```
+
+## Pause Protocol
+
+1. Create `.rune/.continue-here.md` with the format above
+2. Create a WIP commit: `wip: cook phase N paused at task M`
+3. Stop execution
+
+## Resume Protocol
+
+Phase 0 (RESUME CHECK) detects `.continue-here.md` → resumes from exact task position.
+
+This is more granular than Phase 0's plan-level resume — it resumes **within** a phase, not just between phases.
+
+After successful resume and phase completion → delete `.continue-here.md`.

package/skills/cook/references/rfc-template.md

@@ -0,0 +1,52 @@
+# RFC Template — Breaking Change Gate
+
+This file contains the RFC artifact format used in Phase 2.5 (RFC GATE).
+Write this artifact to `.rune/rfc/RFC-<NNN>-<slug>.md` whenever a breaking change is detected.
+
+## Auto-Trigger Conditions (ANY triggers this gate)
+
+- Plan includes `BREAKING CHANGE` annotation
+- Plan modifies a public API signature (added/removed/changed parameters)
+- Plan alters database schema (migration required)
+- Plan removes or renames an exported function/type used by other modules
+- Plan changes authentication/authorization flow
+
+## Skip Conditions
+
+Non-breaking changes, internal refactors, new features with no API surface change.
+
+## RFC Artifact Format
+
+```markdown
+# RFC-<NNN>: <Title>
+
+**Date**: [YYYY-MM-DD]
+**Author**: [agent or user]
+**Status**: Proposed | Approved | Rejected
+**Impact**: [list affected consumers — modules, services, users]
+
+## What Changes
+[Specific breaking change — old behavior → new behavior]
+
+## Why
+[Business/technical justification — why breaking is necessary]
+
+## Migration Path
+[Step-by-step guide for consumers to adapt]
+[Include code examples: before → after]
+
+## Rollback Plan
+[How to revert if the change causes issues]
+
+## Affected Systems
+| System | Impact | Migration Effort |
+|--------|--------|-----------------|
+| [module/service] | [description] | [low/medium/high] |
+```
+
+## Gate Protocol
+
+Present RFC to user for approval. User responds:
+- **"approved"** → proceed to Phase 3
+- **"rejected"** → revise plan
+- **"deferred"** → skip breaking change, implement non-breaking alternative

package/skills/cook/references/sharp-edges.md

@@ -0,0 +1,24 @@
+# Sharp Edges — Known Failure Modes
+
+Check these before declaring done. These are the most common ways cook goes wrong.
+
+| Failure Mode | Severity | Mitigation |
+|---|---|---|
+| Skipping scout to "save time" on a simple task | CRITICAL | Scout Gate blocks this — Phase 1 is mandatory regardless of perceived simplicity |
+| Writing code without user-approved plan | HIGH | Plan Gate: do NOT proceed to Phase 3 without explicit approval ("go", "proceed", "yes") |
+| Claiming "all tests pass" without showing output | HIGH | Constraint 7 blocks this — show actual test runner output via completion-gate |
+| Entering debug↔fix loop more than 3 times without escalating | MEDIUM | After 3 loops → re-plan → if still blocked → Approach Pivot Gate → brainstorm(rescue) |
+| Surrendering "no solution" without triggering Approach Pivot Gate | CRITICAL | MUST invoke brainstorm(rescue) before telling user "can't be done" — pivot to different category first |
+| Re-planning with the same approach category after it fundamentally failed | HIGH | Re-plan = revise steps within same approach. If CATEGORY is wrong → Approach Pivot Gate, not re-plan |
+| Not escalating to sentinel:opus on security-sensitive tasks | MEDIUM | Auth, crypto, payment code → sentinel must run at opus, not sonnet |
+| Running Phase 5 checks sequentially instead of parallel | MEDIUM | Launch preflight+sentinel+review as parallel Task agents for speed |
+| Saying "done" without evidence trail | CRITICAL | completion-gate validates claims — UNCONFIRMED = BLOCK |
+| Analysis paralysis — 5+ reads without writing | HIGH | Analysis Paralysis Guard: act on incomplete info or report BLOCKED with specific missing piece |
+| Fast mode on security-relevant code | HIGH | Fast mode auto-excludes auth/crypto/payments — never fast-track security code |
+| Loading all phase files at once into context | HIGH | Phase File Gate: load ONLY the active phase file — one phase per session |
+| Resuming without checking master plan | MEDIUM | Phase 0 (RESUME CHECK) runs before Phase 1 — detects existing plans |
+| Treating user "stop"/"cancel" as scope change | CRITICAL | Mid-Run Signal Detection: Cancel/Pause are safety signals with absolute priority — never reinterpret as Steer or NewTask |
+| Same tool+args+result called 3+ times without progress | HIGH | Hash-Based Loop Detection: 3x warn, 5x force stop. Only same-input-AND-same-output counts |
+| Ignoring mid-run user messages during autonomous execution | HIGH | Two-stage intent classification: keyword fast-path for simple signals, context for longer. Never queue messages. |
+| Breaking change shipped without RFC review | CRITICAL | Phase 2.5 RFC Gate: any breaking change MUST have RFC artifact + user approval before implementation |
+| Runaway fix loop — fix introduces more bugs than it resolves | HIGH | fix v0.5.0 WTF-likelihood self-regulation: >20% decay = STOP. Hard cap 30 fixes/session via MAX_FIXES exit condition |

package/skills/cook/references/subagent-status.md

@@ -0,0 +1,38 @@
+# Subagent Status Protocol
+
+When cook completes (whether standalone or invoked by `team`), it MUST return one of four statuses.
+Sub-skills invoked by cook (fix, test, review, sentinel, etc.) MUST also return one of these statuses
+so cook can route accordingly.
+
+## Status Table
+
+| Status | Meaning | Cook Action |
+|--------|---------|-------------|
+| `DONE` | Task complete, no issues | Proceed to next phase |
+| `DONE_WITH_CONCERNS` | Task complete but issues noted (e.g., "tests pass but a performance regression observed") | Proceed, but append concern to `.rune/progress.md` and surface in Cook Report; address in Phase 5 (QUALITY) or next review cycle |
+| `NEEDS_CONTEXT` | Cannot proceed without more information (missing requirement, ambiguous spec, unknown environment) | Pause execution. Ask user the specific question(s) blocking progress. Resume from the same phase after answer received. |
+| `BLOCKED` | Hard blocker — cannot continue regardless of context (broken dependency, fundamental incompatibility, exhausted escalation chain) | Trigger escalation chain: debug-fix (3x) → re-plan (1x) → brainstorm rescue (1x) → then escalate to user with full details |
+
+## Message Formats
+
+### DONE_WITH_CONCERNS
+
+Append to `.rune/progress.md`:
+```
+[CONCERN][phase][timestamp] <sub-skill>: <concern description>
+```
+
+### NEEDS_CONTEXT
+
+State exactly:
+1. What is unknown
+2. Why it blocks progress
+3. The two most likely answers (to help the user respond quickly)
+
+### BLOCKED
+
+Include:
+1. The phase
+2. The sub-skill that emitted BLOCKED
+3. The specific blocker
+4. What was already attempted

package/skills/db/SKILL.md

@@ -251,6 +251,18 @@ Known failure modes for this skill. Check these before declaring done.
 - Schema changelog updated in .rune/schema-changelog.md
 - Structured DB Report emitted with PASS/WARN/BLOCK verdict
 
+## Returns
+
+| Artifact | Format | Location |
+|----------|--------|----------|
+| Migration file (up) | SQL or ORM-specific | `migrations/<timestamp>_<name>/` |
+| Rollback script (down) | SQL or ORM-specific | same migration directory |
+| Schema changelog entry | Markdown | `.rune/schema-changelog.md` |
+| Index recommendations | Structured list | inline (DB Report) |
+| DB Report with verdict | Markdown (PASS/WARN/BLOCK) | inline |
+
 ## Cost Profile
 
 ~2000-6000 tokens input, ~800-2000 tokens output. Sonnet for migration generation quality.
+
+**Scope guardrail:** db generates and validates migrations — it does not run them in production. Execution is delegated to `verification` in test environments only.

package/skills/debug/SKILL.md

@@ -3,7 +3,7 @@ name: debug
 description: Root cause analysis for bugs and unexpected behavior. Traces errors through code, uses structured reasoning, and hands off to fix when cause is found. Core of the debug↔fix mesh.
 metadata:
   author: runedev
-  version: "0.7.0"
+  version: "0.8.0"
   layer: L2
   model: sonnet
   group: development
@@ -305,6 +305,7 @@ ALL of these mean: STOP. Return to Step 2 (Gather Evidence).
 ```
 ## Debug Report
 - **Error**: [error message]
+- **Status**: DONE | DONE_WITH_CONCERNS | NEEDS_CONTEXT | BLOCKED
 - **Severity**: critical | high | medium | low
 - **Confidence**: high | medium | low
 - **Fix Attempt**: [1/2/3 — track recurring bugs]
@@ -323,6 +324,12 @@ ALL of these mean: STOP. Return to Step 2 (Gather Evidence).
 - Attempt 1: [what was tried] → [why it didn't hold]
 - Attempt 2: [what was tried] → [why it didn't hold]
 
+### Concerns (if DONE_WITH_CONCERNS)
+- [concern]: [impact assessment] — [suggested remediation]
+
+### Context Needed (if NEEDS_CONTEXT)
+- [what is unknown]: [why it blocks diagnosis] — [two most likely answers]
+
 ### Suggested Fix
 [Description of what needs to change — no code, just direction]
 [If attempt 3: "ESCALATION: 3-fix rule triggered. Recommending redesign via rune:plan."]
@@ -331,6 +338,26 @@ ALL of these mean: STOP. Return to Step 2 (Gather Evidence).
 - `path/to/related.ts` — [why it's relevant]
 ```
 
+### Status Protocol (Subagent Contract)
+
+Debug returns one of four statuses to its caller (cook, fix, test, surgeon). The caller uses this to route next actions.
+
+| Status | When | Example |
+|--------|------|---------|
+| `DONE` | Root cause identified with high confidence, ready for fix | Clear diagnosis with file:line evidence |
+| `DONE_WITH_CONCERNS` | Root cause found but diagnosis has caveats | "Likely race condition but cannot reproduce consistently — fix may need retry logic" |
+| `NEEDS_CONTEXT` | Cannot diagnose without more info — missing repro steps, env details, or access | "Error only occurs in production — need prod logs or env variables to continue" |
+| `BLOCKED` | Exhausted 3 hypothesis cycles, escalation triggered | "3 cycles completed, no confirmed root cause — escalating to problem-solver" |
+
+## Returns
+
+| Artifact | Format | Location |
+|----------|--------|----------|
+| Debug Report | Markdown (inline) | Emitted to calling skill (cook, fix, test, surgeon) |
+| Root cause + location | Inline (Debug Report) | Specific file:line with evidence |
+| Fix recommendation | Inline (Debug Report) | Direction only — no code changes |
+| Debug knowledge base entry | Markdown | `.rune/debug/knowledge-base.md` (appended on success) |
+
 ## Sharp Edges
 
 | Failure Mode | Severity | Mitigation |
@@ -354,9 +381,14 @@ ALL of these mean: STOP. Return to Step 2 (Gather Evidence).
 - Error reproduced (not assumed) with specific reproduction steps documented
 - 2-3 hypotheses formed, each marked CONFIRMED or RULED OUT with file:line evidence
 - Root cause identified at specific file:line
-- Structured Debug Report emitted
+- Structured Debug Report emitted with 4-state status
+- If `DONE_WITH_CONCERNS`: caveats documented with impact assessment
+- If `NEEDS_CONTEXT`: specific questions + two likely answers provided
+- If `BLOCKED`: all 3 hypothesis cycles documented + escalation target identified
 - No code changes made — rune:fix called with the report if fix is needed
 
 ## Cost Profile
 
 ~2000-5000 tokens input, ~500-1500 tokens output. Sonnet for code analysis quality. May escalate to opus for deeply complex bugs.
+
+**Scope guardrail**: Do not apply code changes or expand investigation beyond the locked scope directory unless explicitly delegated by the parent agent.

package/skills/deploy/SKILL.md

@@ -193,6 +193,16 @@ Deploy Report with platform, status (success/failed/rollback), deployed URL, bui
 6. MUST complete release checklist for production deploys — version bump, changelog, rollback plan
 7. MUST create rollback plan artifact before first production deploy of a version
 
+## Returns
+
+| Artifact | Format | Location |
+|----------|--------|----------|
+| Deploy report | Markdown | inline (chat output) |
+| Deploy status (success/failed/rollback) | Text | inline |
+| Health check results (HTTP status, visual) | Markdown | inline |
+| Rollback plan document | Markdown | `.rune/deploy/rollback-<version>.md` |
+| Monitoring confirmation | Text | inline |
+
 ## Sharp Edges
 
 Known failure modes for this skill. Check these before declaring done.

package/skills/design/SKILL.md

@@ -443,6 +443,15 @@ Trading/Fintech — Data-Dense Dark — Web
 | Persistence Gate | .rune/design-system.md written before reporting done | Write file first |
 | Platform Gate | Platform detected before generating tokens | Default to web, note assumption |
 
+## Returns
+
+| Artifact | Format | Location |
+|----------|--------|----------|
+| Design system file | Markdown | `.rune/design-system.md` |
+| Design report | Markdown | inline (chat output) |
+| Accessibility audit findings | Markdown list | inline + appended to design-system.md |
+| UX writing guidelines | Markdown section | `.rune/design-system.md` § UX Writing |
+
 ## Sharp Edges
 
 Known failure modes for this skill. Check these before declaring done.

package/skills/docs/SKILL.md

@@ -294,6 +294,18 @@ Docs Update Report:
 5. MUST NOT generate docs for code that doesn't exist yet (unless explicitly creating spec docs)
 6. API docs MUST match actual route signatures — wrong API docs are worse than no docs
 
+## Returns
+
+| Artifact | Format | Location |
+|----------|--------|----------|
+| README.md | Markdown | project root |
+| ARCHITECTURE.md | Markdown | project root (if 10+ files) |
+| API reference | Markdown | `docs/API.md` |
+| Changelog entry | Markdown (Keep a Changelog) | `CHANGELOG.md` |
+| Docs update report | Markdown | inline (chat output) |
+
+**Scope guardrail:** Documents only what exists in the codebase — never invents features, endpoints, or APIs.
+
 ## Sharp Edges
 
 | Failure Mode | Severity | Mitigation |

package/skills/docs-seeker/SKILL.md

@@ -161,6 +161,17 @@ Known failure modes for this skill. Check these before declaring done.
 - Source URL provided
 - Documentation emitted in output format
 
+## Returns
+
+| Artifact | Format | Location |
+|----------|--------|----------|
+| API reference (signature + params) | Markdown | inline |
+| Minimal working code example | Code block | inline |
+| Deprecation / version notes | Markdown | inline |
+| Source URL | Plain text | inline |
+
 ## Cost Profile
 
 ~300-600 tokens input, ~200-400 tokens output. Haiku. Fast lookup.
+
+**Scope guardrail:** docs-seeker looks up documentation only — it does not apply changes, write code, or interpret whether the API fits the caller's use case.