@rune-kit/rune 2.2.4 → 2.3.0

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,7 +1,7 @@
 {
   "name": "@rune-kit/rune",
-  "version": "2.2.4",
-  "description": "58-skill mesh for AI coding assistants — 5-layer architecture, 200+ connections, 8 platforms (Claude Code, Cursor, Windsurf, Antigravity, Codex, OpenCode, OpenClaw, Generic)",
+  "version": "2.3.0",
+  "description": "59-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": {
     "rune": "./compiler/bin/rune.js"
@@ -9,11 +9,12 @@
   "scripts": {
     "build": "node compiler/bin/rune.js build",
     "doctor": "node compiler/bin/rune.js doctor && node scripts/version-sync-check.js",
-    "test": "node --test compiler/__tests__/*.test.js",
+    "test": "node --test compiler/__tests__/*.test.js scripts/__tests__/*.test.js",
+    "test:coverage": "c8 --reporter=text --reporter=lcov node --test compiler/__tests__/*.test.js scripts/__tests__/*.test.js",
     "lint": "biome check .",
     "lint:fix": "biome check --fix .",
     "format": "biome format --write .",
-    "ci": "biome check . && node --test compiler/__tests__/*.test.js && node compiler/bin/rune.js doctor",
+    "ci": "biome check . && node --test compiler/__tests__/*.test.js scripts/__tests__/*.test.js && node compiler/bin/rune.js doctor",
     "version-check": "node scripts/version-sync-check.js",
     "prepublishOnly": "node scripts/version-sync-check.js"
   },
@@ -57,6 +58,7 @@
     "url": "https://github.com/rune-kit/rune/issues"
   },
   "devDependencies": {
-    "@biomejs/biome": "^2.4.7"
+    "@biomejs/biome": "^2.4.7",
+    "c8": "^10.1.3"
   }
 }

package/skills/adversary/SKILL.md

@@ -266,6 +266,18 @@ Trigger: plan involves auth, crypto, payment, or user data handling.
 - Findings formatted for consumption by cook Phase 3 (if PROCEED) or plan (if REVISE)
 - Strength Notes section acknowledges well-designed aspects of the plan
 
+## Returns
+
+| Artifact | Format | Location |
+|----------|--------|----------|
+| Adversary Report | Markdown | inline (stdout) |
+| Threat findings | Structured list (CRITICAL/HIGH/MEDIUM) | inline |
+| Risk matrix per dimension | Table | inline |
+| Verdict + remediation list | Markdown | inline |
+| Hardened plan notes (if PROCEED) | Text | passed to cook Phase 3 |
+
 ## Cost Profile
 
 ~4000-8000 tokens input (plan + codebase context), ~2000-3000 tokens output. Opus model for adversarial depth. Runs once per feature plan — high cost justified by preventing wasted implementation cycles.
+
+**Scope guardrail:** adversary reviews THE PLAN only — never audits existing codebase quality or rewrites code.

package/skills/audit/SKILL.md

@@ -3,7 +3,7 @@ name: audit
 description: Comprehensive project audit — security, dependencies, code quality, architecture, performance, infra, docs, and mesh analytics. Delegates to specialist skills and generates an 8-dimension health score.
 metadata:
   author: runedev
-  version: "0.1.0"
+  version: "0.3.0"
   layer: L2
   model: sonnet
   group: quality
@@ -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)
 
@@ -55,6 +56,24 @@ Determine:
 
 **Output before proceeding:** Brief project profile, stack summary, and which Framework-Specific Checks will be applied.
 
+### Phase 0.5: Context-Building (Pure Understanding)
+
+<HARD-GATE>
+This phase is FORBIDDEN from producing findings. No BLOCKs, no WARNs, no issues. Context-building only.
+Rushed context = hallucinated vulnerabilities. Slow is fast.
+</HARD-GATE>
+
+For each critical module (entry points, auth, data layer, core business logic):
+1. Read line-by-line. Note at minimum:
+   - **3 invariants**: What MUST always be true for this code to work? (e.g., "user is authenticated before reaching this handler")
+   - **5 assumptions**: What does this code assume about its inputs, environment, and callers?
+   - **3 risks**: What could break if assumptions are violated?
+2. Record findings as context notes — these feed into Phases 1-7, NOT into the final report directly
+
+**Why**: Without this phase, the auditor pattern-matches against known vulnerability lists and hallucinates findings that don't exist in THIS specific codebase. The invariants + assumptions ground all later analysis in reality.
+
+> Source: trailofbits/skills (3.7k★) — mandatory pure context phase before findings.
+
 ---
 
 ### Phase 1: Dependency Audit
@@ -363,6 +382,36 @@ Use `Write` to save `AUDIT-REPORT.md` to the project root with the full findings
 
 Call `rune:journal` to record: audit date, overall health score, verdict, and CRITICAL count.
 
+## Weighted Composite Scoring
+
+Each dimension score feeds into a weighted composite formula that produces a single comparable health score. Use this formula to compute **Overall Health** — not a simple average.
+
+### Scoring Formula
+
+```
+Overall = (Security × 0.25) + (Code Quality × 0.20) + (Architecture × 0.15)
+        + (Dependencies × 0.15) + (Performance × 0.10) + (Infrastructure × 0.08)
+        + (Documentation × 0.07)
+```
+
+Mesh Analytics (Phase 8) is advisory — it contributes 0 to the weighted score but informs the verdict narrative.
+
+### Grade Thresholds
+
+| Score Range | Grade | Verdict | Action |
+|-------------|-------|---------|--------|
+| 90–100 | Excellent | PASS | Routine audit in 3 months |
+| 75–89 | Good | PASS | Address MEDIUM items next sprint |
+| 60–74 | Fair | WARNING | Fix HIGH items within 2 weeks |
+| 40–59 | Poor | FAIL | Fix CRITICAL + HIGH within 1 week |
+| 0–39 | Critical | FAIL | Emergency response — CRITICAL items block all new work |
+
+### Why Weighted (not average)
+
+Security issues cause exponential blast — a 3/10 security score with all other dimensions at 9/10 = overall 72 (Fair), not 8.1 (Good). The formula ensures security and code quality dominate the verdict. Comparable across runs: if Overall moves from 68 → 74 after fixes, the project measurably improved.
+
+> Source: zubair-trabzada/geo-seo-claude (2.7k★) — explicit weighted formula with 5-tier grade thresholds.
+
 ## Severity Levels
 
 ```
@@ -410,6 +459,10 @@ Apply confidence filtering: only report findings with >80% confidence. Consolida
 | Documentation  | [n]    |
 | Mesh Analytics | [n]    |
 
+### Composite Score
+- **Formula**: (Security×0.25) + (Code Quality×0.20) + (Architecture×0.15) + (Dependencies×0.15) + (Performance×0.10) + (Infrastructure×0.08) + (Documentation×0.07)
+- **Weighted Score**: [computed value] → Grade: [Excellent/Good/Fair/Poor/Critical]
+
 ### Top Priority Actions
 1. [action] — [file:line] — [why it matters]
 
@@ -443,6 +496,16 @@ Report saved to: AUDIT-REPORT.md
 | Deps Gate | dependency-doctor report received before assembling final report | Invoke rune:dependency-doctor — do not skip |
 | Report Gate | All 8 phases completed before writing AUDIT-REPORT.md | Complete all phases, note skipped ones |
 
+## Returns
+
+| Artifact | Format | Location |
+|----------|--------|----------|
+| Audit report | Markdown | `AUDIT-REPORT.md` (project root) |
+| 8-dimension health score | Markdown table | `AUDIT-REPORT.md` + inline |
+| Weighted composite score + grade | Markdown | inline + `AUDIT-REPORT.md` |
+| Mesh analytics section | Markdown table | inline + `AUDIT-REPORT.md` |
+| Journal entry | Text | `.rune/adr/` (via `rune:journal`) |
+
 ## Sharp Edges
 
 | Failure Mode | Severity | Mitigation |

package/skills/autopsy/SKILL.md

@@ -195,6 +195,18 @@ Known failure modes for this skill. Check these before declaring done.
 - journal called with health score and surgery queue
 - Autopsy Report emitted with overall health tier and top-3 issues
 
+## Returns
+
+| Artifact | Format | Location |
+|----------|--------|----------|
+| Health score per module | Scored table (0-100) | inline |
+| RESCUE-REPORT.md | Markdown + Mermaid | project root |
+| Surgery queue (priority order) | Ordered list | RESCUE-REPORT.md |
+| Git archaeology findings | Bash output + summary | inline |
+| Journal entry | Text | via `journal` L3 |
+
 ## Cost Profile
 
 ~5000-10000 tokens input, ~2000-4000 tokens output. Opus for deep analysis. Most expensive L2 skill but runs once per rescue.
+
+**Scope guardrail:** autopsy assesses — it does not refactor. All surgery is delegated to `surgeon` after the report is complete.

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:
@@ -259,6 +311,15 @@ Saved to `.rune/features/<feature-name>/requirements.md`
 6. MUST ask ONE question at a time — don't overwhelm user with 5 questions at once
 7. MUST NOT skip BA for non-trivial tasks — "just build it" gets redirected to Question 1
 
+## Returns
+
+| Artifact | Format | Location |
+|----------|--------|----------|
+| Requirements document | Markdown | `.rune/features/<feature-name>/requirements.md` |
+| User stories with acceptance criteria | Markdown (GIVEN/WHEN/THEN) | inline + requirements.md |
+| Scope definition (in/out/assumptions) | Markdown sections | requirements.md |
+| Non-functional requirements table | Markdown table | requirements.md |
+
 ## Sharp Edges
 
 Known failure modes for this skill. Check these before declaring done.
@@ -272,6 +333,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/brainstorm/SKILL.md

@@ -299,6 +299,15 @@ Choose Option B if [specific hedge condition].
 Proceeding to rune:plan with Option A. Constraints to honor: [list].
 ```
 
+## Returns
+
+| Artifact | Format | Location |
+|----------|--------|----------|
+| Option matrix (2-3 Discovery / 3-5 Rescue) | Markdown sections | inline (chat output) |
+| Trade-off analysis per option | Markdown (pros/cons/effort/risk) | inline |
+| Single recommendation with hedge condition | Markdown | inline |
+| Approved design document | Markdown | `docs/plans/<feature>.md` |
+
 ## Sharp Edges
 
 Known failure modes for this skill. Check these before declaring done.
@@ -326,3 +335,5 @@ Known failure modes for this skill. Check these before declaring done.
 ## Cost Profile
 
 ~2000-5000 tokens input, ~1000-2500 tokens output. Opus for creative reasoning depth. Runs infrequently — only when creative exploration is needed.
+
+**Scope guardrail:** Brainstorm produces options and a recommendation — never implementation code or an execution plan. All code and planning begins only after user approves an approach and `rune:plan` is invoked.

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.3.0"
+  version: "1.6.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,25 @@ IF no evidence found:
   → UNCONFIRMED (agent may be right but didn't prove it)
 ```
 
+**3-Axis verification** — categorize each claim into one of three axes, then ensure all axes are covered:
+
+| Axis | Question | Example Claims |
+|------|----------|----------------|
+| **Completeness** | Were all planned tasks done? All specs implemented? | "implemented feature X", "all TODO items done", "migration created" |
+| **Correctness** | Does output match spec intent? Do tests verify real behavior? | "tests pass", "build succeeds", "lint clean", "fixed the bug" |
+| **Coherence** | Does it follow project patterns? Consistent with existing code? | "follows conventions", "uses existing patterns", "no new deps needed" |
+
+If an axis has ZERO claims → flag as gap: "No [Completeness/Correctness/Coherence] evidence found — agent may have skipped this dimension."
+
+> Source: Fission-AI/OpenSpec (32.8k★) — 3-dimensional verification beyond pass/fail.
+
+**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
+5. Check **axis coverage** — are all 3 axes (Completeness/Correctness/Coherence) represented? Missing axis = investigation gap
+
 ### Step 4 — Report
 
 ```
@@ -200,12 +245,16 @@ Completion Gate Report with status (CONFIRMED/UNCONFIRMED/CONTRADICTED), claim v
 | 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
 
 - All completion claims extracted from agent output
 - 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
 - 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.4.0"
+  version: "0.6.0"
   layer: L3
   model: haiku
   group: state
@@ -130,6 +130,23 @@ In addition to tool-call counting, monitor context window percentage when availa
 Debounce: emit advisory max once per 5 tool calls to avoid noise.
 Tool-call thresholds (Steps 1-2) remain the primary signal. Percentage advisory is supplementary — use when CLI status bar data is available.
 
+## Iterative Retrieval (Context-Loading Strategy)
+
+When loading context for a task (Phase 1 of cook, or onboard), use a 4-phase retrieval loop instead of loading everything at once:
+
+```
+1. DISPATCH (broad): Search with initial task keywords → get 5-10 candidate files
+2. EVALUATE: Score each file's relevance (0-1). Note codebase-specific terminology discovered
+3. REFINE: Use discovered terms to search again with better keywords
+4. LOOP: Repeat max 3 cycles. STOP when 3 high-relevance files found (not 10 mediocre ones)
+```
+
+**Why**: The first search cycle reveals codebase-specific terms (custom class names, project conventions, internal APIs) that produce much better results in cycle 2. Loading 3 deeply relevant files beats loading 10 surface-level matches.
+
+**Key rule**: Stop at 3 high-relevance files, not 10 mediocre ones. Quality > quantity for context loading.
+
+> Source: affaan-m/everything-claude-code (91.9k★) — 4-phase iterative retrieval.
+
 ## Context Health Levels
 
 ```
@@ -158,6 +175,71 @@ Note: These are tool call counts, NOT token percentages. Claude Code does not ex
 - Blockers: [if any]
 ```
 
+## Strategic Compact Decision Table
+
+When ORANGE or RED is reached, use this table to determine whether compaction is safe at the current boundary:
+
+| Transition | Compact? | Reason |
+|-----------|----------|--------|
+| 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 |
+| 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 |
+
+**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.
+
+> Source: affaan-m/everything-claude-code (91.9k★) — strategic compact timing decision table.
+
+## 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.
+
+### Token Cost Reference
+
+| Source | Approx. Cost | Loaded When |
+|--------|-------------|-------------|
+| Each MCP tool schema | ~500 tokens | Session start (always) |
+| Each agent description | ~200-400 tokens | Every `Task()` invocation |
+| CLAUDE.md | ~100-2000 tokens | Session start (always) |
+| Skill SKILL.md (full load) | ~500-3000 tokens | When skill is invoked |
+
+### Budget Rules
+
+| Rule | Threshold | Action |
+|------|-----------|--------|
+| Max MCP servers | <10 active | Disable unused MCP servers in settings |
+| Max MCP tools | <80 total | Remove or consolidate bloated MCP servers |
+| Agent descriptions | Only load needed | Use specific `subagent_type` to avoid loading all descriptions |
+| CLAUDE.md size | <150 lines | Move detailed docs to `.rune/` files, keep CLAUDE.md as index |
+
+### Audit Procedure
+
+When context health is YELLOW or worse, or when onboard detects >80 MCP tools:
+
+1. Count total MCP tool schemas loaded (from session start messages)
+2. Count agent descriptions available
+3. Estimate baseline cost: `(tools × 500) + (agents × 300) + CLAUDE.md tokens`
+4. If baseline >15% of estimated context window → flag as **Context Budget Warning**
+5. Rank MCP servers by tool count — suggest disabling servers with most tools and least usage
+
+### Report Addition
+
+When Context Budget Warning fires, append to Context Health report:
+
+```
+### Context Budget
+- **Baseline cost**: ~[N]k tokens ([X]% of estimated window)
+- **MCP tools loaded**: [count] across [N] servers
+- **Top consumers**: [server1] ([N] tools), [server2] ([N] tools)
+- **Recommendation**: Disable [server] to save ~[N]k tokens
+```
+
+> Source: affaan-m/everything-claude-code (91.9k★) — MCP token cost awareness and budget rules.
+
 ## Constraints
 
 1. MUST preserve context fidelity — no summarizing away critical details