@rune-kit/rune 2.7.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/completion-gate/SKILL.md

@@ -4,7 +4,7 @@ description: "Validates agent claims against evidence trail. Catches 'done' with
 user-invocable: false
 metadata:
   author: runedev
-  version: "1.7.0"
+  version: "1.8.0"
   layer: L3
   model: haiku
   group: validation
@@ -91,6 +91,30 @@ Why: Self-Validation catches domain-specific quality issues that generic claim m
 If a skill has Self-Validation and ANY check is UNCONFIRMED or CONTRADICTED → overall verdict cannot be CONFIRMED, even if all explicit claims pass.
 </HARD-GATE>
 
+### Step 1d — Execution Loop Audit
+
+Before validating claims, audit the agent's tool call pattern for execution loops that indicate the agent was stuck but didn't report it:
+
+**Classify the agent's tool calls** from this workflow into two categories:
+
+| Category | Tools | Expected in Phase 4 |
+|----------|-------|---------------------|
+| **Observation** | Read, Grep, Glob, Bash(grep/ls/cat) | <40% of calls |
+| **Effect** | Write, Edit, Bash(build/test/npm) | >60% of calls |
+
+**Loop patterns to detect**:
+
+| Pattern | Detection | Verdict Impact |
+|---------|-----------|----------------|
+| **Observation chain**: 6+ consecutive observation tools in Phase 4 | Count longest observation-only streak | Add WARN: "Agent had {N}-call observation streak during implementation — possible analysis paralysis" |
+| **Low effect ratio**: <20% effect calls during Phase 4 | `effect_calls / total_calls` | Add WARN: "Only {X}% of Phase 4 calls were writes — agent may have been stuck" |
+| **Repeating tool pattern**: Same tool+args called 3+ times | Hash tool+args, count duplicates | Add WARN: "Agent called {tool}({args}) {N} times — possible loop" |
+| **Budget overrun**: Phase 4 exceeded 50 tool calls for a single-file task | Count Phase 4 calls vs files changed | Add WARN: "50+ tool calls for {N} files changed — disproportionate effort" |
+
+**Scoring impact**: Loop warnings don't change individual claim verdicts but ARE included in the Completion Gate Report under a new `### Execution Efficiency` section. This gives the calling orchestrator signal about whether the agent's process was healthy, not just whether the output was correct.
+
+**Skip if**: Nano/Fast rigor — not enough tool calls to meaningfully analyze.
+
 ### Step 2 — Match Evidence
 
 For each claim, look for corresponding evidence in the conversation context:
@@ -167,8 +191,6 @@ UNCONFIRMED — 1 claim lacks evidence, 1 contradicted. Cannot proceed to commit
 
 ### Step 4.5 — Cross-Phase Integration Check
 
-> From GSD (gsd-build/get-shit-done, 30.8k★): "Phase boundaries are where integration bugs hide."
-
 When validating a completed phase in a multi-phase plan, check for integration gaps between phases:
 
 1. **Orphaned exports** — files/functions created in this phase that claim to be used by future phases (see `## Cross-Phase Context → Exports`) but are not yet importable:
@@ -269,6 +291,7 @@ Completion Gate Report with status (CONFIRMED/UNCONFIRMED/CONTRADICTED), claim v
 | Partial completion claimed as full — 80% done but "implemented" | HIGH | Adversarial checklist: check for partial completion, scope mismatch, evidence-claim alignment |
 | Self-Validation skipped — skill has checks but gate ignores them | HIGH | Step 1c: extract Self-Validation from skill's SKILL.md, treat each as implicit claim. Missing = UNCONFIRMED |
 | Plan says done but phase file has unchecked tasks | HIGH | Step 5.5: diff changed files vs phase plan's Files Touched + Tasks sections |
+| Agent stuck in observation loop but claims "implemented" | HIGH | Step 1d: Execution Loop Audit detects low effect ratio and observation chains — flags in report even if claims pass |
 
 ## Done When
 

package/skills/context-engine/SKILL.md

@@ -4,7 +4,7 @@ description: "Context window management. Auto-triggered when context is filling
 user-invocable: false
 metadata:
   author: runedev
-  version: "0.8.0"
+  version: "0.9.0"
   layer: L3
   model: haiku
   group: state
@@ -218,6 +218,54 @@ When processing streaming LLM output (e.g., in skills that invoke AI calls or pr
 - **JSON output**: accumulate until the closing brace — partial JSON can't be parsed
 - **Short responses** (<100 chars expected): overhead of boundary detection exceeds benefit
 
+## Artifact Folding (Large Output Management)
+
+When tool results are excessively large, they consume disproportionate context without proportionate value. **Artifact folding** saves the full output to a file and replaces it in context with a compact preview.
+
+### When to Fold
+
+| Condition | Action |
+|-----------|--------|
+| Tool output > 4000 characters | Fold to artifact |
+| Tool output > 120 lines | Fold to artifact |
+| Multiple tool outputs from the same command class (e.g., 5+ Grep results) | Fold all into single artifact |
+| Code block output > 200 lines | Fold to artifact |
+
+### Folding Procedure
+
+1. **Save full output** to `.rune/artifacts/artifact-{timestamp}-{tool}.md`:
+   ```markdown
+   # Artifact: {tool_name} output
+   Generated: {timestamp}
+   Command: {tool_call_summary}
+   
+   {full_output}
+   ```
+
+2. **Replace in context** with a compact preview:
+   ```
+   [FOLDED: {tool_name} output — {line_count} lines, {char_count} chars]
+   Preview (first 10 lines):
+   {first_10_lines}
+   ...
+   Full output: .rune/artifacts/artifact-{timestamp}-{tool}.md
+   Use Read to access the full artifact if needed.
+   ```
+
+3. **On compaction**: Artifact files survive compaction — the continuation summary references them by path. This means large outputs are preserved across compaction boundaries without consuming context.
+
+### Rules
+
+- **Never fold user messages** — only tool outputs
+- **Never fold error outputs** — errors need full visibility for debugging
+- **Never fold outputs < 1000 chars** — folding overhead exceeds savings
+- **Fold preemptively in YELLOW/ORANGE** — don't wait for RED to start managing output size
+- **Clean up artifacts** at session end: artifacts older than the current session can be deleted (they're already in git history or irrelevant)
+
+### Why
+
+A single `Grep` across a large codebase can return 3000+ lines. Without folding, this consumes ~4000 tokens of context — often more than the rest of the conversation combined. Folding preserves the information (accessible via Read) while keeping context lean. Combined with the Structured Summary compaction technique, artifact folding enables much longer productive sessions.
+
 ## Context Health Levels
 
 ```

package/skills/cook/SKILL.md

@@ -5,13 +5,13 @@ context: fork
 agent: general-purpose
 metadata:
   author: runedev
-  version: "2.0.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.
@@ -634,6 +640,46 @@ Stuck patterns (all banned):
 A wrong first attempt that produces feedback beats perfect understanding that never ships.
 </HARD-GATE>
 
+### Observation/Effect Ratio Tracking
+
+Track every tool call during Phase 4 (IMPLEMENT) as either **observation** (read-only) or **effect** (modifies state):
+
+| Category | Tool Examples |
+|----------|--------------|
+| **Observation** | Read, Grep, Glob, Bash(grep/ls/cat/git log) |
+| **Effect** | Write, Edit, Bash(npm/build/test/mkdir) |
+
+**Detection rules** (check every 8 tool calls during Phase 4):
+
+| Pattern | Threshold | Signal | Action |
+|---------|-----------|--------|--------|
+| **Observation chain** | 6+ consecutive observation tools with zero effects | Agent is stuck reading, not building | Inject: "OBSERVATION LOOP — 6 reads without writing. Act on what you know or report BLOCKED." |
+| **Low effect ratio** | In last 10 calls, effects < 15% | Agent is in analysis mode, not implementation | Inject: "Effect ratio below 15%. Phase 4 is IMPLEMENT — write code, don't just read it." |
+| **Diminishing returns** | Last 3 observations found <2 new relevant facts combined | Searching is no longer productive | Inject: "Diminishing returns — last 3 reads added nothing new. Synthesize and act." |
+| **Repeating sequences** | A-B-A-B or A-B-C-A-B-C pattern across 6+ calls | Circular behavior | Inject: "REPEATING SEQUENCE detected. Break the cycle — try a different approach or report BLOCKED." |
+
+**Important**: These are injected as advisor messages, not hard blocks. The agent can continue if it has good reason, but the message forces conscious acknowledgment of the pattern.
+
+**Skip if**: Phase 1 (UNDERSTAND) — observation-heavy is expected during research. Only track during Phase 4+ where effects should dominate.
+
+### Budget-Aware Phase Progression
+
+Beyond the existing Exit Conditions (MAX_DEBUG_LOOPS, MAX_QUALITY_LOOPS, etc.), track **cumulative budget** across the entire cook session:
+
+| Budget | Limit | What Happens at Limit |
+|--------|-------|----------------------|
+| **Phase 4 react budget** | 15 tool calls per task within Phase 4 | Force: move to next task or report partial completion |
+| **Global replan budget** | 2 replans per session (Phase 4 Step 6) | Force: proceed with current plan or escalate to user |
+| **Quality retry budget** | 3 total quality re-runs across 5a-5d | Force: ship with known issues documented, don't loop |
+| **Total session tool calls** | 150 calls | Force: save state via session-bridge, compact or pause |
+
+**Hard override rules**:
+- If react budget exhausted for a task but task is IN_PROGRESS → force CONTINUE to next task (don't re-attempt)
+- If replan budget exhausted but plan still failing → force escalation (don't attempt 3rd replan)
+- If quality retry budget exhausted → emit concerns in Cook Report, proceed to commit with documented caveats
+
+**Why**: Without hard budgets, agents get trapped in local optimization loops — retrying the same failing approach indefinitely. Budget constraints force escalation or acceptance of partial results, which is always better than an infinite loop.
+
 ### Hash-Based Tool Loop Detection
 
 <MUST-READ path="references/loop-detection.md" trigger="when same tool+args+result appears to be repeating"/>
@@ -766,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: "0.9.0"
+  version: "1.1.0"
   layer: L2
   model: sonnet
   group: development
@@ -178,6 +178,38 @@ After successful root cause identification (Step 5), append entry:
 
 This prevents re-debugging the same issue across sessions.
 
+### Step 2d: Known Error Pattern Matching
+
+Before forming hypotheses, match the error against common **error archetypes**. If a match is found, skip directly to the known fix approach — no hypothesis cycling needed.
+
+**Error Pattern Catalog**:
+
+| Pattern ID | Detection (Error Type + Keywords) | Root Cause | Recovery Hint |
+|------------|----------------------------------|------------|---------------|
+| `STATELESS_LOSS` | `NameError` / `ReferenceError` + variable defined in previous step | Execution context doesn't persist between tool calls | "Combine all variable definitions and usage in a single code block" |
+| `MODULE_NOT_FOUND` | `ModuleNotFoundError` / `Cannot find module` | Dependency not installed or wrong import path | "Check package.json/requirements.txt. Install missing dep, then retry" |
+| `TYPE_MISMATCH` | `TypeError` + "undefined is not a function" / "has no attribute" | Wrong type passed through chain — object where primitive expected or vice versa | "Trace the value backward: where was it created? What type was intended?" |
+| `ASYNC_DEADLOCK` | `TimeoutError` / `Promise` + hang / `await` missing | Async/await misuse — missing await, blocking in async, unresolved promise | "Check: missing await? Blocking call in async context? Unresolved promise chain?" |
+| `PATH_MISMATCH` | `ENOENT` / `FileNotFoundError` + path string in error | Relative vs absolute path, or CWD differs from expected | "Print resolved path. Check CWD. Use path.resolve() or Path.resolve()" |
+| `ENCODING_ISSUE` | `UnicodeDecodeError` / `SyntaxError` + quotes/special chars | Non-ASCII characters in code or data (curly quotes, BOM, etc.) | "Check for smart quotes, BOM markers, or non-ASCII in the file. Use `file` command to check encoding" |
+| `ENV_MISSING` | `KeyError` / "undefined" + env var name | Environment variable not set or .env not loaded | "Check .env file exists and is loaded. Verify var name matches exactly (case-sensitive)" |
+| `CIRCULAR_IMPORT` | `ImportError` + "partially initialized" / "circular" | Module A imports B imports A | "Restructure: move shared types to a third module, or use lazy imports" |
+
+**Matching rules**:
+- Match on error type + 2+ keywords from the Detection column
+- If matched: report the pattern ID and recovery hint in the Debug Report, then proceed to test the known fix approach as H1 (highest priority hypothesis)
+- If NOT matched: proceed to Step 3 (form hypotheses from scratch)
+
+**Error fingerprinting**: When comparing errors across hypothesis cycles, normalize these elements before comparison:
+- Line numbers → `<LINE>`
+- File paths → `<PATH>`
+- Variable/function names → `<IDENT>`
+- Timestamps → `<TIME>`
+
+Two errors with the same fingerprint after normalization are the SAME error — don't re-investigate, the previous hypothesis result still applies.
+
+**Catalog growth**: After each successful debug (Step 5), check: does this error pattern match any existing catalog entry? If not, and the root cause is generalizable (not project-specific), suggest adding it to the catalog via a note in the Debug Report: "New pattern candidate: [pattern] — consider adding to error catalog."
+
 ### Step 3: Form Hypotheses
 
 List exactly 2-3 possible root causes — no more, no fewer.
@@ -373,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 |
@@ -390,6 +444,8 @@ Debug returns one of four statuses to its caller (cook, fix, test, surgeon). The
 | Running same test 3x with same failure without code change | MEDIUM | True stuck loop — no progress possible. Hand off to fix with current incomplete diagnosis |
 | Scope creep via debug — "while investigating, also fix X" | HIGH | Step 1.5 Scope Lock: lock edits to narrowest affected directory. Fix recommendations MUST stay within boundary. Expand only with user confirmation |
 | Debug report recommends touching 5+ unrelated files | HIGH | Symptom of fixing at crash sites instead of source. Backward trace (Step 2) to find origin. If truly 5+ files → likely architectural issue → escalate via 3-Fix Rule |
+| Re-investigating known error patterns from scratch | MEDIUM | Step 2d: match error against Known Error Pattern Catalog first — skip hypothesis cycling for recognized patterns |
+| Same error fingerprint across cycles treated as different errors | MEDIUM | Step 2d: normalize line numbers, paths, variable names before comparison — same fingerprint = same error |
 
 ## Done When
 

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