@rune-kit/rune 2.1.1 → 2.2.1

package/extensions/zalo/skills/zalo-rate-guard.md

@@ -0,0 +1,219 @@
+---
+name: zalo-rate-guard
+pack: "@rune/zalo"
+description: Rate limiting patterns for Zalo OA and personal APIs — token bucket per endpoint, exponential backoff, queue management, quota monitoring, anti-ban strategies.
+model: sonnet
+tools: "Read, Glob, Grep, Bash, Write, Edit"
+---
+
+# zalo-rate-guard
+
+Shared rate limiting layer for both Track A (OA API) and Track B (Personal via zca-js).
+Zalo has **undocumented rate limits** — no official RPM/QPM numbers published.
+Exceeding limits: throttled (429) → warned → OA suspended / account banned.
+Neither `zalo-php-sdk`, `zalo-java-sdk`, nor `zca-js` implement any rate limiting.
+This skill fills that gap.
+
+---
+
+## Estimated Safe Limits
+
+**Track A — OA API:**
+
+| Endpoint | Safe RPM | Burst | Notes |
+|----------|----------|-------|-------|
+| Send CS message | 200 | 10 | Per OA, includes all message types |
+| Send broadcast | 50 | 5 | Monthly quota based on follower count |
+| Get user profile | 300 | 20 | Cacheable — use name cache |
+| Get follower list | 100 | 10 | Paginated, cache results |
+| Upload media | 60 | 5 | Large payloads, slower |
+| Global | 500 | 30 | Total across all endpoints |
+
+**Track B — Personal (zca-js):**
+
+| Action | Safe RPM | Burst | Notes |
+|--------|----------|-------|-------|
+| Send message (DM) | 30 | 5 | Much lower than OA — personal account |
+| Send message (group) | 20 | 3 | Groups are more scrutinized |
+| Friend operations | 10 | 2 | Add/remove friend is very sensitive |
+| Profile lookups | 60 | 10 | Less sensitive, still cache |
+| Global | 100 | 15 | Err on side of caution |
+
+---
+
+## Token Bucket Implementation
+
+```typescript
+import PQueue from 'p-queue'
+
+interface RateLimitConfig {
+  rpm: number        // requests per minute
+  burst: number      // max concurrent
+  retryAfter: number // ms to wait on 429
+}
+
+const LIMITS: Record<string, RateLimitConfig> = {
+  'oa:send_message':   { rpm: 200, burst: 10, retryAfter: 5000 },
+  'oa:broadcast':      { rpm: 50,  burst: 5,  retryAfter: 10000 },
+  'oa:get_profile':    { rpm: 300, burst: 20, retryAfter: 3000 },
+  'oa:upload':         { rpm: 60,  burst: 5,  retryAfter: 5000 },
+  'personal:send_dm':  { rpm: 30,  burst: 5,  retryAfter: 10000 },
+  'personal:send_grp': { rpm: 20,  burst: 3,  retryAfter: 15000 },
+  'personal:friend':   { rpm: 10,  burst: 2,  retryAfter: 30000 },
+}
+
+export class ZaloRateLimiter {
+  private queues = new Map<string, PQueue>()
+
+  constructor() {
+    for (const [key, config] of Object.entries(LIMITS)) {
+      this.queues.set(key, new PQueue({
+        concurrency: config.burst,
+        intervalCap: config.rpm,
+        interval: 60_000, // per minute window
+      }))
+    }
+  }
+
+  async execute<T>(endpoint: string, fn: () => Promise<T>): Promise<T> {
+    const queue = this.queues.get(endpoint)
+    if (!queue) throw new Error(`Unknown endpoint: ${endpoint}`)
+    return queue.add(fn) as Promise<T>
+  }
+
+  queueSize(endpoint: string): number {
+    return this.queues.get(endpoint)?.size ?? 0
+  }
+
+  pending(endpoint: string): number {
+    return this.queues.get(endpoint)?.pending ?? 0
+  }
+}
+```
+
+---
+
+## Exponential Backoff on 429
+
+```typescript
+export async function withBackoff<T>(
+  fn: () => Promise<T>,
+  maxRetries = 3,
+  baseDelay = 1000
+): Promise<T> {
+  for (let attempt = 0; attempt <= maxRetries; attempt++) {
+    try {
+      return await fn()
+    } catch (error: any) {
+      const isRateLimit = error?.status === 429 || error?.error_code === 429
+      if (!isRateLimit || attempt === maxRetries) throw error
+      const delay = baseDelay * Math.pow(2, attempt) + Math.random() * 1000
+      console.warn(`[zalo-rate-guard] Rate limited. Retry ${attempt + 1}/${maxRetries} in ${Math.round(delay)}ms`)
+      await new Promise(r => setTimeout(r, delay))
+    }
+  }
+  throw new Error('Unreachable')
+}
+```
+
+---
+
+## Quota Monitoring (OA Broadcast)
+
+Broadcast quota is a **hard monthly limit** — exceeding it silently drops messages, no error returned.
+
+```typescript
+interface QuotaTracker {
+  monthly_limit: number  // based on follower count + OA level
+  used: number
+  resets_at: Date        // 1st of each month
+}
+
+export function canBroadcast(tracker: QuotaTracker, recipientCount: number): boolean {
+  const remaining = tracker.monthly_limit - tracker.used
+  if (recipientCount > remaining) {
+    console.error(
+      `[zalo-rate-guard] Broadcast quota insufficient: need ${recipientCount}, have ${remaining}/${tracker.monthly_limit}`
+    )
+    return false
+  }
+  return true
+}
+
+export function trackBroadcastUsed(tracker: QuotaTracker, sent: number): QuotaTracker {
+  return { ...tracker, used: tracker.used + sent }
+}
+```
+
+---
+
+## Integration Pattern
+
+```typescript
+// Singleton — shared across the app
+export const limiter = new ZaloRateLimiter()
+
+// Track A: OA message send with rate limiting
+export async function sendOaMessage(userId: string, text: string) {
+  return limiter.execute('oa:send_message', () =>
+    withBackoff(() =>
+      oaApiCall('/message/cs', {
+        recipient: { user_id: userId },
+        message: { text },
+      })
+    )
+  )
+}
+
+// Track B: Personal DM with rate limiting + human jitter
+export async function sendPersonalMessage(threadId: string, text: string) {
+  const jitter = 500 + Math.random() * 1500 // 500–2000ms
+  await new Promise(r => setTimeout(r, jitter))
+  return limiter.execute('personal:send_dm', () =>
+    withBackoff(() => api.sendMessage(text, threadId, 'User'))
+  )
+}
+
+// Track B: Friend operation — highest-risk, extra jitter
+export async function addFriend(userId: string) {
+  const jitter = 2000 + Math.random() * 3000 // 2–5s
+  await new Promise(r => setTimeout(r, jitter))
+  return limiter.execute('personal:friend', () =>
+    withBackoff(() => api.sendFriendRequest(userId), 2, 5000)
+  )
+}
+```
+
+---
+
+## Anti-Ban Strategies
+
+**Track A (OA):**
+1. Stay under safe RPM limits (table above)
+2. Exponential backoff on ALL 429 responses — never retry immediately
+3. Cache user profiles — avoid repeated lookups for the same user
+4. Spread broadcasts over time — don't burst the entire follower list at once
+5. Monitor quota before each broadcast batch — stop before hitting monthly limit
+6. Use `appsecret_proof` on all requests — proves you're the legitimate app owner
+
+**Track B (Personal):**
+1. Much lower limits than OA — personal accounts are watched more closely
+2. Add human-like jitter: 500–2000ms random delay between messages (not optional)
+3. Avoid 3–6 AM (VN timezone) — traffic at those hours flags automated activity
+4. Never change profile info programmatically — triggers manual review
+5. Friend operations are highest-risk — max 10 RPM, prefer lower in practice
+6. Keep sessions long-lived — repeated login/logout is a strong ban signal
+7. Use a consistent device fingerprint (`userAgent` + `IMEI`) per account
+8. On `DuplicateConnection` (error 3000): wait 30s before reconnecting, never spam reconnects
+
+---
+
+## Sharp Edges
+
+- Rate limits are **estimated** — Zalo does not publish official numbers; treat all figures as conservative targets
+- `p-queue` `intervalCap` applies per window, not per request — test behavior under burst
+- 429 without backoff = accelerating toward ban, not slowing down
+- Broadcast quota overflow **silently drops messages** — no 429, no error, just lost sends
+- Stale cached profile data is acceptable; hitting rate limits for fresh data is not
+- Personal account friend operations are the single highest-risk action — handle with care
+- Human jitter for personal track is a survival strategy, not a nice-to-have

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@rune-kit/rune",
-  "version": "2.1.1",
-  "description": "57-skill mesh for AI coding assistants — 5-layer architecture, 200+ connections, all platforms (Claude Code, Cursor, Windsurf, Antigravity)",
+  "version": "2.2.1",
+  "description": "58-skill mesh for AI coding assistants — 5-layer architecture, 200+ connections, 8 platforms (Claude Code, Cursor, Windsurf, Antigravity, Codex, OpenCode, OpenClaw, Generic)",
   "type": "module",
   "bin": {
     "rune": "./compiler/bin/rune.js"
@@ -16,6 +16,9 @@
     "cursor",
     "windsurf",
     "antigravity",
+    "codex",
+    "opencode",
+    "openclaw",
     "ai-assistant",
     "ai-coding",
     "skills",

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/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
 
@@ -170,6 +203,8 @@ This phase is lightweight — a Read + pattern match, not a full scan. It does N
 
 **Goal**: Detect if a master plan already exists for this task. If so, skip Phase 1-2 and resume from the current phase.
 
+**Step 0.5 — Cross-Project Recall**: Call `neural-memory` (Recall Mode) with 3-5 topics relevant to the current task. Load applicable patterns, past decisions, and error history from neural memory. Always prefix queries with the project name to avoid cross-project noise (e.g., `"ProjectName auth pattern"` not just `"auth pattern"`). This activates neurons from past sessions and surfaces context that may not be in the local `.rune/` files.
+
 1. Use `Glob` to check for `.rune/plan-*.md` files
 2. If a master plan exists that matches the current task:
    - Read the master plan file
@@ -405,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.
@@ -470,7 +531,8 @@ This is OPT-IN — only activate if:
    - If Phase 4 had 3 debug-fix loops (max) for a specific error pattern, write a routing override to `.rune/metrics/routing-overrides.json`:
      - Format: `{ "id": "r-<timestamp>", "condition": "<error pattern>", "action": "route to problem-solver before debug", "source": "auto", "active": true }`
    - Max 10 active rules — if exceeded, remove oldest inactive rule
-7. Mark Phase 8 as `completed`
+7. **Step 8.5 — Capture Learnings**: Call `neural-memory` (Capture Mode). Save 2-5 memories covering: architecture decisions made this session, patterns introduced or validated, errors encountered and their root-cause fixes, and any trade-offs chosen. Use rich cognitive language (causal, decisional, comparative — not flat facts). Tag each memory with `[project-name, technology, topic]`. Priority: 5 for routine patterns, 7-8 for key decisions, 9-10 for critical errors. Do NOT batch — save each memory immediately. Do NOT wait for the user to ask.
+8. Mark Phase 8 as `completed`
 
 ## Autonomous Loop Patterns
 
@@ -510,6 +572,26 @@ 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.
+
 ## Error Recovery
 
 | Phase | If this fails... | Do this... |
@@ -530,6 +612,7 @@ If any exit condition triggers without resolution → cook emits `BLOCKED` statu
 
 ## Calls (outbound)
 
+- `neural-memory` (external): Phase 0 (resume) + Phase 8 (complete) — Recall project context at start, capture learnings at end
 - `sentinel-env` (L3): Phase 0.5 — environment pre-flight (first run only)
 - `scout` (L2): Phase 1 — scan codebase before planning
 - `onboard` (L2): Phase 1 — if no CLAUDE.md exists, initialize project context first

package/skills/debug/SKILL.md

@@ -42,6 +42,7 @@ If root cause cannot be identified after 3 hypothesis cycles:
 - `problem-solver` (L3): structured reasoning (5 Whys, Fishbone) for complex bugs
 - `browser-pilot` (L3): capture browser console errors, network failures, visual bugs
 - `sequential-thinking` (L3): multi-variable root cause analysis
+- `neural-memory` (L3): after root cause found — capture error pattern for future recognition
 
 ## Called By (inbound)
 
@@ -130,6 +131,10 @@ Narrow to the single actual cause.
 - Identify the specific file, line number, and code construct responsible
 - Note any contributing factors (environment, data, timing, config)
 
+### Step 5b: Capture Error Pattern
+
+Call `neural-memory` (Capture Mode) to save the error pattern: root cause, symptoms, and fix approach. Tag with [project-name, error, technology].
+
 ### Step 6: 3-Fix Escalation Rule
 
 <HARD-GATE>

package/skills/fix/SKILL.md

@@ -38,6 +38,7 @@ If unsure whether the test is wrong or the implementation is wrong → call `run
 - `docs-seeker` (L3): check correct API usage before applying changes
 - `hallucination-guard` (L3): verify imports after code changes
 - `scout` (L2): find related code before applying changes
+- `neural-memory` (L3): after fix verified — capture fix pattern (cause → solution)
 
 ## Called By (inbound)
 
@@ -119,6 +120,10 @@ Verify correctness of the changes just made.
 - Call `rune:docs-seeker` if any external API, library method, or SDK call was added or changed
 - For complex or risky fixes (auth, data mutation, async logic): call `rune:review` for a full quality check
 
+### Step 6b: Capture Fix Pattern
+
+Call `neural-memory` (Capture Mode) to save the fix pattern: what broke, why, and how it was fixed. Priority 7 for recurring bugs.
+
 ### Step 7: Report
 
 Produce a structured summary of all changes made.

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