@rune-kit/rune 2.2.0 → 2.2.2

package/skills/ba/SKILL.md

@@ -233,6 +233,16 @@ US-1: As a [persona], I want to [action] so that [benefit]
 ## Risks
 - [risk]: [mitigation strategy]
 
+## Decision Classification
+
+| Category | Meaning | Example |
+|----------|---------|---------|
+| **Decisions** (locked) | User confirmed — agent MUST follow | "Use PostgreSQL, not MongoDB" |
+| **Discretion** (agent decides) | User trusts agent judgment | "Pick the best validation library" |
+| **Deferred** (out of scope) | Explicitly NOT this task | "Mobile app — future phase" |
+
+Plan gates on Decision compliance — Discretion items don't need approval.
+
 ## Next Step
 → Hand off to rune:plan for implementation planning
 ```

package/skills/brainstorm/SKILL.md

@@ -3,7 +3,7 @@ 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.
 metadata:
   author: runedev
-  version: "0.3.0"
+  version: "0.4.0"
   layer: L2
   model: opus
   group: creation
@@ -27,6 +27,20 @@ This applies to EVERY task regardless of perceived simplicity.
 ### Discovery Mode (default)
 Normal brainstorming at the start of a task — generate approaches before any code is written.
 
+### Vision Mode
+Activated for product-level rethinks — not "how to implement X" but "should we even build X?" Forces 10x thinking instead of incremental improvement.
+
+**Vision Mode triggers:**
+- Manual: `/rune brainstorm vision <product area>`
+- Called by `@rune-pro/product.feature-spec` when requirements feel incremental
+- When the user says "rethink", "reimagine", "what if we", "step back"
+
+**Vision Mode constraints:**
+1. MUST restate the user's REAL problem (not their proposed solution) — "you asked for a settings page, but your real problem is users can't find the right config"
+2. MUST generate 2-3 approaches where at least 1 eliminates the need for the feature entirely
+3. MUST apply the "10-star experience" lens: what would a 1-star, 5-star, and 10-star version look like?
+4. MUST challenge assumptions: "why does this need to be a page?" "why does the user need to do this at all?"
+
 ### Rescue Mode
 Activated when an approach has been tried and **fundamentally failed** — not a bug, but a wrong approach. Rescue mode forces **category-diverse** alternatives instead of variants of the failed approach.
 
@@ -125,6 +139,7 @@ CRAZY 8s         — 8 ideas in 8 minutes (rapid ideation)
 ### Step 0 — Detect Mode
 
 Check the invocation context:
+- If `mode="vision"` is set, or user says "rethink/reimagine/step back" → **Vision Mode**
 - If `mode="rescue"` is set, or caller is Approach Pivot Gate / 3-Fix Escalation → **Rescue Mode**
 - Otherwise → **Discovery Mode**
 
@@ -139,6 +154,53 @@ State the decision to be made in one clear sentence: "We need to decide HOW TO [
 
 If the problem is unclear, ask the user ONE clarifying question before proceeding.
 
+### Step 1.5 — Problem Restatement (MANDATORY)
+
+After framing the problem, restate it back to the user for confirmation:
+
+```
+"Let me confirm: you want to [X] because [Y],
+and the main constraint is [Z]. Correct?"
+```
+
+DO NOT generate approaches until user confirms the restatement. This prevents wasted ideation on a misunderstood problem — the most expensive brainstorm failure mode.
+
+**Skip conditions** (Rescue Mode only):
+- Rescue Mode: problem is already well-defined by `failure_evidence` — restatement is implicit in the failed approach summary.
+
+### Step 1.75 — Dynamic Questioning (When Clarification Needed)
+
+When Step 1 or Step 1.5 reveals gaps, ask structured clarifying questions using this format:
+
+```
+### [P0|P1|P2] **[DECISION POINT]**
+
+**Question:** [Clear, specific question]
+
+**Why This Matters:**
+- [Architectural consequence — what changes based on the answer]
+- [Affects: cost | complexity | timeline | scale | security]
+
+**Options:**
+| Option | Pros | Cons | Best For |
+|--------|------|------|----------|
+| A      | [+]  | [-]  | [scenario] |
+| B      | [+]  | [-]  | [scenario] |
+
+**If Not Specified:** [Default choice + rationale]
+```
+
+**Priority levels:**
+- **P0**: Blocking — cannot generate approaches without this answer
+- **P1**: High-leverage — significantly changes the recommended approach
+- **P2**: Nice-to-have — refines the recommendation but doesn't change direction
+
+**Rules:**
+1. Ask maximum 3 questions per round (avoid overwhelming the user)
+2. Each question MUST connect to a specific decision point (no generic "what do you want?")
+3. MUST provide a default answer — if user says "you decide", the default is used
+4. Questions generate data, not assumptions — each eliminates implementation paths
+
 ### Step 2 — Generate Approaches
 
 **Discovery Mode**: Produce exactly 2–3 distinct approaches.

package/skills/completion-gate/SKILL.md

@@ -4,7 +4,7 @@ description: "Validates agent claims against evidence trail. Catches 'done' with
 user-invocable: false
 metadata:
   author: runedev
-  version: "1.1.0"
+  version: "1.2.0"
   layer: L3
   model: haiku
   group: validation
@@ -58,6 +58,21 @@ CLAIM PATTERNS:
 
 Extract each claim as: `{ claim: string, source_skill: string }`
 
+### Step 1b — Stub Detection (Existence Theater Check)
+
+Before checking claims, scan all files created/modified in this workflow for stubs:
+
+```
+Grep for stub patterns in new/modified files:
+- "Placeholder" | "TODO" | "Not implemented" | "NotImplementedError"
+- Functions with body: only `return null` / `return {}` / `pass` / `throw`
+- Components returning only a single div with no logic
+```
+
+If ANY stub detected:
+- Add synthetic claim: "implemented [filename]" → CONTRADICTED (file is a stub)
+- This catches agents that create files but don't implement them
+
 ### Step 2 — Match Evidence
 
 For each claim, look for corresponding evidence in the conversation context:
@@ -108,6 +123,23 @@ IF no evidence found:
 UNCONFIRMED — 1 claim lacks evidence, 1 contradicted. Cannot proceed to commit.
 ```
 
+### Step 5 — Evidence Quality Gate
+
+Before emitting verdict, verify evidence quality:
+
+1. **IDENTIFY** — list every claim the agent made (Step 1 output)
+2. **RUN** — confirm verification commands were actually executed (not just planned)
+3. **READ** — read every line of command output (not just exit code)
+4. **VERIFY** — match each claim to a specific evidence quote (file:line or output snippet)
+5. **CLAIM** — only mark CONFIRMED if evidence quote directly supports the claim
+
+| Evidence Quality | Verdict |
+|-----------------|---------|
+| Exit code 0 only, no output read | INSUFFICIENT — re-run and read output |
+| Output read but no quote matched to claim | UNCONFIRMED — cite specific evidence |
+| Quote matches claim exactly | CONFIRMED |
+| Quote contradicts claim | CONTRADICTED |
+
 ## Verdict Rules
 
 ```
@@ -137,6 +169,7 @@ Completion Gate Report with status (CONFIRMED/UNCONFIRMED/CONTRADICTED), claim v
 | Evidence from a DIFFERENT test run (stale) | HIGH | Check that evidence timestamp/context matches current changes |
 | Agent pre-generates evidence by running commands proactively | LOW | This is actually GOOD behavior — we want agents to provide evidence |
 | Completion-gate itself claims "all confirmed" without evidence | CRITICAL | Gate report MUST include the evidence table — no table = report is invalid |
+| Existence Theater — agent creates files but they're stubs | HIGH | Step 1b stub detection: grep for Placeholder/TODO/NotImplementedError in new files |
 
 ## Done When
 

package/skills/context-engine/SKILL.md

@@ -117,6 +117,19 @@ Block further tool calls until compaction is acknowledged.
 
 Emit the context health report to the calling skill.
 
+### Step 6b — Context Percentage Advisory
+
+In addition to tool-call counting, monitor context window percentage when available:
+
+| Remaining | Level | Action |
+|-----------|-------|--------|
+| >35% | SAFE | Continue normally |
+| 25-35% | WARNING | Advise: "Context at ~[X]%. Consider /compact at next phase boundary" |
+| <25% | CRITICAL | Save state via session-bridge → recommend immediate /compact |
+
+Debounce: emit advisory max once per 5 tool calls to avoid noise.
+Tool-call thresholds (Steps 1-2) remain the primary signal. Percentage advisory is supplementary — use when CLI status bar data is available.
+
 ## Context Health Levels
 
 ```

package/skills/cook/SKILL.md

@@ -5,7 +5,7 @@ context: fork
 agent: general-purpose
 metadata:
   author: runedev
-  version: "0.5.0"
+  version: "0.7.0"
   layer: L1
   model: sonnet
   group: orchestrator
@@ -115,6 +115,23 @@ Skip silently on subsequent runs. User can force with `/rune env-check`.
    - Extract decisions relevant to the current task domain (match by keywords: module names, tech choices, patterns)
    - These become **constraints for Phase 2 (PLAN)** — the plan MUST NOT contradict active decisions without explicit user override
    - If no `.rune/decisions.md` exists, skip silently
+### Phase 1 Step 3.5 — Clarification Gate (Lightweight Socratic Check)
+
+Before planning, ask the user at minimum **2 clarifying questions**:
+
+1. **"What does success look like?"** — defines acceptance criteria (how we know we're done)
+2. **"What should NOT change?"** — defines blast radius constraints (what's off-limits)
+
+**Skip conditions** (ALL must be true to skip):
+- Bug fix with clear reproduction steps already provided by user
+- User explicitly said "just do it", "no questions", or "skip questions"
+- Fast mode active AND estimated change < 10 LOC
+- Hotfix chain active (production emergency)
+
+This is NOT the full BA elicitation (5 questions). It's a lightweight 2-question gate that prevents the most common failure: implementing the wrong thing. If the answers reveal complexity → escalate to `rune:ba` for deep requirement analysis.
+
+**Question format**: Use brainstorm's dynamic questioning format when possible (Priority level, Decision Point, Why This Matters, Options table, Default).
+
 4. Invoke scout to scan the codebase:
    - Use `Glob` to find files matching the feature domain (e.g., `**/*auth*`, `**/*user*`)
    - Use `Grep` to search for related patterns, imports, existing implementations
@@ -136,7 +153,16 @@ Skip silently on subsequent runs. User can force with `/rune env-check`.
 
 **Goal**: Detect if domain-specific L4 extension packs apply to this task.
 
-After scout completes (Phase 1), check if the detected tech stack or task description matches any L4 extension pack. If a match is found, read the pack's PACK.md to load domain-specific patterns, constraints, and sharp edges into the current workflow.
+After scout completes (Phase 1), check if the detected tech stack or task description matches any L4 extension pack. If a match is found, load the relevant domain-specific patterns, constraints, and sharp edges into the current workflow.
+
+**Split pack protocol** (context-efficient):
+- `Read` the matching PACK.md index (~60-80 lines) — this contains triggers, skill table, connections, and 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 as before.
 
 1. Check the project's detected stack against the L4 pack mapping:
 
@@ -154,13 +180,20 @@ After scout completes (Phase 1), check if the detected tech stack or task descri
 | `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` |
 
 2. If ≥1 pack matches:
-   - Use `Read` to load the matching PACK.md
-   - Extract the relevant skill's **Workflow** steps and **Constraints**
+   - 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] — applying [skill-name] domain patterns"
+   - Announce: "Loaded @rune/[pack] → [skill-name] (split)" or "Loaded @rune/[pack] → [skill-name] (full)"
 
 3. If 0 packs match: skip silently, proceed to Phase 2
 
@@ -407,6 +440,32 @@ This is OPT-IN — only activate if:
   - User explicitly requests checkpoints
 ```
 
+## Phase Transition Protocol (MANDATORY)
+
+Before entering ANY Phase N+1, assert ALL of the following:
+
+```
+ASSERT Phase N status == completed (in TodoWrite)
+ASSERT Phase N gate condition met (see Mesh Gates table below)
+ASSERT No BLOCK status from any sub-skill in Phase N
+ASSERT No unresolved CRITICAL findings from quality checks
+
+IF any assertion fails:
+  → STOP. Do NOT proceed to Phase N+1.
+  → Log: "BLOCKED at Phase N→N+1 transition: [specific assertion that failed]"
+  → Fix the blocking issue, then re-check assertions.
+```
+
+**Key transitions to enforce:**
+| Transition | Gate | Common Violation |
+|---|---|---|
+| Phase 1 → 2 | Scout Gate (codebase scanned) | Skipping scout "to save time" |
+| Phase 2 → 3 | Plan Gate (user approved plan) | Starting code without approval |
+| Phase 3 → 4 | Test-First Gate (failing tests exist) | Writing code before tests |
+| Phase 4 → 5 | All tests pass | Moving to quality with failing tests |
+| Phase 5 → 6 | Quality gate (no CRITICAL findings) | Ignoring sentinel CRITICAL |
+| Phase 6 → 7 | Verification green (lint + types + build) | Committing broken build |
+
 ## Phase 6: VERIFY
 
 **Goal**: Final automated verification before commit.
@@ -497,6 +556,27 @@ cook instance → commit → push → create PR → wait CI
   IF 3 retries fail → escalate to user with CI logs
 ```
 
+### Formal Pause/Resume (`.continue-here.md`)
+
+When cook must pause mid-phase (context limit, user break, session end before phase completes):
+
+1. Create `.rune/.continue-here.md` with structured handoff:
+```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]
+```
+2. Create a WIP commit: `wip: cook phase N paused at task M`
+3. Phase 0 (RESUME CHECK) detects `.continue-here.md` → resumes from exact task position
+4. After successful resume and phase completion → delete `.continue-here.md`
+
+This is more granular than Phase 0's plan-level resume — it resumes within a phase, not just between phases.
+
 ### Exit Conditions (Mandatory for Autonomous Runs)
 
 Every cook invocation inside `team` or autonomous workflows MUST have exit conditions:
@@ -513,6 +593,40 @@ TIMEOUT_SIGNAL:    If context-watch reports ORANGE, wrap up current phase and ch
 
 If any exit condition triggers without resolution → cook emits `BLOCKED` status with details and stops. Never spin indefinitely.
 
+### 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 | 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 |
+
+**DONE_WITH_CONCERNS logging format** (append to `.rune/progress.md`):
+```
+[CONCERN][phase][timestamp] <sub-skill>: <concern description>
+```
+
+**NEEDS_CONTEXT format**: State exactly what is unknown, why it blocks progress, and what the two most likely answers are (to help the user respond quickly).
+
+**BLOCKED format**: Include the phase, the sub-skill that emitted BLOCKED, the specific blocker, and what was already attempted.
+
+## Deviation Rules
+
+When implementation diverges from plan:
+
+| 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 |
+
+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.
+
 ## Error Recovery
 
 | Phase | If this fails... | Do this... |
@@ -526,6 +640,23 @@ If any exit condition triggers without resolution → cook emits `BLOCKED` statu
 | 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):
+
+| 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 |
+
+**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.
+
 ## Called By (inbound)
 
 - User: `/rune cook` direct invocation — primary entry point
@@ -562,6 +693,24 @@ If any exit condition triggers without resolution → cook emits `BLOCKED` statu
 - `worktree` (L3): Phase 4 — worktree isolation for parallel implementation
 - L4 extension packs: Phase 1.5 — domain-specific patterns when stack matches (see Phase 1.5 mapping table)
 
+## Analysis Paralysis Guard
+
+<HARD-GATE>
+5+ consecutive read-only tool calls (Read, Grep, Glob) without a single write action (Edit, Write, Bash) = STUCK.
+
+You MUST either:
+1. **Act** — write code, run a command, create a file
+2. **Report BLOCKED** — state the specific missing piece: "Cannot proceed because [X]"
+
+Stuck patterns (all banned):
+- Reading 10+ files to "fully understand" before acting
+- Grepping every variation of a string across the entire repo
+- Reading the same file twice in one investigation
+- "Let me check one more thing" — repeated after 5 reads
+
+A wrong first attempt that produces feedback beats perfect understanding that never ships.
+</HARD-GATE>
+
 ## Constraints
 
 1. MUST run scout before planning — no plan based on assumptions alone
@@ -620,6 +769,7 @@ Known failure modes for this skill. Check these before declaring done.
 | 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 |

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.3.0"
+  version: "0.4.0"
   layer: L2
   model: sonnet
   group: development
@@ -101,6 +101,49 @@ Before hypothesizing, add diagnostic logging at EACH component boundary:
 
 This reveals: "secrets reach workflow ✓, workflow reaches build ✗" — pinpoints the failing layer.
 
+### Step 2b: Instrument with Preserved Markers
+
+When adding diagnostic logging or instrumentation during investigation, mark ALL additions with region markers:
+
+```
+// #region agent-debug — [hypothesis being tested]
+console.log('[DEBUG] value at boundary:', data);
+// #endregion agent-debug
+```
+
+Language-appropriate equivalents:
+- Python: `# region agent-debug` / `# endregion agent-debug`
+- Rust: `// region agent-debug` / `// endregion agent-debug`
+
+**Why preserved markers matter:**
+- `rune:fix` will preserve these markers until the bug is fully resolved and tests pass
+- If the bug recurs, markers show exactly what was previously instrumented
+- Cleaning up debug traces before the fix is verified prevents learning from failure history
+- After fix is verified + tests pass → fix will clean up markers in a final pass
+
+<HARD-GATE>
+ALL diagnostic code added during debug MUST be wrapped in `#region agent-debug` markers.
+Unmarked instrumentation will be treated as stray code and removed prematurely.
+</HARD-GATE>
+
+### Step 2c: Check Debug Knowledge Base
+
+Before forming hypotheses, check `.rune/debug/knowledge-base.md`:
+- If file exists → search for matching symptoms/error messages
+- If match found → try known fix FIRST, skip hypothesis cycle
+- If no match → proceed to Step 3
+
+After successful root cause identification (Step 5), append entry:
+```
+### [date] — [symptom summary]
+- **Symptom**: [error message or behavior]
+- **Root Cause**: [what was actually wrong]
+- **Fix**: [what resolved it]
+- **Files**: [affected files]
+```
+
+This prevents re-debugging the same issue across sessions.
+
 ### Step 3: Form Hypotheses
 
 List exactly 2-3 possible root causes — no more, no fewer.
@@ -163,6 +206,16 @@ Produce structured output and hand off to rune:fix.
 - Call `rune:fix` with the full report if fix is needed
 - Do NOT apply any code changes — report only
 
+## Analysis Paralysis Guard
+
+<HARD-GATE>
+Debug is read-heavy by nature — but there are limits.
+
+After Step 4 (Test Hypotheses): if NO hypothesis is confirmed after 3 cycles of Steps 2-4, you MUST stop and escalate. Do NOT start cycle 4. Report all evidence gathered and escalate to problem-solver or sequential-thinking.
+
+Within any single step: 5+ consecutive Read/Grep calls without forming or testing a hypothesis = stuck. Stop reading, form a hypothesis from what you have, and test it. Incomplete hypotheses that get tested are better than perfect hypotheses that never form.
+</HARD-GATE>
+
 ## Red Flags — STOP and Return to Step 2
 
 If you catch yourself thinking any of these, you are GUESSING, not debugging:
@@ -174,6 +227,7 @@ If you catch yourself thinking any of these, you are GUESSING, not debugging:
 - "Here are the main problems: [lists fixes without investigation]"
 - Proposing solutions before tracing data flow
 - "One more fix attempt" (when already tried 2+)
+- "Let me read one more file before forming a hypothesis" (after 5+ reads)
 
 ALL of these mean: STOP. Return to Step 2 (Gather Evidence).
 
@@ -231,6 +285,7 @@ ALL of these mean: STOP. Return to Step 2 (Gather Evidence).
 | Same bug "fixed" 3+ times without questioning architecture | CRITICAL | 3-Fix Escalation Rule: classify failure → same blocker category = brainstorm(rescue), different bugs = plan redesign |
 | Escalating to plan when the APPROACH is wrong (not the module) | HIGH | If all 3 fixes hit the same category of blocker (API limit, platform gap), the approach needs pivoting via brainstorm(rescue), not re-planning |
 | Not tracking fix attempt number for recurring bugs | HIGH | Debug Report MUST include Fix Attempt counter — enables escalation gate |
+| Adding instrumentation without region markers | MEDIUM | All debug logging MUST use `#region agent-debug` — unmarked code gets cleaned up prematurely by fix |
 
 ## Done When
 

package/skills/design/SKILL.md

@@ -57,6 +57,17 @@ Load the design knowledge base before reasoning:
 
 > **Why two layers**: The baseline ships "good enough" universal design knowledge. Users who care about aesthetics create their own `design-dna.md` with curated palettes, font pairings, and style preferences. The design skill works well with either — it just works _better_ with a curated reference.
 
+### External Data Source
+
+Design intelligence data from [UI/UX Pro Max](https://github.com/nextlevelbuilder/ui-ux-pro-max-skill) (MIT, 42.8k★).
+Located at `references/ui-pro-max-data/` — 161 palettes, 84 styles, 73 font pairings, 161 reasoning rules, 99 UX guidelines.
+
+When `references/ui-pro-max-data/` is available:
+- Step 2: query `styles.csv` for domain-matched visual styles (expands from 10 → 84)
+- Step 3: query `ui-reasoning.csv` for industry-specific design rules (161 rules)
+- Step 3: query `colors.csv` for palette alternatives (expands from 10 → 161)
+- Step 6 (Anti-AI): cross-check proposed style against reasoning DB — if flagged as "AI-generic", suggest 3 alternatives
+
 ### Step 1 — Discover
 
 Invoke `scout` to detect:

package/skills/fix/SKILL.md

@@ -3,7 +3,7 @@ name: fix
 description: Apply code changes and fixes. Writes implementation code, applies bug fixes, and verifies changes with tests. Core action hub in the development mesh.
 metadata:
   author: runedev
-  version: "0.3.0"
+  version: "0.4.0"
   layer: L2
   model: sonnet
   group: development
@@ -112,6 +112,17 @@ Single validation at one point can be bypassed by different code paths, refactor
 
 Apply this when: the bug was caused by invalid data flowing through multiple layers. Skip for trivial one-liner fixes.
 
+### Step 5b: Preserve Debug Instrumentation
+
+If `rune:debug` left `#region agent-debug` markers in the code:
+
+1. **During fix**: DO NOT remove these markers — they capture the investigation trail
+2. **After fix verified** (tests pass, lint pass): scan for `#region agent-debug` markers
+3. **Remove markers and their contents** in a final cleanup pass ONLY after full verification
+4. If the fix is partial or tests still fail → KEEP all markers for the next debug cycle
+
+**Why:** Premature cleanup of debug instrumentation erases failure history. If the bug recurs after cleanup, the next debug session starts from zero. Keeping markers until verification means downstream skills can see what was already investigated.
+
 ### Step 6: Self-Review
 
 Verify correctness of the changes just made.
@@ -141,6 +152,19 @@ Produce a structured summary of all changes made.
 5. MUST follow project conventions found by scout — don't invent new patterns
 6. MUST NOT add unplanned features while fixing — fix only what was diagnosed
 7. MUST track fix attempt number — this feeds debug's 3-Fix Escalation classification
+8. MUST preserve `#region agent-debug` markers until fix is fully verified — cleanup only after tests pass
+
+## Scope Gate
+
+| Change Type | Action |
+|-------------|--------|
+| Bug fix (diagnosed cause) | Fix it |
+| Security fix (found during fix) | Fix it + flag to sentinel |
+| Blocking issue (can't complete fix without) | Fix it + document in report |
+| Unrelated improvement | **STOP — create separate task** |
+| Architectural change | **STOP — escalate to cook/plan** |
+
+If fix requires touching >3 files not in the diagnosis → re-diagnose. You're probably fixing a symptom.
 
 ## Mesh Gates
 
@@ -182,6 +206,7 @@ Known failure modes for this skill. Check these before declaring done.
 | Not running tests after each individual change | MEDIUM | Constraint 3: never batch untested changes — run tests after each edit |
 | Fixing at crash site without tracing data origin | HIGH | Defense-in-depth: trace where bad data ORIGINATES, add validation at every layer it passes through |
 | Single-point validation (fix one spot, hope it holds) | MEDIUM | Step 5: add entry + business logic + environment + debug layers for data-flow bugs |
+| Removing debug instrumentation before fix is verified | MEDIUM | Step 5b: preserve `#region agent-debug` markers until all tests pass — premature cleanup erases failure history |
 
 ## Done When
 

package/skills/mcp-builder/SKILL.md

@@ -3,7 +3,7 @@ name: mcp-builder
 description: Build Model Context Protocol servers from specifications. Generates tool definitions, resource handlers, and test suites for MCP servers in TypeScript or Python (FastMCP).
 metadata:
   author: runedev
-  version: "0.2.0"
+  version: "0.3.0"
   layer: L2
   model: sonnet
   group: creation
@@ -174,6 +174,52 @@ const envSchema = z.object({
 export const config = envSchema.parse(process.env);
 ```
 
+### Step 3.5 — Tool Safety Classification
+
+Before generating tests, classify every tool as `query` or `mutation`:
+
+| Category | Examples | Behavior |
+|---|---|---|
+| `query` | read, list, search, get, fetch | Auto-approve — no confirmation needed |
+| `mutation` | create, update, delete, send, write, publish | Require user confirmation before execution |
+
+**Implementation rules:**
+
+1. Add `safety` metadata to each tool definition:
+```typescript
+export const deleteTool = {
+  name: 'delete_user',
+  description: '...',
+  safety: 'mutation' as const,   // ← add this
+  inputSchema: z.object({ id: z.string() }),
+  async handler(input) { ... },
+};
+```
+
+2. For every `mutation` tool, generate a preview step that surfaces WHAT WILL HAPPEN before the action runs:
+```typescript
+// In the handler, before executing:
+if (tool.safety === 'mutation') {
+  return {
+    content: [{ type: 'text', text:
+      `⚠️ Will delete user "${user.name}" (ID: ${input.id}). This cannot be undone.\nConfirm? (yes/no)`
+    }],
+    requiresConfirmation: true,
+  };
+}
+// Proceed only after confirmation received
+```
+
+3. For Python (FastMCP), add a `@confirm_mutation` decorator or inline guard in the docstring:
+```python
+@mcp.tool()
+async def delete_user(id: str) -> str:
+    """[MUTATION] Delete a user by ID. Will prompt for confirmation before executing."""
+    ...
+```
+
+4. Document the safety classification in the README tool catalog (add a `🔒` badge on mutation tools).
+
 ### Step 4 — Generate Tests
 
 For each tool:
@@ -295,6 +341,7 @@ mcp-server-<name>/
 | Tests mock everything → no real integration coverage | MEDIUM | Generate both unit tests (mocked) and integration test template (real API) |
 | Generated server doesn't match MCP spec | HIGH | Use official SDK — don't hand-roll protocol handling |
 | Installation docs only for Claude Code | LOW | Include Cursor/Windsurf config examples too |
+| Mutation tool without confirmation gate | CRITICAL | Step 3.5: classify every tool — any write/delete/send without a preview+confirm step is a footgun |
 
 ## Done When