@rune-kit/rune 2.2.4 → 2.3.0

package/skills/skill-router/SKILL.md

@@ -4,7 +4,7 @@ description: "Meta-enforcement layer that routes EVERY agent action through the
 user-invocable: false
 metadata:
   author: runedev
-  version: "1.2.0"
+  version: "1.3.0"
   layer: L0
   model: haiku
   group: orchestrator
@@ -64,6 +64,17 @@ Before standard routing, check if adaptive routing rules exist:
 - Model hints are written by cook Phase 8 when debug-fix loops hit max retries on the same error pattern
 - Model hints do NOT override explicit user model preferences
 
+### Context Efficiency (Trigger-Table Pattern)
+
+Skill-router's routing table above IS the trigger table — it maps keywords to skill paths without loading any skill content. Skills are loaded on-demand via the Skill tool only when routed. This keeps baseline context usage minimal.
+
+**Rules for context efficiency:**
+- NEVER read a SKILL.md to decide routing — use the routing table keywords
+- NEVER load multiple skills speculatively — route to ONE, let it chain if needed
+- Skill content is loaded by the Skill tool, not by skill-router reading files
+
+> Source: affaan-m/everything-claude-code (91.9k★) — trigger-table lazy loading for 50%+ context reduction.
+
 ### Step 0.25 — Request Classifier (Fast-Path Filter)
 
 Before intent classification, categorize the request into one of 5 types. This determines the **enforcement level** — how strictly routing must be followed.
@@ -284,6 +295,27 @@ These DO NOT need skill routing:
 - Single-line factual answers with no code impact
 - Resuming an already-active skill workflow
 
+## Proactive Skill Recommendations (One-Hop Max)
+
+At the end of a skill's workflow, skill-router MAY suggest a **complementary skill** — limited to ONE recommendation to prevent infinite referral chains.
+
+| After This Skill | Suggest | Rationale |
+|-----------------|---------|-----------|
+| `debug` | `review` | Root cause found — review the fix area for broader issues |
+| `fix` | `test` | Code changed — verify with tests |
+| `plan` | `adversary` | Plan created — stress-test before implementation |
+| `test` (GREEN) | `preflight` | Tests pass — check for edge cases and completeness |
+| `review` (issues found) | `fix` | Issues identified — apply fixes |
+| `sentinel` (findings) | `fix` | Security issues — remediate |
+
+**Rules:**
+- Hard limit: 1 hop. NEVER chain recommendations (fix→test→preflight→...). Suggest ONE, let the user decide.
+- Announcement format: "Suggested next: `rune:<skill>` — [1-line reason]. Run it? (skip to continue)"
+- User can disable with "no suggestions" or "just do what I asked"
+- Inside `cook` orchestration: skip recommendations — cook already manages transitions
+
+> Source: garrytan/gstack v0.9.1 (50.9k★) — one-hop skill chaining with proactive: false escape hatch.
+
 ## Output Format
 
 ### Routing Proof (Required in Every Code Response)

package/skills/surgeon/SKILL.md

@@ -198,6 +198,18 @@ Known failure modes for this skill. Check these before declaring done.
 - Surgery committed with message format `refactor(<module>): <pattern> — <description>`
 - journal updated with module health delta and remaining work
 
+## Returns
+
+| Artifact | Format | Location |
+|----------|--------|----------|
+| Refactored module | Edited source files (max 5) | in-place |
+| Before/after diff | Git diff | via `git diff` |
+| Surgery Report | Markdown | inline |
+| Git commit(s) | Conventional commits | git history |
+| Journal entry | Text | via `journal` L3 |
+
 ## Cost Profile
 
 ~3000-6000 tokens input, ~1000-2000 tokens output. Sonnet. One module per session.
+
+**Scope guardrail:** surgeon operates on ONE module per session (max 5 files). Any work beyond that scope must be deferred to a separate surgeon session.

package/skills/team/SKILL.md

@@ -5,7 +5,7 @@ context: fork
 agent: general-purpose
 metadata:
   author: runedev
-  version: "0.5.0"
+  version: "0.6.0"
   layer: L1
   model: opus
   group: orchestrator
@@ -66,6 +66,28 @@ Lite Mode Phases:
 
 Standard team workflow with worktree isolation (Phases 1-5 as documented below).
 
+### Complexity Tiers (DAG Stage Selection)
+
+Before decomposing, classify the task into a complexity tier. Each tier defines a different DAG (directed acyclic graph) of stages, ensuring the right amount of process for the task's complexity.
+
+| Tier | Signals | DAG Stages | Context Windows |
+|------|---------|------------|-----------------|
+| **Trivial** | ≤3 files, single module, no shared contracts | impl → test | 1 (single cook) |
+| **Medium** | 4-10 files, 2-3 modules, shared interfaces | research → plan → impl → test → review → fix | 3 (plan, impl+test, review+fix) |
+| **Large** | 10+ files, 3+ modules, breaking changes or RFC | research → plan → impl → test → review₁ → fix → review₂ → final merge | 4+ (plan, impl+test, review₁+fix, review₂+merge) |
+
+**Key principle — reviewer isolation**: The agent that writes code MUST NOT review its own code. Each review stage uses a **separate context window** (separate Task invocation) that has never seen the implementation reasoning. This prevents author bias from contaminating the review.
+
+**Stage → Context Window mapping**:
+- `research + plan` = Context Window 1 (opus — architectural reasoning)
+- `impl + test` = Context Window 2 (sonnet — code writing)
+- `review₁ + fix` = Context Window 3 (sonnet — fresh eyes, no impl context)
+- `review₂ + merge` = Context Window 4 (sonnet — final verification, Large tier only)
+
+**Merge queue**: When multiple streams complete at different times, use dependency order for merging. If a later stream's merge creates conflicts with an already-merged stream, provide the conflicting stream's cook report as **conflict context** to the resolution agent — never resolve blindly.
+
+> Source: affaan-m/everything-claude-code (91.9k★) — RFC-driven DAG orchestration with reviewer isolation.
+
 ## Calls (outbound)
 
 - `plan` (L2): high-level task decomposition into independent workstreams
@@ -433,6 +455,16 @@ Dependent streams    → SEQUENTIAL (respecting dependency order)
 All streams done     → MERGE sequentially (avoid conflicts)
 ```
 
+## Returns
+
+| Artifact | Format | Location |
+|----------|--------|----------|
+| Workstream assignments | Markdown (inline) | NEXUS Handoff Templates emitted per stream |
+| Cook Reports (per stream) | Markdown (inline) | Collected from each parallel cook instance |
+| Merged implementation | Source files | `main` branch after Phase 4 merge |
+| Integration test results | Inline stdout | Captured in Phase 5 verify |
+| Team Report | Markdown (inline) | Emitted at end of session |
+
 ## Sharp Edges
 
 Known failure modes for this skill. Check these before declaring done.
@@ -464,3 +496,5 @@ Known failure modes for this skill. Check these before declaring done.
 ## Cost Profile
 
 ~$0.20-0.50 per session. Opus for coordination. Most expensive orchestrator but handles largest tasks.
+
+**Scope guardrail**: Do not invoke launch, rescue, or scaffold autonomously unless explicitly delegated by the parent agent.

package/skills/test/SKILL.md

@@ -3,7 +3,7 @@ name: test
 description: "TDD test writer. Writes failing tests FIRST (red), then verifies they pass after implementation (green). Covers unit, integration, and e2e tests."
 metadata:
   author: runedev
-  version: "0.5.0"
+  version: "1.1.0"
   layer: L2
   model: sonnet
   group: development
@@ -208,14 +208,14 @@ For non-trivial features (3+ test files or 20+ test cases), create a `TEST.md` i
 - `test_e2e.py`: ~XX E2E tests planned (L3/L4)
 
 ## Unit Test Plan (L1)
-| Module | Functions | Edge Cases | Est. Tests |
-|--------|-----------|------------|------------|
-| `core/auth.py` | login, register, refresh | expired token, invalid creds, rate limit | 12 |
+| Module | Functions | Edge Cases | Est. Tests | Req IDs |
+|--------|-----------|------------|------------|---------|
+| `core/auth.py` | login, register, refresh | expired token, invalid creds, rate limit | 12 | REQ-001, REQ-003 |
 
 ## E2E Scenarios (L3/L4)
-| Workflow | Simulates | Operations | Verified |
-|----------|-----------|------------|----------|
-| User signup | New user onboarding | register → verify → login | Token valid, profile created |
+| Workflow | Simulates | Operations | Verified | Req IDs |
+|----------|-----------|------------|----------|---------|
+| User signup | New user onboarding | register → verify → login | Token valid, profile created | REQ-005 |
 
 ## Realistic Workflow Scenarios
 - **[Name]**: [Step 1] → [Step 2] → verify [output properties]
@@ -230,12 +230,64 @@ For non-trivial features (3+ test files or 20+ test cases), create a `TEST.md` i
 - Total: XX | Passed: XX | Failed: 0
 - Execution time: X.Xs | Coverage: XX%
 
+## Requirement Coverage
+| Req ID | Test File(s) | Status |
+|--------|-------------|--------|
+| REQ-001 | `test_auth.py::test_login` | ✅ Covered |
+| REQ-002 | — | ❌ Not covered |
+
 ## Gaps
 - [Areas not covered and why]
 ```
 
 **Why TEST.md**: Planning tests before code catches missing edge cases early. Appending results creates permanent evidence. One document = complete testing story.
 
+## Skill Behavior Tests (Eval Scenarios)
+
+For testing SKILL.md behavior (not code), use **Eval Scenarios** — unit tests for skill files, not code files.
+
+### Eval Scenario Format
+
+```markdown
+## Eval: E[NN] — [scenario name]
+
+### Prompt
+[The exact situation/message an agent receives]
+
+### Expected Reasoning
+[Step-by-step reasoning the agent SHOULD follow]
+
+### Must Include
+- [Assertion 1: what the output MUST contain or do]
+- [Assertion 2]
+
+### Must NOT
+- [Anti-pattern 1: what the output MUST NOT do]
+- [Anti-pattern 2]
+
+### Category
+happy-path | adversarial | edge-case | jailbreak | credential-leak
+```
+
+### Eval Coverage Requirements
+
+A skill is **behavior-tested** when it has evals covering:
+
+| Category | Min Evals | Purpose |
+|----------|-----------|---------|
+| Happy path | 1 | Core workflow executes correctly |
+| Edge case | 1 | Empty input, missing context, unusual state |
+| Adversarial | 1 | Time pressure, sunk cost, authority pressure |
+| Jailbreak / injection | 1 | Prompt injection attempt, "ignore instructions" |
+
+**Minimum**: 4 evals per skill (1 per category). Security-critical skills (sentinel, safeguard): 8+ evals.
+
+### Eval Storage
+
+Save eval files as `skills/<name>/evals.md`. Each eval is a numbered scenario (E01–E24 range). skill-forge Phase 7 checks for evals presence before ship.
+
+> Source: PhucMPham/zalo-agent-cli (35★) — 24 eval scenario format (E01-E24) with Must Include / Must NOT assertions.
+
 ## Error Recovery
 
 - If test framework not found: ask calling skill to specify, or check `package.json` `devDependencies`
@@ -261,6 +313,25 @@ For non-trivial features (3+ test files or 20+ test cases), create a `TEST.md` i
 - `browser-pilot` (L3): Phase 4 — e2e and visual testing for UI flows
 - `debug` (L2): Phase 5 — when existing test regresses unexpectedly
 
+## Data Flow
+
+### Feeds Into →
+
+- `cook` (L1): test results (pass/fail/coverage) → cook's Phase 5 quality gate evidence
+- `completion-gate` (L3): test runner stdout → evidence for "tests pass" claims
+- `fix` (L2): failing test output → fix's target (what to make green)
+
+### Fed By ←
+
+- `plan` (L2): phase file test tasks → test's RED phase targets (what to test)
+- `review` (L2): untested edge cases found during review → new test targets
+- `fix` (L2): implemented code → test's GREEN phase verification target
+
+### Feedback Loops ↻
+
+- `test` ↔ `fix`: test writes failing tests (RED) → fix implements to pass → test verifies (GREEN) → if new failures emerge, loop continues
+- `test` ↔ `debug`: test discovers regression → debug diagnoses root cause → test writes regression test to prevent recurrence
+
 ## Anti-Rationalization Table
 
 | Excuse | Reality |
@@ -273,6 +344,101 @@ For non-trivial features (3+ test files or 20+ test cases), create a `TEST.md` i
 | "I mentally tested it" | Mental testing is not testing. Run the command, show the output. |
 | "This is different because..." | It's not. Write the test first. |
 
+## Advanced: Oracle-Injection E2E Testing
+
+For **data pipelines, AI workflows, and multi-stage processing** where comparing full output structures is impractical, use oracle injection:
+
+1. **Generate a UUID oracle token**: `const oracle = crypto.randomUUID()`
+2. **Inject into synthetic input**: embed the oracle in realistic test data that flows through the pipeline
+3. **Run the full pipeline**: input → all stages → output
+4. **Search for oracle in output**: if found → data flowed end-to-end correctly
+
+```
+// Example: testing a document processing pipeline
+const oracle = "ORACLE-" + crypto.randomUUID();
+const testDoc = `Meeting notes: discussed ${oracle} integration timeline`;
+const result = await pipeline.process(testDoc);
+assert(result.output.includes(oracle), "Oracle not found — pipeline lost data");
+```
+
+**When to use**: E2E tests for pipelines with 3+ stages, LLM-based processing, ETL workflows, or any system where output structure is complex/non-deterministic but data preservation is critical.
+
+**When NOT to use**: Unit tests, simple CRUD, or when exact output comparison is feasible.
+
+> Source: airweave-ai/airweave (6k★) — Bongo oracle-injection pattern for pipeline E2E testing.
+
+## Spec→Test Traceability
+
+When a plan with acceptance criteria exists (`.rune/features/<name>/plan.md` or phase file), every criterion MUST map to at least one test case.
+
+```
+Plan Acceptance Criteria → Test Case → Implementation
+
+AC-1: "User can reset password via email" → test_password_reset_sends_email()
+AC-2: "Rate limit: max 3 reset attempts/hour" → test_password_reset_rate_limit()
+AC-3: "Expired tokens rejected" → test_expired_reset_token_rejected()
+```
+
+**Validation step** (after writing tests): Cross-check plan's acceptance criteria against test names. For each criterion:
+- Has test → OK
+- No test → flag as UNTESTED REQUIREMENT (more serious than uncovered lines)
+
+**Why this is stronger than coverage**: Coverage checks that lines were EXECUTED. Traceability checks that INTENT was VERIFIED. You can have 100% coverage but miss a requirement if the test doesn't assert the right behavior.
+
+**Skip if**: No plan exists (ad-hoc fix), or plan has no acceptance criteria section.
+
+> Source: Fission-AI/OpenSpec (32.8k★) — spec→test traceability validates intent, not just lines.
+
+## Eval-Driven Development
+
+Define **capability evals** and **regression evals** BEFORE writing implementation code. Evals go beyond unit tests — they verify that the agent/system can handle the feature's intent, not just its mechanics.
+
+### Two Eval Types
+
+| Type | Purpose | Pass Criteria | When |
+|------|---------|---------------|------|
+| **Capability eval** | Can the system do this new thing? | pass@k: ≥1 success in k attempts (k=3-5) | Before implementation |
+| **Regression eval** | Did we break existing behavior? | pass^k: ALL k attempts must pass | After implementation |
+
+**pass@k** (capability): At least 1 of k runs succeeds. Used for new features where some variance is acceptable. Threshold: ≥90% pass@3 for standard features, ≥95% pass@5 for critical paths.
+
+**pass^k** (regression): ALL k runs must pass. Used for existing behavior that must never break. If ANY run fails, it's a regression. Threshold: 100% pass^3.
+
+### Eval File Format
+
+Store evals in `.rune/evals/<feature>.md`:
+
+```markdown
+# Eval: <feature name>
+
+## Capability Evals (pass@k)
+| ID | Description | k | Threshold | Status |
+|----|-------------|---|-----------|--------|
+| CAP-1 | [what the system should be able to do] | 3 | 90% | pending |
+
+## Regression Evals (pass^k)
+| ID | Description | k | Status |
+|----|-------------|---|--------|
+| REG-1 | [existing behavior that must not break] | 3 | pending |
+```
+
+### Anti-Pattern: Eval Overfitting
+
+Do NOT overfit evals to specific prompts or known examples. Evals should test the **capability**, not the **exact input**.
+
+- BAD: `"When user says 'hello', respond with 'Hi there!'"` — tests exact string match
+- GOOD: `"When user greets, respond with a greeting"` — tests capability
+
+### Integration with TDD
+
+1. Write eval definitions (capability + regression) → `.rune/evals/<feature>.md`
+2. Write unit/integration tests (RED phase) → test files
+3. Implement feature (GREEN phase) → source files
+4. Run evals to verify capability achieved + no regressions
+5. Preflight checks eval results as part of quality gate
+
+> Source: affaan-m/everything-claude-code (91.9k★) — eval-driven development with pass@k/pass^k distinction.
+
 ## Red Flags — STOP and Start Over
 
 If you catch yourself with ANY of these, delete implementation code and restart with tests:
@@ -353,11 +519,34 @@ Partial mock missing fields that downstream code consumes. Your test passes beca
 If mock setup is 30 lines and the actual test assertion is 3 lines, the test is testing infrastructure, not behavior. This is a code smell that indicates wrong abstraction level.
 **Gate**: "Is my mock setup longer than my test logic?" → If yes: test at a higher level (integration) or extract mock factories.
 
+### Anti-Pattern 6: Test Slop (Framework-Behavior Tests)
+Tests that verify the framework works rather than YOUR code works. If the test would still pass with an empty component/function, it's testing infrastructure.
+**Gate**: "Would this test pass if I deleted my business logic?" → If yes: STOP. Rewrite to test behavior that YOUR code introduces.
+
+Examples of test slop:
+- "renders without crashing" (tests that React works, not your component)
+- "route responds with 200" without checking response body (tests Express, not your handler)
+- Asserting a mock was called N times without checking the RESULT of those calls
+- Type existence tests (`typeof result === 'object'`) when you should test the actual value
+
+> Source: affaan-m/everything-claude-code (91.9k★) — de-sloppify pattern applied to test writing.
+
 **Red flags — any of these means STOP and rethink:**
 - Mock setup longer than test logic
 - `*-mock` test IDs in assertions
 - Methods only called in test files
 - Can't explain in one sentence why a mock is needed
+- Test would pass with empty implementation (test slop)
+
+## Returns
+
+| Artifact | Format | Location |
+|----------|--------|----------|
+| Test files | Source files | Co-located or `__tests__/` per project convention |
+| Test plan + results | Markdown | `TEST.md` in test directory (non-trivial features only) |
+| Eval scenarios | Markdown | `skills/<name>/evals.md` (for skill behavior testing) |
+| Coverage report | Inline stdout | Shown in Test Report |
+| Test Report | Markdown (inline) | Emitted to calling skill (cook, fix, review) |
 
 ## Sharp Edges
 
@@ -375,6 +564,18 @@ Known failure modes for this skill. Check these before declaring done.
 | Modifying source files to make tests work | HIGH | Role boundary: test writes test files ONLY — source changes go to rune:fix |
 | Test-only methods leaking into production code | MEDIUM | Anti-Pattern 2 gate: if method only called by tests → move to test utilities |
 
+## Self-Validation
+
+```
+SELF-VALIDATION (run before emitting Test Report):
+- [ ] Every test file has at least one assertion — no empty test bodies
+- [ ] RED phase output shows actual failures (not "0 tests") — tests were real, not stubs
+- [ ] No test modifies source code — test files only, source changes belong to fix
+- [ ] Test names describe behavior, not implementation ("should reject expired token" not "test function X")
+- [ ] No mocks of the thing being tested — only mock external dependencies
+- [ ] If BA requirements exist (REQ-xxx), every requirement has at least one test — check plan's Traceability Matrix
+```
+
 ## Done When
 
 - Test framework detected from project config files
@@ -383,7 +584,10 @@ Known failure modes for this skill. Check these before declaring done.
 - After implementation: all tests PASS (GREEN phase — actual pass output shown)
 - Coverage ≥80% verified via verification
 - Test Report emitted with framework, test count, RED/GREEN status, and coverage
+- Self-Validation: all checks passed
 
 ## Cost Profile
 
 ~$0.03-0.08 per invocation. Sonnet for writing tests, Bash for running them. Frequent invocation in TDD workflow.
+
+**Scope guardrail**: Do not modify source or implementation files to make tests pass unless explicitly delegated by the parent agent.