@rune-kit/rune 2.8.0 → 2.10.0

package/skills/autopsy/references/repo-analysis-patterns.md

@@ -0,0 +1,113 @@
+# Repo Analysis Patterns
+
+Reference for autopsy Step 0 (repo intelligence) and cross-cutting analysis.
+
+## GitHub API Metrics Interpretation
+
+| Metric | Healthy | Warning | Critical |
+|--------|---------|---------|----------|
+| Commits/week (avg last 12w) | > 5 | 1-5 | < 1 |
+| Contributors (all-time) | > 5 | 2-4 | 1 (bus factor) |
+| Open issues / total issues | < 30% | 30-60% | > 60% |
+| Days since last push | < 14 | 14-90 | > 90 |
+| Stars/fork ratio | > 5:1 | 2-5:1 | < 2:1 (fork-heavy = fragmentation) |
+
+## Bus Factor Assessment
+
+Bus factor = number of contributors who authored > 10% of recent commits (last 6 months).
+
+```bash
+# Bus factor calculation
+git shortlog -sn --since="6 months ago" | awk '{total+=$1; print}' | \
+  awk -v t=$(git shortlog -sn --since="6 months ago" | awk '{s+=$1}END{print s}') \
+  '{pct=$1/t*100; if(pct>10) count++} END{print "Bus factor:", count}'
+```
+
+| Bus Factor | Risk | Action |
+|-----------|------|--------|
+| 1 | Critical | Flag in report — single point of failure |
+| 2-3 | Moderate | Note in report — knowledge concentration |
+| 4+ | Low | Healthy distribution |
+
+## Hotspot-Complexity Correlation
+
+Files that are BOTH hotspots (high change frequency) AND high complexity are the highest-priority rescue targets. Plot on a 2x2 matrix:
+
+```
+                High Complexity
+                     |
+    Refactor NOW     |    Monitor
+    (hot + complex)  |    (cold + complex)
+  -------------------+-------------------
+    Leave alone      |    Review
+    (hot + simple)   |    (cold + simple)
+                     |
+                Low Complexity
+        High Churn ←————→ Low Churn
+```
+
+Priority order: hot+complex > cold+complex > hot+simple > cold+simple.
+
+## Dependency Health Signals
+
+### Outdated packages
+```bash
+# Node.js
+npx npm-check-updates --format group 2>/dev/null | head -40
+
+# Python
+pip list --outdated --format columns 2>/dev/null | head -20
+```
+
+### Known vulnerabilities
+```bash
+# Node.js
+npm audit --json 2>/dev/null | jq '.metadata.vulnerabilities'
+
+# Python
+pip-audit --format json 2>/dev/null | jq '.dependencies | length'
+```
+
+### Circular dependency detection
+```bash
+# Node.js (madge)
+npx madge --circular --extensions ts,js src/ 2>/dev/null
+
+# Python (pydeps)
+pydeps --no-output --show-cycles . 2>/dev/null
+```
+
+## Dead Code Heuristics
+
+A file is likely dead code if ALL of these are true:
+1. No other file imports it (check with grep/madge)
+2. Not referenced in any config (webpack entry, tsconfig paths, package.json bin/main)
+3. Last modified > 6 months ago
+4. Not a test file, fixture, or migration
+
+False positive checklist (do NOT flag these as dead):
+- Dynamic imports (`import()`, `require(variable)`)
+- Plugin/middleware loaded by config (e.g., babel plugins, ESLint rules)
+- CLI entry points referenced in package.json `bin`
+- Database migrations (executed by ORM, not imported)
+- Template files loaded by path string
+
+## Velocity Trend Analysis
+
+Compare commit counts across 3-month windows to detect trajectory:
+
+| Pattern | Signal | Interpretation |
+|---------|--------|---------------|
+| M1 > M2 > M3 | Decelerating | Project may be winding down or blocked |
+| M1 < M2 < M3 | Accelerating | Active development, check for quality regression |
+| M1 ~ M2 ~ M3 | Stable | Healthy maintenance pace |
+| Spiky (high variance) | Irregular | Deadline-driven development — check quality around spikes |
+
+```bash
+# Monthly commit counts for last 6 months
+for i in 0 1 2 3 4 5; do
+  month=$(date -d "$i months ago" +%Y-%m 2>/dev/null || date -v-${i}m +%Y-%m)
+  count=$(git log --after="$month-01" --before="$month-31" --oneline 2>/dev/null | wc -l)
+  echo "$month: $count commits"
+done
+```

package/skills/ba/SKILL.md

@@ -3,7 +3,7 @@ name: ba
 description: Business Analyst agent. Deeply understands user requirements before any planning or coding begins. Asks probing questions, identifies hidden requirements, maps stakeholders, defines scope boundaries, and produces a structured Requirements Document that plan and cook consume.
 metadata:
   author: runedev
-  version: "0.4.0"
+  version: "0.5.0"
   layer: L2
   model: opus
   group: creation
@@ -34,6 +34,7 @@ Output is a Requirements Document → hand off to rune:plan for implementation p
 - `research` (L3): look up similar products, APIs, integrations
 - `plan` (L2): hand off Requirements Document for implementation planning
 - `brainstorm` (L2): when multiple approaches exist for a requirement
+- `design` (L2): when requirements include UI/UX components — hand off visual requirements
 
 ## Called By (inbound)
 
@@ -64,7 +65,7 @@ Read the user's request. Classify the requirement type:
 | Greenfield | "new project", "build from scratch" | Full BA + market context |
 
 If Bug Fix → skip BA, route to cook/debug directly.
-If Refactor → light version (Step 1 + Step 4 only).
+If Refactor → light version (Step 1 + Step 4 only). Skip Steps 2, 2.5, 3, 5, 6.
 
 If existing codebase → invoke `rune:scout` for context before proceeding.
 
@@ -110,6 +111,72 @@ O: 30% faster incident detection (measurable KPI)
 - Product/UX feature → Jobs-to-be-Done (keeps focus on user motivation)
 - Integration → 5 Questions only (frameworks add noise for plumbing tasks)
 
+### Step 2.5 — Ambiguity Scoring (Execution Gate)
+
+After each question round, compute an **Ambiguity Score** to determine if requirements are clear enough to proceed. This prevents premature handoff to `plan` with vague inputs.
+
+#### Scoring Formula
+
+```
+Ambiguity = 1 - weighted_average(dimensions)
+
+Dimensions (weights vary by requirement type):
+  Greenfield:  Goal (40%) + Constraints (30%) + Success Criteria (30%)
+  Feature:     Goal (30%) + Constraints (30%) + Success Criteria (20%) + Integration (20%)
+  Integration: Goal (20%) + Constraints (25%) + Success Criteria (20%) + API Contract (35%)
+```
+
+#### Dimension Scoring (0.0 – 1.0)
+
+| Dimension | 0.0 (Unknown) | 0.5 (Partial) | 1.0 (Clear) |
+|-----------|---------------|----------------|--------------|
+| **Goal** | "Make it better" | "Improve dashboard performance" | "Dashboard loads in <2s with 10k rows" |
+| **Constraints** | No constraints mentioned | "Use existing DB" | "PostgreSQL 15, no new deps, GDPR compliant" |
+| **Success Criteria** | "It should work" | "Users can see their data" | "AC-1.1: GIVEN 10k rows WHEN page loads THEN render <2s" |
+| **Integration** | "Connect to the API" | "Use REST, need auth" | "POST /api/v2/orders, OAuth2, rate limit 100/min" |
+| **API Contract** | "It sends data somewhere" | "JSON payload to endpoint" | "OpenAPI spec provided, request/response schemas defined" |
+
+#### Threshold Gate
+
+| Ambiguity | Level | Action |
+|-----------|-------|--------|
+| **< 15%** | Crystal Clear | Proceed to Step 3 immediately |
+| **15-25%** | Acceptable | Proceed with noted assumptions — flag gaps in Requirements Doc |
+| **25-40%** | Unclear | Ask 1-2 targeted follow-up questions on weakest dimension |
+| **> 40%** | Blocked | Do NOT proceed. Re-ask the weakest dimension question with examples |
+
+<HARD-GATE>
+NEVER hand off to plan with Ambiguity > 40%.
+If user insists "just build it" at > 40%, respond:
+"Ambiguity is [X]% — the weakest area is [dimension]. One more answer cuts this in half: [targeted question]"
+</HARD-GATE>
+
+#### Scoring After Each Question
+
+After each of the 5 Questions (Step 2), update the score:
+
+```
+Round 1 (WHO):    Goal ≈ 0.3, others = 0.0 → Ambiguity ≈ 91%
+Round 2 (WHAT):   Goal ≈ 0.7, Success ≈ 0.3 → Ambiguity ≈ 72%
+Round 3 (WHY):    Goal ≈ 0.9, Success ≈ 0.5 → Ambiguity ≈ 47%
+Round 4 (BOUNDS): Constraints ≈ 0.6 → Ambiguity ≈ 30%
+Round 5 (CONSTR): Constraints ≈ 0.9 → Ambiguity ≈ 12% ✅
+```
+
+If Ambiguity drops below 15% before all 5 questions are asked (e.g., user provides a detailed PRD), skip remaining questions and proceed. The gate is about clarity, not ceremony.
+
+#### Display Format
+
+After completing Step 2, show the user:
+
+```
+Clarity Score: [100 - ambiguity]%
+  Goal:             [██████████] 0.9
+  Constraints:      [████████░░] 0.8
+  Success Criteria: [██████░░░░] 0.6  ← weakest
+  Status: ACCEPTABLE (ambiguity 23%) — proceeding with noted gaps
+```
+
 ### Step 3 — Hidden Requirement Discovery
 
 After the 5 questions, analyze for requirements the user DIDN'T mention:
@@ -332,11 +399,14 @@ Known failure modes for this skill. Check these before declaring done.
 | Requirements doc too verbose (>500 lines) | MEDIUM | Max 200 lines — concise, actionable, testable |
 | Skipping BA for "simple" features that turn out complex | HIGH | Let cook's complexity detection trigger BA, not user judgment |
 | Recommending shortcuts without Completeness Score | MEDIUM | Step 3.5: every option needs X/10 score + dual effort estimate (human vs AI). "90% coverage" is a red flag when 100% costs 15 min more |
+| Handing off to plan with ambiguity > 40% | CRITICAL | Step 2.5 HARD-GATE: compute ambiguity score after elicitation, block handoff if > 40%, ask targeted follow-up on weakest dimension |
+| Skipping ambiguity scoring because "user seems clear" | HIGH | Always compute the score — perceived clarity ≠ measured clarity. The formula catches gaps humans miss |
 
 ## Done When
 
 - Requirement type classified (feature/refactor/integration/greenfield)
 - 5 probing questions asked and answered (or extracted from spec/PRD)
+- Ambiguity Score computed and displayed — must be ≤ 40% before proceeding (≤ 25% preferred)
 - Hidden requirements discovered and confirmed with user
 - Scope defined (in/out/assumptions/dependencies)
 - User stories with testable acceptance criteria produced

package/skills/brainstorm/SKILL.md

@@ -87,6 +87,7 @@ Direct API call ≠ Wrapper/middleware layer ≠ Reverse engineering ≠ Browser
 ## Calls (outbound)
 
 - `plan` (L2): when idea is selected and needs structuring into actionable steps
+- `design` (L2): when selected approach has UI/UX implications — hand off visual decisions
 - `research` (L3): gather data for informed brainstorming (existing solutions, benchmarks)
 - `trend-scout` (L3): market context and trends for product-oriented brainstorming
 - `problem-solver` (L3): structured reasoning frameworks (SCAMPER, First Principles, 6 Hats)

package/skills/cook/SKILL.md

@@ -5,13 +5,13 @@ context: fork
 agent: general-purpose
 metadata:
   author: runedev
-  version: "2.1.0"
+  version: "2.3.0"
   layer: L1
   model: sonnet
   group: orchestrator
   tools: "Read, Write, Edit, Bash, Glob, Grep"
-  emit: phase.complete
-  listen: plan.ready, review.complete
+  emit: phase.complete, checkpoint.request
+  listen: plan.ready, review.complete, ideas.ready, preflight.passed, verification.complete
 ---
 
 # cook
@@ -73,6 +73,7 @@ When `--template <name>` is provided, cook loads a pre-built workflow template i
 - Contains "security", "auth", "vulnerability", "CVE" → `security`
 - Contains "urgent", "hotfix", "production" → `hotfix`
 - Contains "quick", "just", "chỉ cần", "copy", "move", "rename", "bump" → `nano`
+- Contains "graft", "port from", "copy from repo", "clone feature from" → **delegate to `rune:graft`** (not a cook chain — hand off entirely)
 - Contains `--template` → load template workflow (see above)
 - Default → `feature`
 
@@ -379,6 +380,11 @@ If the coder model needs info from other phases, it's in the Cross-Phase Context
 
 Quality checks run in **two stages** — spec compliance gates code review. Reviewing code quality before verifying it matches the spec wastes effort on code that may need rewriting.
 
+**Signal dispatch ordering**: When `fix` emits `code.changed`, 4 listeners react (preflight, sentinel, test, review). Cook coordinates dispatch order — do NOT let all 4 fire simultaneously:
+- **Stage 1**: preflight + sentinel (parallel — independent checks)
+- **Stage 2**: test (after Stage 1 passes — no point testing non-compliant code)
+- **Stage 3**: review (after test passes — review verified code only)
+
 ```
 STAGE 1 (parallel):
   Launch 5a (preflight) + 5b (sentinel) simultaneously.
@@ -806,6 +812,29 @@ When invoked by `team` with a NEXUS Handoff, include the Deliverables table —
 | Cook Report | Markdown (inline) | Emitted at end of session |
 | Session state | Markdown | `.rune/decisions.md`, `.rune/progress.md`, `.rune/conventions.md` |
 
+## Document Ownership
+
+| Scope | Access | Files |
+|-------|--------|-------|
+| **Owns** (read + write) | `.rune/plan-*.md`, `.rune/progress.md`, `.rune/decisions.md`, `.rune/conventions.md`, source files per approved plan |
+| **Reads** (never writes) | `CLAUDE.md`, `SKILL.md` (any), `.rune/contract.md`, `.rune/checkpoint.md` |
+| **Never modifies** | `compiler/**`, `extensions/**`, `PACK.md`, other skills' `SKILL.md`, `.rune/learnings.jsonl` |
+
+When delegating to sub-skills (scout, plan, test, review), each sub-skill owns its own output. Cook coordinates but does not overwrite sub-skill artifacts.
+
+## Anti-Patterns
+
+Common multi-agent failures to explicitly avoid. These are NOT edge cases — they are the most frequent cook failures in production.
+
+| Anti-Pattern | Why It Fails | Correct Approach |
+|---|---|---|
+| **Bypass hierarchy** — skipping scout/plan and jumping to Phase 4 code | Builds wrong thing. Most "wasted work" traces back to missing Phase 1-2 | Follow phase gates. Even "obvious" tasks benefit from 30s of scout |
+| **Shadow decisions** — making architectural choices without logging to decisions.md | Next session repeats the same debate. Team agents contradict each other | Log every non-trivial choice via `decisions.md` or `journal` |
+| **Gold-plating** — adding "nice-to-have" features not in the approved plan | Scope creep, delayed delivery, untested code paths | Build ONLY what's in the plan. Log extras as follow-up tasks |
+| **Test-after** — writing tests after implementation instead of before (TDD violation) | Tests validate implementation bugs, not requirements. Coverage looks good but misses edge cases | Phase 3 (RED) before Phase 4 (GREEN). Always |
+| **Monolithic commit** — one giant commit with all changes | Impossible to revert partially. Review is overwhelming | Commit per phase or per logical unit. Small, reviewable diffs |
+| **Assumption-based implementation** — guessing requirements instead of asking | Builds the wrong thing confidently. User discovers mismatch late | If ambiguous, ask. 30s of clarification saves 30min of rework |
+
 ## Sharp Edges
 
 <MUST-READ path="references/sharp-edges.md" trigger="before declaring done — review all 18 failure modes"/>

package/skills/cook/references/output-format.md

@@ -32,6 +32,39 @@ Also defines the NEXUS Deliverables table format used when cook is invoked by `t
 - Saved to .rune/progress.md
 ```
 
+## Chain Metadata (Cross-Skill Data Forwarding)
+
+Every Cook Report MUST end with a `chain_metadata` YAML block. This enables downstream skills to consume cook's output data without parsing prose. See `docs/references/chain-metadata.md` for the full contract.
+
+```yaml
+chain_metadata:
+  skill: "rune:cook"
+  version: "2.2.0"
+  status: "[same as Cook Report status]"
+  domain: "[area worked on — e.g., auth, payments, compiler]"
+  files_changed:
+    - "[list of files created/modified in this session]"
+  exports:
+    commit_hash: "[actual git hash]"
+    files_changed_count: [N]
+    test_results: { passed: [N], failed: [N], coverage: [N] }
+    quality_gates: { preflight: "[PASS/WARN/FAIL]", sentinel: "[PASS/WARN/FAIL]", review: "[PASS/WARN/FAIL]" }
+    phase_count: [N]
+    concerns: []  # populated if DONE_WITH_CONCERNS
+  suggested_next:  # 1-3 data-driven recommendations based on THIS output
+    - skill: "rune:[skill]"
+      reason: "[grounded in actual data — not generic advice]"
+      consumes: ["[export keys the suggested skill would use]"]
+```
+
+**Rules for suggested_next:**
+- Base suggestions on ACTUAL output data (sentinel WARN → suggest deeper security review, low coverage → suggest more tests)
+- Never suggest skills that already ran successfully in this session
+- Status-aware: BLOCKED → suggest debug/fix, DONE → suggest review/deploy/test
+- Max 3 suggestions, ordered by priority
+
+**When NOT to emit:** When cook is invoked as a sub-step of `autopilot` or `team` — the orchestrator emits its own chain_metadata at the end.
+
 ## Usage Rules
 
 - When cook is invoked **standalone** (not by team): Deliverables table is optional

package/skills/db/SKILL.md

@@ -8,6 +8,7 @@ metadata:
   model: sonnet
   group: development
   tools: "Read, Write, Edit, Bash, Glob, Grep"
+  emit: db.migrated
 ---
 
 # db

package/skills/debug/SKILL.md

@@ -3,7 +3,7 @@ name: debug
 description: Root cause analysis for bugs and unexpected behavior. Traces errors through code, uses structured reasoning, and hands off to fix when cause is found. Core of the debug↔fix mesh.
 metadata:
   author: runedev
-  version: "1.0.0"
+  version: "1.1.0"
   layer: L2
   model: sonnet
   group: development
@@ -405,6 +405,28 @@ Debug returns one of four statuses to its caller (cook, fix, test, surgeon). The
 | Fix recommendation | Inline (Debug Report) | Direction only — no code changes |
 | Debug knowledge base entry | Markdown | `.rune/debug/knowledge-base.md` (appended on success) |
 
+## Chain Metadata
+
+Append to Debug 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:debug"
+  version: "1.1.0"
+  status: "[DONE | DONE_WITH_CONCERNS | NEEDS_CONTEXT | BLOCKED]"
+  domain: "[area debugged]"
+  files_changed: []  # debug never changes files
+  exports:
+    root_cause: { file: "[path]", line: [N], explanation: "[cause]" }
+    severity: "[critical | high | medium | low]"
+    confidence: "[high | medium | low]"
+    fix_recommendation: "[direction for fix skill]"
+  suggested_next:
+    - skill: "rune:fix"
+      reason: "[grounded in root cause — e.g., 'Critical race condition found in auth.ts:42']"
+      consumes: ["root_cause", "fix_recommendation"]
+```
+
 ## Sharp Edges
 
 | Failure Mode | Severity | Mitigation |

package/skills/deploy/SKILL.md

@@ -10,7 +10,7 @@ metadata:
   group: delivery
   tools: "Read, Write, Edit, Bash, Glob, Grep"
   emit: deploy.complete
-  listen: security.passed, tests.passed
+  listen: security.passed, tests.passed, docs.updated, audit.complete, db.migrated
 ---
 
 # deploy

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.8.0"
+  version: "0.9.0"
   layer: L2
   model: sonnet
   group: development
@@ -271,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.