@rune-kit/rune 2.7.0 → 2.10.0

package/skills/design/SKILL.md

@@ -3,7 +3,7 @@ name: design
 description: Design system reasoning. Maps product domain to style, palette, typography, and platform-specific patterns. Generates .rune/design-system.md as the shared design contract for all UI-generating skills.
 metadata:
   author: runedev
-  version: "0.3.0"
+  version: "0.4.0"
   layer: L2
   model: sonnet
   group: creation
@@ -32,6 +32,8 @@ Design system reasoning layer. Converts a product description into a concrete de
 ## Called By (inbound)
 
 - `cook` (L1): before any frontend code generation
+- `brainstorm` (L2): when selected approach has UI/UX implications
+- `ba` (L2): when requirements include UI/UX components
 - `review` (L2): when AI anti-pattern detected in diff
 - `perf` (L2): when Lighthouse Accessibility score blocks
 - User: `/rune design` direct invocation
@@ -97,6 +99,31 @@ From the user's task description + codebase context, classify product type:
 
 If domain is unclear: ask one clarifying question — "Is this closer to X or Y?"
 
+### Step 2.5 — Mood-to-Constraint Mapping
+
+After classifying domain, ask ONE question: **"What should users feel when they use this?"**
+
+Accept a single mood keyword (or infer from context if obvious). Map mood to concrete design constraints:
+
+| Mood | Color Temp | Typography Weight | Whitespace | Animation | Shadow |
+|------|-----------|-------------------|------------|-----------|--------|
+| **Impressed** | Cool (blue-slate) | Heavy display (700-800) | Generous (xl-3xl) | Dramatic reveals (0.8-1.2s ease-out) | Deep, layered |
+| **Excited** | Warm (amber-orange) | Bold contrasts (400 vs 800) | Tight-medium (sm-lg) | Energetic springs (0.4-0.6s spring) | Elevation lifts |
+| **Calm** | Neutral-warm (stone-sage) | Light-medium (300-500) | Very generous (2xl-3xl) | Slow fades (0.6-0.8s ease-out-quad) | Soft, minimal |
+| **Confident** | Cool-neutral (zinc-slate) | Medium-heavy (500-700) | Structured (md-xl) | Precise slides (0.3-0.5s ease) | Crisp, defined |
+| **Playful** | Saturated (multi-hue) | Round + bold (600-700) | Medium, irregular (md-lg) | Bouncy springs (0.4-0.6s spring, overshoot) | Hard/comic (3-5px offset) |
+| **Techy** | Cold (gray-cyan) | Mono-heavy, crisp (400-600) | Dense, grid-aligned (sm-md) | Sharp snaps (0.15-0.3s ease-out) | Minimal or glow |
+| **Professional** | Muted neutrals | System fonts, readable (400-500) | Balanced (md-lg) | Subtle (0.2-0.3s ease) | Standard elevation |
+| **Inspired** | Rich-warm (gold-terracotta) | Editorial display (300-700 range) | Asymmetric, generous | Scroll-driven reveals (0.5-0.8s) | Dramatic, directional |
+
+**Mapping rules:**
+1. Mood constraints OVERRIDE generic domain defaults where they conflict (mood is user intent, domain is convention)
+2. If mood contradicts domain safety (e.g., "Playful" + Healthcare), WARN user: "Playful tone may reduce trust in medical context — proceed?"
+3. Write selected mood + resolved constraints to `.rune/design-system.md` under `## Mood` section
+4. Downstream skills (`animation-patterns`, `palette-picker`, `type-system`) read mood constraints from design-system.md
+
+**Skip if**: User says "no preference" or "just follow domain defaults" — proceed to Step 3 with domain-only reasoning.
+
 ### Step 3 — Apply Domain Reasoning Rules
 
 Map domain to design system parameters:
@@ -333,6 +360,44 @@ sm: 6px | md: 8px | lg: 12px | xl: 16px | full: 9999px
 - [ ] Responsive tested at 375px / 768px / 1024px / 1440px
 ```
 
+### Step 5.5 — UI Design Contract (UI-SPEC.md)
+
+After generating the design system, lock key visual decisions in `.rune/ui-spec.md` — a binding contract that prevents design drift during implementation.
+
+**Why**: design-system.md defines tokens (what's available). UI-SPEC locks decisions (what was chosen and WHY). Without a spec, each component re-decides layout, density, and hierarchy — causing visual inconsistency.
+
+**Generate `.rune/ui-spec.md`:**
+
+```markdown
+# UI Specification: [Project Name]
+Locked: [YYYY-MM-DD] | Mood: [selected mood]
+
+## Layout Decisions
+- Page max-width: [value]px
+- Sidebar: [yes/no] — [width]px [fixed/collapsible]
+- Content density: [compact/balanced/spacious]
+- Card sizing: [uniform/varied] — if varied, specify hierarchy rules
+
+## Visual Hierarchy Rules
+- Primary action: [color] [size] [weight] — ONE per viewport
+- Secondary action: [ghost/outline] style — max 2 per section
+- Data emphasis: [monospace + bold] for numbers, [color accent] for status
+- Section separation: [border/spacing/background] — pick ONE, be consistent
+
+## Component Decisions
+- Card style: [elevated/bordered/glass] — reasoning: [why]
+- Table style: [striped/bordered/minimal] — reasoning: [why]
+- Form layout: [stacked/inline/grid] — reasoning: [why]
+- Navigation: [sidebar/topbar/tabs] — reasoning: [why]
+
+## Locked Anti-Decisions (things we explicitly chose NOT to do)
+- ❌ [rejected option] — because [reason]
+```
+
+<HARD-GATE>
+UI-SPEC.md is a contract. Once written, changes require explicit user approval ("I want to change the card style"). Skills that generate UI (`cook`, `fix`, `scaffold`) MUST read UI-SPEC.md before producing components. Drift from spec = review finding.
+</HARD-GATE>
+
 ### Step 6 — Accessibility Review
 
 Run a focused accessibility audit on the design system and any existing UI code. This step ensures the design contract doesn't produce inaccessible outputs.
@@ -349,6 +414,39 @@ Run a focused accessibility audit on the design system and any existing UI code.
 
 If violations found → add them to `.rune/design-system.md` Anti-Patterns section as concrete rules.
 
+### Step 6.5 — 6-Pillar Visual Audit
+
+Score the generated design system across 6 pillars. Each pillar scored 1-4 (1=Poor, 2=Fair, 3=Good, 4=Excellent). Minimum passing score: **18/24** (average 3.0).
+
+| Pillar | Score 1 (Poor) | Score 2 (Fair) | Score 3 (Good) | Score 4 (Excellent) |
+|--------|---------------|----------------|----------------|---------------------|
+| **Copy** | Placeholder text, generic CTAs ("Submit"), no voice | Real copy but inconsistent tone | Consistent voice, domain-appropriate, clear CTAs | Personality-rich, scannable, microcopy for every state |
+| **Visuals** | Stock photos, generic icons, no visual identity | Consistent icon set, basic imagery | Custom illustrations or curated photography, clear hierarchy | Distinctive visual language, icons tell stories, zero stock |
+| **Color** | Default framework palette, no semantic meaning | Brand colors defined but inconsistent usage | Full semantic palette, dark mode, accessible contrast | Mood-aligned, colorblind-safe, context-adaptive (profit/loss/status) |
+| **Typography** | Single font, no scale | Font pairing exists but inconsistent sizing | Clear hierarchy (display/heading/body/mono), numbers monospace | Mood-aligned pairing, fluid scaling, platform-native where needed |
+| **Spacing** | Inconsistent gaps, cramped or too loose | Base unit defined but not consistently applied | 8px grid, consistent section/component/element spacing | Density variants (compact/default/spacious), rhythm feels intentional |
+| **UX** | Missing states (empty/error/loading), no feedback | Basic states exist, some interactive feedback | All states covered, toast/loading/skeleton, focus management | Delightful micro-interactions, smart defaults, zero dead-ends |
+
+**Audit output:**
+
+```
+### Visual Audit Score: [total]/24
+
+| Pillar | Score | Notes |
+|--------|-------|-------|
+| Copy | 3 | Consistent voice, missing loading microcopy |
+| Visuals | 2 | Using Phosphor icons (good), no custom illustration |
+| Color | 4 | Full semantic palette, colorblind alternates defined |
+| Typography | 3 | JetBrains Mono for numbers, Inter for prose — solid |
+| Spacing | 3 | 8px grid applied, density variants not needed yet |
+| UX | 3 | All states covered, micro-interactions in progress |
+| **Total** | **18/24** | PASS — ship-ready with Copy improvements recommended |
+```
+
+**If score < 18**: Flag specific weak pillars in Design Report. Add improvement tasks to `.rune/design-system.md` under `## Improvement Backlog`.
+
+**Registry safety check**: If an existing component library is in use (shadcn, MUI, etc.), verify the design system doesn't conflict with the library's token structure. Flag collisions.
+
 ### Step 7 — UX Writing Patterns
 
 Generate microcopy guidelines specific to this product domain. UX writing is part of design — not an afterthought.
@@ -448,8 +546,10 @@ Trading/Fintech — Data-Dense Dark — Web
 | Artifact | Format | Location |
 |----------|--------|----------|
 | Design system file | Markdown | `.rune/design-system.md` |
+| UI specification contract | Markdown | `.rune/ui-spec.md` |
 | Design report | Markdown | inline (chat output) |
 | Accessibility audit findings | Markdown list | inline + appended to design-system.md |
+| Visual audit score | Table (6 pillars × 1-4) | inline + appended to design report |
 | UX writing guidelines | Markdown section | `.rune/design-system.md` § UX Writing |
 
 ## Sharp Edges
@@ -462,6 +562,9 @@ Known failure modes for this skill. Check these before declaring done.
 | Purple/indigo accent on non-AI-native product | HIGH | Constraint 3 blocks this — re-generate with domain-appropriate accent |
 | Anti-pattern list copied from generic sources (not domain-specific) | HIGH | Each anti-pattern must cite why it fails in THIS specific domain |
 | design-system.md not written (only reported verbally) | HIGH | Constraint 4 — no file = no persistence = future sessions lose design context |
+| Mood contradicts domain safety conventions | HIGH | Step 2.5 warns user before proceeding (e.g., Playful + Healthcare) |
+| UI-SPEC.md drift — components diverge from locked decisions | HIGH | HARD-GATE: cook/fix must read ui-spec.md before generating UI |
+| Visual audit score < 18 shipped without improvement plan | MEDIUM | Step 6.5 flags weak pillars and creates backlog items |
 | iOS target generating solid-background cards | MEDIUM | Platform Gate: iOS 26 Liquid Glass deprecates this pattern |
 | Android target using hardcoded hex colors | MEDIUM | Platform Gate: MaterialTheme.colorScheme is mandatory for dynamic color |
 
@@ -469,12 +572,16 @@ Known failure modes for this skill. Check these before declaring done.
 
 - Design reference loaded (user override or baseline)
 - Domain classified (one of the 10 categories or explicit custom reasoning)
+- Mood mapped to constraints (or explicitly skipped with "domain defaults")
 - Design system generated with: colors (primitive + semantic), typography, spacing, effects, anti-patterns
 - Platform-specific overrides applied (if iOS/Android target)
+- UI-SPEC.md written with locked layout, hierarchy, and component decisions
 - Accessibility review completed (6 checks: contrast, focus, touch targets, labels, semantic HTML, motion)
+- 6-Pillar Visual Audit scored ≥ 18/24 (or weak pillars flagged with improvement tasks)
 - UX writing guidelines generated (error, empty state, confirmation, loading, button templates)
-- `.rune/design-system.md` written (includes UX Writing section)
-- Design Report emitted with accent/typography reasoning and anti-pattern count
+- `.rune/design-system.md` written (includes Mood + UX Writing sections)
+- `.rune/ui-spec.md` written (design contract for UI-generating skills)
+- Design Report emitted with mood, accent/typography reasoning, visual audit score, and anti-pattern count
 - Pre-Delivery Checklist included in design-system.md
 
 ## Cost Profile

package/skills/docs/SKILL.md

@@ -8,6 +8,7 @@ metadata:
   model: sonnet
   group: delivery
   tools: "Read, Write, Edit, Glob, Grep"
+  emit: docs.updated
 ---
 
 # docs
@@ -192,7 +193,7 @@ After updating any doc, verify consistency across all project documentation:
 Cross-Doc Consistency:
 - [x] README.md ↔ CLAUDE.md: versions match, commands match
 - [x] README.md ↔ docs/index.html: stats match, features match
-- [ ] README.md says "61 skills" but CLAUDE.md says "59" → FIX CLAUDE.md
+- [ ] README.md says "62 skills" but CLAUDE.md says "59" → FIX CLAUDE.md
 ```
 
 **Fix inconsistencies immediately** — don't just report them. Update the stale doc to match the source of truth (usually the code or the most recently updated doc).

package/skills/fix/SKILL.md

@@ -3,7 +3,7 @@ name: fix
 description: Apply code changes and fixes. Writes implementation code, applies bug fixes, and verifies changes with tests. Core action hub in the development mesh.
 metadata:
   author: runedev
-  version: "0.7.0"
+  version: "0.9.0"
   layer: L2
   model: sonnet
   group: development
@@ -68,6 +68,29 @@ Read and fully understand the fix request before touching any file.
 - If the request is ambiguous or root cause is unclear → call `rune:debug` before proceeding
 - Note the scope: single function, single file, or multi-file change
 
+### Step 1b: Recovery Policy Matrix
+
+Before locating code, classify the incoming error/task into a recovery category to determine the right fix strategy. This prevents wasting effort on the wrong approach.
+
+| Error Type | Recovery Action | Strategy |
+|------------|----------------|----------|
+| `INPUT_REQUIRED` — missing user input, ambiguous spec | **PROMPT_USER** | Return NEEDS_CONTEXT with specific questions. Do NOT guess. |
+| `INPUT_INVALID` — wrong format, type mismatch, encoding | **AUTO_FIX** | Fix at validation layer. Add schema validation (Zod/Pydantic) if missing. |
+| `TIMEOUT` — operation exceeded time limit | **RETRY** with adjustment | Increase timeout, add retry with exponential backoff, or chunk the operation. |
+| `POLICY_BLOCKED` — security gate, lint rule, contract violation | **ABORT** | Do NOT work around the policy. Report to caller with the specific rule that blocked. |
+| `PERMISSION_DENIED` — auth failure, file access, API scope | **PROMPT_USER** | Cannot fix permissions programmatically. Report exact permission needed. |
+| `DEPENDENCY_ERROR` — missing package, version conflict, broken dep | **AUTO_FIX** | Install missing dep, resolve version conflict, or suggest alternative package. |
+| `LOGIC_ERROR` — wrong output, incorrect calculation, bad algorithm | **INVESTIGATE** | Do NOT auto-fix. Call `rune:debug` — logic errors need root cause analysis. |
+| `ENVIRONMENT_ERROR` — wrong Node/Python version, missing system dep | **PROMPT_USER** | Report exact version/tool needed. Agent cannot change system environment. |
+
+**Decision flow**:
+1. Read the incoming diagnosis/error
+2. Classify into one of the 8 error types above
+3. Apply the recovery action — this determines whether to proceed (AUTO_FIX, RETRY), ask (PROMPT_USER), stop (ABORT), or re-diagnose (INVESTIGATE)
+4. Announce: "Recovery policy: {error_type} → {action}"
+
+**Why**: Without a recovery matrix, fix attempts the same strategy (read → change → test) for every error type. A POLICY_BLOCKED error doesn't need code reading — it needs the policy reported. An INPUT_REQUIRED error doesn't need debugging — it needs a question asked. Matching strategy to error type eliminates wasted cycles.
+
 ### Step 2: Locate
 
 Find the exact files and lines to change.
@@ -248,6 +271,28 @@ Fix returns one of four statuses to its caller (cook, debug, review, surgeon). T
 | Fix Report | Markdown (inline) | Emitted to calling skill (cook, debug, review, surgeon) |
 | Verification output | Inline (Fix Report) | Lint + types + test results |
 
+## Chain Metadata
+
+Append to Fix 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:fix"
+  version: "0.9.0"
+  status: "[DONE | DONE_WITH_CONCERNS | NEEDS_CONTEXT | BLOCKED]"
+  domain: "[area fixed]"
+  files_changed:
+    - "[list of modified files]"
+  exports:
+    fix_applied: { files: ["[paths]"], description: "[what was fixed]" }
+    verification: { lint: "[PASS/FAIL]", types: "[PASS/FAIL]", tests: "[PASS/FAIL]" }
+    commit_hash: "[hash if committed]"
+  suggested_next:
+    - skill: "rune:test"
+      reason: "[grounded in changes — e.g., 'Modified 3 files in auth module, edge cases need coverage']"
+      consumes: ["fix_applied", "verification"]
+```
+
 ## Sharp Edges
 
 Known failure modes for this skill. Check these before declaring done.
@@ -264,6 +309,7 @@ Known failure modes for this skill. Check these before declaring done.
 | Removing debug instrumentation before fix is verified | MEDIUM | Step 5b: preserve `#region agent-debug` markers until all tests pass — premature cleanup erases failure history |
 | Runaway fix loop — 20+ fixes without checking quality decay | HIGH | Step 4.5: WTF-likelihood self-regulation. >20% risk = STOP. Hard cap 30 fixes/session. Each fix adds risk — diminishing returns after ~15 |
 | Each fix creates a new bug elsewhere — whack-a-mole | CRITICAL | Tight coupling signal. STOP fixing → escalate to debug with note "each fix creates new failure — suspect structural issue". Debug will route to plan for redesign |
+| Applying same fix strategy to every error type | MEDIUM | Step 1b Recovery Policy Matrix: classify error type FIRST — POLICY_BLOCKED needs reporting not fixing, INPUT_REQUIRED needs questions not code |
 
 ## Done When
 

package/skills/graft/SKILL.md

@@ -0,0 +1,352 @@
+---
+name: graft
+description: "Clone, port, or convert features from any GitHub repo into your project. Understand before copy, challenge before implement. 4 modes: port (rewrite), compare (analysis), copy (transplant), improve (copy + optimize)."
+metadata:
+  author: runedev
+  version: "0.1.0"
+  layer: L2
+  model: sonnet
+  group: creation
+  tools: "Read, Write, Edit, Bash, Glob, Grep, WebFetch"
+  emit: graft.complete
+  listen: codebase.scanned
+---
+
+# graft
+
+## Purpose
+
+External code intelligence — structured workflow for learning from, adapting, and integrating features from any public repository into your project. Graft is NOT a copy-paste tool. It enforces understanding before adoption through a mandatory challenge gate that evaluates license compatibility, stack fit, scope, quality, and maintenance health before any code touches your codebase.
+
+<HARD-GATE>
+Challenge gate (Step 4) MUST complete before adaptation planning (Step 5).
+No implementation without confronting trade-offs. This applies to ALL modes except compare.
+Skip only with --fast flag (user accepts full responsibility).
+</HARD-GATE>
+
+## Modes
+
+### Port (default)
+Rewrite the target feature using YOUR stack and patterns. Source code is a reference, not a template. Output is idiomatic to your codebase.
+
+**When**: Different tech stack (Vue→React, Django→FastAPI), or source patterns conflict with your conventions.
+
+### Compare
+Side-by-side analysis only. No code changes. Outputs a structured comparison report.
+
+**When**: Evaluating whether to adopt a feature, benchmarking your implementation against another, or learning patterns without importing code.
+
+### Copy
+Pure transplant with minimal adaptation. Stays as close to the original as possible — only changes imports, paths, and config to fit your project structure.
+
+**When**: Same tech stack, source code is high quality, you want the exact implementation.
+
+### Improve
+Copy the feature, then refactor and optimize. Fix anti-patterns, add missing tests, adapt to your codebase conventions, upgrade deprecated APIs.
+
+**When**: Same stack but source has quality issues, or you want the feature but better.
+
+## Speed Options
+
+| Flag | Research | Challenge Gate | User Approval |
+|------|----------|---------------|---------------|
+| (default) | ✅ Full | ✅ Yes | ✅ Each step |
+| `--auto` | ✅ Full | ✅ Yes | ❌ Auto-approve |
+| `--fast` | ❌ Skip | ❌ Skip | ❌ Auto-approve |
+
+**`--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."
+
+## Smart Intent Detection
+
+| Input Pattern | Detected Mode |
+|---------------|---------------|
+| Contains "compare", "vs", "diff", "analyze" | compare |
+| Contains "copy", "exact", "as-is", "same" | copy |
+| 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 |
+| (default — no keyword match) | port |
+
+## Triggers
+
+- `/rune graft <url> [--port|--compare|--copy|--improve] [--auto|--fast]`
+- Delegated from `cook` when task contains "graft", "port from", "copy from repo", "clone feature from"
+- Auto-trigger: when user pastes a GitHub URL with context like "use this", "like this repo", "steal this"
+
+## Calls (outbound)
+
+- `research` (L3): fetch repo README, docs, understand purpose and architecture
+- `scout` (L2): scan LOCAL codebase for conventions, patterns, stack detection
+- `fix` (L2): implement adapted code (port and improve modes)
+- `review` (L2): post-graft quality check (improve mode only)
+
+## Called By (inbound)
+
+- User: `/rune graft <url>` direct invocation
+- `cook` (L1): delegation when task is "port feature from external repo"
+
+## Data Flow
+
+### Feeds Into →
+
+- `fix` (L2): adaptation plan → fix's implementation targets (port/improve modes)
+- `review` (L2): grafted code → review's analysis targets (improve mode)
+- `test` (L2): new grafted code → test coverage targets
+- `journal` (L3): graft.complete signal → auto-logged for pattern tracking
+
+### Fed By ←
+
+- `scout` (L2): local codebase conventions → graft's adaptation strategy
+- `research` (L3): repo analysis → graft's understanding of source architecture
+
+## Executable Steps
+
+### Step 0 — Parse Input
+<MUST-READ path="references/mode-decision.md" trigger="when auto-detecting mode"/>
+
+Extract from user input:
+1. **URL** — GitHub/GitLab/Bitbucket repo or file URL
+2. **Mode** — explicit flag or auto-detect via intent detection table
+3. **Speed** — `--auto` or `--fast` if present
+4. **Scope** — specific dir/file path if URL points to subdirectory, or user specifies "just the auth module"
+
+Validate URL is accessible. If private repo or URL fails → suggest raw file URLs or manual paste.
+
+### Step 1 — Fetch & Scope
+
+```bash
+# Sparse clone for large repos (skip if small or specific files)
+git clone --depth 1 --filter=blob:none --sparse <url> /tmp/graft-<hash>
+cd /tmp/graft-<hash>
+git sparse-checkout set <target-dir>
+```
+
+For specific files or small repos: use `WebFetch` on raw GitHub URLs instead of cloning.
+
+**Read in this order** (stop when you have enough context):
+1. README.md — purpose, architecture overview
+2. Target dir's files — the actual code to graft
+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?"
+
+### Step 2 — Analyze Source
+
+Understand the target feature's architecture:
+- **What it does** — 2-3 sentence summary
+- **How it works** — key patterns, data flow, core logic
+- **Dependencies** — external packages required, internal imports
+- **Stack** — framework, language version, tooling
+- **Quality signals** — has tests? typed? documented? last commit date?
+
+Output a brief analysis (not full report — save context for later steps).
+
+### Step 3 — Scan Local Codebase
+
+Invoke `rune:scout` (or use cached output if `codebase.scanned` signal received):
+- Local tech stack and version
+- Naming conventions (camelCase vs snake_case, file structure)
+- Existing patterns that overlap with target feature
+- Import style, test framework, state management approach
+
+**Stack comparison**: Produce a quick compatibility matrix:
+```
+| Aspect | Source | Local | Compatible? |
+|--------|--------|-------|-------------|
+| Framework | Next.js 14 | Next.js 15 | ✅ Minor adaptation |
+| Language | TypeScript | TypeScript | ✅ |
+| State | Redux | Zustand | ⚠️ Port needed |
+| Testing | Jest | Vitest | ⚠️ Port needed |
+```
+
+If stack is identical → suggest copy or improve mode (not port).
+If stack differs significantly → force port mode.
+
+### Step 4 — Challenge Gate
+<MUST-READ path="references/challenge-framework.md" trigger="always (unless --fast)"/>
+
+<HARD-GATE>
+Score all 5 dimensions. If 2+ dimensions score ❌ → BLOCK graft.
+If 1 dimension scores ❌ → WARN + require explicit user override.
+Only --fast skips this gate entirely.
+</HARD-GATE>
+
+Present challenge results to user:
+```
+## Challenge Gate Results
+
+| Dimension | Score | Detail |
+|-----------|-------|--------|
+| License | ✅ | MIT — compatible |
+| Stack Fit | ⚠️ | Redux → Zustand migration needed |
+| Scope | ✅ | 6 files, ~400 LOC — manageable |
+| Quality | ✅ | Typed, tested, documented |
+| Maintenance | ⚠️ | Last commit 4 months ago |
+
+**Verdict: PROCEED with caveats** (0 ❌, 2 ⚠️)
+```
+
+Wait for user approval (unless `--auto`).
+
+### Step 5 — Plan Adaptation
+
+Based on mode, produce adaptation plan:
+
+**Compare mode** → skip to output. Write comparison report and STOP.
+
+**Copy mode** → list files to transplant, import path changes, config adjustments. Minimal changes only.
+
+**Port mode** → for each source component, describe the rewrite:
+- Source pattern → local pattern mapping
+- Dependencies to replace (Redux→Zustand, Jest→Vitest)
+- Files to create/modify in local project
+- What to keep vs what to rewrite from scratch
+
+**Improve mode** → copy plan + improvement list:
+- Anti-patterns to fix (mutations, any types, missing error handling)
+- Missing tests to add
+- Deprecated APIs to upgrade
+- Convention mismatches to align
+
+Present plan to user. Wait for approval (unless `--auto`).
+
+### Step 6 — Execute
+
+**Compare mode**: Output report → emit `graft.complete` → done.
+
+**Copy/Port/Improve modes**:
+1. Create/modify files per adaptation plan
+2. For port/improve: invoke `rune:fix` for complex rewrites
+3. For improve: invoke `rune:review` on grafted code
+4. Run project verification (lint, type-check, test if applicable)
+5. Clean up temp clone dir
+
+**Post-execution**: Emit `graft.complete` signal with payload:
+```yaml
+graft.complete:
+  mode: "port|copy|improve|compare"
+  source_url: "<url>"
+  files_changed: ["src/auth/middleware.ts", "src/auth/types.ts"]
+  challenge_score: { license: "pass", stack: "warn", scope: "pass", quality: "pass", maintenance: "warn" }
+```
+
+## Output Format
+
+### Compare Mode Output
+```markdown
+## Graft Comparison: [feature] — [source repo] vs [local]
+
+### Summary
+[2-3 sentences: what was compared, key differences]
+
+### Comparison
+| Aspect | Source | Local | Winner | Notes |
+|--------|--------|-------|--------|-------|
+| [aspect] | [approach] | [approach] | [which] | [why] |
+
+### Recommendations
+- [what to adopt from source]
+- [what to keep from local]
+- [what to graft: specific files/patterns]
+```
+
+### Port/Copy/Improve Output
+```markdown
+## Graft Complete: [feature] from [source]
+
+### Mode: [port|copy|improve]
+### Files Changed
+- `path/file.ts` — [new|modified] — [what changed]
+
+### Adaptations Made
+- [adaptation 1]
+- [adaptation 2]
+
+### Verify
+- [ ] `npm run lint` passes
+- [ ] `npm run test` passes
+- [ ] Feature works as expected
+```
+
+## Returns
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `mode` | enum | port, compare, copy, improve |
+| `source_url` | string | Source repository URL |
+| `files_changed` | string[] | List of created/modified local files |
+| `challenge_score` | object | 5-dimension scores (pass/warn/fail) |
+| `status` | enum | DONE, DONE_WITH_CONCERNS, BLOCKED |
+| `comparison_report` | string? | Markdown report (compare mode only) |
+
+## Constraints
+
+1. MUST run challenge gate before any code changes — no blind copying
+2. MUST clean up temp clone directories after completion
+3. MUST detect and warn about license incompatibility before proceeding
+4. MUST use sparse checkout for repos >100MB — never full clone large repos
+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
+
+## Mesh Gates
+
+| Gate | Requires | If Missing |
+|------|----------|------------|
+| Challenge Gate | 5-dimension score with 0-1 ❌ | BLOCK if 2+ ❌, WARN if 1 ❌ |
+| Scout Gate | Local codebase scanned | Invoke `rune:scout` first |
+| Scope Gate | Target feature ≤15 files | WARN user, suggest narrowing |
+
+## Sharp Edges
+
+| Failure Mode | Severity | Mitigation |
+|---|---|---|
+| 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 |
+| 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 |
+| Port mode when copy would suffice (wasted effort) | MEDIUM | Mode decision tree suggests optimal mode |
+
+## Self-Validation
+
+```
+SELF-VALIDATION (run before emitting graft.complete):
+- [ ] Challenge gate was executed (or --fast acknowledged)
+- [ ] All grafted files follow local naming conventions
+- [ ] No source-specific imports remain (wrong paths, missing packages)
+- [ ] License compatibility confirmed (or user override documented)
+- [ ] Temp clone directory cleaned up
+- [ ] Grafted code compiles/lints without new errors
+IF ANY check fails → fix before reporting done. Do NOT defer to completion-gate.
+```
+
+## Cross-cutting Updates
+
+If this skill is added to the repo (first time):
+- [ ] `README.md` — skill count (61→62), L2 count (28→29)
+- [ ] `docs/ARCHITECTURE.md` — add graft to L2 list
+- [ ] `CLAUDE.md` — add graft to L2 list, routing table, skill count
+- [ ] `docs/index.html` — update meta stats if applicable
+
+## Done When
+
+- Input parsed: URL, mode, speed flags extracted
+- Source fetched and scoped (sparse clone or WebFetch)
+- Source analyzed: patterns, dependencies, stack understood
+- Challenge gate passed (5 dimensions scored, 0-1 ❌)
+- Local codebase scanned for conventions
+- Adaptation plan produced and approved
+- Code grafted per mode (port/copy/improve/compare)
+- Verification passed (lint, type-check, tests)
+- Temp files cleaned up
+- `graft.complete` signal emitted
+- Self-Validation: all checks passed
+
+## Cost Profile
+
+~2000-4000 tokens input (SKILL.md + 1-2 references), ~3000-8000 tokens output (analysis + adaptation + code). Sonnet for execution. Heaviest when port mode rewrites significant code — but that's where the value is highest.
+
+**Scope guardrail**: Do not become a general-purpose code review tool. Graft analyzes external code for adoption purposes only — use `rune:review` for reviewing your own code, `rune:research` for general technology research.