@rune-kit/rune 2.20.0 → 2.21.0

package/skills/cook/SKILL.md

@@ -5,13 +5,13 @@ context: fork
 agent: general-purpose
 metadata:
   author: runedev
-  version: "2.5.0"
+  version: "2.6.0"
   layer: L1
   model: sonnet
   group: orchestrator
   tools: "Read, Write, Edit, Bash, Glob, Grep"
   emit: phase.complete, checkpoint.request
-  listen: plan.ready, review.complete, ideas.ready, preflight.passed, verification.complete
+  listen: plan.ready, review.complete, ideas.ready, preflight.passed, verification.complete, convergence.gaps, convergence.clean
 ---
 
 # cook
@@ -110,8 +110,8 @@ Not every task needs every phase:
 Nano task:           DO → VERIFY → DONE (no phases, auto-detected)
 Simple bug fix:      Phase 1 → 4 → 6 → 7
 Small refactor:      Phase 1 → 4 → 5 → 6 → 7
-New feature:         Phase 1 → 1.5 → 2 → 3 → 4 → 5 → 6 → 7 → 8
-Complex feature:     All phases + brainstorm in Phase 2
+New feature:         Phase 1 → 1.5 → 2 → 3 → 4 → 5 → 6 → 6.5 → 7 → 8  (6.5: conditional — requires requirements.md)
+Complex feature:     All phases (incl. 6.5) + brainstorm in Phase 2
 Security-sensitive:  All phases + sentinel escalated to opus
 Fast mode:           Phase 1 → 4 → 6 → 7 (auto-detected, see below)
 Multi-session:       Phase 0 (resume) → 3 → 4 → 5 → 6 → 7 (one plan phase per session)
@@ -507,12 +507,36 @@ Invoke `rune:session-bridge` after Phase 2, 4, and 5 to save intermediate state.
 
 Before entering ANY Phase N+1, assert: Phase N `completed` in TodoWrite | gate condition met | no BLOCK from sub-skills | no unresolved CRITICAL findings. If any fails → STOP, log "BLOCKED at Phase N→N+1: [assertion]", fix, re-check.
 
-**Key transitions:** 1→2: scout done | 2→3: plan approved | 3→4: failing tests exist | 4→5: all tests pass | 5→6: no CRITICAL findings | 6→7: lint+types+build green.
+**Key transitions:** 1→2: scout done | 2→3: plan approved | 3→4: failing tests exist | 4→5: all tests pass | 5→6: no CRITICAL findings | 6→6.5: lint+types+build green | 6.5→7: convergence.clean or documented escalation (features with requirements.md; others pass through).
 
 ## Phase 6: VERIFY
 
 **REQUIRED SUB-SKILL**: Use `rune:verification` — run lint, type check, full test suite, build. Then `rune:hallucination-guard` to verify imports and API signatures. ALL checks MUST pass before commit.
 
+**Quickstart execution**: if `.rune/features/<name>/quickstart.md` exists (plan Step 3.7 boundary artifact), execute its validation blocks — run each command, compare against its **Expect** line. Any mismatch = verification FAIL (treat like a failing test). If the environment cannot run a block (no browser, no DB), SKIP it with the reason named in the Cook Report — a skipped quickstart is visible debt, never silent.
+
+## Phase 6.5: CONVERGE (Spec↔Code Gap Scan)
+
+**REQUIRED SUB-SKILL**: Use `rune:converge` — verify the ACTUAL codebase matches the spec before committing.
+
+**Trigger**: feature/greenfield chains where `.rune/features/<name>/requirements.md` exists.
+**Skip** (announce the skip): nano/fast/bugfix/refactor/hotfix chains, or no requirements.md (ad-hoc task — Phase 5 gates are the only protection).
+
+1. Invoke `rune:converge` — it re-reads spec/plan/contracts as sole intent, scans present code state, classifies gaps (`missing` / `partial` / `contradicts` / `unrequested`)
+2. **`convergence.clean`** → proceed to Phase 7
+3. **`convergence.gaps`** → inspect the signal's `counts` payload first:
+   - **Unrequested-only** (`counts.missing`=0, `counts.partial`=0, `counts.contradicts`=0, `counts.unrequested`>0): no CV tasks were appended — surface the findings in the Cook Report and proceed to Phase 7. Do NOT enter the remediation loop for informational scope-creep findings
+   - **Otherwise**: converge appended `CV-*` remediation tasks to the active phase file:
+     - Execute the CV tasks (return to Phase 4 loop for them; CRITICAL/HIGH first)
+     - Re-run Phase 6 VERIFY on the remediated code, then re-invoke converge (round 2)
+     - **Max 2 remediation rounds.** Gaps still present after round 2 → produce a Structured Escalation Report (the same gap surviving 2 rounds means the approach is wrong, not the effort)
+4. `unrequested` findings are surfaced to the user in the Cook Report — never silently deleted, never blocking
+
+<HARD-GATE>
+A P1 story with a CRITICAL convergence gap (missing/contradicts) MUST NOT be committed as "done."
+Either remediate within the round cap, or escalate with the gap documented — never claim completion over a known dead path.
+</HARD-GATE>
+
 ## Phase 7: COMMIT
 
 **RECOMMENDED SUB-SKILL**: Use `rune:git` — stage specific files (`git add <files>`, NOT `git add .`), generate semantic commit message from diff. If working from master plan: update phase status `🔄 → ✅`, announce next phase or "All phases complete."
@@ -777,6 +801,7 @@ Mentally track tool call fingerprints. 3 identical calls → WARN. 5 identical c
 | 5 | `constraint-check` | L3 | Audit HARD-GATE compliance across workflow |
 | 6 | `verification` | L3 | Lint + types + tests + build |
 | 6 | `hallucination-guard` | L3 | Verify imports and API calls are real |
+| 6.5 | `converge` | L3 | Spec↔code gap scan for features with requirements.md — dead buttons, missing backends, contradicted decisions |
 | 7 | `journal` | L3 | Record architectural decisions |
 | 8 | `session-bridge` | L3 | Save context for future sessions |
 | any | `context-pack` | L3 | create structured handoff briefings before spawning subagents |
@@ -815,6 +840,7 @@ Mentally track tool call fingerprints. 3 identical calls → WARN. 5 identical c
 | Test-First Gate | Failing tests before Phase 4 | Write tests or get explicit skip |
 | Quality Gate | preflight + sentinel + review before Phase 7 | Fix findings, re-run |
 | Verification Gate | lint + types + tests + build green before commit | Fix, re-run |
+| Convergence Gate | `convergence.clean` (or documented escalation) before Phase 7 for features with requirements.md | Execute CV tasks, re-verify, re-converge (max 2 rounds) |
 
 ## Structured Output Contract (Prompt-as-API Pattern)
 
@@ -910,6 +936,7 @@ SELF-VALIDATION (run before emitting Cook Report):
 - [ ] Plan approval gate was not bypassed — user said "go" (check conversation history)
 - [ ] No Phase 4 code was written before Phase 3 tests (TDD order preserved)
 - [ ] All Phase 5 quality gates (preflight, sentinel, review) ran — not just claimed
+- [ ] Phase 6.5 converge ran for features with requirements.md — or skip announced (no spec) / escalation documented
 - [ ] No quality gate exceeded 3 remediation cycles without user escalation
 - [ ] No upstream issue was fixed by code change alone — UPSTREAM findings re-invoked the source skill
 - [ ] Cook Report contains actual commit hash, not placeholder
@@ -919,6 +946,7 @@ SELF-VALIDATION (run before emitting Cook Report):
 
 All applicable phases complete + Self-Validation passed:
 - User approved plan | All tests PASS (output shown) | preflight+sentinel+review PASS | build green
+- Convergence: `convergence.clean` OR skip announced (no requirements.md) OR escalation documented — never silent
 - Cook Report emitted with commit hash | Session state saved to .rune/ via session-bridge
 
 ## Cost Profile

package/skills/deploy/SKILL.md

@@ -4,13 +4,13 @@ description: "Deploy application to target platform. Use when user explicitly sa
 disable-model-invocation: true
 metadata:
   author: runedev
-  version: "0.7.0"
+  version: "0.8.0"
   layer: L2
   model: sonnet
   group: delivery
   tools: "Read, Write, Edit, Bash, Glob, Grep"
   emit: deploy.complete
-  listen: security.passed, tests.passed, docs.updated, audit.complete, db.migrated
+  listen: security.passed, tests.passed, docs.updated, audit.complete, db.migrated, integration.verified, convergence.clean
 ---
 
 # deploy
@@ -58,6 +58,8 @@ Call `rune:verification` to run the full test suite and build.
 If verification fails → STOP. Do NOT proceed. Report failure with test output.
 ```
 
+**Wiring evidence check (advisory)**: when deploying a FEATURE (not a hotfix — hotfix chain exempt) whose changes touch both UI and api/service/data files, look for cross-layer evidence: `integration.verified` (verification Level 3.5 passed) or `convergence.clean` (converge found zero gaps). Neither present → WARN the user explicitly — "Deploying UI+data changes with no cross-layer wiring evidence. Unit tests alone don't prove the buttons work. Proceed?" — and require confirmation. Advisory, not a block: the user can proceed, but never unknowingly.
+
 Call `rune:sentinel` to run security scan.
 
 ```

package/skills/design/SKILL.md

@@ -3,7 +3,7 @@ name: design
 description: "Design system reasoning. Maps product domain to style, palette, typography, and platform-specific patterns. Generates .rune/design-system.md as the shared design contract for all UI-generating skills."
 metadata:
   author: runedev
-  version: "0.6.0"
+  version: "0.7.0"
   layer: L2
   model: sonnet
   group: creation
@@ -183,6 +183,18 @@ If the design calls for an icon, illustration, or graphic that the agent cannot
 - For illustrations, reference a placeholder string (e.g., `[ILLUSTRATION: empty-state-dashboard]`) that a human or asset-creator pass fills in later.
 - Malformed SVG is the #1 AI tell. A clean labeled placeholder is honest and professional.
 
+**Placeholder Ownership (MANDATORY)**: every placeholder or intentionally inert element the design ships — `[ ICON: ... ]`, `[ILLUSTRATION: ...]`, `[ PLACEHOLDER: ... ]`, and any button/link/form rendered as visual-only (no behavior designed yet) — MUST be listed in `.rune/ui-spec.md` under a `## Unwired Elements` section:
+
+```markdown
+## Unwired Elements
+| Element | Location | Why unwired | Owner of wiring |
+|---------|----------|-------------|-----------------|
+| product-grid | ProductGrid.tsx | awaiting US-2 backend | US-2 Endpoint task |
+| [ ICON: dashboard ] | Sidebar.tsx | asset pass pending | asset-creator |
+```
+
+This list is how downstream gates tell **declared debt** from **accidental dead UI**: `preflight` skips these elements, `verification` reports them as INFO (visible, non-failing), and `converge` counts them as `missing` until wired. A placeholder NOT on this list that reaches implementation = a dead element with no owner — that's the bug this section exists to prevent.
+
 #### Rule 3 — Color Derivation via oklch(), not Manual Shading
 
 When the design needs a darker hover, lighter surface, or tinted state, **derive from the accent via oklch()** — never eyeball a hex value.
@@ -655,6 +667,7 @@ Trading/Fintech — Data-Dense Dark — Web
 11. MUST write measurable rules into design-system.md — never vague directives like "modern typography" or "tasteful spacing" (Step 2.9 Rule 4)
 12. MUST NOT use pure `#000` / `#fff` for default text or background, MUST NOT ship lorem ipsum (Step 2.9 Rule 5)
 13. MUST list CJK-capable font FIRST in stack if product targets Chinese/Japanese/Korean (Step 2.9 Rule 6)
+14. MUST list every intentionally inert/placeholder element in `.rune/ui-spec.md` under `## Unwired Elements` (element, location, why unwired, wiring owner) — Placeholder Ownership (Step 2.9 Rule 2)
 
 ## Mesh Gates (L1/L2 only)
 
@@ -670,6 +683,7 @@ Trading/Fintech — Data-Dense Dark — Web
 | oklch-Derivation Gate | All accent variants derived via `oklch(from ...)` | Rewrite manual hex shades as relative oklch |
 | Measurable-Constraints Gate | Every rule in design-system.md is testable (concrete units, hex/oklch, ratios) | Rewrite vague directives as measurable specs (Step 2.9 Rule 4 table) |
 | No-Pure-No-Lorem Gate | No `#000`/`#fff` in semantic tokens; no lorem ipsum in output | Swap to oklch neutrals; replace lorem with real data or labelled placeholder |
+| Placeholder-Ownership Gate | Every inert/placeholder element shipped is listed in `.rune/ui-spec.md` `## Unwired Elements` (element, location, why, wiring owner) | Add the missing rows before reporting done — an unlisted placeholder is a dead element with no owner |
 
 ## Returns
 

package/skills/plan/SKILL.md

@@ -1,9 +1,9 @@
 ---
 name: plan
-description: "Create structured implementation plans from requirements. Produces master plan + phase files for enterprise-scale project management. Master plan = overview (<80 lines). Phase files = execution detail (<150 lines each). Each session handles 1 phase. Uses opus for deep reasoning."
+description: "Create structured implementation plans from requirements. Produces master plan + phase files for enterprise-scale project management. Master plan = overview (<80 lines). Phase files = execution detail (<200 lines each). Each session handles 1 phase. Uses opus for deep reasoning."
 metadata:
   author: runedev
-  version: "1.6.0"
+  version: "1.7.0"
   layer: L2
   model: opus
   group: creation
@@ -16,7 +16,7 @@ metadata:
 
 ## Purpose
 
-Strategic planning engine for the Rune ecosystem. Produces a **master plan + phase files** architecture — NOT a single monolithic plan. The master plan is a concise overview (<80 lines) that references separate phase files, each containing enough detail (<150 lines) that ANY model can execute with high accuracy.
+Strategic planning engine for the Rune ecosystem. Produces a **master plan + phase files** architecture — NOT a single monolithic plan. The master plan is a concise overview (<80 lines) that references separate phase files, each containing enough detail (<200 lines) that ANY model can execute with high accuracy.
 
 **Design principle: Plan for the weakest coder.** Phase files are designed so that even an Amateur-level model (Haiku) can execute them with minimal errors. When the plan satisfies the Amateur's needs, every model benefits — Junior (Sonnet) executes near-perfectly, Senior (Opus) executes flawlessly.
 
@@ -34,7 +34,7 @@ For trivial tasks (1-2 phases, < 5 files): inline plan is acceptable.
 ```
 .rune/
   plan-<feature>.md          ← Master plan: phases overview, goals, status tracker (<80 lines)
-  plan-<feature>-phase1.md   ← Phase 1 detail: tasks, acceptance criteria, files to touch (<150 lines)
+  plan-<feature>-phase1.md   ← Phase 1 detail: tasks, acceptance criteria, files to touch (<200 lines)
   plan-<feature>-phase2.md   ← Phase 2 detail
   ...
 ```
@@ -162,14 +162,35 @@ Phase files are SELF-CONTAINED execution instructions — designed for the weake
 </HARD-GATE>
 
 Phase decomposition rules:
-- **Foundation first**: types, schemas, core engine
+- **Foundation first**: types, schemas, core engine. A Foundational phase holds ONLY what 2+ stories share — it BLOCKS story phases but stays minimal
 - **Dependencies before consumers**: create what's imported before the importer
+- **Ordering law WITHIN each slice**: Data → Logic → Endpoints/Services → UI → Integration. UI is structurally LAST — a UI task whose slice has no upstream data/logic/endpoint task (and doesn't consume Foundational or a prior slice's contract) is an INVALID plan, not a style choice. The button and the endpoint it calls are one slice's tasks, never split across slices
 - **Test alongside**: each phase includes its own test tasks
 - **Max 5-7 tasks per phase**: if more, split the phase
 - **Vertical slices over horizontal layers**: prefer "auth end-to-end" over "all models → all APIs → all UI" (see `references/vertical-slice.md` for tracer-bullet template, AFK/HITL labels, granularity rules)
+- **Story-grouped backbone from BA**: if `.rune/features/<name>/tasks.md` exists, its `## US-n` sections map to slices — refine them, do NOT flatten back into layer groups
 
 Tasks within each phase MUST be organized into waves (parallel-safe groupings). See `references/wave-planning.md`.
 
+### Step 3.7 — Boundary Artifacts (Contracts-First)
+<MUST-READ path="references/boundary-artifacts.md" trigger="when the feature crosses a UI↔data boundary — templates for data-model.md, contracts/, quickstart.md"/>
+
+**Detect the boundary**: requirements.md has a `## Key Entities` section AND any user story renders a UI surface (page/screen/form/component) — OR the task description implies user interaction with persisted data (submit, save, login, search, checkout).
+
+**If the boundary exists, plan MUST emit — BEFORE writing phase files:**
+
+| Artifact | Location | Content |
+|----------|----------|---------|
+| `data-model.md` | `.rune/features/<name>/` | Key Entities expanded: fields, types, validation rules, state transitions |
+| `contracts/` | `.rune/features/<name>/contracts/` | One file per interface: endpoint/function, request/response shape, error cases — each mapped to the `US-n` it serves |
+| `quickstart.md` | `.rune/features/<name>/` | Runnable end-to-end validation: prerequisites, setup commands, per-story Independent Test steps, expected outcomes |
+
+Rules:
+- Tasks are then DERIVED from contracts: every contract file → ≥1 implementation task + ≥1 test task inside the story it serves. A UI task referencing no contract (and no prior slice's contract) is orphaned — fix the plan
+- A story that touches data but maps to no entity in data-model.md = spec gap → bounce to `ba` (Upstream Inconsistency)
+- quickstart.md is the feature's executable end-to-end validation — write commands that actually run, not prose. Task derivation adds a "run quickstart validation" task to the final phase, so the plan itself guarantees it gets executed
+- **Skip** when no boundary: pure-UI features (styling, layout), pure-backend (cron, migration), libraries. Announce the skip: "No UI↔data boundary — skipping boundary artifacts"
+
 ### Step 4 — Write Master Plan File
 <MUST-READ path="references/plan-templates.md" trigger="when writing the master plan file"/>
 
@@ -208,9 +229,35 @@ Performance Constraints section is optional (only when NFRs apply).
 
 When presenting alternatives (from brainstorm or Step 3), rate each **Completeness X/10**. Always recommend the higher-completeness option — with AI, the marginal cost of completeness is near-zero.
 
+### Step 5.7 — Coverage Gate (after phase files, before presenting)
+
+**Task ID scheme**: every task in a phase file carries the ID `P<phase>-T<seq>` — phase number + sequential position within that phase (`P2-T3` = phase 2, task 3). Phase file task labels use this ID (see `references/plan-templates.md`). Coverage Summary, Traceability Matrix, and Change Stacking `depends_on` all reference tasks by this ID.
+
+When BA requirements exist, build the **Coverage Summary** — every `FR-n` and `US-n` mapped to the task IDs that implement it:
+
+```markdown
+## Coverage Summary
+| Key | Priority | Tasks | Covered |
+|-----|----------|-------|---------|
+| US-1 | P1 | P1-T2, P1-T3, P2-T1 | ✅ |
+| FR-3 | — | P2-T4 | ✅ |
+| US-3 | P2 | — | ❌ deferred to v2 (explicit) |
+```
+
+<HARD-GATE>
+A P1 story or its FRs with ZERO tasks = the plan is INCOMPLETE — do NOT present it for approval. Fix the plan first.
+P2/P3 zero-coverage is allowed ONLY with an explicit deferral line in the master plan ("US-3 deferred to v2 — user-visible in Coverage Summary"), never silently.
+</HARD-GATE>
+
+**Sequencing note**: task IDs exist only AFTER Step 5 writes the phase files — so this step runs after Step 5, and you MUST go back and `Edit` the already-written master plan file (`.rune/plan-<feature>.md`) to insert the `## Coverage Summary` section (before `## Architecture`). Present the UPDATED master plan at Step 6. A master plan presented without its Coverage Summary is a Step 5.7 violation, not an oversight.
+
+**Size spillover**: if the table exceeds ~15 rows, write the full table to `.rune/plan-<feature>-coverage.md` instead, and put a one-line pointer + the ❌/deferred rows only in the master plan (the 80-line cap stays intact; zero-coverage rows are never hidden in the spillover file).
+
+Skip when no requirements.md exists (ad-hoc tasks).
+
 ### Step 6 — Present and Get Approval
 
-Present the **master plan** to user (NOT all phase files). User reviews: phase breakdown, key decisions, risks, completeness scores. Wait for explicit approval ("go", "proceed", "yes") before writing phase files.
+Present the **master plan** to user (NOT all phase files). User reviews: phase breakdown, key decisions, risks, completeness scores, **coverage summary**. Wait for explicit approval ("go", "proceed", "yes") before writing phase files.
 
 ### Step 6.5 — Update Feature Map (Always)
 <MUST-READ path="references/feature-map.md" trigger="every plan invocation"/>
@@ -330,6 +377,9 @@ When producing phase files with wave-based task grouping, every task MUST declar
 12. MUST include rejection criteria — explicit "DO NOT" anti-patterns to prevent common mistakes
 13. MUST include cross-phase context — what's assumed from prior phases, what's exported for future
 14. MUST update `.rune/features.md` after every non-trivial plan — feature map is a living artifact
+15. MUST emit boundary artifacts (data-model.md, contracts/, quickstart.md) when the feature crosses a UI↔data boundary — tasks derive from contracts, not the reverse
+16. MUST order layers within each slice Data → Logic → Endpoint → UI — a UI task with no upstream chain in its slice is an invalid plan
+17. MUST NOT present a plan where a P1 story has zero task coverage — Coverage Summary is part of the master plan
 
 ## Returns
 
@@ -338,6 +388,9 @@ When producing phase files with wave-based task grouping, every task MUST declar
 | Master plan | Markdown | `.rune/plan-<feature>.md` |
 | Phase files | Markdown | `.rune/plan-<feature>-phase<N>.md` (one per phase) |
 | Feature spec | Markdown | `.rune/features/<name>/spec.md` (Feature Spec Mode only) |
+| Data model | Markdown | `.rune/features/<name>/data-model.md` (Step 3.7 — UI↔data boundary only) |
+| Interface contracts | Markdown (one per interface) | `.rune/features/<name>/contracts/` (Step 3.7) |
+| Quickstart validation | Markdown (executable steps) | `.rune/features/<name>/quickstart.md` (Step 3.7) |
 | Roadmap | Markdown | `.rune/roadmap.md` (Roadmap Mode only) |
 | Feature map | Markdown | `.rune/features.md` (auto-maintained) |
 | Inline plan | Markdown (inline) | Emitted directly for trivial tasks |
@@ -349,7 +402,7 @@ Append to plan output when invoked standalone. Suppress when called as sub-skill
 ```yaml
 chain_metadata:
   skill: "rune:plan"
-  version: "1.6.0"
+  version: "1.7.0"
   status: "[DONE | DONE_WITH_CONCERNS | NEEDS_CONTEXT | BLOCKED]"
   domain: "[area planned]"
   files_changed:
@@ -401,6 +454,11 @@ chain_metadata:
 | Missing dependency between tasks that share artifacts | HIGH | Every task declares `provides[]` and `requires[]` — cycle detection + missing dep check before dispatch |
 | New feature planned without checking existing feature map | HIGH | Step 1 reads `.rune/features.md` — catches overlaps, conflicts, and missing dependencies before planning begins |
 | Feature map never created — gaps accumulate silently | MEDIUM | Step 6.5 always runs (create or update) — feature map grows organically with each plan invocation |
+| UI task planned with no endpoint/contract behind it (dead button at plan time) | CRITICAL | Step 3.7: contracts/ emitted before phase files; every UI task cites its contract; ordering law makes UI structurally last in its slice |
+| P1 story silently missing from tasks (frontend-only plan) | CRITICAL | Step 5.7 Coverage Gate: P1 zero-coverage = plan not presentable; Coverage Summary visible in master plan at approval |
+| Boundary artifacts skipped because "the feature is simple" | HIGH | Detection is mechanical (Key Entities + UI surface), not judgment. Skips are announced, never silent |
+| quickstart.md written as prose instead of runnable commands | MEDIUM | Every step needs an **Expect** with observable outcome — cook executes this file at VERIFY |
+| BA's story-grouped tasks.md flattened back into layer groups | HIGH | Step 3 rule: `## US-n` sections map to slices — refine, don't flatten |
 
 ## Self-Validation
 
@@ -412,6 +470,9 @@ SELF-VALIDATION (run before presenting plan to user):
 - [ ] Phase files have ALL Amateur-Proof sections (data flow, code contracts, failure scenarios, rejection criteria)
 - [ ] Locked decisions from BA are reflected in plan — none contradicted or ignored
 - [ ] Every BA requirement has a corresponding Req ID in at least one phase's Traceability Matrix
+- [ ] Coverage Summary built (Step 5.7) — no P1 story/FR with zero tasks; P2/P3 gaps have explicit deferral lines
+- [ ] Boundary artifacts emitted if UI↔data boundary detected — every contract has a consumer, every UI task cites its contract (or justifies Contract: none)
+- [ ] Layer order within every slice: no UI task precedes its slice's data/logic/endpoint tasks
 - [ ] `.rune/features.md` updated with current feature (or created if first run)
 - [ ] No cross-feature conflicts detected (or flagged to user if found)
 ```
@@ -427,6 +488,8 @@ SELF-VALIDATION (run before presenting plan to user):
   - Failure scenarios table, rejection criteria (DO NOTs)
   - Cross-phase context (assumes/exports), acceptance criteria
 - Every code-producing phase has test tasks
+- Boundary artifacts emitted (data-model.md + contracts/ + quickstart.md) when UI↔data boundary detected — or skip announced
+- Coverage Summary in master plan — every P1 story/FR covered, P2/P3 gaps explicitly deferred
 - Master plan presented to user with "Awaiting Approval"
 - User has explicitly approved
 - Self-Validation: all checks passed

package/skills/plan/references/boundary-artifacts.md

@@ -0,0 +1,127 @@
+# Boundary Artifacts (Contracts-First)
+
+> Reference for `plan` skill — Step 3.7.
+> Load when the feature crosses a UI↔data boundary.
+
+The single most common incomplete-implementation failure is a UI element wired to nothing —
+the button renders, the endpoint doesn't exist. Boundary artifacts make the interface surface
+a REVIEWABLE ARTIFACT at plan time, so a missing backend is visible before any code is written.
+
+## Detection
+
+Emit boundary artifacts when BOTH are true:
+1. `requirements.md` has a `## Key Entities` section (feature involves data)
+2. Any user story renders a UI surface — page, screen, form, component — OR the task
+   implies user interaction with persisted data (submit, save, login, search, checkout)
+
+Skip (and announce the skip) for: pure-UI features (styling, layout, static content),
+pure-backend (cron jobs, migrations, CLI), libraries with no UI.
+
+## Artifact 1: data-model.md
+
+Save to `.rune/features/<name>/data-model.md`. Expand each Key Entity from the spec:
+
+```markdown
+# Data Model: [Feature Name]
+
+## Order
+| Field | Type | Validation | Notes |
+|-------|------|-----------|-------|
+| id | uuid | generated | PK |
+| userId | uuid | must reference existing User | FK → User |
+| status | enum | draft \| submitted \| fulfilled | state machine below |
+| items | OrderItem[] | min 1 item | |
+
+**State transitions**: draft → submitted (on user submit, validates items) → fulfilled
+(on admin action). No transition skips submitted. Invalid transition = 409.
+
+**Relationships**: User 1—N Order. Order 1—N OrderItem.
+```
+
+Rules: every entity from the spec's Key Entities appears here. Every state named in the
+spec has an explicit transition trigger. Validation rules come from AC error cases.
+
+## Artifact 2: contracts/
+
+Save one file per interface to `.rune/features/<name>/contracts/`. Filename: `<verb>-<resource>.md`
+(e.g., `create-order.md`, `list-orders.md`).
+
+```markdown
+# Contract: POST /api/orders
+
+**Serves**: US-1 (AC-1.1, AC-1.2)
+
+## Request
+```json
+{ "items": [{ "productId": "uuid", "quantity": 1 }] }
+```
+Validation: items non-empty; quantity ≥ 1; productId exists.
+
+## Response 201
+```json
+{ "id": "uuid", "status": "submitted", "items": [...] }
+```
+
+## Errors
+| Case | Status | Body |
+|------|--------|------|
+| empty items (AC-1.2) | 422 | `{ "error": "items must not be empty" }` |
+| unknown productId | 404 | `{ "error": "product not found" }` |
+| unauthenticated | 401 | — |
+
+## Consumers
+- `OrderForm` component (US-1 UI task) — submit handler calls this endpoint
+```
+
+Rules:
+- Every contract names the `US-n` it serves and the AC cases its errors cover
+- Every contract names its **Consumers** — the UI component or caller that will invoke it.
+  A contract with no consumer, or a UI task with no contract, is an orphan → fix the plan
+- Non-HTTP interfaces (IPC, function boundary, event) use the same shape: input, output, errors, consumers
+
+## Artifact 3: quickstart.md
+
+Save to `.rune/features/<name>/quickstart.md`. This is EXECUTABLE, not prose — the
+final phase carries a "run quickstart validation" task (see Task derivation below),
+and `converge` traces each story's acceptance scenarios against these steps, so the
+feature cannot be declared done without them passing.
+
+```markdown
+# Quickstart: [Feature Name]
+
+## Prerequisites
+- `npm install` done, DB running (`docker compose up -d db`)
+- Migrations applied: `npm run db:migrate`
+
+## Validate US-1 (P1): submit an order
+1. `npm run dev`
+2. `curl -s -X POST localhost:3000/api/orders -H 'content-type: application/json' \
+     -d '{"items":[{"productId":"<seed-id>","quantity":1}]}'`
+   **Expect**: 201, body contains `"status":"submitted"`
+3. `curl -s localhost:3000/api/orders` — **Expect**: list contains the new order
+4. UI path: open /orders/new → add item → Submit → **Expect**: redirect to /orders,
+   new order visible in list
+
+## Validate US-1 error path (AC-1.2)
+1. Submit with empty items → **Expect**: 422, form shows "items must not be empty"
+```
+
+Rules:
+- One validation block per P1 story (P2/P3 optional), derived from the story's Independent Test
+- Every step has an **Expect** with an observable outcome — status code, body content, visible UI state
+- Commands must actually run in the project's environment; if the env can't run them
+  (no browser, no DB), say so in Prerequisites and give the closest executable check
+
+## Task derivation
+
+After emitting the three artifacts, derive tasks:
+
+| Source | Derived tasks |
+|--------|---------------|
+| Each entity in data-model.md | 1 schema/model task (in Foundational if shared by 2+ stories, else in its story) |
+| Each contract file | 1 contract test task + 1 implementation task, inside the story it serves, BEFORE that story's UI task |
+| Each contract's Consumers line | the UI task's Logic field references the contract file |
+| quickstart.md | 1 "run quickstart validation" task in the final phase |
+
+Cross-check before Coverage Gate (Step 5.7): every contract implemented, every consumer wired,
+every quickstart block runnable. An unimplemented contract = the dead button, caught at plan time.

package/skills/plan/references/plan-templates.md

@@ -29,6 +29,16 @@ Save to `.rune/plan-<feature>.md`. Max 80 lines.
 - Discretion (agent): [list — agent chose X because Y]
 - Deferred: [list — explicitly excluded from this feature]
 
+## Coverage Summary
+<!-- Step 5.7 — only when BA requirements exist. P1 zero-coverage = plan not presentable.
+     Inserted AFTER phase files exist (task IDs come from them). If >15 rows, move the full
+     table to .rune/plan-<feature>-coverage.md and keep only a pointer + ❌/deferred rows here. -->
+| Key | Priority | Tasks | Covered |
+|-----|----------|-------|---------|
+| US-1 | P1 | P1-T2, P1-T3 | ✅ |
+| FR-3 | — | P2-T4 | ✅ |
+| US-3 | P2 | — | ❌ deferred to v2 (explicit) |
+
 ## Architecture
 <brief system diagram or component list — NOT implementation detail>
 
@@ -89,23 +99,32 @@ function validateInput(raw: unknown): TradeEntry[];  // throws ValidationError
 
 Each task MUST include: **File** (exact path), **Test** (test file or N/A), **Verify** (shell command), **Commit** (semantic message). Granularity: 2-5 min per task. If >10min, decompose.
 
-- [ ] Task 1 — Create calculateProfit function
-  - Req: REQ-001 (P&L calculation)
+**Task IDs**: label every task `P<phase>-T<seq>` (phase number + position within phase). Coverage Summary, Traceability Matrix, and `depends_on` reference these IDs.
+
+**Req IDs**: when BA produced `FR-n`/`US-n` IDs, use THOSE IDs in the Req field and Traceability Matrix — do NOT renumber as REQ-n. The `REQ-n` format is only for ad-hoc plans with no BA spec.
+
+When BA requirements exist, each task also carries **Story** (`US-n` it serves) — and UI tasks carry **Contract** (the `contracts/` file whose endpoint the UI invokes; see `references/boundary-artifacts.md`). A UI task with `Contract: none` MUST justify why (static UI, consumes prior slice's contract).
+
+- [ ] P2-T1 — Create calculateProfit function
+  - Req: FR-1 (P&L calculation)
+  - Story: US-1
   - File: `src/foo/bar.ts` (new)
   - Test: `tests/foo/bar.test.ts` (new)
   - Verify: `npm test -- --grep "calculateProfit"`
   - Commit: `feat(trading): add calculateProfit with fee calculation`
   - Logic: sum entries by side, apply fees (0.1% per trade), return net P&L
   - Edge: empty array → return { netPnL: 0, totalFees: 0, winRate: 0 }
-- [ ] Task 2 — Add input validation
-  - Req: REQ-002 (input validation)
+- [ ] P2-T2 — Add input validation
+  - Req: FR-2 (input validation)
+  - Story: US-1
   - File: `src/foo/baz.ts` (modify)
   - Test: `tests/foo/baz.test.ts` (new)
   - Verify: `npm test -- --grep "validateInput"`
   - Commit: `feat(trading): add input validation for trade entries`
   - Logic: check side is 'long'|'short', prices > 0, quantity > 0
-- [ ] Task 3 — Write integration tests
-  - Req: REQ-001, REQ-002 (integration coverage)
+- [ ] P2-T3 — Write integration tests
+  - Req: FR-1, FR-2 (integration coverage)
+  - Story: US-1
   - File: `tests/foo/bar.test.ts` (modify)
   - Test: N/A — this IS the test task
   - Verify: `npm test -- --grep "trading" && npx tsc --noEmit`
@@ -157,10 +176,10 @@ Each task MUST include: **File** (exact path), **Test** (test file or N/A), **Ve
 ## Traceability Matrix
 | Req ID | Requirement | Task(s) | Test(s) | Status |
 |--------|-------------|---------|---------|--------|
-| REQ-001 | P&L calculation with fees | Task 1 | `tests/foo/bar.test.ts` | ⬚ |
-| REQ-002 | Input validation | Task 2 | `tests/foo/baz.test.ts` | ⬚ |
+| FR-1 | P&L calculation with fees | P2-T1 | `tests/foo/bar.test.ts` | ⬚ |
+| FR-2 | Input validation | P2-T2 | `tests/foo/baz.test.ts` | ⬚ |
 
-Every requirement from BA's Requirements Document MUST appear in this matrix. Missing requirement = incomplete phase. `completion-gate` checks this matrix during verification.
+Every requirement from BA's Requirements Document MUST appear in this matrix, using BA's own IDs (`FR-n`/`US-n` — REQ-n only when no BA spec exists). Missing requirement = incomplete phase. `completion-gate` checks this matrix during verification.
 
 ## Files Touched
 - `src/foo/bar.ts` — new

package/skills/plan/references/vertical-slice.md

@@ -10,6 +10,7 @@
 2. **Demoable on its own** — when the slice is merged, you can demo it (or run a single command to verify). If demoing requires "and now switch to the other PR", the slices were drawn wrong.
 3. **Narrow but complete** — one user story, one happy path, minimal error handling. Edge cases are *separate slices*, not bigger versions of the same slice.
 4. **Independently grabbable** — any developer or agent should be able to pick up Slice N without reading Slice N+1. Dependencies declared explicitly, not implicit.
+5. **Layer order WITHIN the slice: Data → Logic → Endpoint/Service → UI → Integration.** UI is structurally last. The button and the endpoint it calls are ONE slice's tasks — a slice whose UI task has no upstream endpoint task (and consumes no prior slice's contract) ships a dead button. If the slice has a contract file (`references/boundary-artifacts.md`), the contract test task precedes the implementation task.
 
 ## Slice types
 
@@ -25,13 +26,14 @@
 ```markdown
 ### Slice: [verb-led title]
 - **Type**: AFK | HITL
-- **Story**: As a [persona], I want to [action] so that [benefit]
-- **Path through layers**:
+- **Story**: US-n — As a [persona], I want to [action] so that [benefit]
+- **Path through layers** (this is also the BUILD ORDER — top to bottom):
   - Schema: [migration / type addition]
-  - API: [endpoint or function signature]
-  - UI: [component or surface]
-  - Test: [verification approach]
-- **Demoable**: [exact command or click-path that shows it works]
+  - Logic: [business rule / validation]
+  - API: [endpoint or function signature — cite `contracts/<file>.md` if one exists]
+  - UI: [component or surface — names the API line above as its call target]
+  - Test: [verification approach — must cross UI→API, not mock the whole chain]
+- **Demoable**: [exact command or click-path that shows it works — reuse the story's Independent Test]
 - **Blocked by**: [slice IDs] | None — can start immediately
 - **Out of scope** (explicit): [what this slice does NOT cover]
 ```

package/skills/preflight/SKILL.md

@@ -3,7 +3,7 @@ name: preflight
 description: "Pre-commit quality gate that catches 'almost right' code. Use when about to commit — auto-fires before commit to validate logic correctness, error handling, regressions, and completeness. Goes beyond linting."
 metadata:
   author: runedev
-  version: "1.1.0"
+  version: "1.2.0"
   layer: L2
   model: sonnet
   group: quality
@@ -150,6 +150,7 @@ Verify that new code ships complete:
 - New feature → has at least one test file
 - New configuration option → has documentation (inline comment or docs file)
 - New database query → has corresponding migration file if schema changed
+- **Cross-layer pairing**: new interactive component (button/form/action) → its handler chain reaches a REAL endpoint/service that exists in the codebase — OR the plan explicitly scopes it UI-only with a mock (stated, not assumed). Unexcused missing pair = **BLOCK**, not WARN: a dead interactive element is incomplete work presented as complete. (Mirror check: new endpoint this diff → ≥1 consumer or a NAMED future task consuming it)
 
 **Framework-specific completeness (apply only if detected):**
 - React component with async data → must have `loading` state AND `error` state
@@ -238,6 +239,7 @@ When UI/Frontend hook is triggered, run these checks on all `.tsx`/`.jsx`/`.svel
 | **Scale Minimum — hero display** | `<h1>` with `text-3xl` or smaller (30px) when the heading is in a hero/landing section | WARN: "Hero heading below 48px at {file}:{line} — insufficient visual hierarchy" |
 | **Hand-rolled SVG for standard icons** | Inline `<svg viewBox=` in JSX when the surrounding comment/class names indicate standard iconography (dashboard, menu, close, chevron, arrow, search, home, user, settings, bell, trash) | WARN: "Hand-rolled SVG at {file}:{line} — use @phosphor-icons/react or huge-icons, or ship boxed placeholder" |
 | **Manual hex accent shading** | CSS/Tailwind config defining 2+ sibling `--accent-hover` / `--accent-pressed` / `--accent-active` with hex literals (no `oklch(from ...)` or design-token chain) | WARN: "Manual hex shade at {file}:{line} — derive via oklch(from var(--accent) calc(l - 0.08) c h)" |
+| **Dead interactive element** | `<button>`/`<form>`/action element with no bound handler (any framework syntax: `onClick=`, `on:click=`, `@click`, `v-on:`), `onClick={() => {}}`, `href="#"` on an action link (not navigation/scroll anchors), or `preventDefault()`-only submit — in files of THIS diff (skip elements listed in `.rune/ui-spec.md` `## Unwired Elements`; prop-origin handlers like `onClick={props.onSave}` count as bound) | BLOCK: "Dead interactive at {file}:{line} — element renders but does nothing" |
 | **Missing states** | Components fetching data without loading/error/empty states | WARN: "Async component at {file} missing [loading|error|empty] state" |
 | **Icon accessibility** | Decorative icons without `aria-hidden="true"`, functional icons without `aria-label` | WARN: "Icon at {file}:{line} missing aria attribute" |
 | **Inline styles** | `style={{` or `style=` attribute usage instead of classes/tokens | WARN: "Inline style at {file}:{line} — use CSS class or Tailwind" |
@@ -336,8 +338,8 @@ Invoke `rune:sentinel` on the changed files. Attach sentinel's output verbatim u
 
 ### Step 6 — Generate Verdict
 Aggregate all findings:
-- Any BLOCK from sentinel OR a logic issue that would cause data corruption or security bypass → overall **BLOCK**
-- Any missing error handling, regression risk with no tests, or incomplete feature → **WARN**
+- Any BLOCK from sentinel OR a logic issue that would cause data corruption or security bypass OR a dead interactive element (Step 4 cross-layer pairing / Step 4.5 dead-interactive check) OR a BLOCK from any domain hook → overall **BLOCK**
+- Any missing error handling, regression risk with no tests, or incomplete feature (other than the BLOCK cases above) → **WARN**
 - Only style or best-practice suggestions → **PASS**
 
 Report PASS, WARN, or BLOCK. For WARN, list each item the developer must acknowledge. For BLOCK, list each item that must be fixed before proceeding.
@@ -410,6 +412,8 @@ WARN — 3 issues found (0 blocking, 3 must-acknowledge). Resolve before commit
 | Domain hooks not triggered when pack is installed | HIGH | Step 4.5 auto-detects file patterns — if pack is installed but hooks don't fire, check file pattern matching |
 | Domain hooks overriding generic checks | HIGH | HARD-GATE: domain hooks are ADDITIVE — they never replace Steps 1-4 |
 | Pack Hard-Stop Thresholds ignored in preflight | MEDIUM | Step 4.5 Pack Integration must read installed pack thresholds — test with each new pack |
+| Dead interactive element downgraded to WARN ("just a loading-state issue") | CRITICAL | Step 4 cross-layer pairing + Step 4.5 dead-interactive check are BLOCK — a button wired to nothing is incomplete work, not a style nit |
+| Flagging design's declared placeholders as dead interactives | MEDIUM | Elements listed in `.rune/ui-spec.md` `## Unwired Elements` are design debt tracked by converge — skip, don't BLOCK |
 
 ## Done When
 
@@ -417,6 +421,8 @@ WARN — 3 issues found (0 blocking, 3 must-acknowledge). Resolve before commit
 - Error handling verified on all async functions and HTTP calls
 - Regression impact assessed — dependent files identified via scout
 - Completeness checklist passed (validation schema, loading/error states, test file)
+- Cross-layer pairing checked (Step 4): every new interactive component's handler chain reaches a real endpoint/service or has an explicit UI-only scope
+- Dead-interactive scan done (Step 4.5 UI hook) on all UI files in the diff
 - Sentinel invoked and its output attached in Security section
 - Structured report emitted with PASS / WARN / BLOCK verdict and file:line for every finding
 

package/skills/skill-router/SKILL.md

@@ -177,6 +177,7 @@ For users who know exactly what they want:
 | Fix bug / debug only (no fix) | `rune:debug` → `rune:fix` | L2 chain |
 | Marketing assets only | `rune:marketing` | L2 |
 | Gather requirements / BA / elicit needs | `rune:ba` | L2 — requires opus |
+| "Did it fully implement?" / "does code match spec?" / check completeness | `rune:converge` | L3 — needs requirements.md |
 | Generate / update docs | `rune:docs` | L2 |
 | Build MCP server | `rune:mcp-builder` | L2 |
 | Red-team / challenge a plan / stress-test | `rune:adversary` | L2 — requires opus |
@@ -193,6 +194,7 @@ These are rarely invoked directly — they're called by Tier 1/2 skills:
 | `rune:verification` | cook, fix | Run lint/test/build |
 | `rune:hallucination-guard` | cook, fix | Verify imports |
 | `rune:completion-gate` | cook | Validate claims |
+| `rune:converge` | cook | Spec↔code gap scan (Phase 6.5) |
 | `rune:sentinel-env` | cook, scaffold, onboard | Environment pre-flight |
 | `rune:research` / `rune:docs-seeker` | any | Look up docs |
 | `rune:session-bridge` | cook, team | Save context (in-session state handoff) |