@rune-kit/rune 2.20.0 → 2.21.0

package/README.md

@@ -5,7 +5,7 @@
 <p align="center">
   <strong>Less skills. Deeper connections.</strong><br>
   A lean, interconnected skill ecosystem for AI coding assistants.<br>
-  64 skills · 204 connections · 40 signals · 13 platforms · MIT
+  65 skills · 204 connections · 43 signals · 13 platforms · MIT
 </p>
 
 <p align="center">
@@ -23,7 +23,7 @@
 
 Most skill ecosystems are either **too many isolated skills** (540+ that don't talk to each other) or **rigid pipelines** (A → B → C, if B fails everything stops).
 
-Rune is a **mesh** — 64 skills with 204 connections + 40 signals across a 5-layer architecture. Skills call each other bidirectionally, forming resilient workflows that adapt when things go wrong.
+Rune is a **mesh** — 65 skills with 204 connections + 43 signals across a 5-layer architecture. Skills call each other bidirectionally, forming resilient workflows that adapt when things go wrong.
 
 ```
 Pipeline:  A → B → C → D         (B fails = stuck)
@@ -83,7 +83,11 @@ _Methodology: Claude Code CLI headless mode (`claude -p --output-format json`),
 
 ---
 
-## What's New (v2.20.0 — Spec Discipline)
+## What's New (v2.21.0 — Convergence)
+
+> **v2.21.0 (2026-07-03):** Kills the most expensive silent failure in AI-built apps: **the dead button** — UI renders, click does nothing, backend never existed. New `converge` skill (65th) re-reads your spec/plan/contracts as the sole source of intent and scans the ACTUAL code for `missing` / `partial` / `contradicts` / `unrequested` gaps, appending remediation tasks until spec and code converge (`cook` Phase 6.5, max 2 rounds then honest escalation). The whole chain got teeth: `ba` v1.2.0 emits story-sliced specs (P1/P2/P3 priorities, per-story **Independent Test**, **Key Entities**), `plan` v1.7.0 emits **contracts-first boundary artifacts** (`data-model.md` + `contracts/` + `quickstart.md`) with a P1 zero-coverage HARD-GATE and a Data→Logic→Endpoint→UI ordering law (UI is structurally last), `verification` v0.6.0 adds **Level 3.5 INTERACTION WIRED** (traces button → handler → route across React/Svelte/Vue syntax), `completion-gate` v1.9.0 makes the E2E flow trace mandatory for UI+data diffs (single-phase included), and `deploy` v0.8.0 warns before shipping UI+data changes with no wiring evidence. 3 new mesh signals (`convergence.gaps`, `convergence.clean`, `integration.verified`). Every gate is diff-scoped — legacy debt warns, new work fails.
+
+### Previous (v2.20.0 — Spec Discipline)
 
 > **v2.20.0 (2026-07-02):** Closes the "plan without spec" gap — a `brainstorm → plan → cook` chain no longer skips `ba`. Two new gates (`brainstorm` spec-presence + `cook` Phase 0 **Spec-Backfill Gate**) force requirements before code on every bypass path, not just brainstorm's. Batch also lands `ba` v1.1.0 (EARS `FR-n` functional-requirements layer), `adversary` v0.4.0 (reasoning-mode catalog + steelman-first), and a context-hook fix (session_id keying — no more false "100% compact"). Mesh **204 connections**, 1,559 tests.
 
@@ -215,7 +219,7 @@ cook ───emit:phase.complete────→ session-bridge
 
 ## What Rune Is (and Isn't)
 
-Rune started as a **Claude Code plugin** and now compiles to **every major AI IDE**. Same 64 skills, same mesh connections, same workflows — zero knowledge loss across platforms.
+Rune started as a **Claude Code plugin** and now compiles to **every major AI IDE**. Same 65 skills, same mesh connections, same workflows — zero knowledge loss across platforms.
 
 | | Rune Provides | Claude Code Provides |
 |---|---|---|
@@ -307,14 +311,14 @@ npx @rune-kit/rune init --platform windsurf
 npx @rune-kit/rune init --platform antigravity
 ```
 
-This compiles all 64 skills into your IDE's rules format. Same knowledge, same workflows.
+This compiles all 65 skills into your IDE's rules format. Same knowledge, same workflows.
 
 ### Platform Comparison
 
 | Feature | Claude Code | Cursor / Windsurf / Others |
 |---------|-------------|---------------------------|
 | Skills available | 64/64 | 64/64 |
-| Mesh connections | 203 sync + 40 signals (programmatic) | 203 sync + 40 signals (rule references) |
+| Mesh connections | 204 sync + 43 signals (programmatic) | 204 sync + 43 signals (rule references) |
 | Workflows & HARD-GATEs | Full | Full |
 | Extension packs | 14 | 14 |
 | Subagent parallelism | Native | Sequential fallback |
@@ -667,7 +671,7 @@ See [docs/MULTI-PLATFORM.md](docs/MULTI-PLATFORM.md) for the full architecture.
 | Doc | What's inside |
 |-----|---------------|
 | [`docs/GETTING_STARTED.md`](docs/GETTING_STARTED.md) | Your first 5 minutes with Rune — install to first `/rune cook` |
-| [`docs/SKILLS.md`](docs/SKILLS.md) | All 64 skills, searchable by intent and layer |
+| [`docs/SKILLS.md`](docs/SKILLS.md) | All 65 skills, searchable by intent and layer |
 | [`docs/SIGNALS.md`](docs/SIGNALS.md) | Canonical signal inventory — 25 events, emit/listen graph |
 | [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md) | 5-layer mesh architecture reference |
 | [`docs/VISION.md`](docs/VISION.md) | Philosophy — what Rune is and isn't |
@@ -683,7 +687,7 @@ See [docs/MULTI-PLATFORM.md](docs/MULTI-PLATFORM.md) for the full architecture.
 Core Skills:       64 (L0: 1 │ L1: 5 │ L2: 30 │ L3: 28)
 Extension Packs:   14 free + 9 pro + 4 business
 Mesh Connections:  203 sync calls (rune doctor)
-Mesh Signals:      40 signals · 50 emit/listen edges (rune doctor)
+Mesh Signals:      43 signals · 55 emit/listen edges (rune doctor)
 Connections/Skill: 3.2 avg
 Platforms:         8 (Claude Code, Cursor, Windsurf, Antigravity, Codex, OpenCode, OpenClaw, Generic)
 Compiler:          ~1400 LOC (parser + 8 transforms + 8 adapters + CLI)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rune-kit/rune",
-  "version": "2.20.0",
+  "version": "2.21.0",
   "description": "64-skill mesh for AI coding assistants — runtime auto-discipline via native hooks (Claude/Cursor/Windsurf/Antigravity), 5-layer architecture, 215+ connections, multi-platform compiler. v2.17 adds quarantine L3 for prompt-injection advisory on untrusted external content.",
   "type": "module",
   "bin": {

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.1.0"
+  version: "1.2.0"
   layer: L2
   model: opus
   group: creation
@@ -479,7 +479,9 @@ Rules (full guidance in [references/ears-format.md](references/ears-format.md)):
 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]
@@ -487,9 +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)
 
@@ -572,11 +593,14 @@ 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
 ### Out of Scope
@@ -634,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
 
@@ -720,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
 
@@ -727,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 |
 
@@ -761,7 +791,11 @@ Known failure modes for this skill. Check these before declaring done.
 | 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 |
@@ -784,6 +818,9 @@ Known failure modes for this skill. Check these before declaring done.
 - Scope defined (in/out/assumptions/dependencies)
 - 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/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 |

package/skills/converge/SKILL.md

@@ -0,0 +1,178 @@
+---
+name: converge
+description: "Spec↔code convergence scan. Use after implementation to verify the ACTUAL codebase matches the spec/plan — detects missing backends, dead buttons, partial wiring, scope creep. Classifies gaps (missing/partial/contradicts/unrequested), appends remediation tasks, loops until converged. The direct answer to 'the UI renders but nothing works' syndrome."
+metadata:
+  author: runedev
+  version: "0.1.0"
+  layer: L3
+  model: sonnet
+  group: verification
+  tools: "Read, Glob, Grep"
+  emit: convergence.gaps, convergence.clean
+  listen: verification.complete
+---
+
+# converge
+
+## Purpose
+
+Post-implementation gap detector. Re-reads the spec, plan, and tasks as the **sole source of intent**, inspects the ACTUAL codebase (present state, not the diff), and classifies every intent key as implemented or gapped. Where verification asks "does it build?", converge asks "**is everything the spec promised actually in the code?**"
+
+This is the skill that catches the most expensive silent failure: a P1 story's UI exists, renders, passes lint/type/build — and its backend was never written.
+
+<HARD-GATE>
+Converge DETECTS — it never fixes. No Edit, no Write to source files.
+Its ONLY write is APPENDING a `## Convergence` task section to the plan's task file.
+Existing file content is never rewritten, reordered, or deleted. Zero gaps = zero writes.
+</HARD-GATE>
+
+## Called By (inbound)
+
+- `cook` (L1): Phase 6.5 CONVERGE — after VERIFY, before COMMIT, for feature/greenfield chains with a requirements.md
+- User: `/rune converge` — "did it fully implement the spec?", "check completeness", "does the code match the spec?"
+
+## Calls (outbound)
+
+None — pure L3 verification utility. Reports gaps; cook decides what to execute.
+
+## Executable Steps
+
+### Step 1 — Build the Intent Inventory
+
+Load intent sources (all that exist; requirements.md is mandatory — without it, STOP and report `NO_SPEC`):
+
+1. `.rune/features/<name>/requirements.md` — extract keys: every `FR-n`, every `US-n` with priority + Independent Test, every `AC-n.m` (as `US-n/AC-n.m`), every Key Entity
+2. `.rune/plan-<feature>.md` + phase files — Key Decisions, Coverage Summary, task list with `P<phase>-T<seq>` IDs
+3. `.rune/features/<name>/contracts/*.md` — each contract: its endpoint, its `Serves:` story, its `Consumers:` list
+4. `.rune/features/<name>/data-model.md` — entities, state transitions
+5. `.rune/features/<name>/quickstart.md` — per-story validation steps
+6. `.rune/ui-spec.md` `## Unwired Elements` (if present) — designed placeholders that MUST NOT count as implemented
+
+The inventory is a flat list of keys: `FR-3`, `US-1/AC-1.2`, `contract:create-order`, `entity:Order`, `decision:<slug>`.
+
+### Step 2 — Build the Code-Scope Map
+
+Map intent → code locations. NO full-repo read — targeted lookups only:
+
+1. `Glob` every file path named in plan tasks — does it exist?
+2. `Grep` entity names (from data-model.md) across schema/model directories
+3. `Grep` each contract's endpoint path/route across the codebase — implementation AND callers
+4. `Grep` component names from UI tasks — definition AND the handler symbols they bind
+
+### Step 3 — Classify Gaps
+
+For every intent key, assign exactly one verdict:
+
+| Verdict | Meaning | Example |
+|---------|---------|---------|
+| `implemented` | Code fully realizes the key | Endpoint exists, has logic, has a caller |
+| `missing` | Required work absent entirely | Contract file exists, no route implements it |
+| `partial` | Started but a link in the chain is dead | Button + handler exist; handler's fetch targets a route that doesn't exist |
+| `contradicts` | Code diverges from a locked decision or AC | Spec says soft-delete; code hard-deletes |
+| `unrequested` | Code maps to NO intent key (scope creep — surfaced, not blocked) | New admin page no story asked for |
+
+**Dead-interaction trace** (run for every UI element an AC references):
+
+```
+element → handler bound? → handler body non-trivial? → calls service/fetch?
+        → target route/function EXISTS in codebase? → route touches the entity the AC names?
+```
+
+First broken link = `partial`, keyed to that element's `US-n/AC-n.m`. Elements listed in `## Unwired Elements` are automatically `missing` (designed placeholder, never wired). Heuristics: `onClick={() => {}}`, `href="#"` on action links, `console.log`-only handlers, `preventDefault()`-only submits, `fetch('/api/...')` where no route file matches — all break the chain.
+
+### Step 4 — Assign Severity
+
+| Severity | Condition |
+|----------|-----------|
+| CRITICAL | `missing` or `contradicts` gap that blocks a **P1 story's** acceptance scenario or Independent Test |
+| HIGH | `partial` on a P1 story, or `missing`/`contradicts` on P2 |
+| MEDIUM | Any gap on P3; `unrequested` code touching shared modules |
+| LOW | `unrequested` isolated code; cosmetic divergence |
+
+### Step 5 — Append Remediation Tasks (APPEND-ONLY)
+
+If gaps exist, append to the ACTIVE phase file (or master plan task section if no phase file):
+
+```markdown
+## Convergence (round N)
+> Appended by converge — spec↔code gaps found. Do not edit rows above this section.
+- [ ] CV-N.1 [CRITICAL] Implement POST /api/orders route per contract:create-order (missing) — `src/api/orders.ts`
+- [ ] CV-N.2 [HIGH] Wire OrderForm submit to POST /api/orders per US-1/AC-1.1 (partial: handler fetches nonexistent route) — `src/components/OrderForm.tsx`
+```
+
+Task format: `CV-<round>.<seq> [severity] <imperative> per <intent-key> (<gap-type>) — <file path>`. Every task cites its intent key — a remediation task with no key is itself a converge violation.
+
+**Deduplication**: when multiple intent keys trace to the SAME absent/broken artifact (e.g., `contract:create-order` missing AND `US-1/AC-1.1` partial, both resolved by implementing `src/api/orders.ts`), emit ONE combined CV task citing all keys — `CV-1.1 [CRITICAL] Implement POST /api/orders per contract:create-order + US-1/AC-1.1 (missing/partial) — src/api/orders.ts`. One target file = one task; the report table still lists every key's verdict separately.
+
+If ZERO gaps: write nothing (task file stays byte-identical), emit `convergence.clean`.
+
+### Step 6 — Emit Verdict
+
+- Gaps found → emit `convergence.gaps` with `{feature, round, counts: {missing, partial, contradicts, unrequested}, critical: N}`
+- Clean → emit `convergence.clean` with `{feature, round, keys_checked: N}`
+
+The caller (cook Phase 6.5) executes appended tasks and re-invokes converge — loop until clean, max 2 remediation rounds before escalation.
+
+## Output Format
+
+```
+## Convergence Report — <feature> (round N)
+
+Intent keys checked: 23 | implemented: 19 | gaps: 4
+
+| Key | Verdict | Severity | Evidence |
+|-----|---------|----------|----------|
+| contract:create-order | missing | CRITICAL | contracts/create-order.md exists; no route matches POST /api/orders (grep: 0 hits in src/) |
+| US-1/AC-1.1 | partial | HIGH | OrderForm.tsx:42 fetch('/api/orders') → route absent |
+| US-3/AC-3.1 | implemented | — | route src/api/list.ts:12, caller OrderList.tsx:8 |
+| (none) | unrequested | LOW | src/pages/admin-stats.tsx maps to no story |
+
+Verdict: 2 gaps blocking P1 → convergence.gaps emitted, 2 tasks appended (CV-1.1, CV-1.2)
+```
+
+Every row needs `file:line` evidence or a grep result count — verdicts without evidence are hallucinations.
+
+## Constraints
+
+1. MUST treat spec/plan/contracts as the sole source of intent — never infer intent from the code itself
+2. MUST inspect present codebase state, not the git diff — earlier phases may have broken older work
+3. MUST give every gap an intent key, a gap-type, a severity, and file-level evidence
+4. MUST append remediation tasks — never rewrite, reorder, or delete existing task content
+5. MUST NOT edit source code — converge detects, fix/cook remediate
+6. MUST surface `unrequested` code as findings, never silently delete or block on it
+7. MUST report `NO_SPEC` and stop when no requirements.md exists — converge without a spec is vibes
+
+## Sharp Edges
+
+| Failure Mode | Severity | Mitigation |
+|---|---|---|
+| Inferring intent from code ("this helper implies a story") | CRITICAL | Intent inventory comes ONLY from Step 1 artifacts — code is evidence, never intent |
+| Verdict without file:line or grep evidence | CRITICAL | Output format requires Evidence column — no evidence, no verdict |
+| Rewriting the task file instead of appending | CRITICAL | HARD-GATE: append-only; zero gaps = zero writes (byte-identical file) |
+| Marking `implemented` because the file exists | HIGH | Existence ≠ implementation — run the dead-interaction trace; a route with `res.status(501)` is `partial` |
+| Counting a designed placeholder as implemented | HIGH | `.rune/ui-spec.md` Unwired Elements are automatically `missing` |
+| Infinite converge loop (gaps never reach zero) | HIGH | Caller caps at 2 remediation rounds → Structured Escalation Report; same gap surviving 2 rounds = approach is wrong, not effort |
+| Fixing the gap itself "since it's small" | HIGH | Converge never edits source — emit the task, let fix own the change |
+| Scanning the whole repo (context blowout) | MEDIUM | Step 2 is targeted Glob/Grep from intent keys — not a repo read |
+| Treating `unrequested` as an error to delete | MEDIUM | Scope creep is surfaced for human decision — it may be wanted, undocumented work |
+
+## Done When
+
+- Intent inventory built from requirements.md + plan + contracts (or NO_SPEC reported)
+- Every intent key has a verdict with file-level evidence
+- Dead-interaction trace run for every AC-referenced UI element
+- Gaps appended as `CV-*` tasks with intent keys (or task file byte-identical when clean)
+- `convergence.gaps` or `convergence.clean` emitted with counts
+- Convergence Report rendered with evidence column
+
+## Returns
+
+| Artifact | Format | Location |
+|----------|--------|----------|
+| Convergence Report | Markdown table with evidence | inline |
+| Remediation tasks | `CV-<round>.<seq>` checklist (append-only) | active phase file / master plan |
+| Signal | `convergence.gaps` \| `convergence.clean` with counts | mesh |
+
+## Cost Profile
+
+~2000-5000 tokens input (spec + plan + targeted greps), ~500-1500 tokens output. Sonnet — the dead-interaction trace needs code comprehension, not just pattern matching. Runs once per feature (plus ≤2 remediation rounds).

package/skills/converge/references/eval-fixtures.md

@@ -0,0 +1,59 @@
+# Converge Eval Fixtures
+
+> Behavioral test scenarios for `converge`. Each fixture defines inputs (spec + code state)
+> and the EXACT expected verdict. Use these to verify converge behaves correctly after any
+> edit to its SKILL.md — and as seeds for a future automated eval harness.
+
+## Fixture 1 — Dead button (the canonical failure)
+
+**Spec**: `US-1 [P1]` "submit an order", `AC-1.1: GIVEN valid items WHEN user clicks Save THEN order persisted and visible in list`. Contract `contracts/create-order.md` → `POST /api/orders`, Consumers: `OrderForm`.
+
+**Code state**: `OrderForm.tsx` exists, renders `<button onClick={handleSave}>Save</button>`; `handleSave` calls `fetch('/api/orders', {method:'POST'})`. NO route file implements `POST /api/orders`.
+
+**Expected**: `contract:create-order` → `missing` CRITICAL (P1). `US-1/AC-1.1` → `partial` (chain breaks at route-exists). Two `CV-1.*` tasks appended citing those keys. `convergence.gaps` emitted. **FAIL IF**: verdict is `implemented` because OrderForm exists, or converge edits OrderForm itself.
+
+## Fixture 2 — Fully wired (clean pass)
+
+**Spec**: same as Fixture 1.
+
+**Code state**: `OrderForm.tsx` handler → `fetch POST /api/orders`; `src/api/orders.ts` implements the route, validates items, persists via `Order` model; `OrderList.tsx` fetches and renders.
+
+**Expected**: all keys `implemented` with file:line evidence. ZERO writes — task file byte-identical. `convergence.clean` emitted. **FAIL IF**: any "improvement" task is appended (converge is not a reviewer), or the task file is touched at all.
+
+## Fixture 3 — Contradicts a locked decision
+
+**Spec**: requirements.md Decision (locked): "soft-delete only — records marked `deletedAt`, never removed". Plan Key Decisions repeats it.
+
+**Code state**: `src/api/orders.ts` delete handler runs `DELETE FROM orders WHERE id = ?`.
+
+**Expected**: `decision:soft-delete` → `contradicts`, CRITICAL if a P1 AC covers deletion (else HIGH). Task: `CV-1.1 [CRITICAL] Replace hard delete with deletedAt flag per decision:soft-delete (contradicts) — src/api/orders.ts`. **FAIL IF**: classified `implemented` because "a delete exists".
+
+## Fixture 4 — Unrequested code (scope creep surfaced, not blocked)
+
+**Spec**: stories US-1..US-3 cover order CRUD only.
+
+**Code state**: everything from Fixture 2 PLUS `src/pages/admin-stats.tsx` (a dashboard no story mentions).
+
+**Expected**: all spec keys `implemented`; one `unrequested` finding (LOW — isolated) listing admin-stats.tsx. `convergence.gaps` emitted (unrequested counts as a gap for reporting) BUT no CV task demanding deletion — the finding is informational for the user. **FAIL IF**: converge deletes the file, appends a "remove admin-stats" task, or hides the finding.
+
+## Fixture 5 — Placeholder counted honestly
+
+**Spec**: `US-2 [P2]` "browse products", AC-2.1 names a product grid.
+
+**Code state**: `ProductGrid.tsx` renders `[ PLACEHOLDER: product-grid ]` boxes; `.rune/ui-spec.md` lists `product-grid` under `## Unwired Elements`.
+
+**Expected**: `US-2/AC-2.1` → `missing` HIGH (P2) — Unwired Elements are auto-missing regardless of how substantive the placeholder markup looks. **FAIL IF**: `implemented` or `partial` (a designed placeholder is not "started work").
+
+## Fixture 6 — No spec (honest refusal)
+
+**Spec**: no `.rune/features/*/requirements.md` exists.
+
+**Expected**: converge reports `NO_SPEC` and stops. No inventory invented from the code, no tasks appended. **FAIL IF**: converge scans the code and fabricates intent keys from what it finds.
+
+## Fixture 7 — Remediation survives round 1 (escalation path)
+
+**Spec**: same as Fixture 1. **Round 1**: converge found `contract:create-order` missing, appended `CV-1.1`. Cook executed CV-1.1 but implemented a stub: `src/api/orders.ts` exists, handler returns `res.status(501)`.
+
+**Code state at round 2**: route file exists, body is a 501 stub; OrderForm unchanged.
+
+**Expected**: round 2 verdict for `contract:create-order` → `partial` (file exists but Level-2-style stub — a 501 is not an implementation), still CRITICAL (P1). `CV-2.1` appended. After round 2 the caller's cap is exhausted → cook produces a Structured Escalation Report with the surviving gap named. **FAIL IF**: classified `implemented` because the route file now exists, or converge silently allows a round 3.