@rune-kit/rune 2.2.6 → 2.3.0

package/skills/plan/references/completeness-scoring.md

@@ -0,0 +1,37 @@
+# Completeness Scoring
+
+> Reference for `plan` skill — Step 5.5.
+> Load this when presenting alternative approaches from brainstorm or Step 3 decisions.
+
+## Scoring Table
+
+When presenting alternatives, rate each with **Completeness X/10**:
+
+| Score | Meaning |
+|-------|---------|
+| 9-10 | Complete — all edge cases, full coverage, production-ready |
+| 7-8 | Happy path covered, some edges skipped |
+| 4-6 | Shortcut — defers significant work |
+| 1-3 | Minimal viable, debt guaranteed |
+
+## Rules
+
+- **Always recommend the higher-completeness option.** With AI-assisted coding, the marginal cost of completeness is near-zero.
+- Show **dual effort estimates** for each approach: `(human: ~X / AI: ~Y)`
+- **Anti-pattern**: "Option B saves 70 LOC" → 70 LOC delta is meaningless with AI. Choose complete. The last 10% of coverage is where production bugs hide.
+
+> Source: garrytan/gstack v0.9.0 — "Boil the Lake" principle.
+
+## Example Format
+
+```
+**Option A: Full validation with Zod** — Completeness 9/10
+- Covers: schema validation, error messages, type inference
+- human: ~2h / AI: ~15min
+- Recommended ✅
+
+**Option B: Manual checks** — Completeness 5/10
+- Covers: happy path only, defers edge cases
+- human: ~30min / AI: ~5min
+- Not recommended — defers 40% of error handling
+```

package/skills/plan/references/outcome-block.md

@@ -0,0 +1,41 @@
+# Outcome Block Format
+
+> Reference for `plan` skill — mandatory output section for all plan outputs.
+> Load this when writing the final section of any master plan, phase file, or inline plan.
+
+## Format
+
+Every plan output MUST end with an **Outcome Block**:
+
+```markdown
+## Outcome Block
+
+### What Was Planned
+<1-2 sentences: what this plan delivers when all phases execute successfully>
+
+### Immediate Next Action
+<The SINGLE next action the executor should take right now — not a list, one action>
+Example: "Load phase 1 file and execute Wave 1 tasks (create types, validation schema)"
+
+### How to Measure Success
+| Metric | Target | How to Check |
+|--------|--------|-------------|
+| Tests pass | 100% green | `npm test` or `pytest -v` |
+| Type errors | 0 | `tsc --noEmit` or `mypy` |
+| Phase complete | All tasks ✅ | phase file task list |
+| <domain metric> | <value> | <command> |
+```
+
+## Rules
+
+1. Outcome Block is the LAST section in every plan output (master plan, phase file, inline plan)
+2. "Immediate Next Action" = ONE action, present tense, imperative mood. Not a list.
+3. "How to Measure" table MUST include at least one verifiable shell command
+4. For phase files: Immediate Next Action = "Execute Wave 1: [list Wave 1 task names]"
+5. For master plans: Immediate Next Action = "Await approval, then load phase 1 file"
+
+## Why This Matters
+
+Plans without a clear "what to do NOW" cause executor drift — agents re-read the plan, re-analyze, and pick arbitrary starting points. The Immediate Next Action eliminates ambiguity: there is exactly ONE right first move.
+
+> Source: Affitor/affiliate-skills — every output ends with: outcome achieved + immediate next action + measurement metric ("What happened → What to do now → How to measure").

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

@@ -0,0 +1,193 @@
+# Plan Templates
+
+> Reference for `plan` skill — Steps 4 and 5.
+> Load this when writing master plan files or phase files.
+
+## Master Plan Template
+
+Save to `.rune/plan-<feature>.md`. Max 80 lines.
+
+```markdown
+# Feature: <name>
+
+## Overview
+<1-3 sentences: what and why>
+
+## Phases
+| # | Name | Status | Plan File | Summary |
+|---|------|--------|-----------|---------|
+| 1 | Foundation | ⬚ Pending | plan-X-phase1.md | Types, core engine, basic UI |
+| 2 | Interaction | ⬚ Pending | plan-X-phase2.md | Dialogue, combat, items |
+| 3 | Polish | ⬚ Pending | plan-X-phase3.md | Effects, sounds, game over |
+
+## Key Decisions
+- <decision 1 — chosen approach and why>
+- <decision 2>
+
+## Decision Compliance
+- Decisions (locked): [list from requirements.md — plan MUST honor these]
+- Discretion (agent): [list — agent chose X because Y]
+- Deferred: [list — explicitly excluded from this feature]
+
+## Architecture
+<brief system diagram or component list — NOT implementation detail>
+
+## Dependencies
+- <external dep>: <status>
+
+## Risks
+- <risk>: <mitigation>
+```
+
+No implementation details — that's what phase files are for.
+
+---
+
+## Phase File Template (Amateur-Proof)
+
+Save to `.rune/plan-<feature>-phase<N>.md`. Max 200 lines.
+
+Phase files follow the **Amateur-Proof Template** — designed so that even the weakest model (Haiku) can execute without guessing. Every section exists because an Amateur said "I need this to code correctly."
+
+```markdown
+# Phase N: <name>
+
+## Goal
+<What this phase delivers — 1-2 sentences>
+
+## Data Flow
+<5-line ASCII diagram showing how data moves through this phase's components>
+```
+User Input → validateInput() → calculateProfit() → formatResult() → API Response
+                                      ↓
+                                 TradeEntry[]
+```
+
+## Code Contracts
+<Function signatures, interfaces, schemas that this phase MUST implement>
+<This is the MOST IMPORTANT section — coder implements these contracts>
+
+```typescript
+interface TradeEntry {
+  side: 'long' | 'short';
+  entryPrice: number;
+  exitPrice: number;
+  quantity: number;
+}
+
+interface ProfitResult {
+  netPnL: number;
+  totalFees: number;
+  winRate: number;
+}
+
+function calculateProfit(entries: TradeEntry[]): ProfitResult;
+function validateInput(raw: unknown): TradeEntry[];  // throws ValidationError
+```
+
+## Tasks
+
+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)
+  - 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)
+  - 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)
+  - File: `tests/foo/bar.test.ts` (modify)
+  - Test: N/A — this IS the test task
+  - Verify: `npm test -- --grep "trading" && npx tsc --noEmit`
+  - Commit: `test(trading): add integration tests for edge cases`
+  - Cases: happy path, empty input, negative values, overflow
+
+## Failure Scenarios
+<What should happen when things go wrong — coder MUST implement these>
+
+| When | Then | Error Type |
+|------|------|-----------|
+| entries is empty array | return zero-value ProfitResult | No error (valid edge case) |
+| entry has negative price | throw ValidationError("price must be positive") | ValidationError |
+| entry has quantity = 0 | throw ValidationError("quantity must be > 0") | ValidationError |
+| calculation overflows Number.MAX_SAFE_INTEGER | use BigInt or throw OverflowError | OverflowError |
+
+## Performance Constraints
+<Non-functional requirements — skip if not applicable>
+
+| Metric | Requirement | Why |
+|--------|-------------|-----|
+| Input size | Must handle 10,000 entries | Production data volume |
+| Response time | < 100ms for 10K entries | Real-time dashboard |
+| Memory | < 50MB for 10K entries | Container memory limit |
+
+## Rejection Criteria (DO NOT)
+<Anti-patterns the coder MUST avoid — things that seem right but are wrong>
+
+- ❌ DO NOT use `toFixed()` for financial calculations — use Decimal.js or integer cents
+- ❌ DO NOT mutate the input array — create new objects (immutability rule)
+- ❌ DO NOT use `any` type — full TypeScript strict
+- ❌ DO NOT import from Phase 2+ files — this phase is self-contained
+
+## Cross-Phase Context
+<What this phase assumes from previous phases / what future phases expect from this one>
+
+- **Assumes**: Phase 1 created `src/shared/types.ts` with base types
+- **Exports for Phase 3**: `calculateProfit()` will be imported by `src/dashboard/PnLCard.tsx`
+- **Interface contract**: ProfitResult shape MUST NOT change — Phase 3 depends on it
+
+## Acceptance Criteria
+- [ ] All tasks marked done
+- [ ] Tests pass with 80%+ coverage on new code
+- [ ] No TypeScript errors (`tsc --noEmit` passes)
+- [ ] Failure scenarios all handled (table above)
+- [ ] Performance: calculateProfit(10K entries) < 100ms
+- [ ] No `any` types, no mutation, no `toFixed()` for money
+
+## 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` | ⬚ |
+
+Every requirement from BA's Requirements Document MUST appear in this matrix. Missing requirement = incomplete phase. `completion-gate` checks this matrix during verification.
+
+## Files Touched
+- `src/foo/bar.ts` — new
+- `src/foo/baz.ts` — modify
+- `tests/foo/bar.test.ts` — new
+```
+
+Must be self-contained — coder should NOT need to read master plan or other phases to execute.
+
+---
+
+## Inline Plan Template (Trivial Tasks)
+
+For trivial tasks (1-2 phases, < 5 files, < 100 LOC):
+
+```
+## Plan: [Task Name]
+
+### Changes
+1. [file]: [what to change] — [function signature]
+2. [file]: [what to change]
+
+### Tests
+- [test file]: [test cases]
+
+### Risks
+- [risk]: [mitigation]
+
+Awaiting approval.
+```

package/skills/plan/references/wave-planning.md

@@ -0,0 +1,44 @@
+# Wave-Based Task Grouping
+
+> Reference for `plan` skill — Step 3 (Decompose into Phases).
+> Load this when writing wave-structured task lists inside a phase.
+
+## Wave Format
+
+Tasks inside a phase MUST be organized into **waves** based on dependency analysis. Independent tasks within the same wave can execute in parallel.
+
+```
+## Tasks
+
+### Wave 1 (parallel — no dependencies)
+- [ ] Task 1 — Create types/interfaces
+  - File: `src/types.ts` (new)
+  - ...
+- [ ] Task 2 — Create validation schema
+  - File: `src/validation.ts` (new)
+  - ...
+
+### Wave 2 (depends on Wave 1)
+- [ ] Task 3 — Implement core logic (imports types from Task 1)
+  - File: `src/core.ts` (new)
+  - depends_on: [Task 1]
+  - ...
+
+### Wave 3 (depends on Wave 2)
+- [ ] Task 4 — Wire into API endpoint (imports core from Task 3)
+  - File: `src/routes/api.ts` (modify)
+  - depends_on: [Task 3]
+  - ...
+- [ ] Task 5 — Write integration tests (tests core from Task 3)
+  - File: `tests/core.test.ts` (new)
+  - depends_on: [Task 3]
+  - ...
+```
+
+## Wave Rules
+
+- **Wave 1** = tasks with zero dependencies (types, schemas, configs) — always first
+- **Subsequent waves**: a task goes in the earliest wave where ALL its `depends_on` tasks are in prior waves
+- Tasks within the same wave have NO dependencies on each other → safe for parallel dispatch
+- `depends_on` field is MANDATORY for Wave 2+ tasks — explicit is better than implicit
+- `team` orchestrator can dispatch wave tasks as parallel subagents; solo `cook` executes sequentially within a wave but respects wave ordering

package/skills/plan/references/workflow-registry.md

@@ -0,0 +1,53 @@
+# Workflow Registry (4-View)
+
+> Reference for `plan` skill — Step 4.5.
+> Load this when building a Workflow Registry for complex features (4+ phases OR 3+ user-facing workflows).
+
+## When to Use
+
+Build this registry BEFORE writing phase files for complex features. It catches missing pieces, dead ends, and integration gaps at plan time — not implementation time.
+
+**Skip conditions**: trivial tasks, inline plans, single-workflow features.
+
+> Source: agency-agents (msitarzewski/agency-agents, 50.8k★): "Every route is an entry point. Every worker is a workflow. If it's missing from the registry, it doesn't exist."
+
+## 4-View Format
+
+```markdown
+## Workflow Registry
+
+### View 1: By Workflow
+| Workflow | Entry Point | Components Touched | Exit Point | Phase |
+|----------|-------------|-------------------|------------|-------|
+| User signup | POST /auth/register | AuthService, UserRepo, EmailService | 201 + email sent | Phase 1 |
+| Password reset | POST /auth/reset | AuthService, EmailService, TokenRepo | 200 + reset email | Phase 2 |
+
+### View 2: By Component
+| Component | Used By Workflows | Owner Phase | Status |
+|-----------|-------------------|-------------|--------|
+| AuthService | signup, login, reset | Phase 1 | Planned |
+| EmailService | signup, reset, invite | Phase 2 | Planned |
+| TokenRepo | reset, invite | Phase 2 | Missing ← RED FLAG |
+
+### View 3: By User Journey
+| Journey | Steps (workflow chain) | Happy Path | Error Path |
+|---------|----------------------|------------|------------|
+| New user → first action | signup → verify email → login → onboard | 4 steps | signup fail, email bounce |
+
+### View 4: By State
+| Step | User Sees | DB State | Logs | Operator Sees |
+|------|-----------|----------|------|---------------|
+| After signup | "Check your email" | user.status=pending | user.created event | New user in admin |
+| After verify | Dashboard | user.status=active | user.verified event | Active user count +1 |
+```
+
+## Validation Rules
+
+- Every component in View 2 MUST appear in at least one workflow in View 1 — orphaned components = dead code
+- Every workflow in View 1 MUST map to a phase — unphased workflows will be forgotten
+- **"Missing" status in View 2 = red flag** — component needed but not planned in any phase → add to a phase or create new phase
+- Every user journey step in View 3 MUST have a corresponding state row in View 4
+
+## Output Placement
+
+Add the registry to the master plan file (it fits within the 80-line budget when tables are compact). Phase files reference it but don't duplicate it.

package/skills/preflight/SKILL.md

@@ -3,7 +3,7 @@ name: preflight
 description: Pre-commit quality gate that catches "almost right" code. Goes beyond linting — checks logic correctness, error handling, regressions, and completeness.
 metadata:
   author: runedev
-  version: "0.3.0"
+  version: "0.6.0"
   layer: L2
   model: sonnet
   group: quality
@@ -158,6 +158,41 @@ Verify that new code ships complete:
 
 If any completeness item is missing, flag as **WARN** with: what is missing, which file needs it.
 
+### Step 4.2 — Coherence Check
+
+Verify that new code is **consistent with existing project patterns** — not just correct, but coherent with the codebase it lives in.
+
+| Check | What To Look For | Severity |
+|-------|------------------|----------|
+| Naming conventions | New functions/variables follow project's existing naming style (camelCase, snake_case, etc.) | WARN |
+| File organization | New files placed in correct directory per project structure (e.g., utils/ not lib/, components/ not ui/) | WARN |
+| Import patterns | Uses project's established import style (absolute vs relative, barrel exports vs direct) | WARN |
+| Error handling style | Matches project's existing pattern (Result type, try/catch, error codes) | WARN |
+| State management | Uses same state approach as rest of project (Zustand, context, stores) | BLOCK if different paradigm |
+| API patterns | Follows existing response format, middleware chain, auth pattern | BLOCK if diverges |
+| Design system usage | Uses existing design tokens/components, not inline overrides | WARN |
+
+**Detection**: Read 2-3 existing files in the same directory as the change. Compare patterns. Flag divergences.
+
+**Skip if**: Project has no established patterns (greenfield, <5 files), or CLAUDE.md/conventions.md explicitly says "no conventions yet."
+
+> Source: Fission-AI/OpenSpec (32.8k★) — Coherence axis: "follows design.md? matches project patterns?"
+
+### Step 4.3 — Eval Verification
+
+If `.rune/evals/` directory exists with eval definition files, verify eval results as part of the quality gate.
+
+| Check | Action | Severity |
+|-------|--------|----------|
+| Capability eval defined but not run | Feature has `.rune/evals/<feature>.md` with CAP-* entries but no results | WARN: "Capability evals defined but not executed" |
+| Regression eval failing | Any REG-* eval with status=fail | BLOCK: "Regression detected — existing behavior broken" |
+| Capability eval below threshold | CAP-* eval pass@k below defined threshold | WARN: "Capability eval below threshold (X% vs Y% required)" |
+| No eval file for new feature | New feature added (detected by new test files + new source files) but no `.rune/evals/` entry | INFO: "Consider defining capability evals for new feature" |
+
+**Skip if**: No `.rune/evals/` directory exists (project hasn't adopted eval-driven development).
+
+> Source: affaan-m/everything-claude-code (91.9k★) — eval-driven development as quality gate.
+
 ### Step 4.5 — Domain Quality Hooks
 
 Apply domain-specific quality checks based on detected file types in the diff. These extend the generic completeness checks in Step 4 with deeper domain validation.
@@ -204,6 +239,38 @@ When a domain pack is installed (e.g., `@rune-pro/finance`, `@rune-pro/legal`),
 - `src/billing/invoice.ts:42` — WARN: price calculation uses `toFixed(2)` instead of `Intl.NumberFormat`
 ```
 
+### Step 4.8 — Preflight Composite Score
+
+After all domain hooks (Step 4.5) and completeness checks (Step 4) complete, compute a **Preflight Health Score** to make the verdict numeric and comparable across runs.
+
+### Formula
+
+```
+Preflight Score = (Logic × 0.30) + (Error Handling × 0.20) + (Completeness × 0.20) + (Coherence × 0.15) + (Regression Risk × 0.15)
+```
+
+**5 verification axes** (Completeness + Correctness via Logic + Coherence — 3D verification model):
+
+Each dimension is scored per staged files:
+- 0 BLOCK findings in dimension → 100
+- 1 BLOCK → dimension capped at 30
+- 1 WARN → dimension capped at 75
+- Each additional WARN → subtract 10 (floor: 40)
+
+### Grade Thresholds
+
+| Score | Grade | Verdict |
+|-------|-------|---------|
+| 90–100 | Excellent | PASS |
+| 75–89 | Good | PASS with notes |
+| 60–74 | Fair | WARN |
+| 40–59 | Poor | WARN (escalate to developer) |
+| 0–39 | Critical | BLOCK |
+
+Score is appended to the Preflight Report footer. Useful for tracking quality trend across sprints when cook logs preflight scores to `.rune/metrics/`.
+
+> Source: zubair-trabzada/geo-seo-claude (2.7k★) — weighted formula, 5-tier thresholds, comparable across runs.
+
 ### Step 5 — Security Sub-Check
 Invoke `rune:sentinel` on the changed files. Attach sentinel's output verbatim under the "Security" section of the preflight report. If sentinel returns BLOCK, preflight verdict is also BLOCK.
 
@@ -237,9 +304,17 @@ Report PASS, WARN, or BLOCK. For WARN, list each item the developer must acknowl
 - `api/users.ts` — new POST endpoint missing input validation schema
 - `components/Form.tsx` — no loading state during submission
 
+### Coherence
+- `api/users.ts` — uses `res.json()` but project convention is `sendResponse()` wrapper
+- `utils/newHelper.ts` — placed in utils/ but project uses helpers/ directory
+
 ### Security (from sentinel)
 - [sentinel findings if any]
 
+### Composite Score
+- Logic: [score] | Error: [score] | Completeness: [score] | Coherence: [score] | Regression: [score]
+- **Preflight Score**: [weighted value] → Grade: [Excellent/Good/Fair/Poor/Critical]
+
 ### Verdict
 WARN — 3 issues found (0 blocking, 3 must-acknowledge). Resolve before commit or explicitly acknowledge each WARN.
 ```
@@ -252,6 +327,16 @@ WARN — 3 issues found (0 blocking, 3 must-acknowledge). Resolve before commit
 4. MUST verify error messages are user-friendly and don't leak internal details
 5. MUST check that async operations have proper error handling and cleanup
 
+## Returns
+
+| Artifact | Format | Location |
+|----------|--------|----------|
+| Preflight report | Markdown | inline (chat output) |
+| Issue list (BLOCK/WARN by category) | Markdown list | inline |
+| Preflight health score | Markdown table | inline (footer of report) |
+| Spec compliance verdict | Markdown table | inline |
+| Domain quality findings | Markdown section | inline |
+
 ## Sharp Edges
 
 | Failure Mode | Severity | Mitigation |

package/skills/rescue/SKILL.md

@@ -413,6 +413,16 @@ Rollback point: git tag rune-rescue-baseline (set in Phase 0)
 - **Rollback Tag**: [git tag name]
 ```
 
+## Returns
+
+| Artifact | Format | Location |
+|----------|--------|----------|
+| Rescue state | Markdown | `RESCUE-STATE.md` (updated each session) |
+| Characterization tests | Source files | Written by `rune:safeguard` per module |
+| Refactored modules | Source files | Modified in-place, committed per surgery session |
+| Health score comparison | Inline (Rescue Report) | Baseline vs final autopsy scores |
+| Rescue Report | Markdown (inline) | Emitted at session end (per module and final) |
+
 ## Sharp Edges
 
 Known failure modes for this skill. Check these before declaring done.

package/skills/retro/SKILL.md

@@ -309,6 +309,17 @@ SELF-VALIDATION (run before emitting report):
 - Narrative report emitted
 - No code was modified
 
+## Returns
+
+| Artifact | Format | Location |
+|----------|--------|----------|
+| Retrospective narrative report | Markdown (~800-1500 words) | inline |
+| Retro JSON snapshot | JSON | `.rune/retros/{YYYY-MM-DD}.json` |
+| Per-person breakdown | Markdown sections | inline |
+| Action items + habits | Ordered lists | inline |
+
 ## Cost Profile
 
 ~3000-5000 tokens input (git history parsing), ~2000-4000 tokens output (narrative). Sonnet for analysis quality. Runs infrequently (weekly/sprint cadence).
+
+**Scope guardrail:** retro is read-only — it analyzes and reports. It does NOT modify code, create PRs, or change any files except its own output artifacts in `.rune/retros/`.