@rune-kit/rune 2.18.1 → 2.21.0

package/skills/graft/SKILL.md

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

package/skills/onboard/SKILL.md

@@ -306,6 +306,49 @@ Suggest switching to interview mode (but don't force it) when:
 
 Output: `"ℹ️ This project is hard to auto-detect. Run /rune onboard --interview for guided setup."`
 
+### Step 6f — Emit comprehension.json
+
+Write `.rune/comprehension.json` conforming to `compiler/schemas/comprehension.schema.json`.
+This is ADDITIVE — do not touch any of the Markdown files created above.
+
+Populate from the scan data already collected in Steps 2–3:
+
+```json
+{
+  "project": "<project name from Step 2>",
+  "generated_at": "<ISO 8601 timestamp>",
+  "source": "onboard",
+  "health_score": null,
+  "layers": [
+    { "id": "api", "name": "API / Routes", "color": "service" },
+    { "id": "service", "name": "Business Logic", "color": "service" },
+    { "id": "data", "name": "Data / Storage", "color": "data" },
+    { "id": "ui", "name": "UI / Views", "color": "code" },
+    { "id": "util", "name": "Utilities", "color": "code" }
+  ],
+  "domains": [],
+  "modules": [
+    {
+      "id": "<relative file path or module id>",
+      "name": "<file or module name>",
+      "layer": "<id from layers — best-guess from file path>",
+      "type": "file",
+      "complexity": "simple",
+      "files": 1,
+      "summary": "<one-line description>"
+    }
+  ],
+  "edges": []
+}
+```
+
+Rules:
+- `modules[]` — include only the entry points and config files read in Steps 1–3 (5–15 items max). Do not enumerate all project files.
+- `layers[]` — include only layers actually detected; omit unused ones.
+- `edges[]` — leave empty; onboard does not trace cross-file dependencies.
+- `health_score` — set to null; health scoring requires autopsy.
+- If `.rune/comprehension.json` already exists, overwrite it (generated output, not human-written).
+
 ### Step 7 — Commit
 Use `Bash` to stage and commit the generated files:
 ```bash
@@ -413,6 +456,7 @@ Known failure modes for this skill. Check these before declaring done.
 - .rune/ directory initialized with conventions, decisions, progress, session-log, instincts
 - .rune/DEVELOPER-GUIDE.md written with setup commands from actual scan
 - All generated commands verified to exist in package.json/Makefile/etc.
+- .rune/comprehension.json written conforming to comprehension.schema.json (project, generated_at, source:"onboard", modules[], edges[])
 - Onboard Report emitted with Generated + Skipped + Observations sections
 
 ## Returns
@@ -424,6 +468,7 @@ Known failure modes for this skill. Check these before declaring done.
 | Decision log (initialized) | Markdown | `.rune/decisions.md` |
 | Developer onboarding guide | Markdown | `.rune/DEVELOPER-GUIDE.md` |
 | Session/progress files | Markdown | `.rune/progress.md`, `.rune/session-log.md` |
+| Comprehension graph | JSON | `.rune/comprehension.json` |
 
 ## Cost Profile
 

package/skills/perf/SKILL.md

@@ -3,7 +3,7 @@ name: perf
 description: "Performance regression gate. Detects N+1 queries, sync-in-async, missing indexes, memory leaks, and bundle bloat before they reach production. Ranks findings by Cost Impact Hierarchy (architecture > data transfer > compute > DB > caching) so fix priority maps to actual unit-cost reduction."
 metadata:
   author: runedev
-  version: "0.4.0"
+  version: "0.5.0"
   layer: L2
   model: sonnet
   group: quality
@@ -43,6 +43,9 @@ Performance regression gate. Analyzes code changes for patterns that cause measu
 
 - `references/cost-reference.md` — Cost priority hierarchy, quick wins checklist, instance right-sizing, data transfer traps, serverless optimization, observability cost control, managed vs self-hosted matrix, unit economics tracking. Load when cost analysis or FinOps context detected.
 - `references/scalability-reference.md` — Bottleneck identification flow, performance thresholds, API patterns (cursor pagination, rate limiting, circuit breaker, graceful shutdown), caching strategies, queue-based load leveling, concurrency patterns, K8s HPA, CDN headers, load testing. Load when scaling or infrastructure optimization context detected.
+- `../deploy/references/observability.md` — Instrumentation discipline (RED/USE metrics, percentiles-not-averages, cardinality bounds, structured logs, correlation IDs). Load when establishing the *measurement basis* for an optimization — you cannot optimize what you do not measure.
+
+**Measure before optimizing.** A perf finding without a metric behind it is a guess. Before recommending a fix, confirm the hotpath actually emits the signal that proves it is slow: RED latency as a **histogram** (read p95/p99 — averages hide the slow tail), bounded label cardinality, and a correlation ID to tie a slow trace to its logs. If the instrumentation does not exist yet, that absence is itself a finding (`UNMEASURED_HOTPATH`). See `../deploy/references/observability.md` for the instrumentation contract.
 
 ## Executable Steps
 

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