@rune-kit/rune 2.2.3 → 2.2.6

package/extensions/saas/skills/billing-integration.md

@@ -1,16 +1,16 @@
 ---
 name: "billing-integration"
 pack: "@rune/saas"
-description: "Billing integration — Stripe and LemonSqueezy (Stripe alternative for Vietnam/non-US sellers). Subscription lifecycle, webhook handling, usage-based billing, dunning management, and tax handling."
+description: "Billing integration — Stripe, LemonSqueezy, and Polar. Subscription lifecycle, one-time checkout, webhook handling, Standard Webhooks verification, usage-based billing, dunning management, digital product delivery, and tax handling."
 model: sonnet
 tools: [Read, Edit, Write, Grep, Glob, Bash]
 ---
 
 # billing-integration
 
-Billing integration — Stripe and LemonSqueezy (Stripe alternative for Vietnam/non-US sellers). Subscription lifecycle, webhook handling, usage-based billing, dunning management, and tax handling.
+Billing integration — Stripe, LemonSqueezy, and Polar. Subscription lifecycle, one-time payment checkout, webhook handling, Standard Webhooks signature verification, usage-based billing, dunning management, digital product delivery, and tax handling.
 
-> **Vietnam note**: Stripe requires a US/EU entity and is unavailable for direct signup from Vietnam. LemonSqueezy acts as Merchant of Record — handles VAT, tax compliance, and payouts globally. Prefer LemonSqueezy for solo founders and small teams in Vietnam/Southeast Asia.
+> **Provider selection**: Stripe requires a US/EU entity. LemonSqueezy and Polar act as Merchant of Record — handle VAT, tax compliance, and payouts globally. Prefer LemonSqueezy or Polar for solo founders in Vietnam/Southeast Asia. Polar is optimized for developer tools and digital products (open source monetization, one-time purchases, CLI tools).
 
 #### Workflow
 
@@ -29,6 +29,15 @@ For products where billing scales with usage (API calls, seats, storage): create
 **Step 5 — Dunning management flow**
 When `invoice.payment_failed` fires: Day 0 — notify customer, retry in 3 days. Day 3 — retry + second email. Day 7 — retry + urgent email + in-app warning banner. Day 14 — suspend account (read-only mode), email with payment link. Day 21 — cancel subscription, archive data with 30-day recovery window. Never hard-delete on cancellation.
 
+**Step 6 — Hosted checkout flow (one-time + subscription)**
+For products sold as one-time purchases (lifetime deals, digital products, CLI tools): create a checkout session server-side with product ID + metadata (user identifier, tier), redirect user to provider's hosted checkout page, listen for `order.paid` webhook to fulfill. This pattern works across all providers — only the API shape differs. Always pass fulfillment context (user ID, GitHub username, email) in checkout metadata so the webhook handler can deliver without a second lookup.
+
+**Step 7 — Standard Webhooks signature verification**
+Polar (and any provider using the Standard Webhooks spec via Svix) sends three headers: `webhook-id`, `webhook-timestamp`, `webhook-signature`. Verify with HMAC-SHA256: `sign(base64decode(secret), "{webhook-id}.{timestamp}.{rawBody}")`. Compare against all signatures in the header (space-separated `v1,{base64}`). Also check timestamp is within 5 minutes to prevent replay attacks. This is different from Stripe's `constructEvent` or LemonSqueezy's `x-signature` — detect which spec the provider uses.
+
+**Step 8 — Digital product delivery**
+After payment confirmation, deliver the product automatically. Three common patterns: (a) **Repo access** — call GitHub/GitLab API to add user as collaborator with `pull` permission. Pass username in checkout metadata. Handle 201 (invited) and 204 (already collaborator). (b) **License key** — generate unique key, store in DB with expiry + tier + features, email to customer. Provide public verification endpoint for the product to call at startup. (c) **Download link** — generate signed URL with expiry (S3 presigned, R2 signed). Email link + store for re-download. For all patterns: store delivery result alongside order, implement retry for partial failures, sync to central dashboard for tracking.
+
 #### Example
 
 ```typescript
@@ -94,6 +103,76 @@ app.post('/billing/webhook/lemonsqueezy', express.raw({ type: 'application/json'
   res.json({ received: true });
 });
 
+// Polar — hosted checkout for one-time purchases (developer tools, digital products)
+// Create checkout session server-side, redirect client to checkout.url
+app.post('/checkout/create', async (req, res) => {
+  const { productId, githubUsername, email } = req.body;
+
+  const checkout = await fetch('https://api.polar.sh/v1/checkouts/', {
+    method: 'POST',
+    headers: {
+      Authorization: `Bearer ${process.env.POLAR_ACCESS_TOKEN}`,
+      'Content-Type': 'application/json',
+    },
+    body: JSON.stringify({
+      products: [productId],
+      success_url: `${process.env.APP_URL}/checkout/success?checkout_id={CHECKOUT_ID}`,
+      ...(email ? { customer_email: email } : {}),
+      metadata: { github_username: githubUsername, tier: 'pro' }, // fulfillment context
+    }),
+  }).then(r => r.json());
+
+  res.json({ url: checkout.url }); // redirect client to this URL
+});
+
+// Polar webhook — Standard Webhooks spec (also used by Svix, Resend, Clerk)
+app.post('/billing/webhook/polar', express.raw({ type: 'application/json' }), async (req, res) => {
+  const webhookId = req.headers['webhook-id'] as string;
+  const timestamp = req.headers['webhook-timestamp'] as string;
+  const signature = req.headers['webhook-signature'] as string;
+
+  // Verify: HMAC-SHA256(base64decode(secret), "{id}.{timestamp}.{body}")
+  const secret = Buffer.from(process.env.POLAR_WEBHOOK_SECRET!.replace(/^whsec_/, ''), 'base64');
+  const content = `${webhookId}.${timestamp}.${req.body.toString()}`;
+  const expected = crypto.createHmac('sha256', secret).update(content).digest('base64');
+
+  const valid = signature.split(' ').some(s => {
+    const parts = s.split(',');
+    return parts.length === 2 && parts[1] === expected;
+  });
+  if (!valid) return res.status(403).json({ error: 'Invalid signature' });
+
+  // Replay protection: reject timestamps older than 5 minutes
+  if (Math.abs(Date.now() / 1000 - Number(timestamp)) > 300) {
+    return res.status(403).json({ error: 'Timestamp too old' });
+  }
+
+  const event = JSON.parse(req.body.toString());
+  if (event.type !== 'order.paid') return res.json({ received: true });
+
+  const { metadata } = event.data;
+  // Deliver based on product type using metadata set during checkout
+  if (metadata.github_username) {
+    await inviteToRepo(metadata.github_username, 'org/private-repo', 'pull');
+  }
+
+  res.json({ received: true });
+});
+
+// Digital product delivery — GitHub repo invite
+const inviteToRepo = async (username: string, repo: string, permission: string) => {
+  const res = await fetch(`https://api.github.com/repos/${repo}/collaborators/${username}`, {
+    method: 'PUT',
+    headers: {
+      Authorization: `Bearer ${process.env.GITHUB_TOKEN}`,
+      Accept: 'application/vnd.github+json',
+    },
+    body: JSON.stringify({ permission }),
+  });
+  // 201 = invited, 204 = already collaborator — both are success
+  return { success: res.status === 201 || res.status === 204, status: res.status };
+};
+
 // Usage-based billing — report metered usage to Stripe
 const reportUsage = async (tenantId: string, quantity: number) => {
   const subscription = await db.subscription.findUnique({ where: { tenantId } });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rune-kit/rune",
-  "version": "2.2.3",
+  "version": "2.2.6",
   "description": "58-skill mesh for AI coding assistants — 5-layer architecture, 200+ connections, 8 platforms (Claude Code, Cursor, Windsurf, Antigravity, Codex, OpenCode, OpenClaw, Generic)",
   "type": "module",
   "bin": {

package/skills/audit/SKILL.md

@@ -32,6 +32,7 @@ Comprehensive project health audit across 8 dimensions (7 project + 1 mesh analy
 - `journal` (L3): record audit date, overall score, and verdict
 - `constraint-check` (L3): audit HARD-GATE compliance across project skills
 - `sast` (L3): Phase 2 — deep static analysis (Semgrep, Bandit, ESLint security rules)
+- `retro` (L2): Phase 6 — engineering velocity and health dimension (rune:retro)
 
 ## Called By (inbound)
 

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.2.0"
+  version: "0.4.0"
   layer: L2
   model: opus
   group: creation
@@ -85,6 +85,32 @@ Each question must be asked separately, wait for answer before next.
 Exception: if user provides a detailed spec/PRD → extract answers from it, confirm with user.
 </HARD-GATE>
 
+#### Structured Elicitation Frameworks
+
+Choose the framework that fits the requirement type. Use it to STRUCTURE the 5 Questions above, not replace them.
+
+| Framework | When to Use | Structure |
+|-----------|------------|-----------|
+| **PICO** | Clinical, research, data-driven, or A/B testing features | **P**opulation (who), **I**ntervention (what change), **C**omparison (vs what), **O**utcome (measurable result) |
+| **INVEST** | User stories for sprint-sized features | **I**ndependent, **N**egotiable, **V**aluable, **E**stimable, **S**mall, **T**estable |
+| **Jobs-to-be-Done** | Product features, user workflows | "When [situation], I want to [motivation] so I can [expected outcome]" |
+
+> Source: K-Dense claude-scientific-skills (literature-review PICO pattern), adapted for software BA.
+
+**PICO Example (data feature):**
+```
+P: Dashboard users monitoring real-time metrics
+I: Add anomaly detection alerts
+C: vs. current manual threshold setting
+O: 30% faster incident detection (measurable KPI)
+```
+
+**When to apply which:**
+- Feature Request → INVEST (ensures stories are sprint-ready)
+- Data/Analytics/Research feature → PICO (forces measurable outcome definition)
+- Product/UX feature → Jobs-to-be-Done (keeps focus on user motivation)
+- Integration → 5 Questions only (frameworks add noise for plumbing tasks)
+
 ### Step 3 — Hidden Requirement Discovery
 
 After the 5 questions, analyze for requirements the user DIDN'T mention:
@@ -108,6 +134,32 @@ After the 5 questions, analyze for requirements the user DIDN'T mention:
 
 Present discovered hidden requirements to user: "I found N additional requirements you may not have considered: [list]. Which are relevant?"
 
+### Step 3.5 — Completeness Scoring (Options & Alternatives)
+
+When presenting options, alternatives, or scope decisions to the user, rate each with a **Completeness score (X/10)**:
+
+| Score | Meaning | Guidance |
+|-------|---------|----------|
+| 9-10 | Complete — all edge cases, full coverage, production-ready | Always recommend |
+| 7-8 | Covers happy path, skips some edges | Acceptable for MVP |
+| 4-6 | Shortcut — defers significant work to later | Flag trade-off explicitly |
+| 1-3 | Minimal viable, technical debt guaranteed | Only for time-critical emergencies |
+
+**Always recommend the higher-completeness option** unless the delta is truly expensive. With AI-assisted coding, the marginal cost of completeness is near-zero:
+
+| Task Type | Human Team | AI-Assisted | Compression |
+|-----------|-----------|-------------|-------------|
+| Boilerplate / scaffolding | 2 days | 15 min | ~100x |
+| Test writing | 1 day | 15 min | ~50x |
+| Feature implementation | 1 week | 30 min | ~30x |
+| Bug fix + regression test | 4 hours | 15 min | ~20x |
+
+**When showing effort estimates**, always show both scales: `(human: ~X / AI: ~Y)`. The compression ratio reframes "too expensive" into "15 minutes more."
+
+**Anti-pattern**: "Choose B — it covers 90% of the value with less code." → If A is only 70 lines more, choose A. The last 10% is where production bugs hide.
+
+> Source: garrytan/gstack v0.9.0 — "Boil the Lake" principle. Completeness is cheap when AI makes the marginal cost near-zero.
+
 ### Step 4 — Scope Definition
 
 Based on all gathered information, produce:
@@ -272,6 +324,7 @@ Known failure modes for this skill. Check these before declaring done.
 | Missing hidden requirements (auth, error handling, edge cases) | HIGH | Step 3 checklist is mandatory scan |
 | 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 |
 
 ## Done When
 

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.2.0"
+  version: "1.5.0"
   layer: L3
   model: haiku
   group: validation
@@ -73,6 +73,24 @@ If ANY stub detected:
 - Add synthetic claim: "implemented [filename]" → CONTRADICTED (file is a stub)
 - This catches agents that create files but don't implement them
 
+### Step 1c — Self-Validation Check
+
+If the skill that just ran has a `## Self-Validation` section, extract its checklist and treat each item as an implicit claim:
+
+```
+For each Self-Validation check in the skill's SKILL.md:
+  1. Read the check (e.g., "at least one assertion per test")
+  2. Look for evidence in tool output that this check was satisfied
+  3. If evidence found → add as CONFIRMED claim
+  4. If no evidence → add as UNCONFIRMED claim ("Self-Validation: [check] — no evidence")
+```
+
+Why: Self-Validation catches domain-specific quality issues that generic claim matching (Step 2) cannot detect. A test skill knows "no assertions = useless test" but completion-gate doesn't — unless the skill's Self-Validation tells it to check.
+
+<HARD-GATE>
+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 2 — Match Evidence
 
 For each claim, look for corresponding evidence in the conversation context:
@@ -87,7 +105,15 @@ For each claim, look for corresponding evidence in the conversation context:
 | "no security issues" | Sentinel report with PASS verdict | Sentinel skill output |
 | "coverage ≥ X%" | Coverage tool output with actual percentage | Test runner with coverage flag |
 
-### Step 3 — Validate Each Claim
+### Step 3 — Validate Each Claim (Default-FAIL Mindset)
+
+<HARD-GATE>
+Default posture is FAIL, not PASS. Actively seek 3-5 issues per review.
+Zero issues found = red flag — look harder, not a sign of quality.
+This prevents rubber-stamping where the gate confirms everything without scrutiny.
+</HARD-GATE>
+
+> Source: msitarzewski/agency-agents (50.8k★) — "Default to finding 3-5 issues. Zero issues = red flag, look harder."
 
 For each claim + evidence pair:
 
@@ -100,6 +126,12 @@ IF no evidence found:
   → UNCONFIRMED (agent may be right but didn't prove it)
 ```
 
+**Adversarial validation checklist** (run AFTER initial verdicts):
+1. Re-read each CONFIRMED claim — is the evidence actually proving THIS claim, or a different one?
+2. Check for **partial completion** — did the agent do 80% but claim 100%? (e.g., "implemented feature" but only the happy path)
+3. Check for **scope mismatch** — does the evidence prove the SPECIFIC claim or a broader/narrower version?
+4. If all claims are CONFIRMED on first pass, apply **skeptic sweep**: re-examine the weakest 2 claims with heightened scrutiny
+
 ### Step 4 — Report
 
 ```
@@ -123,6 +155,34 @@ IF no evidence found:
 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:
+   ```
+   Grep for the export name in the current codebase:
+   - If export exists AND is importable → CONFIRMED
+   - If export exists but has wrong signature vs phase file contract → CONTRADICTED
+   - Expected export missing entirely → UNCONFIRMED ("Phase N claims to export X but X not found")
+   ```
+
+2. **Uncalled routes** — API endpoints added in this phase but not wired to any frontend/consumer yet:
+   - This is OK if a future phase handles wiring (check master plan)
+   - Flag as WARN if no future phase mentions consuming this route
+
+3. **Auth gaps** — new endpoints or pages without authentication/authorization:
+   - `Grep` for route handlers without auth middleware
+   - Flag as WARN (may be intentional for public endpoints, but worth checking)
+
+4. **E2E flow trace** — for the primary user flow this phase enables:
+   - Trace: entry point → business logic → data layer → response
+   - If any step in the chain is missing or stubbed → CONTRADICTED
+
+**This step is OPTIONAL for single-phase tasks and MANDATORY for multi-phase master plans.**
+
 ### Step 5 — Evidence Quality Gate
 
 Before emitting verdict, verify evidence quality:
@@ -170,6 +230,11 @@ Completion Gate Report with status (CONFIRMED/UNCONFIRMED/CONTRADICTED), claim v
 | Agent pre-generates evidence by running commands proactively | LOW | This is actually GOOD behavior — we want agents to provide evidence |
 | Completion-gate itself claims "all confirmed" without evidence | CRITICAL | Gate report MUST include the evidence table — no table = report is invalid |
 | Existence Theater — agent creates files but they're stubs | HIGH | Step 1b stub detection: grep for Placeholder/TODO/NotImplementedError in new files |
+| Cross-phase integration gaps — exports exist but wrong signature | HIGH | Step 4.5: verify exports match Code Contracts from phase file |
+| Phase complete but E2E flow broken — missing link in the chain | MEDIUM | Step 4.5 E2E flow trace: entry → logic → data → response must all be connected |
+| 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 |
 
 ## Done When
 

package/skills/cook/SKILL.md

@@ -5,7 +5,7 @@ context: fork
 agent: general-purpose
 metadata:
   author: runedev
-  version: "0.7.0"
+  version: "1.3.0"
   layer: L1
   model: sonnet
   group: orchestrator
@@ -248,6 +248,55 @@ This phase is lightweight — a Read + pattern match, not a full scan. It does N
 
 **Gate**: User MUST approve the plan before proceeding. Do NOT skip this.
 
+### Phase 2.5: RFC GATE (Breaking Changes Only)
+
+**Goal**: Formal change management for breaking changes. Prevents unreviewed breaking changes from reaching production.
+
+**Auto-trigger conditions** (ANY triggers this gate):
+- Plan includes `BREAKING CHANGE` annotation
+- Plan modifies a public API signature (added/removed/changed parameters)
+- Plan alters database schema (migration required)
+- Plan removes or renames an exported function/type used by other modules
+- Plan changes authentication/authorization flow
+
+**Skip conditions**: Non-breaking changes, internal refactors, new features with no API surface change.
+
+**RFC Artifact** (`.rune/rfc/RFC-<NNN>-<slug>.md`):
+
+```markdown
+# RFC-<NNN>: <Title>
+
+**Date**: [YYYY-MM-DD]
+**Author**: [agent or user]
+**Status**: Proposed | Approved | Rejected
+**Impact**: [list affected consumers — modules, services, users]
+
+## What Changes
+[Specific breaking change — old behavior → new behavior]
+
+## Why
+[Business/technical justification — why breaking is necessary]
+
+## Migration Path
+[Step-by-step guide for consumers to adapt]
+[Include code examples: before → after]
+
+## Rollback Plan
+[How to revert if the change causes issues]
+
+## Affected Systems
+| System | Impact | Migration Effort |
+|--------|--------|-----------------|
+| [module/service] | [description] | [low/medium/high] |
+```
+
+**Gate**: RFC MUST be written and presented to user for approval. User responds: "approved" → proceed. "rejected" → revise plan. "deferred" → skip breaking change, implement non-breaking alternative.
+
+<HARD-GATE>
+Breaking change without RFC = BLOCKED. No exceptions.
+"It's just a small change" is the #1 excuse for production incidents from unreviewed breaking changes.
+</HARD-GATE>
+
 ## Phase 2.5: ADVERSARY (Red-Team Challenge)
 
 **Goal**: Stress-test the approved plan BEFORE writing code — catch flaws at plan time, not implementation time.
@@ -322,6 +371,11 @@ If the coder model needs info from other phases, it's in the Cross-Phase Context
 1. Mark Phase 4 as `in_progress`
 2. **Phase-file execution** — if working from a master plan + phase file:
    - Execute tasks listed in the phase file (the `## Tasks` section)
+   - **Wave-based execution**: if tasks are organized into waves (see `plan` skill), execute wave-by-wave:
+     - Wave 1 tasks first (no dependencies — can run in parallel if inside `team`)
+     - Wave 2 tasks only after ALL Wave 1 tasks complete
+     - Within a wave: `team` dispatches as parallel subagents; solo cook runs sequentially
+     - If a task in Wave N fails → do NOT start Wave N+1. Fix or DECOMPOSE the failed task first
    - Follow code contracts from `## Code Contracts` section
    - Respect rejection criteria from `## Rejection Criteria` section
    - Handle failure scenarios from `## Failure Scenarios` section
@@ -341,6 +395,8 @@ If the coder model needs info from other phases, it's in the Cross-Phase Context
      - Prefer `asyncio.gather()` for parallel I/O operations
      - Use `asyncio.TaskGroup` (Python 3.11+) for structured concurrency
 4. If stuck on unexpected errors → invoke `rune:debug` (max 3 debug↔fix loops)
+   - Debug will scope-lock to the affected directory (Step 1.5) — fix recommendations stay within boundary
+   - If debug recommends changes outside plan scope → treat as R4 deviation (ASK user first)
 5. **Re-plan check** — before proceeding to Phase 5, evaluate:
    - Did debug-fix loops hit max (3) for any area? → trigger re-plan
    - Were files modified outside the approved plan scope? → trigger re-plan
@@ -419,6 +475,7 @@ PARALLEL EXECUTION:
 **REQUIRED SUB-SKILL**: Use `rune:completion-gate`
 - Validate that agent claims match evidence trail
 - Check: tests actually ran (stdout captured), files actually changed (git diff), build actually passed
+- Check: no truncated code files (`// ...`, `// rest of code`, bare ellipsis) — agent MUST complete all output
 - Any UNCONFIRMED claim → BLOCK with specific gap identified
 
 **Gate**: If sentinel finds CRITICAL security issue → STOP, fix it, re-run. Non-negotiable.
@@ -577,6 +634,34 @@ When cook must pause mid-phase (context limit, user break, session end before ph
 
 This is more granular than Phase 0's plan-level resume — it resumes within a phase, not just between phases.
 
+### Mid-Run Signal Detection (Two-Stage Intent Classification)
+
+When user sends a message DURING cook execution (mid-phase), classify intent before acting:
+
+**Stage 1 — Keyword Fast-Path** (no LLM reasoning needed, <60 chars):
+
+| Pattern | Intent | Action |
+|---------|--------|--------|
+| "stop", "cancel", "dừng", "abort" | `Cancel` | Save progress → emit Cook Report with status BLOCKED → stop |
+| "status", "tiến độ", "progress", "where are you" | `StatusQuery` | Reply with current phase + task + % estimate → resume |
+| "wait", "pause", "đợi" | `Pause` | Create `.rune/.continue-here.md` → WIP commit → stop |
+| "skip this", "bỏ qua", "next" | `Steer` | Skip current task → proceed to next task/phase |
+
+**Stage 2 — Context Classification** (if no keyword match AND message >60 chars):
+
+| Intent | Signal | Action |
+|--------|--------|--------|
+| `Steer` | Modifies scope but keeps goal ("actually use Redis instead of Memcached") | Update plan inline, note deviation in Cook Report |
+| `NewTask` | Unrelated to current work ("also fix the login page") | Log to `.rune/backlog.md`, continue current task. Announce: "Noted for later — staying on current task." |
+| `Clarification` | Answers a question cook asked, or provides missing context | Absorb into current phase context, resume |
+
+> Source: goclaw (832★) — two-stage intent classification prevents expensive LLM calls for simple signals like "stop" or "status".
+
+<HARD-GATE>
+NEVER treat a Cancel/Pause signal as a Steer or NewTask. User safety signals take absolute priority.
+If ambiguous between Cancel and Steer → ask user: "Did you mean stop, or change approach?"
+</HARD-GATE>
+
 ### Exit Conditions (Mandatory for Autonomous Runs)
 
 Every cook invocation inside `team` or autonomous workflows MUST have exit conditions:
@@ -586,6 +671,8 @@ MAX_DEBUG_LOOPS:   3 per error area (already enforced)
 MAX_QUALITY_LOOPS: 2 re-runs of Phase 5 (fix→recheck cycle)
 MAX_REPLAN:        1 re-plan per cook session (Phase 4 re-plan check)
 MAX_PIVOT:         1 approach pivot per cook session (Approach Pivot Gate)
+MAX_FIXES:         30 per session (hard cap — fix's WTF-likelihood self-regulation)
+WTF_THRESHOLD:     20% quality decay risk → STOP fixing, commit progress, re-assess
 TIMEOUT_SIGNAL:    If context-watch reports ORANGE, wrap up current phase and checkpoint
 ```
 
@@ -693,6 +780,26 @@ Do NOT ask user until repair budget is spent.
 - `worktree` (L3): Phase 4 — worktree isolation for parallel implementation
 - L4 extension packs: Phase 1.5 — domain-specific patterns when stack matches (see Phase 1.5 mapping table)
 
+## Data Flow
+
+### Feeds Into →
+
+- `journal` (L3): architectural decisions made during cook → ADR entries for future sessions
+- `session-bridge` (L3): cook's context (plan, decisions, progress) → .rune/ state files for next session
+- `neural-memory` (external): learnings from this cook run → persistent cross-session memory
+
+### Fed By ←
+
+- `ba` (L2): Requirements Document → cook's Phase 1 UNDERSTAND input
+- `plan` (L2): master plan + phase files → cook's Phase 2-4 execution roadmap
+- `session-bridge` (L3): .rune/.continue-here.md → cook's Phase 0 resume context
+- `neural-memory` (external): past project decisions → cook's Phase 0 context recall
+
+### Feedback Loops ↻
+
+- `cook` ↔ `debug`: cook encounters bug during Phase 4 → debug diagnoses → cook resumes with fix. Debug may discover the plan is wrong → cook triggers Approach Pivot
+- `cook` ↔ `test`: cook writes tests in Phase 3 (RED), implements in Phase 4 (GREEN), runs tests again → failures loop back to Phase 4 fix
+
 ## Analysis Paralysis Guard
 
 <HARD-GATE>
@@ -711,6 +818,38 @@ Stuck patterns (all banned):
 A wrong first attempt that produces feedback beats perfect understanding that never ships.
 </HARD-GATE>
 
+### Hash-Based Tool Loop Detection (Content-Aware)
+
+The 5-read counter above catches obvious paralysis. This catches **same-input-same-output loops** — where the agent keeps calling the same tool with the same arguments and getting the same result, making zero progress.
+
+**Detection logic** (conceptual — tracked mentally, not via actual SHA256):
+
+```
+For each tool call, track:
+  argsHash = fingerprint(tool_name + arguments)
+  resultHash = fingerprint(result content)
+
+IF same argsHash AND same resultHash seen before:
+  consecutive_identical += 1
+ELSE:
+  consecutive_identical = 0
+
+Thresholds:
+  3 identical calls → WARN: "Loop detected — same tool, same args, same result 3x. Change approach."
+  5 identical calls → FORCE STOP: "True stuck loop. Must try different tool or different arguments."
+```
+
+**Key distinction**: retry-with-different-result is NOT a loop (e.g., re-running tests after a fix). Only same-input-AND-same-output counts.
+
+> Source: goclaw (832★) — SHA256-based loop detection distinguishes true stuck loops from productive retries.
+
+**Common loop patterns to catch**:
+| Pattern | Looks Like | Actually |
+|---------|-----------|----------|
+| Re-reading same file after failed edit | `Read(file.ts)` → same content 3x | Agent forgot what it read — act on existing knowledge |
+| Re-running same failing test without code change | `Bash(npm test)` → same failure 3x | No code was changed between runs — fix first, then test |
+| Grepping same pattern across different paths | `Grep("pattern", src/)` → `Grep("pattern", lib/)` → same 0 results | Pattern doesn't exist — change search terms |
+
 ## Constraints
 
 1. MUST run scout before planning — no plan based on assumptions alone
@@ -739,13 +878,23 @@ A wrong first attempt that produces feedback beats perfect understanding that ne
 
 ```
 ## Cook Report: [Task Name]
-- **Status**: complete | partial | blocked
+- **Status**: DONE | DONE_WITH_CONCERNS | NEEDS_CONTEXT | BLOCKED
 - **Phases**: [list of completed phases]
 - **Files Changed**: [count] ([list])
 - **Tests**: [passed]/[total] ([coverage]%)
 - **Quality**: preflight [PASS/WARN] | sentinel [PASS/WARN] | review [PASS/WARN]
 - **Commit**: [hash] — [message]
 
+### Deliverables (NEXUS response — when invoked by team)
+| # | Deliverable | Status | Evidence |
+|---|-------------|--------|----------|
+| 1 | [from handoff] | DELIVERED | [file path or test output quote] |
+| 2 | [from handoff] | DELIVERED | [file path or test output quote] |
+| 3 | [from handoff] | PARTIAL | [what's missing and why] |
+
+### Concerns (if DONE_WITH_CONCERNS)
+- [concern]: [impact assessment] — [suggested remediation]
+
 ### Decisions Made
 - [decision]: [rationale]
 
@@ -754,6 +903,8 @@ A wrong first attempt that produces feedback beats perfect understanding that ne
 - Saved to .rune/progress.md
 ```
 
+> When cook is invoked standalone (not by team), the Deliverables table is optional. When invoked by team with a NEXUS Handoff, the Deliverables table is MANDATORY — team uses it to track acceptance criteria across streams.
+
 ## Sharp Edges
 
 Known failure modes for this skill. Check these before declaring done.
@@ -773,6 +924,22 @@ Known failure modes for this skill. Check these before declaring done.
 | Fast mode on security-relevant code | HIGH | Fast mode auto-excludes auth/crypto/payments — never fast-track security code |
 | Loading all phase files at once into context | HIGH | Phase File Gate: load ONLY the active phase file — one phase per session |
 | Resuming without checking master plan | MEDIUM | Phase 0 (RESUME CHECK) runs before Phase 1 — detects existing plans |
+| Treating user "stop"/"cancel" as scope change | CRITICAL | Mid-Run Signal Detection: Cancel/Pause are safety signals with absolute priority — never reinterpret as Steer or NewTask |
+| Same tool+args+result called 3+ times without progress | HIGH | Hash-Based Loop Detection: 3x warn, 5x force stop. Only same-input-AND-same-output counts — retries with different results are fine |
+| Ignoring mid-run user messages during autonomous execution | HIGH | Two-stage intent classification: keyword fast-path for simple signals, context classification for longer messages. Never queue user messages — process immediately |
+| Breaking change shipped without RFC review | CRITICAL | Phase 2.5 RFC Gate: any breaking change MUST have RFC artifact + user approval before implementation |
+| Runaway fix loop — fix introduces more bugs than it resolves | HIGH | fix v0.5.0 WTF-likelihood self-regulation: >20% decay = STOP. Hard cap 30 fixes/session via MAX_FIXES exit condition. Regressions +15%, blast radius +5%/file |
+
+## Self-Validation
+
+```
+SELF-VALIDATION (run before emitting Cook Report):
+- [ ] Every phase in Phase Skip Rules was either executed or explicitly skipped with reason
+- [ ] Plan approval gate was not bypassed — user said "go" (check conversation history)
+- [ ] No Phase 4 code was written before Phase 3 tests (TDD order preserved)
+- [ ] All Phase 5 quality gates (preflight, sentinel, review) ran — not just claimed
+- [ ] Cook Report contains actual commit hash, not placeholder
+```
 
 ## Done When
 
@@ -784,6 +951,7 @@ Known failure modes for this skill. Check these before declaring done.
 - Commit created with semantic message
 - Cook Report emitted with commit hash and phase list
 - Session state saved to .rune/ via session-bridge
+- Self-Validation: all checks passed
 
 ## Cost Profile