@rune-kit/rune 2.18.1 → 2.20.0

package/skills/ba/SKILL.md

@@ -3,7 +3,7 @@ name: ba
 description: "Business Analyst agent. Use when starting a new feature requiring requirements elicitation BEFORE plan or cook. Asks probing questions, identifies hidden requirements, maps stakeholders, defines scope boundaries, and produces a structured Requirements Document that plan and cook consume."
 metadata:
   author: runedev
-  version: "1.0.0"
+  version: "1.1.0"
   layer: L2
   model: opus
   group: creation
@@ -44,6 +44,7 @@ Output is a Requirements Document → hand off to rune:plan for implementation p
 - `cook` (L1): before Phase 2 PLAN, when task is non-trivial
 - `scaffold` (L1): Phase 1, before any project generation
 - `plan` (L2): when plan receives vague requirements
+- `brainstorm` (L2): standalone ideation that picked an approach for a new feature with no spec — hands the chosen approach to `ba` for requirements before `plan`
 - `mcp-builder` (L2): requirements elicitation before MCP server design
 - User: `/rune ba` direct invocation
 
@@ -389,6 +390,7 @@ Run each, label verdict 🟢 pass / 🟡 warn / 🔴 fail:
 | # | Check | 🔴 Fail | 🟢 Pass |
 |---|-------|---------|---------|
 | 1 | Every Acceptance Criterion traces to a User Story | AC orphaned | 1:N mapping clear |
+| 1b | Every EARS `FR-n` (Step 4.5) traces up to a User Story AND down to an AC | FR has no AC (untested promise) or no story (orphan behavior) | FR → story + AC both present |
 | 2 | Every Business Rule (Q5) is enforced in an AC or Exception Flow | Rule has no enforcement path | Rule → specific AC or exception |
 | 3 | Scope IN ∩ Scope OUT = ∅ | Direct overlap in phrasing | Sets disjoint |
 | 4 | Every user-story flow has a terminal state | State loop without exit condition | Terminal state explicit |
@@ -402,6 +404,7 @@ Run each, label verdict 🟢 pass / 🟡 warn / 🔴 fail:
 ```
 Logic Consistency Report:
   1. AC → User Story:      🟢 all AC trace to US-1 or US-2
+  1b. EARS FR → story+AC:  🟢 FR-1..FR-5 each map to a story and an AC
   2. Business rule → AC:   🟡 "no duplicate emails" cited — exception flow missing
   3. Scope disjoint:       🟢
   4. Terminal states:      🟢
@@ -441,6 +444,36 @@ Based on all gathered information, produce:
 **Dependencies** (things that must exist before we can build):
 - [APIs, services, libraries, access, existing code]
 
+### Step 4.5 — Functional Requirements (EARS)
+<MUST-READ path="references/ears-format.md" trigger="when writing the functional-requirements section for a Feature/Integration/Greenfield requirement"/>
+
+Translate each in-scope item (Step 4) into atomic, testable **functional requirements** using EARS (Easy Approach to Requirements Syntax). EARS sits between user stories (WHY) and acceptance criteria (HOW we prove it) — it names exactly WHAT the system shall do, with an explicit trigger or condition.
+
+Pick the simplest EARS template that fits each behavior; give each a stable ID (`FR-1`, `FR-2`, …):
+
+| Type | Template |
+|------|----------|
+| Ubiquitous | The `<system>` shall `<response>`. |
+| Event-driven | When `<trigger>`, the `<system>` shall `<response>`. |
+| State-driven | While `<state>`, the `<system>` shall `<response>`. |
+| Optional | Where `<feature is included>`, the `<system>` shall `<response>`. |
+| Unwanted | If `<unwanted condition>`, then the `<system>` shall `<response>`. |
+| Complex | While `<state>`, when `<trigger>`, the `<system>` shall `<response>`. |
+
+```
+FR-1  The API shall return responses in JSON.
+FR-2  When a request omits a valid auth token, the API shall respond with HTTP 401.
+FR-3  If the payment provider times out, then the system shall mark the order pending and queue a retry.
+```
+
+Rules (full guidance in [references/ears-format.md](references/ears-format.md)):
+- **One `shall` per requirement** — compound "shall do A and B" splits into two `FR-n`.
+- **Named subject, testable response** — never "it shall handle gracefully". Move measurable limits into the response; pure performance targets stay in NFRs (Step 6).
+- **Don't smuggle HOW** — observable behavior only; leave implementation to `plan`.
+- Every `FR-n` traces up to a User Story and down to an Acceptance Criterion (checked in Step 3.6).
+
+**Skip EARS** for Bug Fix and Refactor types (no new behavior to specify). For plumbing/integration, a few event-driven + unwanted-behavior lines suffice — don't pad with ubiquitous filler. EARS is a format recommendation, not a gate.
+
 ### Step 5 — User Stories & Acceptance Criteria
 
 For each in-scope feature, generate:
@@ -456,6 +489,7 @@ Rules:
 - Primary user story first, then edge cases
 - Every user story has at least 2 acceptance criteria (happy path + error)
 - Acceptance criteria are TESTABLE — they become test cases in Phase 3
+- Each AC proves a specific `FR-n` from Step 4.5 — cite it (`AC-1.2 → FR-3`). Every unwanted-behavior `FR` (the `If …` lines) needs an error-path AC; that's where EARS earns its keep
 
 ### Step 6 — Non-Functional Requirements (NFRs)
 
@@ -540,6 +574,9 @@ Created: [date] | BA Session: [summary]
 ## User Stories
 [from Step 5]
 
+## Functional Requirements
+[from Step 4.5 — EARS-format FR-n list; skip for Bug Fix/Refactor]
+
 ## Scope
 ### In Scope
 ### Out of Scope
@@ -718,6 +755,10 @@ Known failure modes for this skill. Check these before declaring done.
 | All three tiers have same resources/effort | MEDIUM | Quick Win should be low-effort. If all tiers need "2 engineers, 3 months" → re-scope Quick Win to something achievable in 1 sprint |
 | Skipping Logic Consistency check because ambiguity is low | CRITICAL | Step 3.6 HARD-GATE: clarity ≠ consistency. A 90% clarity spec can still contain pairwise contradictions (scope IN/OUT overlap, rules with no enforcement, orphan ACs) |
 | Handing off to plan with unresolved 🔴 consistency fails | CRITICAL | Step 3.6 gate: 1+ 🔴 = BLOCK. 🟡 allowed only when logged as Risk in requirements.md |
+| Vague functional requirements ("system shall be fast/user-friendly") instead of EARS | MEDIUM | Step 4.5: every FR uses an EARS template with a named subject + testable response; vague targets move to NFRs (Step 6) |
+| Compound EARS requirement ("shall do A and B and C") hiding untested behavior | MEDIUM | Step 4.5: one `shall` per `FR-n` — split compounds so each behavior gets its own AC |
+| EARS `FR-n` with no acceptance criterion (untested promise) | MEDIUM | Step 3.6 check 1b: every FR traces down to an AC and up to a User Story |
+| Manufacturing EARS requirements for a bug fix or refactor | LOW | Step 4.5: skip EARS when there's no new behavior to specify — format recommendation, not ceremony |
 | Producing only requirements.md, skipping mermaid and tasks.md | HIGH | Step 7 is a triad — plan's contract expects all 3. Sequence diagram is always produced; state machine only if stateful; tasks.md always produced |
 | Mermaid diagram unrelated to actual user stories (decorative only) | MEDIUM | Sequence must trace AC-1.1 of US-1; state machine nodes must map to state-bearing ACs. Auditable by pattern-match |
 | tasks.md as flat list instead of layered | MEDIUM | Derivation rules enforce 1 US → Interface task, 1 rule → Logic + Unit test, 1 AC → Test task, 1 NFR → verification. Skipping layers loses plan's backbone structure |
@@ -741,7 +782,8 @@ Known failure modes for this skill. Check these before declaring done.
 - Ambiguity Score computed and displayed — must be ≤ 40% before proceeding (≤ 25% preferred)
 - Hidden requirements discovered and confirmed with user
 - Scope defined (in/out/assumptions/dependencies)
-- User stories with testable acceptance criteria produced
+- Functional requirements written in EARS format (FR-n) — skip for Bug Fix/Refactor
+- User stories with testable acceptance criteria produced, each AC citing the `FR-n` it proves
 - Non-functional requirements assessed (relevant ones only)
 - Logic Consistency Report produced — 0 🔴 before handoff (🟡 logged as Risks)
 - Tiered recommendations generated (Quick Win / Differentiation / Moat) — skip for Bug Fix/Refactor

package/skills/ba/references/ears-format.md

@@ -0,0 +1,91 @@
+# EARS — Easy Approach to Requirements Syntax
+
+EARS (Mavin et al., Rolls-Royce) constrains a functional requirement to one of a
+few sentence templates. The constraint is the value: every requirement becomes a
+single, atomic, testable "shall" statement with an explicit trigger or condition —
+which kills the two classic requirement defects, **ambiguity** and **compound scope**.
+
+EARS sits **between** user stories and acceptance criteria:
+
+```
+User Story  (WHY)   →  EARS Functional Requirement  (WHAT the system shall do)  →  Acceptance Criterion  (HOW we prove it)
+As a user, I want…  →  When X, the system shall Y.                              →  GIVEN … WHEN … THEN …
+```
+
+A user story is intent. An AC is a test. EARS is the contract in between — the
+precise behavior the test verifies. Skipping it lets vague stories ("make login
+smooth") flow straight into vague tests.
+
+## The 5 Templates (+ 1 combined)
+
+Give each requirement a stable ID (`FR-1`, `FR-2`, …). Pick the **simplest**
+template that fits — escalate only when the behavior genuinely needs it.
+
+| # | Type | Template | Use when |
+|---|------|----------|----------|
+| 1 | **Ubiquitous** | The `<system>` shall `<response>`. | Always-active behavior, no trigger or precondition. |
+| 2 | **Event-driven** | When `<trigger>`, the `<system>` shall `<response>`. | A discrete event/input causes the behavior. |
+| 3 | **State-driven** | While `<state>`, the `<system>` shall `<response>`. | Behavior holds for the duration of a state. |
+| 4 | **Optional** | Where `<feature is included>`, the `<system>` shall `<response>`. | Behavior exists only when an optional feature/config is present. |
+| 5 | **Unwanted** | If `<unwanted condition>`, then the `<system>` shall `<response>`. | Error handling, failure modes, abuse, invalid input. |
+| 6 | **Complex** | While `<state>`, when `<trigger>`, the `<system>` shall `<response>`. | A trigger handled differently depending on state. |
+
+### Examples (good)
+
+```
+FR-1  (ubiquitous)   The API shall return responses in JSON.
+FR-2  (event-driven) When a request omits a valid auth token, the API shall respond with HTTP 401.
+FR-3  (state-driven) While the account is in maintenance mode, the system shall reject all write operations.
+FR-4  (optional)     Where rate limiting is enabled, the API shall reject the 101st request per minute with HTTP 429.
+FR-5  (unwanted)     If the payment provider times out, then the system shall mark the order pending and queue a retry.
+FR-6  (complex)      While a checkout is in progress, when the cart total changes, the system shall recompute tax before payment.
+```
+
+## Rules for a well-formed EARS requirement
+
+1. **Named subject, never "it".** The `<system>` is a concrete component ("the
+   API", "the scheduler", "the login form") — not a pronoun.
+2. **One shall per requirement.** Two behaviors → two `FR-n`. Compound "shall do A
+   and B" hides one of them from testing.
+3. **Testable response.** "shall respond with HTTP 401" is testable; "shall handle
+   it gracefully" / "shall be fast" is not. Move measurable limits into the response
+   ("within 200 ms", "with HTTP 429"). Pure performance targets stay in NFRs (Step 6).
+4. **Trigger/condition is observable.** "When the user clicks Submit" — yes. "When
+   appropriate" — no.
+5. **Active voice.** "the system shall reject…" not "requests are rejected".
+6. **Don't smuggle HOW.** EARS captures observable behavior, not implementation
+   ("…shall store the token in Redis" → leave Redis to plan; say "…shall persist the
+   session token").
+
+## Anti-patterns
+
+| Smell | Why it fails | Fix |
+|-------|--------------|-----|
+| "The system shall be user-friendly." | Not testable, no trigger. | Reframe as a concrete event/response, or move to NFR/UX. |
+| "When X, the system shall do A and B and C." | Compound — partial passes hide. | Split into 3 EARS requirements. |
+| "It shall validate input." | "It" is ambiguous; "validate" is vague. | "If a field fails validation, then the form shall display the field-level error." |
+| Every requirement is Ubiquitous. | Triggers/states were dropped → context lost. | Most real requirements are event- or unwanted-behavior. Look for the trigger. |
+| EARS restates the user story verbatim. | No added precision. | The story is WHY; the EARS line is the specific observable behavior. |
+
+## Traceability (feeds Step 3.6 Logic Consistency)
+
+EARS is only worth the ceremony if it chains:
+
+- Every `FR-n` traces **up** to at least one User Story (it exists for a reason).
+- Every `FR-n` traces **down** to at least one Acceptance Criterion (it gets proven).
+- Every **unwanted-behavior** requirement (`If …`) should map to an error-path AC —
+  this is where EARS earns its keep, by forcing failure modes to be named, not assumed.
+
+An `FR-n` with no AC is an untested promise. An AC with no `FR-n` is a test for a
+behavior nobody specified. Both are consistency failures.
+
+## When to keep it light
+
+- **Bug fix / Refactor** → skip EARS entirely (no new behavior to specify).
+- **Plumbing / Integration** → a handful of event-driven + unwanted-behavior lines is
+  usually enough; don't manufacture ubiquitous requirements to pad the list.
+- **Small feature** → 3–7 requirements is typical. If you have 30, the feature is an
+  epic — hand the split to `plan`.
+
+EARS is a **format recommendation**, not a gate. The goal is precision per
+requirement, not requirement count.

package/skills/brainstorm/SKILL.md

@@ -103,7 +103,8 @@ Direct API call ≠ Wrapper/middleware layer ≠ Reverse engineering ≠ Browser
 
 ## Calls (outbound)
 
-- `plan` (L2): when idea is selected and needs structuring into actionable steps
+- `ba` (L2): when no requirements spec exists yet AND brainstorm is a standalone entry point — hand off for requirement elicitation BEFORE plan (never when `ba` is the caller — would loop)
+- `plan` (L2): when idea is selected and needs structuring into actionable steps (spec already exists, or task is a refactor/config change with no new behavior)
 - `design` (L2): when selected approach has UI/UX implications — hand off visual decisions
 - `research` (L3): gather data for informed brainstorming (existing solutions, benchmarks)
 - `trend-scout` (L3): market context and trends for product-oriented brainstorming
@@ -124,6 +125,7 @@ Direct API call ≠ Wrapper/middleware layer ≠ Reverse engineering ≠ Browser
 ## Cross-Hub Connections
 
 - `brainstorm` ↔ `plan` — bidirectional: brainstorm generates options → plan structures the chosen one, plan needs exploration → brainstorm ideates
+- `brainstorm` → `ba` — a standalone brainstorm that picks an approach for a NEW feature with no requirements spec routes to `ba` first (WHAT before HOW). Suppressed when `ba` is the caller — that direction is `ba` → `brainstorm` and re-invoking would loop.
 
 ## Reasoning Frameworks
 
@@ -374,12 +376,33 @@ For each rejected option, state:
 
 The "Revisit if" clause is critical — it turns a rejection into a future trigger, not a permanent dismissal.
 
-### Step 5 — Return to Plan
-Pass the recommended approach back to `rune:plan` for structuring into an executable implementation plan. Include:
+### Step 5 — Hand Off (Spec Gate → BA if missing, then Plan)
+
+Before structuring the chosen approach, check whether a requirements spec exists. Choosing an approach answers **HOW** — it does NOT answer **WHAT** (requirements, acceptance criteria, scope boundaries, hidden requirements). Handing a bare approach straight to `plan` produces a plan with no spec behind it — the "plan without spec" gap that turns into vibe-coding.
+
+**Spec-presence gate:**
+
+1. `Glob` `.rune/features/*/requirements.md`.
+2. **Route to `rune:plan` directly** if ANY of:
+   - A requirements doc already exists (BA ran earlier this session, or a continuation).
+   - Brainstorm was invoked BY `ba` or `cook` (mode/caller from Step 0) — the spec step is already in the chain; re-invoking `ba` would loop.
+   - The chosen approach implies NO new user-facing behavior (pure refactor, config change, infra swap, dependency choice).
+3. **Route to `rune:ba` FIRST** (then `ba` hands to `plan`) if ALL of:
+   - No requirements doc exists, AND
+   - Brainstorm is a standalone entry point (user ran `/rune brainstorm …` directly), AND
+   - The chosen approach implies new feature behavior (a new capability, workflow, or product surface).
+
+<HARD-GATE>
+Do NOT skip `ba` on the way to `plan` for a NEW feature just because an approach was already chosen.
+Approach ≠ requirements. A plan built on a chosen approach but no acceptance criteria is a plan without a spec.
+Loop guard: if `ba` was the caller, hand back to `plan` normally — NEVER re-invoke `ba`.
+</HARD-GATE>
+
+Pass to the next skill (`ba` or `plan`):
 - The chosen option name
-- Key constraints to honor in the plan
-- Any risks identified that the plan must mitigate
-- The Not Doing list (so plan knows what's explicitly out of scope)
+- Key constraints to honor
+- Any risks identified that must be mitigated
+- The Not Doing list (so the next skill knows what's explicitly out of scope)
 
 If the user rejects the recommendation, return to Step 2 with adjusted constraints and regenerate.
 
@@ -456,6 +479,7 @@ Known failure modes for this skill. Check these before declaring done.
 | [Rescue] Skipping Collision-Zone/Inversion frameworks | HIGH | Conventional thinking already failed — MUST use at least one breakthrough framework |
 | [Rescue] All approaches are "clean/proper" — no hacky option | MEDIUM | At least 1 must be unconventional — wrappers, reverse-engineering, debug mode abuse, proxy layers |
 | Calling plan directly instead of presenting options first | CRITICAL | Steps 2-3 are mandatory — present options, get approval, THEN call plan |
+| Handing a chosen approach straight to `plan` for a new feature with no requirements spec | CRITICAL | Step 5 spec-presence gate: standalone brainstorm + no `requirements.md` + new behavior → route to `ba` FIRST. Approach (HOW) is not a spec (WHAT). Skipping `ba` here is the "plan without spec" vibe-coding gap |
 | "Creative" options that ignore stated constraints | MEDIUM | Every option must satisfy the constraints declared in Step 1 |
 | Missing "Not Doing" list — rejected options not documented | MEDIUM | Step 4.75 is MANDATORY — every rejected option needs trade-off rationale + "Revisit if" condition |
 | [Design-It-Twice] Single agent producing N options instead of N parallel subagents | HIGH | Step 2.5 — constraint pinning happens at spawn, not in a loop. Each constraint = one Task call |
@@ -470,7 +494,8 @@ Known failure modes for this skill. Check these before declaring done.
 - User has explicitly approved an approach (not implied or assumed)
 - Selected option documented with rationale
 - Constraints for plan phase listed explicitly
-- `plan` (L2) called with the approved approach and constraints
+- Step 5 spec-presence gate evaluated — routed to `ba` (new feature, no spec, standalone) or `plan` (spec exists, or ba/cook was the caller, or no new behavior)
+- Next skill (`ba` or `plan`) called with the approved approach and constraints
 
 ## Cost Profile
 

package/skills/cook/SKILL.md

@@ -282,7 +282,12 @@ After scout completes, check if the detected tech stack or task description matc
 **Step 0.5 — Cross-Project Recall**: Call `neural-memory` (Recall Mode) with 3-5 topics relevant to the current task. Always prefix queries with the project name (e.g., `"ProjectName auth pattern"` not `"auth pattern"`).
 
 1. Use `Glob` to check for `.rune/plan-*.md` files
-2. If a master plan exists matching the current task: Read it → find first `⬚ Pending` or `🔄 Active` phase → load ONLY that phase file → announce "Resuming from Phase N" → skip to Phase 4
+2. If a master plan exists matching the current task:
+   - **Step 0.55 — Spec-Backfill Gate (HARD-GATE)**: Before resuming, `Glob` `.rune/features/*/requirements.md`. If NO requirements doc exists AND the task is a **Feature / Integration / Greenfield** (same classification as the Phase 1 BA-gate — NOT a bug fix, refactor, or trivial change), the plan was produced without a spec (e.g., a `brainstorm → plan` bypass that skipped `ba`). Do NOT resume blindly:
+     1. Invoke `rune:ba` to backfill requirements (5-question elicitation, or Synthesis Mode if the plan + conversation already carry enough context) → produces `.rune/features/<name>/requirements.md`.
+     2. Re-invoke `rune:plan` to reconcile the existing plan against the new spec — if the plan contradicts a locked Decision or misses a requirement, revise the affected phase files and get user re-approval (Re-Planning protocol).
+     3. THEN resume. For Bug Fix / Refactor / trivial tasks, skip this gate — no spec is expected.
+   - Read the (reconciled) master plan → find first `⬚ Pending` or `🔄 Active` phase → load ONLY that phase file → announce "Resuming from Phase N" → skip to Phase 4
 3. If no master plan exists → proceed to Phase 1 as normal
 
 **Step 0.6 — Contract Load**: Use `Glob` to check for `.rune/contract.md`. If it exists:
@@ -802,6 +807,7 @@ Mentally track tool call fingerprints. 3 identical calls → WARN. 5 identical c
 | Gate | Requires | If Missing |
 |------|----------|------------|
 | Resume Gate | Phase 0 checks for master plan before starting | Proceed to Phase 1 |
+| Spec-Backfill Gate | Feature/greenfield resume requires `requirements.md` to exist alongside the plan | Plan without spec → invoke `rune:ba` to backfill, reconcile plan, THEN resume |
 | Scout Gate | scout output before Phase 2 | Invoke rune:scout first |
 | Plan Gate | User-approved plan before Phase 3 | Cannot proceed |
 | Adversary Gate | adversary verdict before Phase 3 for features | Skip for bugfix/hotfix/refactor |
@@ -881,6 +887,7 @@ Common multi-agent failures to explicitly avoid. These are NOT edge cases — th
 | Anti-Pattern | Why It Fails | Correct Approach |
 |---|---|---|
 | **Bypass hierarchy** — skipping scout/plan and jumping to Phase 4 code | Builds wrong thing. Most "wasted work" traces back to missing Phase 1-2 | Follow phase gates. Even "obvious" tasks benefit from 30s of scout |
+| **Resume without spec** — a `brainstorm → plan` chain produced a plan file, so Phase 0 skips to Phase 4 and `ba` never runs | Plan exists but no requirements/acceptance criteria — a plan without a spec. Ships confident code for the wrong "what" | Spec-Backfill Gate (Step 0.55): feature/greenfield resume with no `requirements.md` → run `ba`, reconcile plan, THEN resume |
 | **Shadow decisions** — making architectural choices without logging to decisions.md | Next session repeats the same debate. Team agents contradict each other | Log every non-trivial choice via `decisions.md` or `journal` |
 | **Gold-plating** — adding "nice-to-have" features not in the approved plan | Scope creep, delayed delivery, untested code paths | Build ONLY what's in the plan. Log extras as follow-up tasks |
 | **Test-after** — writing tests after implementation instead of before (TDD violation) | Tests validate implementation bugs, not requirements. Coverage looks good but misses edge cases | Phase 3 (RED) before Phase 4 (GREEN). Always |

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. When the diagnosed cause is a memory leak in a long-running process, escalates to perf for cost-impact framing (leaks drive OOM-restart → cold-start → autoscaler spend, often 20-40% bill inflation)."
 metadata:
   author: runedev
-  version: "1.3.0"
+  version: "1.4.0"
   layer: L2
   model: sonnet
   group: development
@@ -174,6 +174,8 @@ ALL diagnostic code added during debug MUST be wrapped in `#region agent-debug`
 Unmarked instrumentation will be treated as stray code and removed prematurely.
 </HARD-GATE>
 
+**Observability gap as a finding.** If you had to add temporary `console.log` markers because the code emitted *nothing useful* about this path, that absence is itself a root-cause-adjacent signal: the bug was hard to diagnose because the system is blind here. When the fix lands, recommend converting the throwaway markers into **durable structured telemetry** (a stable event name + correlation ID, not prose) so the next occurrence is a query, not another archaeology session. This is advisory — note it in the report, don't block on it. Contract: `../deploy/references/observability.md`.
+
 ### Step 2c: Check Debug Knowledge Base
 
 Before forming hypotheses, check `.rune/debug/knowledge-base.md`:
@@ -427,7 +429,7 @@ Append to Debug Report when invoked standalone. Suppress when called as sub-skil
 ```yaml
 chain_metadata:
   skill: "rune:debug"
-  version: "1.2.0"
+  version: "1.4.0"
   status: "[DONE | DONE_WITH_CONCERNS | NEEDS_CONTEXT | BLOCKED]"
   domain: "[area debugged]"
   files_changed: []  # debug never changes files

package/skills/deploy/SKILL.md

@@ -4,7 +4,7 @@ description: "Deploy application to target platform. Use when user explicitly sa
 disable-model-invocation: true
 metadata:
   author: runedev
-  version: "0.6.0"
+  version: "0.7.0"
   layer: L2
   model: sonnet
   group: delivery
@@ -290,6 +290,24 @@ Production observability (Datadog, Sentry, New Relic, Honeycomb, Logtail) bills
 
 This overlaps with `perf` Step 8.6 (Observability Cost Control). `perf` finds the code patterns that emit overheavy telemetry; `deploy` ensures the platform-side ingestion + retention defaults are configured before the first prod release where the bill compounds.
 
+## Instrumentation Readiness (pre-prod advisory gate)
+
+> Two observability concerns, kept separate: the section *above* ("Observability Cost in Deploys") gates the telemetry **bill** (retention/sampling/cardinality config). This section gates whether the telemetry **exists and works** at all. Both run; neither replaces the other.
+
+Cost config (above) answers "is the telemetry *affordable*". This answers "does the telemetry *exist and work*". A feature with retries, queues, external calls, or new endpoints that ships **zero new telemetry** is shipping blind — the first incident becomes archaeology.
+
+<MUST-READ path="references/observability.md" trigger="first prod deploy of a feature that adds I/O, endpoints, jobs, or external integrations"/>
+
+Before the first production deploy of such a feature, verify the **Instrumentation Readiness Checklist** in `references/observability.md`. This is **advisory** (WARN, not BLOCK) — do not stop a deploy over missing telemetry, but surface the gap:
+
+```
+INSTRUMENTATION_GAP — feature adds [endpoint/job/integration] with no new
+structured logs / RED metrics / correlation ID. First incident will be blind.
+→ See deploy/references/observability.md before shipping.
+```
+
+Skip for: static sites, config-only changes, hotfixes (flag for follow-up), non-prod deploys.
+
 ## Output Format
 
 Deploy Report with platform, status (success/failed/rollback), deployed URL, build time, and checks (tests, security, HTTP, visual, monitoring). See Step 6 Report above for full template.
@@ -328,6 +346,7 @@ Known failure modes for this skill. Check these before declaring done.
 | Resources deployed without cost-allocation tags | HIGH | Step 1 pre-deploy MUST verify Environment/Team/Service tags. Untagged = unfalsifiable cost claims downstream |
 | Self-host migration recommended on bill threshold alone | HIGH | Crossover rule requires ALL 3 conditions: bill + ops bandwidth + customization need. Single-criterion recommendations produce engineering-debt swap |
 | Defaults shipped on observability stack | MEDIUM | Verify retention + sampling + cardinality config BEFORE first prod deploy; defaults often bleed > compute bill |
+| Feature ships with zero telemetry (logs/metrics/traces) | MEDIUM | Instrumentation Readiness advisory gate — WARN `INSTRUMENTATION_GAP` (skip for static sites/config-only/hotfix per section); first incident is blind without it. See `references/observability.md` |
 | Premature self-host (< 10K MAU) | MEDIUM | Flag `PREMATURE_SELFHOST` — managed equivalent at this scale is cheaper than engineering time spent operating |
 
 ## Done When

package/skills/deploy/references/observability.md

@@ -0,0 +1,146 @@
+# Observability & Instrumentation Reference
+
+Code you cannot observe is code you cannot operate. Instrumentation is written **alongside** the feature, like tests — not bolted on after the first incident. A feature that ships without telemetry turns its first user-reported bug into archaeology instead of a query.
+
+This reference is the shared instrumentation discipline. `deploy` gates on it before prod, `perf` uses it as the measurement basis, `debug` leaves it behind so the next investigation is fast.
+
+---
+
+## 1. Define "working" before instrumenting
+
+Telemetry without a question is noise. Before adding anything, write 2-4 questions an on-call engineer will ask about this feature:
+
+```
+FEATURE: checkout payment retry
+ON-CALL WILL ASK:
+1. What fraction of payments succeed first-try vs after retry?
+2. When a payment fails permanently, why? (provider error / timeout / validation?)
+3. Is the payment provider slower than usual?
+→ Every signal below must answer one of these.
+```
+
+If you cannot name the questions, you are not ready to instrument — you will log everything and learn nothing.
+
+## 2. One signal per question
+
+| Signal | Answers | Cost profile |
+|---|---|---|
+| **Structured log** | "What happened in this specific case?" | Per-event; grows with traffic |
+| **Metric** | "How often / how fast, in aggregate?" | Fixed per series; cheap to query |
+| **Trace** | "Where did time go across services?" | Per-request; usually sampled |
+
+Rule of thumb: **metrics say *that* something is wrong, traces say *where*, logs say *why*.**
+
+## 3. Structured logging
+
+Log events, not prose. Every line is a JSON object with a stable event name and machine-readable fields:
+
+```ts
+// BAD: string interpolation — unqueryable, inconsistent
+logger.info(`Payment ${id} failed for ${userId} after ${n} retries`);
+
+// GOOD: stable event name + structured fields
+logger.warn({ event: 'payment_failed', paymentId: id, provider: 'stripe', errorCode: err.code, attempt: n }, 'payment failed');
+```
+
+**Log levels — consistent meaning:**
+
+| Level | Meaning | On-call action |
+|---|---|---|
+| `error` | Invariant broken; someone may need to act | Investigate |
+| `warn` | Degraded but handled (retry succeeded, fallback used) | Watch trends |
+| `info` | Significant business event (order placed, job finished) | None |
+| `debug` | Diagnostic detail | Off in prod by default |
+
+**Correlation IDs are mandatory.** Generate or accept a request ID at the system boundary; attach it to every log line, span, and outbound call. Without it you cannot reconstruct one request from interleaved logs:
+
+```ts
+app.use((req, res, next) => {
+  req.id = req.headers['x-request-id'] ?? crypto.randomUUID();
+  req.log = logger.child({ requestId: req.id });
+  res.setHeader('x-request-id', req.id);
+  next();
+});
+```
+
+**Never log secrets, tokens, passwords, or full PII.** Telemetry pipelines are a classic data-leak path (hard rule, shared with `sentinel`). Allowlist fields; never log whole request bodies.
+
+## 4. Metrics — RED and USE
+
+- **Request-driven services** (endpoints, external deps): instrument **RED** — **R**ate (req/s), **E**rrors (failure rate), **D**uration (latency *histogram*).
+- **Resources** (queues, pools, hosts): instrument **USE** — **U**tilization, **S**aturation, **E**rrors.
+
+```ts
+const httpDuration = new Histogram({
+  name: 'http_request_duration_seconds',
+  labelNames: ['method', 'route', 'status_class'],   // '2xx', not '200'
+  buckets: [0.05, 0.1, 0.25, 0.5, 1, 2.5, 5],
+});
+```
+
+**Cardinality is the failure mode.** Every unique label combination is a separate time series. Labels must come from small fixed sets (route template, status class, provider). Never use user IDs, raw URLs, request IDs, or error-message text as labels — that belongs in logs/traces.
+
+```
+OK as label:    route="/api/tasks/:id"  status_class="5xx"  provider="stripe"
+NEVER a label:  user_id, email, request_id, full URL, error message text
+```
+
+**Averages never, percentiles always.** An average hides the 1% of users having a terrible time. Use histograms; read p50/p95/p99.
+
+## 5. Distributed tracing
+
+Use OpenTelemetry (vendor-neutral). Auto-instrumentation covers HTTP/gRPC/common DB clients with near-zero code:
+
+```ts
+// tracing.ts — imported before anything else
+const sdk = new NodeSDK({ serviceName: 'checkout-service', instrumentations: [getNodeAutoInstrumentations()] });
+sdk.start();
+```
+
+Add manual spans only around meaningful internal work (`applyDiscounts`, `chargeProvider`) with the attributes on-call filters by. Propagate context across every async boundary (HTTP headers, queue metadata) or the trace dies at the gap. Sample head-based at a low rate; keep 100% of errors if the backend supports tail sampling.
+
+## 6. Alerting — symptoms, not causes
+
+Alert on **what users feel**, not on internal causes:
+
+```
+SYMPTOM (page-worthy):        CAUSE (dashboard, not a page):
+error rate > 1% for 5 min     CPU at 85%
+p99 latency > 2s              one pod restarted
+queue age > 10 min            disk at 70%
+```
+
+Cause-based alerts fire when nothing is wrong and miss failures you did not predict. Every alert must:
+
+1. **Be actionable.** If the response is "ignore it, it self-heals" → delete it.
+2. **Link to a runbook** — even three lines: what it means, first query to run, escalation path.
+3. **Have a threshold + duration** justified by an SLO or historical data, not a guess.
+4. **Use two severities only** — *page* (user-facing, act now) and *ticket* (degradation, act this week). A third tier trains people to ignore everything.
+
+## 7. Verify the telemetry itself
+
+Instrumentation is code; it can be wrong. Before calling it done, trigger the paths and look at the real output:
+
+- Force an error in staging → find it by `requestId`, confirm fields are structured (not `[object Object]`).
+- Send test traffic → metric series appear with expected labels and sane values.
+- Follow one request end-to-end in the tracing UI → no broken spans.
+- Fire each new alert once (lower the threshold temporarily) → it reaches the right channel and the runbook link works.
+
+---
+
+## Instrumentation Readiness Checklist (gate)
+
+A feature is observable-ready when:
+
+- [ ] On-call questions written down; each signal maps to one
+- [ ] All logs structured (JSON), stable event names, correlation ID on every line
+- [ ] No secrets/tokens/PII in any log line (spot-check actual output)
+- [ ] RED metrics on every new endpoint + external dependency, bounded labels
+- [ ] Latency is a histogram; p95/p99 queryable
+- [ ] One request followable end-to-end without broken spans
+- [ ] Every new alert is symptom-based, has a runbook link, was test-fired once
+- [ ] An induced staging failure was located via telemetry alone, without reading source
+
+## Cost note
+
+Instrumentation has a bill. Retention, sampling, and cardinality defaults bleed money (see `deploy` → "Observability Cost in Deploys" and `perf` Step 8.6). Instrument for the on-call questions — not for completeness. Three queryable events beat three hundred prose lines.

package/skills/graft/SKILL.md

@@ -3,7 +3,7 @@ name: graft
 description: "Clone, port, or convert features from any GitHub repo into your project. Use when stealing patterns from external repos or porting proven code. Understand before copy, challenge before implement. 4 modes: port (rewrite), compare (analysis), copy (transplant), improve (copy + optimize)."
 metadata:
   author: runedev
-  version: "0.2.0"
+  version: "0.3.0"
   layer: L2
   model: sonnet
   group: creation
@@ -25,9 +25,10 @@ When you clone a repo you see hundreds of files. **That tree is a menu — optio
 - Read the README + the **2-5 files that implement the target feature**. Skip the rest.
 - If you cannot name the specific files you need before reading, you do not know what you want yet — go back to Step 0 and narrow scope.
 - `WebFetch` on raw GitHub URLs beats `git clone` whenever you know the exact files. Use clone only when discovery is genuinely needed.
-- A graft that reads >10 source files is almost always a scoping failure, not a thorough one.
 
-This rule applies to ALL modes. Copy mode is not an excuse to import a directory wholesale — you still select files deliberately.
+**Reading to understand is not grafting.** The discipline above caps the **graft scope** — the files you actually transplant, port, or improve into your codebase (2-5, hard-cap 10). It does NOT cap how many files you may *read to learn a pattern*. Studying a 24-skill library to extract one convention legitimately reads dozens of files but grafts almost none. Keep the two counts separate: a wide read with a narrow graft is thorough; a wide graft is the failure mode.
+
+This menu discipline applies to the **transplant modes** (port, copy, improve). Copy mode is not an excuse to import a directory wholesale — you still select files deliberately. **Compare mode and survey scope (`--deep`)** are exempt from the read cap by design: their job is breadth of understanding, not transplant. They still must NOT import code wholesale — wide reading, narrow (or zero) graft.
 
 <HARD-GATE>
 Challenge gate (Step 4) MUST complete before adaptation planning (Step 5).
@@ -67,6 +68,17 @@ Copy the feature, then refactor and optimize. Fix anti-patterns, add missing tes
 
 **`--fast` warning**: Skipping challenge gate means no license check, no quality assessment. User accepts full responsibility. Announce: "Fast mode: skipping challenge gate. You are responsible for license and quality review."
 
+## Scope Depth
+
+Orthogonal to mode and speed. Controls how widely you may read.
+
+| Scope | Read budget | Graft scope | When |
+|-------|-------------|-------------|------|
+| (default) | 2-5 files, hard-cap 10 | the feature's files | Transplant one feature/module |
+| `--deep` (survey) | unbounded reads, full clone OK | narrow — patterns extracted, not files copied | Study a whole repo/library to learn architecture or compare many components |
+
+**`--deep` is for understanding, not importing.** Use it when the goal is "what can I learn from this repo" rather than "port this function." Pairs naturally with `compare` mode. It relaxes the read cap and the scope-guard warning — but the transplant discipline still holds: extract the *pattern*, then graft narrowly (often into multiple existing skills/files rather than copying source files 1:1).
+
 ## Smart Intent Detection
 
 | Input Pattern | Detected Mode |
@@ -76,6 +88,7 @@ Copy the feature, then refactor and optimize. Fix anti-patterns, add missing tes
 | Contains "improve", "better", "adapt", "upgrade" | improve |
 | Contains "port", "convert", "rewrite", "migrate" | port |
 | URL points to specific file/dir (not repo root) | Auto-scope to that path |
+| Contains "survey", "study", "learn from", "what can I take", "deep dive" | compare + `--deep` |
 | (default — no keyword match) | port |
 
 ## Triggers
@@ -140,9 +153,9 @@ For specific files or small repos: use `WebFetch` on raw GitHub URLs instead of
 3. package.json / pyproject.toml / Cargo.toml — dependencies and stack
 4. Tests for target feature — understand expected behavior
 
-**Scope guard**: If target feature spans >15 files or >2000 LOC → WARN user: "Feature is large. Suggest narrowing to [specific module]. Continue anyway?"
+**Scope guard**: If target feature spans >15 files or >2000 LOC → WARN user: "Feature is large. Suggest narrowing to [specific module]. Continue anyway?" (Suppressed under `--deep`/compare — breadth is the point there.)
 
-**Menu discipline**: Before reading file #6, pause and ask "do I actually need this, or am I eating the menu?" If the answer isn't a concrete reason tied to the target feature, stop reading and move to Step 2.
+**Menu discipline** (transplant modes): Before reading file #6, pause and ask "do I actually need this *to graft it*, or am I eating the menu?" If the answer isn't a concrete reason tied to the target feature, stop reading and move to Step 2. Under `--deep`/survey scope this gate is lifted — read as widely as understanding requires, but keep the graft scope narrow (Step 5).
 
 ### Step 2 — Analyze Source
 
@@ -204,6 +217,8 @@ Wait for user approval (unless `--auto`).
 
 ### Step 5 — Plan Adaptation
 
+**Graft scope stays narrow regardless of how widely you read.** If this run used `--deep`/survey to study a library, the read cap was lifted — but the adaptation plan below still selects a small set of files/patterns to actually transplant. A wide survey legitimately feeds a `copy`/`improve` plan that grafts only the 2-5 best files; it does not license importing the surveyed tree.
+
 Based on mode, produce adaptation plan:
 
 **Compare mode** → skip to output. Write comparison report and STOP.
@@ -302,7 +317,7 @@ graft.complete:
 5. MUST respect local conventions — grafted code should look native, not foreign
 6. MUST NOT modify the source repository — read-only access only
 7. MUST NOT graft without scoping — always narrow to specific feature/module
-8. MUST treat the source file tree as a menu, not a meal — read the 2-5 files the feature actually needs, not every file you can see
+8. MUST treat the source file tree as a menu, not a meal for **transplant** — graft the 2-5 files the feature actually needs, not every file you can see. Reading widely to understand (esp. under `--deep`/compare) is allowed; grafting widely is not
 
 ## Mesh Gates
 
@@ -319,7 +334,8 @@ graft.complete:
 | Grafting GPL code into MIT project | CRITICAL | Challenge gate checks license — blocks incompatible |
 | Blindly copying code without understanding | CRITICAL | HARD-GATE: challenge before implement |
 | Context overflow from large source files | HIGH | Scope guard: >15 files or >2000 LOC triggers warning |
-| Reading the whole repo instead of the feature | HIGH | "Tree is a menu" rule — pause before file #6, justify each read |
+| Reading the whole repo instead of the feature | HIGH | "Tree is a menu" rule — pause before file #6, justify each read (transplant modes only) |
+| Forcing a pattern-study graft into the 10-file feature cap | MEDIUM | Use `--deep`/survey scope — wide read, narrow graft; cap counts grafted files, not reads |
 | Grafted code doesn't match local conventions | HIGH | Step 3 scans local patterns, Step 5 plans adaptation |
 | Stale source (abandoned repo) | MEDIUM | Maintenance dimension in challenge gate |
 | Private repo URL fails | MEDIUM | Fallback to WebFetch raw URLs or manual paste |
@@ -335,7 +351,7 @@ SELF-VALIDATION (run before emitting graft.complete):
 - [ ] License compatibility confirmed (or user override documented)
 - [ ] Temp clone directory cleaned up
 - [ ] Grafted code compiles/lints without new errors
-- [ ] Source files read count ≤10 (menu discipline) — if >10, document why in the output
+- [ ] **Graft scope** ≤10 files (files actually transplanted/ported/improved) — if >10, document why. This is NOT the read count: under `--deep`/compare you may read far more to understand, but the files you graft stay narrow.
 IF ANY check fails → fix before reporting done. Do NOT defer to completion-gate.
 ```