@rune-kit/rune 2.18.1 → 2.21.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.2.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,12 +444,44 @@ 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:
 
 ```
-US-1: As a [persona], I want to [action] so that [benefit]
+US-1 [P1]: As a [persona], I want to [action] so that [benefit]
+  Independent Test: [specific action proving this story works end-to-end on its own —
+                     e.g., "submit the form with valid data and see the saved record listed"]
   AC-1.1: GIVEN [context] WHEN [action] THEN [result]
   AC-1.2: GIVEN [error case] WHEN [action] THEN [error handling]
   AC-1.3: GIVEN [edge case] WHEN [action] THEN [graceful behavior]
@@ -454,8 +489,28 @@ US-1: As a [persona], I want to [action] so that [benefit]
 
 Rules:
 - Primary user story first, then edge cases
+- **Every story carries a priority**: `P1` = MVP-critical (the P1 set alone must be a viable, demoable product), `P2` = important, `P3` = nice-to-have. Implementing ONLY the P1 stories must still yield a working feature
+- **Every story carries an Independent Test** — one concrete user action that proves the story end-to-end (through UI, logic, AND data if the story touches them). If no single action can prove it, the story is sliced wrong — split or merge until it can. This field is what downstream verification gates (plan's Coverage Gate, `converge`'s gap scan, completion-gate's evidence trail) trace against
 - 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
+- An AC whose THEN clause stops at the UI ("THEN the button shows a spinner") for a story that persists or fetches data is INCOMPLETE — the THEN must name the observable outcome ("THEN the order appears in the list / the record is persisted")
+
+### Step 5.5 — Key Entities (mandatory if feature involves data)
+
+If ANY user story creates, reads, updates, or deletes data, list the key entities — WHAT the data is, not HOW it's stored (no table names, no column types, no ORM detail):
+
+```
+## Key Entities
+- **Order**: what a customer submits — items, quantities, status (draft → submitted → fulfilled). One User has many Orders.
+- **User**: the person placing orders — identity, contact. Referenced by Order.
+```
+
+Rules:
+- One line per entity: name, what it represents, key attributes (plain language), relationships
+- State-bearing entities name their lifecycle states — these become the state machine in requirements.mermaid
+- This section SEEDS `plan`'s data-model.md — a story that touches data but has no entity here is a spec gap (plan will bounce it back)
+- Skip entirely for stateless features (pure computation, styling, config)
 
 ### Step 6 — Non-Functional Requirements (NFRs)
 
@@ -538,7 +593,13 @@ Created: [date] | BA Session: [summary]
 - Affected systems: [what]
 
 ## User Stories
-[from Step 5]
+[from Step 5 — each with [P1|P2|P3] priority and Independent Test]
+
+## Functional Requirements
+[from Step 4.5 — EARS-format FR-n list; skip for Bug Fix/Refactor]
+
+## Key Entities
+[from Step 5.5 — mandatory if feature involves data; omit section for stateless features]
 
 ## Scope
 ### In Scope
@@ -597,40 +658,42 @@ Skip state machine if feature is stateless (simple CRUD with no lifecycle). Sequ
 
 #### Artifact 3: tasks.md
 
-Pre-broken implementation tasks by layer. Plan refines this backbone, does not create from scratch. Save to `.rune/features/<feature-name>/tasks.md`:
+Pre-broken implementation tasks **grouped by user story** (vertical slices), NOT by layer. Plan refines this backbone, does not create from scratch. Save to `.rune/features/<feature-name>/tasks.md`:
 
 ```markdown
 # Implementation Tasks: [Feature Name]
 
-## Data Layer
-- [ ] Schema — [tables/models from AC]
-- [ ] Migration up + down
-- [ ] Seed/fixtures if tests need them
+## Foundational (blocking prerequisites)
+> Shared infrastructure NO story can start without. Keep minimal.
+- [ ] Schema/migrations for Key Entities shared by 2+ stories
+- [ ] Auth/routing/middleware skeleton (only if 2+ stories need it)
 
-## Logic Layer
-- [ ] [each Q5 Business Rule → one task]
-- [ ] Validation for [each AC error case]
-- [ ] State transitions from requirements.mermaid (if present)
+## US-1 [P1]: [story title]
+> Layer order WITHIN the story: Data → Logic → Endpoint → UI → Test. UI never first.
+- [ ] Data: [entity/migration this story owns, if not Foundational]
+- [ ] Logic: [each Business Rule this story enforces → one task]
+- [ ] Endpoint: [handler/service/API this story calls — skip only if story is pure-UI]
+- [ ] UI: [component/surface — calls the Endpoint task above; a UI element and the
+      endpoint it calls are ONE story's tasks, never split across stories]
+- [ ] Test: [each AC of this story → one test; happy path + error]
+- **Checkpoint**: US-1 independently functional — run its Independent Test
 
-## Interface Layer (API / UI)
-- [ ] [each User Story → one endpoint or UI component]
-- [ ] Contract schema from AC (request/response)
-- [ ] Error handling for [each AC error]
-
-## Test Layer
-- [ ] Unit: [each business rule → one test]
-- [ ] Integration: [each AC happy path]
-- [ ] Regression: [each AC error case]
+## US-2 [P2]: [story title]
+- [ ] ... (same internal structure)
 
 ## NFR Verification
 - [ ] [each NFR from Step 6 → one measurement task]
 ```
 
 Derivation rules:
-- 1 User Story → ≥1 Interface task
-- 1 Business Rule → 1 Logic task + 1 Unit test task
-- 1 AC → ≥1 Test task (happy path + error)
+- 1 User Story → 1 `## US-n` section containing ALL its layers (data through test) — a story section with only UI/Endpoint tasks and no Logic/Data/Test is a broken slice; a UI task with no Endpoint task above it (and no pure-UI justification) is a dead button in waiting
+- 1 Business Rule → 1 Logic task + 1 test task, inside the story that enforces it
+- 1 AC → ≥1 Test task inside its story (happy path + error)
 - 1 NFR → 1 NFR Verification task
+- Foundational holds ONLY what 2+ stories share — story-specific work stays in the story
+- P1 sections first; completing all P1 sections + Foundational = viable MVP
+
+**Why story-grouped**: layer-grouped backbones ("all Data → all Logic → all Interface") invite the executor to finish the Interface layer and stop — shipping UI with no wiring. Story-grouped means every completed section is a demoable end-to-end slice.
 
 #### Handoff
 
@@ -683,6 +746,10 @@ Inside `requirements.md` the **Decision Classification** table MUST appear verba
 8. MUST NOT write code or plan implementation — BA produces WHAT, plan produces HOW
 9. MUST ask ONE question at a time by default; bundle yes/no batches only after user shows concise replies
 10. MUST NOT skip BA for non-trivial tasks — "just build it" gets redirected to Question 1
+11. MUST assign [P1|P2|P3] priority to every user story — the P1 set alone must be a viable, demoable product
+12. MUST give every user story an Independent Test — one concrete action proving it end-to-end
+13. MUST list Key Entities when any story touches data (Step 5.5) — a data-touching story with no entity is a spec gap
+14. MUST group tasks.md by user story (vertical slices), never by layer
 
 ## Returns
 
@@ -690,7 +757,7 @@ Inside `requirements.md` the **Decision Classification** table MUST appear verba
 |----------|--------|----------|
 | Requirements document | Markdown | `.rune/features/<feature-name>/requirements.md` |
 | Visual model | Mermaid (sequence + optional state machine) | `.rune/features/<feature-name>/requirements.mermaid` |
-| Implementation task backbone | Markdown checklist by layer | `.rune/features/<feature-name>/tasks.md` |
+| Implementation task backbone | Markdown checklist by user story (vertical slices — Data→Logic→Endpoint→UI→Test per US-n) | `.rune/features/<feature-name>/tasks.md` |
 | Logic Consistency Report | Markdown section | Embedded in requirements.md |
 | Ambiguity + Completeness scores | Markdown display blocks | Embedded in requirements.md |
 
@@ -718,9 +785,17 @@ 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 |
+| tasks.md grouped by layer instead of by story | HIGH | Story-grouped derivation: 1 US → 1 section with ALL its layers (Data→Logic→Interface→Test). Layer-grouped backbones invite "finish the UI layer and stop" — the dead-button root cause |
+| Story with UI tasks but no Logic/Data/Test tasks (broken slice) | HIGH | Step 7 Artifact 3 rule: a `## US-n` section containing only UI/Endpoint tasks is invalid — the UI element and the endpoint it calls belong to the SAME story |
+| Story without an Independent Test (unprovable slice) | HIGH | Step 5 rule: every story names one concrete action proving it end-to-end. Can't name one → story is sliced wrong |
+| AC whose THEN stops at the UI for a data-touching story | HIGH | Step 5 rule: THEN must name the observable outcome (record persisted / data returned), not just the widget state |
+| Data-touching story with no Key Entity listed | MEDIUM | Step 5.5: plan bounces specs where a story touches data absent from Key Entities |
 | Re-litigating a previously rejected concept without surfacing it | HIGH | Step 1.5 HARD-GATE: scan `.out-of-scope/` first; exact match (≥0.8) MUST be surfaced before elicitation begins |
 | Skipping Step 1.5 because `.out-of-scope/` directory looks empty | MEDIUM | Empty directory is silent-skip OK; directory absent entirely is silent-skip OK; never skip due to "I don't think this matches anything" — let the matcher decide |
 | User asserts behavior; agent records user's version without grep verification | HIGH | Step 2.6 HARD-GATE: every "the system does X" assertion gets grep'd; conflicts surface to user before recording |
@@ -741,7 +816,11 @@ 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
+- Every story has a [P1|P2|P3] priority and an Independent Test; P1 set alone = viable MVP
+- Key Entities listed (if feature involves data) — seeds plan's data-model.md
+- tasks.md grouped by user story (vertical slices), Foundational section minimal
 - 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/completion-gate/SKILL.md

@@ -4,7 +4,7 @@ description: "Validates agent claims against evidence trail. Use when verifying
 user-invocable: false
 metadata:
   author: runedev
-  version: "1.8.0"
+  version: "1.9.0"
   layer: L3
   model: haiku
   group: validation
@@ -189,9 +189,9 @@ If an axis has ZERO claims → flag as gap: "No [Completeness/Correctness/Cohere
 UNCONFIRMED — 1 claim lacks evidence, 1 contradicted. Cannot proceed to commit.
 ```
 
-### Step 4.5 — Cross-Phase Integration Check
+### Step 4.5 — Integration Check (Cross-Phase + Cross-Layer)
 
-When validating a completed phase in a multi-phase plan, check for integration gaps between phases:
+Check for integration gaps — between phases AND between layers:
 
 1. **Orphaned exports** — files/functions created in this phase that claim to be used by future phases (see `## Cross-Phase Context → Exports`) but are not yet importable:
    ```
@@ -201,19 +201,28 @@ When validating a completed phase in a multi-phase plan, check for integration g
    - Expected export missing entirely → UNCONFIRMED ("Phase N claims to export X but X not found")
    ```
 
-2. **Uncalled routes** — API endpoints added in this phase but not wired to any frontend/consumer yet:
-   - This is OK if a future phase handles wiring (check master plan)
-   - Flag as WARN if no future phase mentions consuming this route
+2. **Uncalled routes** — API endpoints added in this task but not wired to any frontend/consumer:
+   - **BLOCK** if the route was created in THIS task AND a user story/AC references the interaction it serves — an uncalled route behind a story's UI is a dead path, not future work
+   - WARN (deferral allowed) ONLY if a NAMED future-phase task explicitly references consuming this route (verifiable in the master plan/phase files — "a future phase will handle it" without a task ID is not an excuse)
 
 3. **Auth gaps** — new endpoints or pages without authentication/authorization:
    - `Grep` for route handlers without auth middleware
    - Flag as WARN (may be intentional for public endpoints, but worth checking)
 
-4. **E2E flow trace** — for the primary user flow this phase enables:
-   - Trace: entry point → business logic → data layer → response
+4. **E2E flow trace** — for the primary user flow this task enables:
+   - Trace: entry point → handler → business logic → data layer → response
    - If any step in the chain is missing or stubbed → CONTRADICTED
 
-**This step is OPTIONAL for single-phase tasks and MANDATORY for multi-phase master plans.**
+**When this step is MANDATORY** (any one triggers it — single-phase tasks included):
+- The diff touches BOTH a UI file (`.tsx/.jsx/.vue/.svelte/.html`) AND an api/service/data file — where "api/service/data file" = any file whose path contains a segment from: `api`, `routes`, `handlers`, `services`, `service`, `stores`, `store`, `db`, `database`, `models`, `repositories`, `repo`, `queries` — OR any file exporting functions matching `create*`/`update*`/`delete*`/`fetch*`/`save*`/`post*` verb patterns
+- The feature spec has a `## Key Entities` section
+- The task description contains any of these exact words: `click`, `submit`, `save`, `login`, `signup`, `search`, `checkout`, `upload`, `delete`, `order`, `pay` — EXCEPT when the phrase is explicitly local-only ("save to clipboard", "save locally", "client-side only")
+- Multi-phase master plan (always, as before)
+
+Skip ONLY when none of the above hold (pure-UI styling, pure-backend plumbing, docs/config).
+"Single-phase" is NOT a skip reason — most dead-button escapes are single-phase tasks.
+
+**De-dup**: if preflight (Step 4/4.5) or verification (Level 3.5) already flagged the same element/route in this session, cite the cross-reference instead of emitting a duplicate finding — one dead button = one finding + cross-refs, not three findings.
 
 ### Step 5 — Evidence Quality Gate
 
@@ -286,7 +295,9 @@ Completion Gate Report with status (CONFIRMED/UNCONFIRMED/CONTRADICTED), claim v
 | Completion-gate itself claims "all confirmed" without evidence | CRITICAL | Gate report MUST include the evidence table — no table = report is invalid |
 | Existence Theater — agent creates files but they're stubs | HIGH | Step 1b stub detection: grep for Placeholder/TODO/NotImplementedError in new files |
 | Cross-phase integration gaps — exports exist but wrong signature | HIGH | Step 4.5: verify exports match Code Contracts from phase file |
-| Phase complete but E2E flow broken — missing link in the chain | MEDIUM | Step 4.5 E2E flow trace: entry → logic → data → response must all be connected |
+| Phase complete but E2E flow broken — missing link in the chain | HIGH | Step 4.5 E2E flow trace: entry → handler → logic → data → response must all be connected |
+| Skipping Step 4.5 because the task is single-phase | CRITICAL | Mandatory triggers: UI+data diff, Key Entities in spec, or interaction-implying task — single-phase is where most dead buttons escape |
+| Excusing an uncalled route with "a future phase will wire it" (no task named) | HIGH | Step 4.5 #2: deferral requires a NAMED future-phase task referencing the route — vibes-deferral = BLOCK |
 | Rubber-stamping — all CONFIRMED without scrutiny | HIGH | Default-FAIL mindset: actively seek 3-5 issues. Zero issues = red flag, apply skeptic sweep on weakest 2 claims |
 | Partial completion claimed as full — 80% done but "implemented" | HIGH | Adversarial checklist: check for partial completion, scope mismatch, evidence-claim alignment |
 | Self-Validation skipped — skill has checks but gate ignores them | HIGH | Step 1c: extract Self-Validation from skill's SKILL.md, treat each as implicit claim. Missing = UNCONFIRMED |