@rune-kit/rune 2.17.1 → 2.18.0

package/skills/perf/SKILL.md

@@ -1,9 +1,9 @@
 ---
 name: perf
-description: "Performance regression gate. Detects N+1 queries, sync-in-async, missing indexes, memory leaks, and bundle bloat before they reach production."
+description: "Performance regression gate. Detects N+1 queries, sync-in-async, missing indexes, memory leaks, and bundle bloat before they reach production. Ranks findings by Cost Impact Hierarchy (architecture > data transfer > compute > DB > caching) so fix priority maps to actual unit-cost reduction."
 metadata:
   author: runedev
-  version: "0.3.0"
+  version: "0.4.0"
   layer: L2
   model: sonnet
   group: quality
@@ -139,6 +139,30 @@ def get(key):
 ```
 Finding: `UNBOUNDED_CACHE — [file:line] — dict grows indefinitely — add LRU eviction or TTL`
 
+**Closure-captured arrays:**
+```javascript
+// BAD: closure retains entire `items` even after only `id` is needed
+function makeHandler(items) {
+  return (e) => items.find(x => x.id === e.id);  // items array retained
+}
+// GOOD: extract minimum data
+function makeHandler(items) {
+  const ids = new Set(items.map(x => x.id));
+  return (e) => ids.has(e.id);
+}
+```
+Finding: `CLOSURE_RETAIN — [file:line] — closure captures full collection — extract needed fields only`
+
+**Timer / interval without clear:**
+- `setInterval` / `setTimeout` callback referencing component state without cleanup on unmount
+- Finding: `LEAK_TIMER — [file:line] — interval not cleared — add clearInterval in cleanup`
+
+**Cost framing — memory leak = cost driver:**
+
+Unbounded caches + forgotten listeners + closure-captured arrays produce a chain reaction in production: memory grows → process exceeds container limit → orchestrator kills + cold-starts → cold-start latency spike → autoscaler provisions more replicas → bill climbs 20-40% versus a leak-free baseline. The leak finding is also a COST finding. When tagging severity, escalate any leak in a long-running process (worker, daemon, queue consumer) to **BLOCK** even if heap profile is currently under threshold — the slope, not the absolute, determines OOM timing.
+
+Cross-link to `debug` when a leak surfaces during diagnosis: `debug` finds the cause, `perf` quantifies the cost driver and recommends scope (LRU vs WeakRef vs explicit lifecycle).
+
 ### Step 5 — Bundle Analysis (frontend only)
 
 If project type is frontend:
@@ -276,6 +300,69 @@ Total estimated monthly                                  $X.XX
 
 **Key insight**: The most impactful optimization is often **model selection per operation** — using a cheaper model for background tasks (summarization, classification, metadata extraction) while reserving expensive models for primary user-facing interactions. A 10x cost reduction on 60% of calls = 6x overall savings.
 
+### Step 8.6 — Observability Cost Control
+
+Logging, tracing, and metrics infrastructure is often the **second-largest cloud bill line after compute** for production workloads. Most observability cost is self-inflicted — high-cardinality labels, unsampled traces, or 100% INFO log retention. Scan for the four common patterns:
+
+**Sampling discipline:**
+| Layer | Healthy default | Anti-pattern |
+|---|---|---|
+| INFO logs | 5-10% sample, 100% on warn/error | 100% retention on all levels |
+| Distributed traces | 5-10% normal, 100% on errors or > p95 latency | Head-based 100% sampling |
+| Metrics | Pre-aggregated at agent (no per-event metrics) | Per-event metrics emission |
+| Debug logs | Off in prod; on-demand via runtime flag | Always-on debug retention |
+
+**Findings to emit:**
+
+| Pattern | Finding | Cost impact |
+|---|---|---|
+| Log line emits unique IDs (`user_id`, `request_id`, `trace_id`) AS A METRIC LABEL | `HIGH_CARDINALITY_METRIC — [file:line] — label [name] is unbounded — move to log/trace, not metric` | Metric stores explode 100x+ ingestion cost |
+| No sampling on INFO logs | `LOG_NO_SAMPLE — [file:line] — INFO logged at 100% — add sampling (10% INFO, 100% warn+)` | 10x log volume = 10x bill |
+| Trace sampling head-based at 100% | `TRACE_NO_SAMPLE — [file:line] — head sampling 100% — switch to tail-based 5-10% with always-on for errors/slow` | 20x trace volume |
+| `console.log` in production hot path | `LOG_HOT_PATH — [file:line] — log emitted per request in tight loop — gate behind LOG_LEVEL or remove` | Logs dominate IOPS; throttles real traffic |
+| Sentry / OTel SDK with no scrubbing config | `OBS_NO_SCRUB — [file:line] — payloads emitted unscrubbed — risk PII + cost (large payloads)` | Compliance + ingestion cost |
+
+**Cost framing**: same project, same business logic; the observability cost line moves 5-20x depending on whether sampling is disciplined. Especially severe in serverless/edge runtimes where every invocation pays cold-start log ingestion overhead.
+
+## Cost Impact Hierarchy
+
+Not every perf finding has the same cost impact. When the report has multiple findings competing for engineering attention, rank them by where they sit in this hierarchy — fixes higher up the tree deliver more $ per engineering hour than fixes lower down.
+
+```
+Tier 1 — Architecture choices (10x impact)
+  • Hot loop running on wrong runtime (serverless cold-start per call vs warm container)
+  • N+1 queries that fan out to upstream rate limit (compounds with retries)
+  • Single-region for global users (egress + latency cost)
+
+Tier 2 — Data transfer (3-5x impact)
+  • Cross-AZ chatter (per-GB egress)
+  • Uncompressed responses (gzip = 70-90% reduction)
+  • Image format (WebP/AVIF = 25-50% reduction over JPEG/PNG)
+  • Log/trace volume (see Step 8.6)
+
+Tier 3 — Compute right-sizing (2-3x impact)
+  • Oversized instance types
+  • Over-provisioned autoscaler floor
+  • Always-on workers for bursty traffic
+
+Tier 4 — DB optimization (1.5-2x impact)
+  • Missing index on hot query
+  • N+1 within a single DB connection (cheaper than cross-service N+1)
+  • Connection pool sizing
+  • Query result caching
+
+Tier 5 — Caching layer (1.2-1.5x impact)
+  • CDN cache hit rate
+  • Application-level memoization
+  • Read-through cache for hot reads
+```
+
+**Reporting rule**: when verdict is BLOCK or WARN, group findings by tier in the report. Operator should NOT optimize Tier 5 caching when a Tier 1 architecture mismatch is sitting unaddressed — the Tier 1 fix subsumes the Tier 5 gain.
+
+**Unit economics anchor**: where possible, attach a unit-cost delta to each finding (e.g., `LOG_NO_SAMPLE` → `~$X/mo per 10k req` based on operator's current observability vendor pricing). If unit-cost data unavailable, flag the finding with the tier-based multiplier band instead of leaving impact blank.
+
+**Cost-allocation precondition**: a perf report's cost claims are only auditable if cloud resources have allocation tags (Environment, Team, Service). If `deploy` artifacts show untagged resources, raise a WARN `COST_UNATTRIBUTED — resources lack allocation tags — anomaly detection blind; tag-first then optimize`.
+
 ## Output Format
 
 ```
@@ -321,6 +408,10 @@ Known failure modes for this skill. Check these before declaring done.
 | Skipping framework checks because framework not detected | MEDIUM | If scout returns unknown framework, run generic checks + note in report |
 | Calling browser-pilot on backend-only project | LOW | Check project type in Step 1 — browser-pilot only for frontend/fullstack |
 | Reporting WARN as BLOCK (severity inflation) | MEDIUM | BLOCK = measurable regression on hot path; WARN = pattern that could be slow |
+| Memory leak found, severity left as MEDIUM | HIGH | Leak in long-running process = cost driver (OOM restart loop → autoscaler spend). Escalate to BLOCK when process lifetime > 1 hour |
+| High-cardinality label silently added as metric tag | HIGH | `user_id` / `request_id` / `trace_id` as METRIC label explodes ingestion cost 100x. Move to log/trace, never metric |
+| Findings reported without tier ranking when multiple compete | MEDIUM | Cost Impact Hierarchy groups by tier (1-5). Tier 1 fix subsumes Tier 5 gain; operator otherwise optimizes wrong target |
+| Cost claim made without cloud tag prerequisite | MEDIUM | Untagged resources = anomaly detection blind. Pair perf findings with WARN `COST_UNATTRIBUTED` when cloud tags missing |
 
 ## Done When
 

package/skills/sentinel-env/SKILL.md

@@ -3,7 +3,7 @@ name: sentinel-env
 description: "Environment-aware pre-flight check. Use when starting work in a new environment, switching machines, or when 'works on my machine' bugs surface. Validates OS, runtime versions, installed tools, port availability, env vars, and disk space BEFORE coding starts. Like sentinel but for the environment, not the code."
 metadata:
   author: runedev
-  version: "0.3.0"
+  version: "0.4.0"
   layer: L3
   model: haiku
   group: validation
@@ -130,7 +130,7 @@ Detect and verify tools the project depends on:
    | 5 | Platform desktop-app bundle (macOS `.app/Contents/Resources`, Windows `%LOCALAPPDATA%\Programs`, Linux `/opt`) | Desktop app users (~40% of population) |
    | 6 | PATH lookup (`which`/`where.exe`) | Standard shell users |
    | 7 | Package manager global bin (`npm config get prefix`, `pnpm`, `pipx --list`, `cargo install --root`) | npm-global on Windows (PATH oversight) |
-   | 8 | Platform common directories (`~/.local/bin`, `~/.npm-global/bin`, Homebrew, `%APPDATA%\npm`, `%LOCALAPPDATA%\Microsoft\WindowsApps`, `%ProgramFiles%\nodejs`) | Manual installers |
+   | 8 | Platform common directories — Unix: `~/.local/bin`, `~/.npm-global/bin`, `~/.bun/bin`, `~/.cargo/bin`, `~/.deno/bin`, `~/.volta/bin`, `~/.asdf/shims`, `~/.proto/bin`, `/opt/homebrew/bin`, `/usr/local/bin`. Windows: `%APPDATA%\npm`, `%USERPROFILE%\.bun\bin`, `%USERPROFILE%\.cargo\bin`, `%USERPROFILE%\.deno\bin`, `%LOCALAPPDATA%\Microsoft\WindowsApps`, `%ProgramFiles%\nodejs` | Bun / Cargo / Deno / Volta / asdf / proto users + manual installers |
    | 9 | Platform release archive names (e.g., `codex-x86_64-unknown-linux-musl`, `<tool>-aarch64-apple-darwin`) | Release-tarball downloaders |
 
    **Verdict:**

package/skills/skill-forge/SKILL.md

@@ -3,7 +3,7 @@ name: skill-forge
 description: "Use when creating new Rune skills, editing existing skills, or verifying skill quality before deployment. Applies TDD discipline to skill authoring — test before write, verify before ship."
 metadata:
   author: runedev
-  version: "1.8.0"
+  version: "1.9.0"
   layer: L2
   model: opus
   group: creation
@@ -436,6 +436,46 @@ Wire the skill into the mesh:
 5. **Write Self-Validation** — 3-5 domain-specific checks unique to this skill's output. Ask: "What quality issues can ONLY this skill catch?"
 6. **Verify no conflicts** — new skill's output format compatible with consumers?
 
+### Phase 6.25 — EXAMPLES (output-format skills only)
+
+Output-format skills (skills that produce visual or text artifacts a human will see) SHOULD ship a literal example of the output alongside SKILL.md. The example is a target the agent can copy from — not a description it must interpret.
+
+**Applies to:**
+- `design`, `asset-creator`, `slides`, `marketing`, `video-creator`, `doc-processor`
+- Any pack skill whose primary output is a rendered artifact (HTML page, slide deck, social card, video script, report PDF)
+
+**Does not apply to:**
+- Process / orchestration skills (`cook`, `plan`, `review`) — their output is structural, not rendered
+- Diagnostic skills (`debug`, `audit`, `perf`) — their output is findings, not artifacts
+
+**Convention:**
+
+```
+skills/<name>/
+├── SKILL.md
+├── references/
+│   └── ...
+└── examples/
+    ├── README.md           # short index: which example fits which scenario
+    ├── <scenario-1>.html   # or .md / .json / .svg per skill domain
+    ├── <scenario-2>.html
+    └── ...
+```
+
+**Why a literal example beats a description:**
+- An agent can copy structure, density, and rhythm from a real file. It cannot copy them from "make it modern."
+- A reviewer can diff agent output against the example to spot drift.
+- Examples are the test corpus for the skill — if a new style emerges, the example shows whether SKILL.md kept up.
+
+**Quality bar:**
+- Each example MUST render without error in the target environment (browser, Marp, Notion, etc.)
+- Each example MUST use real-looking data, not lorem ipsum (mirrors design Step 2.9 Rule 5)
+- Cover at least 2 scenarios per skill — minimum spread reveals which decisions are baked in vs which are scenario-driven
+
+**Soft, not HARD-GATE:** Per Rune's no-discipline-heavy-grafts policy, don't enforce as a ship blocker. A new skill without examples ships fine; reviewers may suggest adding them. Existing output-format skills are encouraged (not required) to backfill examples on the next material edit.
+
+**Inspiration:** Pattern adapted from `nexu-io/html-anything` (Apache-2.0), where every "surface skill" ships a hand-authored `example.html` so the agent has a copy target. They make it a ship blocker; we make it a strong recommendation.
+
 ### Phase 6.5 — EXTENSION AUTHORING (if building an extension, not a skill)
 
 Extensions augment existing skills with optional capabilities. Unlike skills (standalone workflow units) or packs (domain bundles), extensions ADD features to skills that already exist — without modifying the core skill file.
@@ -566,6 +606,12 @@ git commit -m "feat: add [skill-name] — [one-line purpose]"
 - [ ] ARCHITECTURE.md updated
 - [ ] CLAUDE.md updated
 
+**Output-format skills only (recommended, not blocking):**
+- [ ] `examples/` directory present with ≥ 2 scenario examples
+- [ ] `examples/README.md` indexes which example fits which scenario
+- [ ] Each example renders without error in its target environment
+- [ ] No lorem ipsum in any example (use real-looking data)
+
 **Extension-specific (if building an extension):**
 - [ ] EXTENSION.md manifest present with extends, requires, install_method
 - [ ] install.sh + install.ps1 tested (non-destructive merge)

package/skills/surgeon/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: surgeon
-description: "Incremental refactorer. Use within a rescue workflow after safeguard has set up safety nets. Refactors ONE module per session using proven patterns — Strangler Fig, Branch by Abstraction, Expand-Migrate-Contract."
+description: "Incremental refactorer. Use when refactoring ONE module at a time within a rescue workflow after safeguard has set up safety nets — never as a standalone refactor for greenfield code. Applies proven patterns: Strangler Fig, Branch by Abstraction, Expand-Migrate-Contract."
 metadata:
   author: runedev
   version: "0.2.0"

package/skills/team/SKILL.md

@@ -5,7 +5,7 @@ context: fork
 agent: general-purpose
 metadata:
   author: runedev
-  version: "1.0.0"
+  version: "1.1.0"
   layer: L1
   model: opus
   group: orchestrator
@@ -165,8 +165,34 @@ GATE CHECK — before proceeding:
   [ ] Total streams ≤ 3
   [ ] Change Stacking check: no file appears in touches[] of 2+ parallel streams
   [ ] Every stream's requires[] is satisfied by a prior stream's provides[] or existing code
+  [ ] Shared Contract Gate: if 2+ parallel streams consume the same interface/type/API, the contract MUST be defined before any stream starts (see below)
 
 If any check fails → re-invoke plan with conflict notes.
+
+**Shared Contract Gate:**
+
+When parallel streams both depend on a shared interface (types, API contract, database schema), that contract must be locked before streams start. Otherwise two agents may independently define incompatible versions.
+
+```
+Detection:
+  → Grep each stream's file list for shared imports (types, interfaces, API clients)
+  → If stream A and stream B both import from the same module:
+      EITHER: move that module to a dependency stream (depends_on: [])
+      OR: define the contract inline in the NEXUS Handoff as "Code Contracts" section
+
+Contract format in NEXUS Handoff:
+  ### Code Contracts (locked — do not modify)
+  ```typescript
+  // Shared interface — both streams consume this, neither owns it
+  interface OrderResult {
+    orderId: string;
+    status: 'pending' | 'filled' | 'cancelled';
+    filledAt?: Date;
+  }
+  ```
+  Streams may consume this contract but MUST NOT modify it.
+  If a stream discovers the contract is insufficient → status = NEEDS_CONTEXT, not silent modification.
+```
 ```
 
 **1d. Question Gate (non-trivial tasks only).**