@rune-kit/rune 2.6.0 → 2.8.0

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.6.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:
@@ -210,6 +232,29 @@ Before emitting verdict, verify evidence quality:
 | Quote matches claim exactly | CONFIRMED |
 | Quote contradicts claim | CONTRADICTED |
 
+### Step 5.5 — Plan Diff Check
+
+When validating a phase within a master plan, diff actual changes against the phase plan file:
+
+1. **Read the active phase plan** — `Glob` for `.rune/plan-*-phase*.md` matching the current phase
+2. **Extract `## Files Touched`** — build a list of expected files (new/modify/delete)
+3. **Extract `## Tasks`** — build a list of all `- [ ]` and `- [x]` items
+4. **Compare against actual changes** — `git diff --name-only` (or file system scan)
+5. **Report**:
+
+| Check | Status |
+|-------|--------|
+| Unchecked task in phase plan (`- [ ]` still exists) | **INCOMPLETE** — task was not done |
+| File in plan's "Files Touched" but not in actual diff | **MISSING** — planned file was never touched |
+| File in actual diff but NOT in plan's "Files Touched" | **UNPLANNED** — scope creep (warn, not block) |
+| All tasks `[x]` AND all planned files touched | **PLAN-ALIGNED** |
+
+```
+Plan Diff: PLAN-ALIGNED | INCOMPLETE (2 unchecked tasks) | MISSING (1 file never touched)
+```
+
+**Skip if**: No active phase plan found (single-task, no master plan). **MANDATORY** for multi-phase master plans.
+
 ## Verdict Rules
 
 ```
@@ -245,6 +290,8 @@ Completion Gate Report with status (CONFIRMED/UNCONFIRMED/CONTRADICTED), claim v
 | Rubber-stamping — all CONFIRMED without scrutiny | HIGH | Default-FAIL mindset: actively seek 3-5 issues. Zero issues = red flag, apply skeptic sweep on weakest 2 claims |
 | 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
 
@@ -252,6 +299,7 @@ Completion Gate Report with status (CONFIRMED/UNCONFIRMED/CONTRADICTED), claim v
 - Each claim matched against tool output evidence
 - Verdict table emitted with claim/evidence/verdict for each item
 - All 3 verification axes (Completeness/Correctness/Coherence) have at least one claim checked
+- Plan diff check passed (if multi-phase): all tasks checked, all planned files touched
 - Overall verdict: CONFIRMED / UNCONFIRMED / CONTRADICTED
 - If not CONFIRMED: specific gaps listed with remediation steps
 

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.6.0"
+  version: "0.9.0"
   layer: L3
   model: haiku
   group: state
@@ -145,6 +145,127 @@ When loading context for a task (Phase 1 of cook, or onboard), use a 4-phase ret
 
 **Key rule**: Stop at 3 high-relevance files, not 10 mediocre ones. Quality > quantity for context loading.
 
+## Compaction Technique: Structured Summary with Continuation Point
+
+When compaction is triggered (RED or approved ORANGE), generate a **structured summary** that replaces the full conversation history while preserving therapeutic continuity — the ability to resume exactly where work left off.
+
+### Summary Structure
+
+The compaction summary MUST include these sections in order:
+
+```markdown
+## Compaction Summary (generated at [tool call count])
+
+### Topics Covered
+- [bullet list of distinct topics/tasks worked on this session]
+
+### Key Decisions Made
+- [decision]: [rationale] — affects [files/modules]
+
+### Active Threads
+- [what was being worked on when compaction triggered — the "where we are now" anchor]
+- Current file: [path], current function/section: [name]
+- Partial progress: [what's done vs what remains in the immediate task]
+
+### Emotional/Priority Context
+- [user urgency level, blocking issues, deadlines mentioned]
+- [any user frustrations or preferences expressed this session]
+
+### Continuation Point
+> Resume: [exact next action to take — not vague "continue working" but specific "implement the validation logic in src/auth/validate.ts:47 using the Zod schema defined in Step 2"]
+```
+
+### Why This Structure
+
+Most compaction loses the **continuation point** — the agent knows WHAT was discussed but not WHERE to resume. The "Active Threads" and "Continuation Point" sections solve this by preserving:
+1. The exact file and function being edited
+2. What's done vs remaining in the current micro-task
+3. The specific next action (not a summary of the plan, but the next concrete step)
+
+### Rules
+
+- Summary MUST be <500 tokens — if longer, you're summarizing too much detail
+- "Active Threads" section is the most critical — get this wrong and the agent restarts from scratch
+- Never include full file contents in the summary — only paths and line references
+- Include user tone/urgency signals — these are lost in pure technical summaries
+
+## Incremental Stream Processing
+
+When processing streaming LLM output (e.g., in skills that invoke AI calls or process tool output incrementally), use **sentence-level buffering** instead of waiting for the full response:
+
+### Pattern: Buffer → Detect Boundary → Act
+
+```
+1. ACCUMULATE: Feed incoming chunks into a text buffer
+2. DETECT: Check for sentence boundaries:
+   - Primary: 40+ chars ending in . ! ? ; :
+   - Secondary: paragraph break (\n\n) with 15+ chars accumulated
+   - Never split mid-word or mid-code-block
+3. EXTRACT: Remove the complete sentence from the buffer
+4. ACT: Process the extracted sentence immediately (e.g., queue for TTS, parse for structured data, update progress display)
+5. CONTINUE: Keep accumulating the next sentence while processing the current one
+```
+
+### When to Use
+
+- **Skills that stream AI responses to the user**: process and display incrementally instead of waiting for the full response
+- **Background note-taking**: extract key points from streaming output as they arrive
+- **Progress reporting**: detect milestone keywords in streaming output to update progress
+
+### When NOT to Use
+
+- **Code generation**: wait for the full code block — partial code is useless
+- **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
 
 ```
@@ -182,7 +303,7 @@ When ORANGE or RED is reached, use this table to determine whether compaction is
 | Research → Planning | YES | Research findings summarize well; key decisions survive |
 | Planning → Implementation | YES | Plan is in files (.rune/plan-*.md); context can reload from artifacts |
 | Debug → Next feature | YES | Debug findings are in Debug Report; fix has the diagnosis |
-| Mid-implementation (Phase 4) | **NO** | Losing file paths, partial changes, and test state is catastrophic |
+| Mid-implementation (Phase 4) | **CONDITIONAL** | Safe ONLY at task boundaries within Phase 4 (after a file is fully written + tested). Never mid-file-edit. See Mid-Loop Compaction below |
 | After failed approach → Pivot | YES | Failed approach should be discarded; fresh context helps |
 | Quality (Phase 5) → Verify | **NO** | Quality findings reference specific file:line in current context |
 | After commit (Phase 7) | YES | Work is persisted in git; safe boundary |
@@ -190,6 +311,22 @@ When ORANGE or RED is reached, use this table to determine whether compaction is
 **What survives compaction**: Task description, file paths mentioned, key decisions, plan reference, current phase.
 **What is lost**: Full file contents read, intermediate reasoning, exact error messages, tool output details.
 
+### Mid-Loop Compaction (Phase 4 Emergency)
+
+> From goclaw (nextlevelbuilder/goclaw, 832★): "Compact during run, not just at session boundary."
+
+When context hits RED during Phase 4 (implementation), compaction IS possible at **clean split points**:
+
+1. **Find a clean boundary**: completed task within the phase (file fully written + tests pass for that file)
+2. **Flush state first**: call `session-bridge` to save progress, then call `neural-memory` to capture decisions
+3. **Split 70/30**: preserve 70% of remaining context for continuation, summarize 30% of completed work
+4. **Never break tool pairs**: compaction MUST NOT split a `tool_use` from its `tool_result` — always keep pairs together
+5. **Inject continuation marker**: after compaction, include: "Resuming Phase 4. Tasks [1-3] complete. Currently on task 4. Plan file: `.rune/plan-X-phaseN.md`"
+
+**Timeout fallback**: If clean boundary can't be found within 30 seconds, create `.rune/.continue-here.md` and pause instead.
+
+**Skip if**: Context is ORANGE (not RED), or fewer than 3 tasks remain in the phase.
+
 ## Context Budget Audit (Baseline Cost Awareness)
 
 MCP tool schemas and agent descriptions consume significant baseline context before any work begins. This section helps identify and reduce invisible context waste.
@@ -251,6 +388,8 @@ Known failure modes for this skill. Check these before declaring done.
 | Injecting stale context from previous session without marking it historical | HIGH | Constraint 3: all loaded context must include session date marker |
 | Premature compaction from over-estimated utilization | MEDIUM | Tool count is directional only — sessions with heavy Read calls may need lower thresholds; only block at confirmed RED |
 | Not activating large-file adjustment on Python/Java codebases | MEDIUM | Track Read calls returning >500 lines; if ≥3 occur, switch to adjusted (0.8x) thresholds for the session |
+| Mid-loop compaction breaks tool_use/tool_result pair | CRITICAL | Always keep tool pairs together — splitting causes orphaned results and context corruption |
+| Mid-loop compaction without flushing state first | HIGH | session-bridge + neural-memory MUST run before compaction — losing unsaved decisions is worse than hitting context limit |
 
 ## Done When
 

package/skills/cook/SKILL.md

@@ -5,7 +5,7 @@ context: fork
 agent: general-purpose
 metadata:
   author: runedev
-  version: "1.7.0"
+  version: "2.1.0"
   layer: L1
   model: sonnet
   group: orchestrator
@@ -39,14 +39,41 @@ Cook supports predefined workflow chains for common task types. Use these as sho
 /rune cook security   → Full pipeline + sentinel@opus + sast (all phases, security-escalated)
 /rune cook hotfix     → Minimal: fix → verify → commit (Phase 4 → 6 → 7, skip scout if user provides context)
 /rune cook nano       → Trivial: do → verify → done (no phases, ≤3 steps)
+/rune cook --template <name> → Load pre-built workflow template from installed Pro/Business packs
 ```
 
+### Template Workflows (Pro/Business)
+
+When `--template <name>` is provided, cook loads a pre-built workflow template instead of auto-detecting:
+
+```
+/rune cook --template product-discovery   → Pro: stakeholder interviews → problem framing → competitive → spec → validation
+/rune cook --template product-launch      → Pro: spec lock → implement → quality gates → staged rollout → announcement
+/rune cook --template product-iteration   → Pro: metrics review → feedback synthesis → re-prioritize → implement → measure
+/rune cook --template data-exploration    → Pro: data profiling → hypotheses → statistical testing → visualization → report
+/rune cook --template data-pipeline       → Pro: schema design → ETL → quality gates → deploy → monitoring
+/rune cook --template sales-outreach-campaign → Pro: prospect research → messaging → sequence → A/B test → launch
+/rune cook --template sales-deal-review   → Pro: account deep-dive → risk assessment → competitive strategy → action plan
+/rune cook --template support-incident-response → Pro: triage → diagnose → fix → verify → postmortem → KB update
+/rune cook --template support-kb-refresh  → Pro: audit → gap analysis → draft → review → publish
+```
+
+**Template resolution**: Templates are `.md` files in `extensions/pro-*/templates/` or `extensions/business-*/templates/`. Each template defines: phases, skill connections, mesh signals, and acceptance criteria. The compiler includes templates in pack output during build.
+
+**When --template is used**:
+1. Skip Phase 1.5 (auto-detection) — template pre-selects domain and pack
+2. Skip Phase 1.7 (workflow matching) — template IS the workflow
+3. Load template phases as the master plan (Phase 2 becomes "review template plan" not "create plan")
+4. Execute each template phase in order, invoking declared skills
+5. Emit template's declared signals on completion
+
 **Chain selection**: If user invokes `/rune cook` without a chain type, auto-detect from the task description:
 - Contains "bug", "fix", "broken", "error" → `bugfix`
 - Contains "refactor", "clean", "restructure" → `refactor`
 - Contains "security", "auth", "vulnerability", "CVE" → `security`
 - Contains "urgent", "hotfix", "production" → `hotfix`
 - Contains "quick", "just", "chỉ cần", "copy", "move", "rename", "bump" → `nano`
+- Contains `--template` → load template workflow (see above)
 - Default → `feature`
 
 ## Phase Skip Rules
@@ -177,7 +204,11 @@ Skip if: bug fix with clear repro steps | user said "just do it" | fast mode + <
 5. Invoke scout to scan the codebase (Glob + Grep + Read on relevant files)
 6. Summarize: what exists, project conventions, files likely to change, active decision constraints
 7. **Python async detection**: if Python project detected, `Grep` for async indicators (`async def`, `await`, `aiosqlite`, `aiohttp`, `asyncio.run`). If ≥3 matches → flag as **"async-first Python"** — new code defaults to `async def`
-8. Mark Phase 1 as `completed`
+8. **Explore-Before-Commit**: If scout reveals multiple viable approaches (e.g., 2+ libraries, 2+ architectural patterns), do NOT commit to an approach yet. Instead:
+   - List alternatives with 1-line trade-off each
+   - Flag to Phase 2 (plan) for formal comparison
+   - Separating "thinking" (Phase 1) from "committing" (Phase 2) prevents premature lock-in
+9. Mark Phase 1 as `completed`
 
 **Gate**: If scout finds the feature already exists → STOP and inform user.
 
@@ -212,7 +243,15 @@ After scout completes, check if the detected tech stack or task description matc
 
 ## Phase 0: RESUME CHECK (Before Phase 1)
 
-**Goal**: Detect if a master plan already exists for this task. If so, skip Phase 1-2 and resume from the current phase.
+**Goal**: Detect if a master plan already exists for this task, or if a `--template` was specified. If so, skip Phase 1-2 and resume/load the workflow.
+
+**Step 0.4 — Template Detection**: If user passed `--template <name>`:
+1. Search installed pack templates for the name: `Glob` for `extensions/*/templates/<name>.md` and `extensions/pro-*/templates/<name>.md`
+2. If found: `Read` the template file → parse phases, signals, connections, acceptance criteria
+3. Generate a master plan from the template: each template phase becomes a plan phase
+4. Write plan files to `.rune/plan-<template-name>.md` + `.rune/plan-<template-name>-phaseN.md`
+5. Announce "Loading template: <name> (<pack>)" → skip Phase 1, 1.5, 1.7, 2 → proceed to Phase 4 with Phase 1 of the template
+6. If template not found: warn user and fall through to normal workflow
 
 **Step 0.5 — Cross-Project Recall**: Call `neural-memory` (Recall Mode) with 3-5 topics relevant to the current task. Always prefix queries with the project name (e.g., `"ProjectName auth pattern"` not `"auth pattern"`).
 
@@ -427,7 +466,15 @@ Before entering ANY Phase N+1, assert: Phase N `completed` in TodoWrite | gate c
 2. Save to `.rune/decisions.md` (approach + trade-offs), `.rune/progress.md` (task complete), `.rune/conventions.md` (new patterns)
 3. **Skill metrics** → `.rune/metrics/skills.json`: increment phase run/skip counts, quality gate results, debug loop counts under `cook` key
 4. **Routing overrides** (H3): if Phase 4 hit max loops for an error pattern → write rule to `.rune/metrics/routing-overrides.json`. Max 10 active rules.
-5. **Step 8.5 — Capture Learnings**: `neural-memory` (Capture Mode) — 2-5 memories: architecture decisions, patterns, error root-causes, trade-offs. Cognitive language (causal/decisional/comparative). Tags: `[project, tech, topic]`. Priority 5 routine / 7-8 decisions / 9-10 critical errors.
+5. **Step 8.5 — Cross-Cutting Sweep**: After commit, check if this phase changed stats (skill count, test count, signal count, pack count, layer counts). If ANY stat changed:
+   - [ ] `README.md` — stats, badges, feature list
+   - [ ] `docs/index.html` (landing page) — meta tags, hero badge, install section, mesh stats, footer
+   - [ ] `dashboard.html` (if local) — KPI cards, test count, skill tabs, layer counts
+   - [ ] `CLAUDE.md` — commands, test count, skill list
+   - [ ] `MEMORY.md` — milestones, version info
+
+   **Skip if**: No stats changed (pure refactor, docs-only, style change). **MANDATORY** if any numeric stat in README differs from actual.
+6. **Step 8.6 — Capture Learnings**: `neural-memory` (Capture Mode) — 2-5 memories: architecture decisions, patterns, error root-causes, trade-offs. Cognitive language (causal/decisional/comparative). Tags: `[project, tech, topic]`. Priority 5 routine / 7-8 decisions / 9-10 critical errors.
 6. Mark Phase 8 as `completed`
 
 ## Autonomous Loop Patterns
@@ -487,6 +534,56 @@ If ambiguous between Cancel and Steer → ask user: "Did you mean stop, or chang
 Hard caps: MAX_DEBUG_LOOPS=3, MAX_QUALITY_LOOPS=2, MAX_REPLAN=1, MAX_PIVOT=1, MAX_FIXES=30, WTF_THRESHOLD=20%.
 Escalation chain: debug-fix (3x) → re-plan (1x) → brainstorm rescue (1x) → THEN escalate to user.
 
+### Structured Escalation Report
+
+> From agency-agents (msitarzewski/agency-agents, 50.8k★): "After 3 retry failures, structured escalation prevents cargo-cult retrying."
+
+When escalation chain exhausts (all retries hit) or cook returns `BLOCKED`, produce a Structured Escalation Report instead of a vague "I can't do this":
+
+```markdown
+## Escalation Report
+- **Task**: [original task description]
+- **Status**: BLOCKED
+- **Attempts**: [count] across [N] phases
+
+### Failure History
+| # | Approach | Phase | Outcome | Root Cause |
+|---|---------|-------|---------|------------|
+| 1 | Direct fix | Phase 4 | Tests fail — null ref in auth.ts:42 | Missing user context |
+| 2 | Re-plan with guard clause | Phase 4 | Build fails — circular import | Guard approach introduces cycle |
+| 3 | Brainstorm rescue → adapter pattern | Phase 4 | Tests pass but perf regression 3x | Adapter adds indirection overhead |
+
+### Root Cause Analysis
+[1-2 sentences: why ALL approaches failed — is it architectural, environmental, or requirements-level?]
+
+### Recommended Resolutions (pick one)
+1. **Reassign** — different skill/agent with fresh context
+2. **Decompose** — break into smaller sub-tasks that CAN succeed independently
+3. **Revise requirements** — relax constraint X to unblock (specify which)
+4. **Accept partial** — ship what works, defer blocked portion
+5. **Defer** — park this task, work on something else first
+
+### Impact Assessment
+- **Blocked by this**: [downstream tasks/phases that depend on this]
+- **Not blocked**: [independent work that can continue]
+```
+
+<HARD-GATE>
+"Bad work is worse than no work." Cook MUST produce this report rather than attempting a 4th variant of a failing approach. Escalating is not failure — shipping broken code is.
+</HARD-GATE>
+
+### Subagent Question Gate
+
+> From superpowers (obra/superpowers, 84k★): "Subagents that start work without asking questions produce the wrong thing 40% of the time."
+
+Before dispatching a sub-skill (fix, test, review) for a non-trivial task (3+ files OR ambiguous scope):
+
+1. **Invite questions**: Include in the handoff: "Before starting, ask up to 3 clarifying questions if anything is unclear."
+2. **Answer before work**: If the sub-skill returns questions → answer them, THEN re-dispatch with answers included.
+3. **Skip if**: Fast/Nano rigor, single-file fix, or sub-skill is haiku-tier (too cheap to gate).
+
+This prevents the #1 parallel work failure: sub-skill assumes wrong interpretation, builds 500 LOC, then gets rejected in review.
+
 ### Subagent Status Protocol
 
 <MUST-READ path="references/subagent-status.md" trigger="when cook or any sub-skill needs to return a status"/>
@@ -537,6 +634,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"/>
@@ -615,6 +752,42 @@ Mentally track tool call fingerprints. 3 identical calls → WARN. 5 identical c
 | Quality Gate | preflight + sentinel + review before Phase 7 | Fix findings, re-run |
 | Verification Gate | lint + types + tests + build green before commit | Fix, re-run |
 
+## Structured Output Contract (Prompt-as-API Pattern)
+
+When cook invokes sub-skills that produce structured output (e.g., `ba` for requirements, `plan` for implementation plans, `test` for test specs), use the **Prompt-as-API-Contract** pattern: specify the exact output schema in the invocation prompt so the sub-skill returns machine-parseable results, not free-form prose.
+
+### Pattern
+
+```
+INVOCATION: "Analyze [X] and return results as JSON matching this schema:
+{
+  "insights": [{ "id": string, "category": string, "description": string, "actionable": string }],
+  "confidence": number,
+  "next_steps": string[]
+}
+Do NOT include explanatory text outside the JSON block."
+```
+
+### When to Apply
+
+| Phase | Sub-skill | Output Contract |
+|-------|-----------|----------------|
+| Phase 1 | `ba` | `{ requirements: [{id, priority, description, acceptance_criteria}], ambiguities: string[] }` |
+| Phase 2 | `plan` | `{ phases: [{name, tasks: [{description, files, effort}], dependencies}] }` |
+| Phase 3 | `test` | `{ test_cases: [{name, type, file, assertion}], coverage_targets: string[] }` |
+| Phase 5 | `review` | `{ findings: [{severity, file, line, description, fix}], verdict: "PASS"|"WARN"|"BLOCK" }` |
+
+### Rules
+
+- Include 1-2 concrete examples in the prompt — examples are worth more than schema descriptions
+- Always specify "Do NOT include explanatory text outside the JSON/markdown block" — LLMs default to wrapping structured output in prose
+- When the output will be consumed by another skill (not displayed to user), ALWAYS use this pattern
+- When the output will be displayed to the user, use markdown format instead — humans don't read JSON
+
+### Why
+
+Free-form sub-skill output forces the calling skill to parse natural language — fragile and lossy. Structured contracts make skill-to-skill communication reliable, enable automated validation, and reduce the tokens wasted on parsing instructions.
+
 ## Output Format
 
 <MUST-READ path="references/output-format.md" trigger="before emitting the Cook Report at end of any session"/>

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.8.0"
+  version: "1.0.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.
@@ -232,6 +264,21 @@ Track fix attempts in the Debug Report. If this is attempt N>1 for the same symp
 - Explain why the previous fix didn't hold
 - If N=3: trigger the escalation gate above — classify and route accordingly
 
+### 3+ Fixes as Architectural Signal
+
+> From superpowers (obra/superpowers, 84k★): "Each fix revealing new problems elsewhere = structural issue, not a bug hunt."
+
+When 3+ **distinct** fixes fail (not retries of the same fix), STOP treating it as a bug:
+
+| Signal | Interpretation | Next Step |
+|--------|---------------|-----------|
+| Same blocker each time (API limit, platform gap) | Wrong approach | `brainstorm(mode="rescue")` — need fundamentally different path |
+| Different bugs each fix (null → race → type) | Wrong architecture | `plan` redesign — module has structural problems |
+| Each fix creates a new bug elsewhere | Tight coupling | The module boundary is wrong — need to redraw boundaries before fixing |
+| Fix works locally but fails in integration | Missing contract | Cross-module interface is undefined — add explicit contracts first |
+
+**Key insight**: After 3 failures, question the DESIGN, not the CODE. "Try harder" is never the right answer at this point.
+
 ### Step 7: Report
 
 Produce structured output and hand off to rune:fix.
@@ -375,6 +422,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/docs/SKILL.md

@@ -3,7 +3,7 @@ name: docs
 description: Auto-generate and maintain project documentation. Creates README, API docs, architecture docs, changelogs, and keeps them in sync with code changes. The "docs are never outdated" skill.
 metadata:
   author: runedev
-  version: "0.2.0"
+  version: "0.3.0"
   layer: L2
   model: sonnet
   group: delivery
@@ -174,9 +174,32 @@ Never silently remove doc content. If code was deleted, mark the doc section as
 
 Delegate to `rune:git changelog` to produce a changelog entry from commits since last docs update.
 
-#### Step 4 — Report
+#### Step 4 — Cross-Doc Consistency Pass
 
-Show user: what was updated, what was added, what was flagged for review.
+> From gstack (garrytan/gstack, 50.9k★): "Cross-document consistency prevents the #2 docs problem: docs that exist but contradict each other."
+
+After updating any doc, verify consistency across all project documentation:
+
+| Check | Files | What to Compare |
+|-------|-------|----------------|
+| **Version numbers** | README, CLAUDE.md, package.json, CHANGELOG | Must all match current version |
+| **Feature lists** | README, landing page, CLAUDE.md | Same features listed (may differ in detail level) |
+| **Stats** | README, CLAUDE.md, landing page, dashboard | Skill count, test count, signal count must match |
+| **Commands** | README, CLAUDE.md, docs/ | Same commands with same flags |
+| **Tech stack** | README, ARCHITECTURE.md, CLAUDE.md | Consistent framework/library references |
+
+```
+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
+```
+
+**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).
+
+#### Step 5 — Report
+
+Show user: what was updated, what was added, what was flagged for review. Include Cross-Doc Consistency results.
 
 ### API Mode
 
@@ -316,6 +339,8 @@ Docs Update Report:
 | API docs with wrong request/response shapes | HIGH | Extract from Zod/Pydantic/TypeScript types, not from memory |
 | Missing Quick Start section | MEDIUM | Constraint 4: every README has Quick Start |
 | Changelog with orphan PR links | LOW | Validate PR numbers exist before linking |
+| Cross-document inconsistency (README says X, CLAUDE.md says Y) | HIGH | Step 7: Cross-Doc Consistency Pass — verify stats, versions, and feature lists match across all docs |
+| Updating one doc but not others (stats drift) | HIGH | After any doc update, sweep all related docs for stale stats — especially README ↔ CLAUDE.md ↔ landing page |
 
 ## Done When