@rune-kit/rune 2.1.1 → 2.2.1

package/skills/neural-memory/SKILL.md

@@ -0,0 +1,362 @@
+---
+name: neural-memory
+description: "Cross-session cognitive persistence via Neural Memory MCP. Captures decisions, patterns, errors, and insights with rich semantic links. Provides recall, hypothesis tracking, and evidence-based reasoning across projects."
+metadata:
+  author: rune-kit
+  version: 0.1.0
+  layer: L3
+  model: haiku
+  group: state
+  tools:
+    - mcp__neural-memory__nmem_remember
+    - mcp__neural-memory__nmem_recall
+    - mcp__neural-memory__nmem_auto
+    - mcp__neural-memory__nmem_hypothesize
+    - mcp__neural-memory__nmem_evidence
+    - mcp__neural-memory__nmem_predict
+    - mcp__neural-memory__nmem_verify
+    - mcp__neural-memory__nmem_edit
+    - mcp__neural-memory__nmem_forget
+    - mcp__neural-memory__nmem_health
+    - mcp__neural-memory__nmem_consolidate
+    - mcp__neural-memory__nmem_explain
+    - mcp__neural-memory__nmem_gaps
+    - mcp__neural-memory__nmem_stats
+    - mcp__neural-memory__nmem_review
+    - mcp__neural-memory__nmem_cognitive
+    - Read
+    - Grep
+---
+
+# neural-memory
+
+## Purpose
+
+Bridges Rune's file-based persistence (session-bridge, journal) with Neural Memory MCP's semantic graph. While session-bridge saves decisions to `.rune/` files and journal tracks ADRs locally, neural-memory captures **cross-project learnable patterns** — decisions, error root causes, architectural insights, and workflow preferences — into a persistent cognitive layer that compounds across every project and session.
+
+Without this skill, each project is an island. With it, a caching pattern discovered in Project A auto-surfaces when Project B faces a similar problem.
+
+## Triggers
+
+**Auto-trigger:**
+- Session start → Run **Recall Mode** (load relevant context before any work)
+- After `cook` completes a feature → Run **Capture Mode** (save learnings)
+- After `debug` finds root cause → Run **Capture Mode** (save error pattern)
+- After `review` finds issues → Run **Capture Mode** (save code quality insight)
+- After `rescue` completes a phase → Run **Capture Mode** (save refactoring pattern)
+- After `journal` writes an ADR → Run **Capture Mode** (extract to nmem)
+- Session end / before compaction → Run **Flush Mode** (capture remaining context)
+
+**Manual trigger:**
+- `/rune recall <topic>` — search neural memory for a topic
+- `/rune remember <text>` — save a specific memory
+- `/rune brain-health` — check neural memory health + maintenance
+- `/rune hypothesize <question>` — start hypothesis tracking
+
+## Calls (outbound)
+
+| Skill | When | Why |
+|-------|------|-----|
+| `session-bridge` | After Capture Mode | Sync key decisions back to `.rune/` files |
+
+## Called By (inbound)
+
+| Skill | When | Why |
+|-------|------|-----|
+| `cook` | Phase 0 (resume) + Phase 8 (complete) | Recall project context at start, capture learnings at end |
+| `debug` | After root cause found | Capture error pattern for future recognition |
+| `fix` | After fix verified | Capture fix pattern (cause → solution) |
+| `review` | After review complete | Capture code quality insight |
+| `rescue` | Phase start + phase end | Recall past refactoring patterns, capture new ones |
+| `plan` | Before architecture decisions | Recall past decisions on similar problems |
+| `session-bridge` | Step 6 (cross-project extraction) | Extract generalizable patterns to nmem |
+| `journal` | After ADR written | Extract decision + rejected alternatives to nmem |
+| `context-engine` | Before compaction | Trigger Flush Mode to preserve context |
+| `sentinel` | After security finding | Capture vulnerability pattern |
+| `incident` | After resolution | Capture incident root cause + fix |
+
+## Modes
+
+### Mode 1: Recall (Session Start / Before Decisions)
+
+Load relevant context from neural memory before starting work.
+
+**Step 1 — Identify Recall Topics**
+Read `.rune/progress.md` and current task context to determine 3-5 diverse recall topics.
+Always prefix queries with the project name to avoid cross-project noise.
+
+```
+GOOD: "Rune compiler cross-reference resolution"
+GOOD: "MyTrend PocketBase auth session handling"
+BAD:  "cross-reference" (too generic, returns all projects)
+BAD:  "auth" (returns noise from every project)
+```
+
+**Step 2 — Execute Recall**
+Call `nmem_recall` for each topic. Use diverse angles:
+- Technology-specific: `"<project> React state management"`
+- Problem-specific: `"<project> caching strategy decision"`
+- Pattern-specific: `"<project> error handling approach"`
+
+**Step 3 — Synthesize Context**
+Summarize recalled memories into actionable context:
+- Decisions that apply to current task
+- Patterns that worked (or failed) before
+- Constraints or preferences from past sessions
+- Open hypotheses still being tracked
+
+**Step 4 — Surface Gaps**
+If recall returns thin results for the current domain, note the gap.
+Call `nmem_gaps(action="detect")` if working in a domain with sparse memories.
+
+---
+
+### Mode 2: Capture (After Task Completion)
+
+Extract learnable patterns from completed work and save to neural memory.
+
+**Step 1 — Classify What Happened**
+Determine which memory types to create from the completed task:
+
+| What happened | Memory type | Priority | Example |
+|---------------|-------------|----------|---------|
+| Chose approach A over B | `decision` | 7 | "Chose Zustand over Redux because single-store simpler for this scale" |
+| Found and fixed a bug | `error` | 7 | "Root cause was stale closure in useEffect — fixed by adding dep array" |
+| Discovered a reusable pattern | `insight` | 6 | "This codebase uses barrel exports for every feature module" |
+| Learned user preference | `preference` | 8 | "User prefers Phosphor Icons over Lucide for all UI work" |
+| Established a workflow | `workflow` | 6 | "Deploy: build → test → push → verify CI → tag" |
+| Found a fact worth keeping | `fact` | 5 | "API rate limit is 100 req/min on free tier" |
+| Received instruction to follow | `instruction` | 8 | "Always run prettier before commit in this project" |
+
+**Step 2 — Craft Rich Memories**
+Each memory MUST use cognitive language patterns for strong neural connections:
+
+```
+BAD:  "PostgreSQL" (flat, no context — orphan neuron)
+GOOD: "Chose PostgreSQL over MongoDB because ACID needed for payment processing"
+
+BAD:  "Fixed auth bug" (no root cause — useless for future recall)
+GOOD: "Auth cookie expired silently because SameSite=Lax blocked cross-origin. Fixed by setting SameSite=None + Secure flag"
+
+BAD:  "React project structure" (vague — won't match specific queries)
+GOOD: "Rune compiler uses 3-stage pipeline: Parse SKILL.md → Transform cross-refs → Emit per-platform files"
+```
+
+**Cognitive patterns to use:**
+- **Causal**: "X caused Y because Z", "Root cause was X which led to Y"
+- **Temporal**: "After upgrading to v3, the middleware broke because of new cookie format"
+- **Decisional**: "Chose X over Y because Z", "Rejected X due to Y"
+- **Comparative**: "X is 3x faster than Y for read-heavy workloads"
+- **Relational**: "X depends on Y", "X replaced Y", "X connects to Y through Z"
+
+**Step 3 — Tag and Prioritize**
+Every memory MUST include:
+- **Tags**: `[project-name, technology, topic]` — lowercase, specific
+- **Priority**: 5 (normal), 7-8 (important decisions/errors), 9-10 (critical security/breaking)
+- **Max length**: 1-3 sentences. If longer, split into focused pieces.
+
+**Step 4 — Save Memories**
+Call `nmem_remember` for each memory. Save 2-5 memories per completed task:
+- A bug fix has: root cause, fix approach, prevention insight
+- A feature has: architecture decision, pattern used, trade-off made
+- A review has: quality issue found, fix suggestion, pattern to avoid
+
+**Step 5 — Reinforce Connections**
+After saving, call `nmem_recall` on the topic to reinforce new neural connections.
+This activates related neurons and strengthens the memory graph.
+
+---
+
+### Mode 3: Hypothesis Tracking
+
+Track uncertain decisions with evidence over time.
+
+**Step 1 — Form Hypothesis**
+When making an uncertain architectural or design decision:
+```
+nmem_hypothesize("Redis will handle our session load better than Memcached
+                   because our access pattern is 80% reads with complex data types")
+```
+
+**Step 2 — Collect Evidence**
+As you work, update the hypothesis with evidence:
+```
+nmem_evidence(hypothesis_id, "Redis handled 10K concurrent sessions with
+              p99 < 5ms in load test — SUPPORTS hypothesis")
+
+nmem_evidence(hypothesis_id, "Memory usage 2x higher than Memcached estimate
+              — WEAKENS hypothesis for memory-constrained deployments")
+```
+
+**Step 3 — Make Predictions**
+Create falsifiable predictions:
+```
+nmem_predict("If we switch to Redis Cluster, session failover time will drop
+              from 30s to < 2s")
+```
+
+**Step 4 — Verify Outcomes**
+After deployment/testing, verify:
+```
+nmem_verify(prediction_id, outcome="Failover time dropped to 1.2s — CONFIRMED")
+```
+
+---
+
+### Mode 4: Flush (Session End / Pre-Compaction)
+
+Capture remaining context before session ends.
+
+**Step 1 — Scan Unsaved Context**
+Review the current session for:
+- Decisions made but not yet captured
+- Errors encountered and their resolutions
+- Patterns discovered during exploration
+- User preferences expressed
+
+**Step 2 — Batch Save**
+Call `nmem_auto(action="process", text="<session summary>")` with a concise summary
+of the session's key outcomes, decisions, and learnings.
+
+**Step 3 — Update Session Bridge**
+If significant decisions were captured, also call `session-bridge` to sync
+the most important ones to `.rune/decisions.md` for local persistence.
+
+---
+
+### Mode 5: Maintenance (Weekly / On-Demand)
+
+Keep the neural memory healthy and useful.
+
+**Step 1 — Health Check**
+Call `nmem_health()` to assess brain status. Key metrics:
+- Consolidation % (low = run consolidation)
+- Orphan % (>20% = prune disconnected memories)
+- Activation levels (low = recall more diverse topics)
+- Connectivity (low = use richer cognitive language)
+- Diversity (low = vary memory types)
+
+**Step 2 — Consolidation**
+If brain has >100 memories or consolidation is low:
+```
+nmem_consolidate  — merge episodic → semantic memories
+```
+
+**Step 3 — Review Queue**
+Call `nmem_review(action="queue")` to surface memories needing attention:
+- Outdated decisions that may no longer apply
+- Low-confidence memories that need evidence
+- Wall-of-text memories (>500 chars) that should be split
+
+**Step 4 — Corrections**
+Fix bad memories:
+- Wrong type → `nmem_edit(memory_id, type="correct_type")`
+- Wrong content → `nmem_edit(memory_id, content="corrected text")`
+- Outdated → `nmem_forget(memory_id, reason="outdated")`
+- Sensitive/garbage → `nmem_forget(memory_id, hard=true)`
+
+**Step 5 — Connection Tracing**
+Use `nmem_explain(entity_a, entity_b)` to trace paths between concepts.
+Useful for understanding why certain memories surface together.
+
+## Output Format
+
+### Recall Report
+```
+## Neural Memory Recall — <project>
+
+### Loaded Context
+- <memory 1 summary — decision/pattern/insight>
+- <memory 2 summary>
+- <memory 3 summary>
+
+### Applicable to Current Task
+- <how memory X applies>
+- <how memory Y applies>
+
+### Gaps Detected
+- <domain with sparse coverage>
+```
+
+### Capture Report
+```
+## Neural Memory Capture — <task summary>
+
+### Saved Memories
+| # | Type | Priority | Tags | Content (preview) |
+|---|------|----------|------|--------------------|
+| 1 | decision | 7 | [project, tech, topic] | Chose X over Y because... |
+| 2 | error | 7 | [project, bug, tech] | Root cause was X... |
+| 3 | insight | 6 | [project, pattern] | This codebase uses... |
+
+### Reinforced Topics
+- <topic recalled to strengthen connections>
+```
+
+### Health Report
+```
+## Neural Memory Health
+
+| Metric | Value | Status |
+|--------|-------|--------|
+| Total memories | N | — |
+| Consolidation | N% | ✅ / ⚠️ |
+| Orphans | N% | ✅ / ⚠️ |
+| Activation | level | ✅ / ⚠️ |
+| Top penalty | <metric> | Fix: <action> |
+
+### Recommended Actions
+1. <action with command>
+```
+
+## Constraints
+
+1. **MUST prefix all recall queries with project name** — generic queries return cross-project noise that confuses the AI. The ONLY exception is intentional cross-project searches.
+2. **MUST use rich cognitive language** — flat facts ("X exists") create orphan neurons with zero connections. Every memory MUST include WHY, BECAUSE, or relationship context.
+3. **MUST NOT save wall-of-text memories** — max 1-3 sentences per memory. Split longer content into focused pieces. Memories >500 chars degrade recall quality.
+4. **MUST NOT duplicate file-based state** — don't save task progress, file paths, or git history to nmem. Those belong in `.rune/` files (session-bridge) or git. nmem is for *learnable patterns* only.
+5. **MUST save 2-5 memories per completed task** — a single memory per task is insufficient. Capture the decision, the reasoning, the pattern, and the prevention insight separately.
+6. **MUST NOT save sensitive data** — no API keys, passwords, tokens, or PII. Mask or omit sensitive values.
+7. **MUST tag every memory** — always include `[project-name, technology, topic]`. Tags enable future recall precision.
+
+## Sharp Edges
+
+| Failure Mode | Severity | Mitigation |
+|---|---|---|
+| Cross-project noise from generic queries | HIGH | Always prefix queries with project name. Use `nmem_explain` to trace unexpected connections |
+| Orphan neurons from flat facts | HIGH | Enforce cognitive language patterns (causal, decisional, comparative). Run `nmem_health` to detect orphan % |
+| Memory bloat from over-saving | MEDIUM | Cap at 5 memories per task. Run `nmem_consolidate` weekly. Use `nmem_review` to prune |
+| Stale decisions applied to changed codebase | MEDIUM | Include temporal context ("As of v2.1, ..."). Verify recalled decisions against current code before applying |
+| Duplicate memories from repeated sessions | MEDIUM | Before saving, `nmem_recall` the topic first to check for existing memories. Update rather than create duplicates |
+| Loss of nuance from oversimplification | LOW | Save rejected alternatives alongside chosen approach. Use `nmem_hypothesize` for uncertain decisions |
+
+## Done When
+
+**Recall Mode:**
+- 3-5 diverse topics recalled with project-name prefix
+- Applicable context summarized for current task
+- Gaps noted if coverage is thin
+
+**Capture Mode:**
+- 2-5 memories saved with rich cognitive language
+- All memories tagged with `[project, technology, topic]`
+- Priority assigned (5-10 scale)
+- Connections reinforced via post-save recall
+
+**Flush Mode:**
+- All significant unsaved decisions captured
+- `nmem_auto` called with session summary
+- Session-bridge synced if major decisions made
+
+**Maintenance Mode:**
+- `nmem_health` run and metrics assessed
+- Top penalty addressed with specific action
+- Review queue processed (outdated/bloated memories fixed)
+
+## Cost Profile
+
+- **Recall**: ~200-500 tokens (3-5 queries + synthesis)
+- **Capture**: ~300-600 tokens (2-5 memories + reinforcement)
+- **Flush**: ~100-300 tokens (auto-process + sync)
+- **Maintenance**: ~500-1000 tokens (health + consolidate + review)
+- **Hypothesis**: ~200-400 tokens per hypothesis lifecycle

package/skills/plan/SKILL.md

@@ -88,6 +88,7 @@ High-level multi-feature planning — organize features into milestones.
 - `research` (L3): external knowledge lookup
 - `sequential-thinking` (L3): complex architecture with many trade-offs
 - L4 extension packs: domain-specific architecture patterns
+- `neural-memory` | Before architecture decisions | Recall past decisions on similar problems
 
 ## Called By (inbound)
 
@@ -113,6 +114,8 @@ High-level multi-feature planning — organize features into milestones.
 
 Use findings from `rune:scout` if already available. If not, invoke `rune:scout` with the project root to scan directory structure, detect framework, identify key files, and extract existing patterns. Do NOT skip this step — plans without context produce wrong file paths.
 
+Call `neural-memory` (Recall Mode) to check for past architecture decisions on similar problems before making new ones.
+
 ### Step 2 — Classify Complexity
 
 Determine if the task needs master plan + phase files or inline plan:

package/skills/rescue/SKILL.md

@@ -40,6 +40,7 @@ Legacy refactoring orchestrator for safely modernizing messy codebases. Rescue r
 - `session-bridge` (L3): save rescue state between sessions
 - `onboard` (L2): generate context for unfamiliar legacy project
 - `dependency-doctor` (L3): audit dependencies in legacy project
+- `neural-memory` | Phase start + phase end | Recall past refactoring patterns, capture new ones
 
 ## Called By (inbound)
 
@@ -72,6 +73,8 @@ Note: SURGERY todos are added dynamically — one per module identified in Phase
 
 Mark todo[0] `in_progress`.
 
+Call `neural-memory` (Recall Mode) for past refactoring patterns in similar codebases.
+
 **0a. Full health assessment.**
 
 ```
@@ -344,6 +347,8 @@ REQUIRED SUB-SKILL: rune:journal
 Bash: git tag rune-rescue-complete
 ```
 
+Call `neural-memory` (Capture Mode) to save refactoring patterns and decisions from this rescue.
+
 Mark VERIFY todo `completed`.
 
 ---

package/skills/review/SKILL.md

@@ -3,7 +3,7 @@ name: review
 description: Code quality review — patterns, security, performance, correctness. Finds bugs, suggests improvements, triggers fix for issues found. Escalates to opus for security-critical code.
 metadata:
   author: runedev
-  version: "0.2.0"
+  version: "0.3.0"
   layer: L2
   model: sonnet
   group: development
@@ -41,6 +41,7 @@ Every review MUST cite at least one specific concern, suggestion, or explicit ap
 - `review-intake` (L2): structured intake for complex multi-file reviews
 - `sast` (L3): static analysis security scan on reviewed code
 - L4 extension packs: domain-specific review patterns when context matches (e.g., @rune/ui for frontend, @rune/security for auth code)
+- `neural-memory` | After review complete | Capture code quality insight
 
 ## Called By (inbound)
 
@@ -69,14 +70,17 @@ Determine what to review.
 - If context is unclear: use `rune:scout` to identify all files touched by the change
 - List every file in scope before proceeding — do not review files outside the stated scope
 
-### Step 2: Logic Check
+### Step 2: Logic Check (Production-Critical Focus)
 
-Read each changed file and check for correctness.
+Read each changed file. Prioritize bugs that **pass CI but break production** — these are the highest-value findings because linters and type checkers already catch the rest.
 
 - Use `Read` on every file in scope
+- **Race conditions**: async operations without proper sequencing, shared mutable state, missing locks
+- **State corruption**: mutations that affect other consumers, cache invalidation gaps, stale closures
+- **Silent failures**: caught errors that swallow context, empty catch blocks, promises without rejection handling
+- **Data loss paths**: write operations without confirmation, delete without soft-delete, truncation without backup
+- **Edge cases**: empty input, null/undefined, zero, negative numbers, empty arrays, Unicode, timezone boundaries
 - Check for: logic errors, off-by-one errors, incorrect conditionals, broken async/await patterns
-- Check for: missing error handling, uncaught promise rejections, silent failures
-- Check for: edge cases — empty input, null/undefined, zero, negative numbers, empty arrays
 - Flag each finding with file path, line number, and severity
 
 **Common patterns to flag:**
@@ -162,6 +166,39 @@ Identify gaps in test coverage.
 - If untested code found: call `rune:test` with specific instructions on what to test
 - Flag as HIGH if business logic is untested, MEDIUM if utility code is untested
 
+### Step 5.5: Two-Stage Review Gate
+
+Separate spec compliance from code quality. Most reviews conflate both — this gate forces the distinction.
+
+**Stage 1 — Spec Compliance (check FIRST)**
+
+Before evaluating code quality, verify the implementation matches what was asked:
+
+- Load the originating plan, task, ticket, or `requirements.md` if available
+- Does the implementation cover every acceptance criterion? Check each one explicitly
+- Is there **under-engineering** — requirements stated but not implemented?
+- Is there **over-engineering** — abstractions, generalization, or features beyond scope?
+- Does the file/function structure match what the plan specified?
+
+Flag spec deviations as HIGH — clean code that misses requirements ships broken products.
+
+```
+# Spec Compliance Checklist
+[ ] All acceptance criteria from plan/ticket covered
+[ ] No stated requirements missing from implementation
+[ ] No unrequested features added (scope creep)
+[ ] API surface matches what was specified (signatures, endpoints, return types)
+[ ] File structure matches plan (no renamed or relocated files without justification)
+```
+
+If spec violations found: document them separately from code quality findings in the report. Label as `SPEC-MISS` or `SPEC-CREEP`.
+
+**Stage 2 — Code Quality**
+
+Proceed to Step 6 only after Stage 1 passes. Code quality findings (bugs, patterns, security, coverage) are the existing Steps 2–5 above.
+
+The review report MUST show both stages: spec compliance verdict first, then code quality findings.
+
 ### Step 6: Report
 
 Produce a structured severity-ranked report.
@@ -181,6 +218,7 @@ After reporting:
 - If any CRITICAL findings: call `rune:fix` immediately with the finding details
 - If any HIGH findings: call `rune:fix` with the finding details
 - If untested code: call `rune:test` with specific coverage gaps identified
+- Call `neural-memory` (Capture Mode) to save any novel code quality patterns or recurring issues found.
 
 ## Framework-Specific Checks
 
@@ -338,6 +376,7 @@ LOW       — style inconsistency, naming suggestion, minor refactor opportunity
 | Expanding review scope beyond the diff | MEDIUM | Limit to `git diff` scope — do not creep into adjacent unchanged files |
 | Security finding without sentinel escalation | HIGH | Any auth/crypto/payment code touched → MUST call rune:sentinel |
 | Skipping UI anti-pattern checks for frontend changes | MEDIUM | Any .tsx/.jsx/.svelte/.vue in diff → MUST run UI/UX Anti-Pattern Checks section |
+| Skipping spec compliance check (Step 5.5 Stage 1) | HIGH | Code quality without spec check ships clean code that does the wrong thing — always load the plan/ticket before reviewing quality |
 | Treating purple/indigo accent as "just a color choice" | MEDIUM | It is a documented AI-generated UI signature — always flag for domain justification |
 
 ## Done When

package/skills/review-intake/SKILL.md

@@ -3,7 +3,7 @@ name: review-intake
 description: Use when receiving code review feedback, PR comments, or external suggestions before implementing any changes. Prevents blind implementation, enforces verification-first discipline.
 metadata:
   author: runedev
-  version: "1.0.0"
+  version: "1.1.0"
   layer: L2
   model: sonnet
   group: quality
@@ -112,9 +112,25 @@ UNCLEAR:  "Need clarification on [specific aspect]."
 BANNED: "You're absolutely right!"
 BANNED: "Great point!" / "Great catch!"
 BANNED: "Thanks for catching that!"
+BANNED: "I agree with your suggestion"
+BANNED: "That's a good idea"
+BANNED: "I see what you mean"
+BANNED: Any sentence that adds no technical information
 BANNED: Any performative gratitude — actions speak, not words.
 ```
 
+<HARD-GATE>
+Every response to a review item MUST start with an ACTION VERB:
+- "Fixed — [description]"
+- "Reverted — [reason]"
+- "Deferred — [reason + ticket]"
+- "Pushed back — [technical evidence]"
+- "Clarifying — [question]"
+
+Responses starting with praise, agreement, or social pleasantries are BLOCKED.
+This is a professional code review, not a conversation — signal with actions, not words.
+</HARD-GATE>
+
 When replying to GitHub PR comments, reply in the thread:
 ```bash
 gh api repos/{owner}/{repo}/pulls/{pr}/comments/{id}/replies \