@rune-kit/rune 2.7.0 → 2.10.0

package/skills/session-bridge/SKILL.md

@@ -3,12 +3,12 @@ name: session-bridge
 description: Universal context persistence across sessions. Auto-saves decisions, conventions, and progress to .rune/ files. Loads state at session start. Use when any skill makes architectural decisions or establishes patterns that must survive session boundaries.
 metadata:
   author: runedev
-  version: "0.5.0"
+  version: "0.6.0"
   layer: L3
   model: haiku
   group: state
   tools: "Read, Write, Edit, Glob, Grep"
-  listen: phase.complete
+  listen: phase.complete, checkpoint.request
 ---
 
 # session-bridge
@@ -23,6 +23,8 @@ Solve the #1 developer complaint: context loss across sessions. Session-bridge a
 - Auto-trigger: when a convention/pattern is established
 - Auto-trigger: before context compaction
 - Auto-trigger: at session end (stop hook)
+- Signal: `checkpoint.request` — explicit checkpoint from cook/team mid-phase
+- `/checkpoint` — manual checkpoint (save exact resume point)
 - `/rune status` — manual state check
 
 ## Calls (outbound)
@@ -40,12 +42,14 @@ Solve the #1 developer complaint: context loss across sessions. Session-bridge a
 
 ```
 .rune/
-├── decisions.md      — Architectural decisions log
-├── conventions.md    — Established patterns & style
-├── progress.md       — Task progress tracker
-├── session-log.md    — Brief log of each session
-├── instincts.md      — Learned project-specific patterns (trigger→action)
-└── cumulative-notes.md — Living project understanding (profile, themes, relationships)
+├── decisions.md        — Architectural decisions log
+├── conventions.md      — Established patterns & style
+├── progress.md         — Task progress tracker
+├── session-log.md      — Brief log of each session
+├── instincts.md        — Learned project-specific patterns (trigger→action)
+├── cumulative-notes.md — Living project understanding (profile, themes, relationships)
+├── learnings.jsonl     — Structured learning log (append-only, queryable)
+└── checkpoint.md       — Exact resume point for cross-session continuity
 ```
 
 ## Execution
@@ -199,6 +203,48 @@ Extract atomic "instincts" — learned trigger→action patterns — from this s
 
 **Max instincts**: Keep `.rune/instincts.md` under 20 entries. When full, evict the lowest-confidence entry.
 
+#### Step 5.8 — Learnings Log (Structured JSONL)
+
+Append structured learning entries to `.rune/learnings.jsonl` — an append-only log that captures decisions, insights, and error resolutions in a machine-queryable format. Unlike markdown state files (which are for human reading), JSONL enables fast filtering and "latest winner" lookups.
+
+**Entry schema** — one JSON object per line:
+
+```json
+{"ts":"2026-04-04T14:30:00Z","skill":"cook","type":"decision","key":"state-lib","insight":"Chose Zustand over Redux — fewer re-renders in dashboard with 50+ real-time widgets","confidence":0.8,"files":["src/store/index.ts"]}
+```
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `ts` | ISO 8601 | When the learning was captured |
+| `skill` | string | Which skill produced this learning |
+| `type` | enum | `decision` · `error` · `insight` · `convention` · `performance` |
+| `key` | string | Dedup key — latest entry per key+type wins on read |
+| `insight` | string | 1-2 sentences, causal language ("Chose X because Y", "Root cause was X") |
+| `confidence` | 0.1–1.0 | How certain this learning is (0.3=hunch, 0.7=validated, 0.9=battle-tested) |
+| `files` | string[] | Optional — affected file paths |
+
+**Write rules:**
+- Append only — never edit or delete lines in the JSONL file
+- Max 1-3 entries per session (only genuinely transferable learnings)
+- Use causal/comparative language, not flat facts
+- Key must be kebab-case, descriptive (e.g., `auth-lib`, `db-migration-strategy`, `react-hook-pitfall`)
+
+**Read rules (latest-winner):**
+- When loading learnings, group by `key+type` and take the entry with the latest `ts`
+- This means updating a learning = just append a new entry with the same key+type
+- No dedup needed on write — dedup happens on read
+
+**Query patterns** (for other skills or session-start):
+- All learnings: read `.rune/learnings.jsonl`, parse line-by-line
+- By type: filter `type === "error"` to surface past mistakes before coding
+- By skill: filter `skill === "cook"` to see cook-specific learnings
+- By recency: sort by `ts` descending, take top N
+- Surface top 5 learnings at session start if file has 10+ entries
+
+**Pruning**: When file exceeds 100 entries, compact by keeping only the latest-winner per key+type. Write compacted entries to a new file, replace original.
+
+**Why**: Markdown state files (decisions.md, conventions.md) are great for human reading but hard to query programmatically. JSONL enables structured recall — "show me all errors from last week" or "what did we decide about auth?" — without parsing markdown headers.
+
 #### Step 5.9 — Cumulative Project Notes (Structured Memory)
 
 Maintain a running **cumulative notes** file at `.rune/cumulative-notes.md` that evolves across sessions. Unlike `progress.md` (which tracks tasks) or `decisions.md` (which logs choices), cumulative notes capture the **living understanding** of the project — patterns learned, relationships discovered, recurring themes, and open threads.
@@ -336,6 +382,81 @@ Present the loaded context to the agent in a structured summary:
 
 Identify the next concrete task from `progress.md` → "Next Session Should" section. Present it as the recommended starting point to the calling orchestrator.
 
+### Checkpoint Mode (explicit save-and-resume point)
+
+Unlike Save Mode (which captures session state broadly), Checkpoint Mode creates an **exact resume point** — a single file that tells the next session precisely where to pick up, what's in-flight, and what decisions are load-bearing.
+
+**Trigger**: User says `/checkpoint`, or `cook`/`team` emits `checkpoint.request` signal when pausing mid-phase.
+
+#### Step 1 — Capture resume state
+
+Collect into a structured checkpoint:
+
+```markdown
+# Checkpoint — [YYYY-MM-DD HH:MM]
+
+## What I Was Doing
+[1-2 sentences: the exact task and sub-step in progress]
+
+## Current Git State
+- Branch: [branch name]
+- Last commit: [short hash + message]
+- Uncommitted changes: [list of modified/untracked files, or "clean"]
+- Stashed: [yes/no — if yes, stash message]
+
+## Decisions Made This Session (Load-Bearing)
+[Only decisions that affect the remaining work — not all decisions]
+- [Decision 1]: [choice + why]
+- [Decision 2]: [choice + why]
+
+## What's Left (Ordered)
+1. [Next immediate step — be specific: file, function, what to change]
+2. [Step after that]
+3. [Remaining steps...]
+
+## Context the Next Session Needs
+[Critical info that's NOT in the code or git history — mental model, gotchas discovered, things tried and failed]
+- [Item 1]
+- [Item 2]
+
+## Resume Command
+[Exact instruction for the next session to pick up — e.g., "Continue Phase 2 Task 3: implement the retry logic in src/api/client.ts, the happy path is done, need error handling"]
+```
+
+#### Step 2 — Write checkpoint file
+
+Write to `.rune/checkpoint.md` (overwrite — only one active checkpoint at a time).
+
+#### Step 3 — Confirm to user
+
+```
+## Checkpoint Saved
+- **Resume point**: [1-line summary of what to continue]
+- **Git state**: [branch] @ [commit hash] — [clean/N uncommitted files]
+- **Remaining tasks**: [count]
+- Next session will auto-detect this checkpoint and offer to resume.
+```
+
+#### Checkpoint Resume (in Load Mode)
+
+At Load Mode Step 1, after checking `.rune/*.md` existence, also check for `.rune/checkpoint.md`:
+
+- If checkpoint exists, read it FIRST (before other state files)
+- Present the resume point prominently:
+  ```
+  ## Checkpoint Detected — [date]
+  **Resume**: [Resume Command from checkpoint]
+  **Git state**: [branch] @ [commit] — [clean/dirty]
+  **Tasks remaining**: [count]
+  ```
+- After successful resume (user confirms they've picked up where they left off), rename checkpoint:
+  ```bash
+  mv .rune/checkpoint.md .rune/checkpoint-[date].resolved.md
+  ```
+- Keep last 3 resolved checkpoints for history, delete older ones
+
+**Why**: Save Mode captures everything broadly. Checkpoint captures the **exact needle position** — like a bookmark in a book vs. a summary of chapters read. The next session doesn't need to scan all state files to figure out what to do; the checkpoint tells it directly.
+
 ## Output Format
 
 ### Save Mode
@@ -352,11 +473,21 @@ Identify the next concrete task from `progress.md` → "Next Session Should" sec
 ```
 ## Session Bridge — Loaded
 - **Last session**: [date and summary]
+- **Checkpoint**: [detected — resume point] | [none]
 - **Decisions on file**: [count]
 - **Conventions on file**: [count]
+- **Learnings on file**: [count] (top 5 surfaced if 10+)
 - **Next task**: [task description]
 ```
 
+### Checkpoint Mode
+```
+## Checkpoint Saved
+- **Resume point**: [1-line summary]
+- **Git state**: [branch] @ [hash] — [clean/N files]
+- **Remaining tasks**: [count]
+```
+
 ## Constraints
 
 1. MUST save decisions, conventions, and progress — not just a status line
@@ -374,6 +505,9 @@ Known failure modes for this skill. Check these before declaring done.
 | Load mode presenting stale context without age marker | MEDIUM | Mark each loaded entry with its session date — caller knows how fresh it is |
 | Silent failure when git unavailable | MEDIUM | Note "no git available" in report — do not fail silently or skip without logging |
 | Loading poisoned .rune/ files without verification | CRITICAL | Step 1.5 integrity-check MUST run before loading — TAINTED = block load |
+| Learnings JSONL grows unbounded | MEDIUM | Auto-compact at 100 entries — keep only latest-winner per key+type |
+| Checkpoint stale after code changes | MEDIUM | Checkpoint includes git state — if branch/commit differ at resume, warn user that checkpoint may be outdated |
+| Multiple checkpoints overwrite each other | LOW | By design — only one active checkpoint. Resolved ones archived with date suffix |
 
 ## Done When (Save Mode)
 
@@ -381,17 +515,29 @@ Known failure modes for this skill. Check these before declaring done.
 - conventions.md updated with all new patterns established
 - progress.md updated with completed/in-progress/blocked task status
 - session-log.md appended with one-line session summary
+- learnings.jsonl appended with 1-3 structured entries (if transferable learnings exist)
 - Git commit made (or "no git" noted in report)
 - Session Bridge Saved report emitted
 
 ## Done When (Load Mode)
 
 - .rune/*.md files found and read
+- Checkpoint detected and presented (if exists)
+- Learnings surfaced (top 5 if 10+ entries)
 - Last session summary presented
 - Current in-progress and blocked tasks identified
-- Next task recommendation from progress.md
+- Next task recommendation from progress.md (or checkpoint resume command)
 - Session Bridge Loaded report emitted
 
+## Done When (Checkpoint Mode)
+
+- Git state captured (branch, commit, uncommitted files)
+- Load-bearing decisions documented
+- Remaining tasks listed in execution order
+- Resume command written (specific enough for a fresh session to act on)
+- checkpoint.md written to .rune/
+- Checkpoint Saved report emitted
+
 ## Cost Profile
 
 ~100-300 tokens per save. ~500-1000 tokens per load. Always haiku. Negligible cost.

package/skills/skill-forge/SKILL.md

@@ -3,7 +3,7 @@ name: skill-forge
 description: Use when creating new Rune skills, editing existing skills, or verifying skill quality before deployment. Applies TDD discipline to skill authoring — test before write, verify before ship.
 metadata:
   author: runedev
-  version: "1.6.0"
+  version: "1.7.0"
   layer: L2
   model: opus
   group: creation
@@ -33,6 +33,7 @@ The skill that builds skills. Applies Test-Driven Development to skill authoring
 ## Called By (inbound)
 
 - `cook` (L1): when the feature being built IS a new skill
+- `scaffold` (L1): when scaffolded project includes custom skills
 
 ## References
 
@@ -276,6 +277,47 @@ Research (Meincke et al., 2025, 28,000 conversations) shows 33% → 72% complian
 
 **Ethical test**: Would this serve the user's genuine interests if they fully understood the technique?
 
+### Phase 5.5 — SECURITY MODEL
+
+Every skill that touches external systems, user data, or destructive operations MUST define an explicit Security Model section. This is a contract — not aspirational, but testable.
+
+**Add to SKILL.md after Sharp Edges:**
+
+```markdown
+## Security Model
+
+### Trust Boundaries
+- [What this skill reads] — e.g., "Reads .env files, user source code, git history"
+- [What this skill writes] — e.g., "Writes to .rune/ only, never modifies source code"
+- [What this skill executes] — e.g., "Runs npm test, never runs arbitrary shell commands"
+
+### This Skill Will NEVER
+- [Explicit denial 1] — e.g., "Execute user-provided strings as shell commands"
+- [Explicit denial 2] — e.g., "Read or log credential files (.env, secrets.json)"
+- [Explicit denial 3] — e.g., "Send data to external endpoints"
+
+### Threat Surface
+| Threat | Mitigated By |
+|--------|-------------|
+| Prompt injection via user input | Input validated before processing |
+| Credential exposure in output | Secrets pattern detection before emit |
+| Destructive operation on wrong target | Confirmation gate before delete/overwrite |
+```
+
+**When to require Security Model:**
+- Skill uses `Bash` tool → REQUIRED (can execute arbitrary commands)
+- Skill reads `.env` or credentials → REQUIRED
+- Skill writes/deletes files outside `.rune/` → REQUIRED
+- Skill calls external APIs or MCP tools → REQUIRED
+- Skill is read-only analysis (review, audit, scout) → OPTIONAL but recommended
+
+**Eval integration**: Phase 7 evals for skills with Security Model MUST include:
+- E05: Attempt to make skill execute unintended command
+- E06: Attempt to make skill expose credentials in output
+- E07: Attempt to make skill write outside its declared boundary
+
+If Security Model is required but missing → Phase 7 EVAL HARD-GATE blocks ship.
+
 ### Phase 6 — INTEGRATE
 
 Wire the skill into the mesh:

package/skills/skill-router/{skill.md → 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.3.0"
+  version: "1.4.0"
   layer: L0
   model: haiku
   group: orchestrator
@@ -328,9 +328,34 @@ These DO NOT need skill routing:
 
 At the end of a skill's workflow, skill-router MAY suggest a **complementary skill** — limited to ONE recommendation to prevent infinite referral chains.
 
+### Chain Metadata Awareness (Priority Source)
+
+When a previous skill's output contains a `chain_metadata` block in the conversation context, skill-router MUST use it as the PRIMARY source for next-skill suggestions:
+
+1. **Read `chain_metadata.suggested_next`** — these are data-driven recommendations from the skill that just ran. They have MORE context than the hardcoded table below.
+2. **Read `chain_metadata.status`** — override suggestion logic based on outcome:
+   - `BLOCKED` → suggest `debug` or `fix` regardless of what the hardcoded table says
+   - `NEEDS_CONTEXT` → suggest `scout` or `research`
+   - `DONE_WITH_CONCERNS` → suggest `review` or `sentinel`
+3. **Read `chain_metadata.domain`** — trigger L4 pack auto-suggest (see below)
+4. **Forward `chain_metadata.exports`** — when announcing the suggestion, mention what data is available: "Review can use the 5 changed files and test results from cook."
+
+**Conflict resolution:** If `chain_metadata.suggested_next` recommends skill A but the hardcoded table below recommends skill B, **prefer chain_metadata** — it was generated from actual output data, not generic rules.
+
+**Announcement format with chain_metadata:**
+```
+Suggested next: `rune:<skill>` — <chain_metadata.suggested_next.reason>
+Available data: <list of export keys the suggested skill would consume>
+Run it? (skip to continue)
+```
+
+### Hardcoded Fallback Table
+
+When NO chain_metadata is present (skill didn't emit one, or legacy invocation), fall back to this static table:
+
 | After This Skill | Suggest | Rationale |
 |-----------------|---------|-----------|
-| `debug` | `review` | Root cause found — review the fix area for broader issues |
+| `debug` | `fix` | Root cause found — apply the fix |
 | `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 |

package/skills/team/SKILL.md

@@ -5,7 +5,7 @@ context: fork
 agent: general-purpose
 metadata:
   author: runedev
-  version: "0.7.0"
+  version: "0.8.0"
   layer: L1
   model: opus
   group: orchestrator
@@ -477,6 +477,29 @@ All streams done     → MERGE sequentially (avoid conflicts)
 | Integration test results | Inline stdout | Captured in Phase 5 verify |
 | Team Report | Markdown (inline) | Emitted at end of session |
 
+## Document Ownership
+
+| Scope | Access | Files |
+|-------|--------|-------|
+| **Owns** (read + write) | `.rune/team-report-*.md`, worktree branches, merge commits |
+| **Reads** (never writes) | `.rune/plan-*.md`, `.rune/contract.md`, `CLAUDE.md`, cook reports from sub-agents |
+| **Never modifies** | Source files directly (delegates to cook instances), `SKILL.md` files, `compiler/**` |
+
+Each cook instance owns its declared file set (disjoint). Team owns coordination artifacts only — never touches source code directly.
+
+## Anti-Patterns
+
+Common multi-agent orchestration failures. These cause the most expensive rework in team workflows.
+
+| Anti-Pattern | Why It Fails | Correct Approach |
+|---|---|---|
+| **Overlapping file ownership** — two agents write to the same file | Merge conflicts, lost work, non-deterministic output | Enforce disjoint `touches[]` per stream. Move shared files to a single owner |
+| **Blind merge** — merging cook reports without reviewing them | Poisoned output propagates. One bad stream corrupts the whole feature | `integrity-check` + `completion-gate` on every cook report before merge |
+| **Over-parallelization** — launching 5+ agents for a 3-file task | Context fragmentation, coordination overhead > implementation time | Auto-detect: ≤5 files → lite mode (max 2 agents). Full mode caps at 3 |
+| **Cross-domain implementation** — one agent implements both frontend and backend | Domain expertise diluted. Agent makes shallow choices in unfamiliar territory | Split by domain. Frontend agent ≠ backend agent. Each gets domain context |
+| **Missing handoff context** — bare prompt to cook instance without scope/conventions | Agent guesses project conventions, uses wrong patterns, produces inconsistent code | NEXUS Handoff Template: always include metadata, deliverables, conventions, quality expectations |
+| **Sequential when parallel is safe** — running independent streams one by one | Wastes time. 3 independent streams × 5min = 15min sequential vs 5min parallel | Check dependency graph. Independent streams → parallel. Dependent → sequential |
+
 ## Sharp Edges
 
 Known failure modes for this skill. Check these before declaring done.

package/skills/test/SKILL.md

@@ -3,13 +3,13 @@ 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: "1.1.0"
+  version: "1.2.0"
   layer: L2
   model: sonnet
   group: development
   tools: "Read, Write, Edit, Bash, Glob, Grep"
   emit: tests.passed, tests.failed
-  listen: code.changed
+  listen: code.changed, db.migrated
 ---
 
 # test
@@ -542,6 +542,33 @@ Examples of test slop:
 | Coverage report | Inline stdout | Shown in Test Report |
 | Test Report | Markdown (inline) | Emitted to calling skill (cook, fix, review) |
 
+## Chain Metadata
+
+Append to Test Report when invoked standalone. Suppress when called as sub-skill inside an L1 orchestrator (cook, team, etc.) — the orchestrator emits a consolidated block. See `docs/references/chain-metadata.md`.
+
+```yaml
+chain_metadata:
+  skill: "rune:test"
+  version: "1.2.0"
+  status: "[DONE]"
+  domain: "[area tested]"
+  files_changed:
+    - "[test files created/modified]"
+  exports:
+    test_results: { passed: [N], failed: [N], coverage: [N] }
+    test_files: ["[paths to test files]"]
+    status: "[RED | GREEN]"  # RED = TDD failing (expected), GREEN = all pass
+  suggested_next:  # status-aware — pick based on RED or GREEN
+    # When GREEN:
+    - skill: "rune:preflight"
+      reason: "[grounded in results — e.g., 'All 15 tests GREEN, check edge case completeness']"
+      consumes: ["test_results", "test_files"]
+    # When RED (TDD expected):
+    - skill: "rune:fix"
+      reason: "[grounded in failures — e.g., '3 tests RED as expected, implement to make them pass']"
+      consumes: ["test_results", "test_files"]
+```
+
 ## Sharp Edges
 
 Known failure modes for this skill. Check these before declaring done.

package/skills/verification/SKILL.md

@@ -9,6 +9,7 @@ metadata:
   group: validation
   tools: "Read, Bash, Glob, Grep"
   listen: code.changed
+  emit: verification.complete
 ---
 
 # verification
@@ -101,8 +102,6 @@ Compile all results into the structured report. Update all TodoWrite items to co
 
 ### 3-Level Artifact Verification
 
-> From GSD (gsd-build/get-shit-done, 30.8k★): "Task done ≠ Goal achieved."
-
 Every file created or modified during implementation must pass ALL 3 levels:
 
 **Level 1 — EXISTS**: File is on disk, non-empty.