@rune-kit/rune 2.18.1 → 2.21.0

package/hooks/lib/context-key.cjs

@@ -0,0 +1,37 @@
+'use strict';
+
+// Shared state-file keying for Rune context hooks (rune-pulse, context-sense,
+// context-inject).
+//
+// State files are keyed by the Claude Code session_id, which Claude Code passes
+// on stdin to the statusline AND to every PreToolUse / UserPromptSubmit hook in
+// the same session. Because the key is identical across all of them, the hooks
+// always read the SAME pulse file the statusline wrote — and because it is
+// unique per session, counters reset automatically when a new session starts.
+//
+// process.cwd() was the previous key. It silently differed between the
+// statusline and the hook processes (e.g. different launch directories), so the
+// hooks could never find the statusline's real-percentage pulse file and fell
+// back to a stale, never-reset tool-call counter — reporting ~100% "compact
+// now" while the real context was a fraction of that.
+//
+// Falls back to a cwd hash only when session_id is unavailable (older Claude
+// Code builds that don't pass it), which preserves the legacy behavior instead
+// of crashing.
+
+const os = require('node:os');
+const path = require('node:path');
+
+function resolveStateKey(sessionId, cwd) {
+  if (typeof sessionId === 'string') {
+    const safe = sessionId.replace(/[^a-zA-Z0-9_-]/g, '').slice(0, 36);
+    if (safe) return `s_${safe}`;
+  }
+  return `cwd_${Buffer.from(cwd || process.cwd()).toString('base64url').slice(0, 16)}`;
+}
+
+function stateFile(prefix, sessionId, cwd) {
+  return path.join(os.tmpdir(), `${prefix}-${resolveStateKey(sessionId, cwd)}.json`);
+}
+
+module.exports = { resolveStateKey, stateFile };

package/hooks/metrics-collector/index.cjs

@@ -1,5 +1,6 @@
 // Rune Metrics Collector Hook
-// PostToolUse on Skill — captures skill invocations for H3 mesh analytics
+// PostToolUse on Skill|Task|Agent — captures skill invocations for H3 mesh analytics
+// (skills run both via the Skill tool and as rune:* subagents via Task/Agent)
 // Append-only JSONL to tmpdir. Flushed to .rune/metrics/ at session end.
 // Async: true — never blocks skill execution.
 //
@@ -8,11 +9,11 @@
 const fs = require('fs');
 const path = require('path');
 const os = require('os');
+const { resolveStateKey, stateFile } = require('../lib/context-key.cjs');
 
-const cwd = process.cwd();
-const hash = Buffer.from(cwd).toString('base64url').slice(0, 16);
-const metricsFile = path.join(os.tmpdir(), `rune-metrics-${hash}.jsonl`);
-const watchFile = path.join(os.tmpdir(), `rune-context-watch-${hash}.json`);
+// metricsFile + watchFile are keyed by the Claude Code session_id (parsed from
+// stdin in the handler) so they reset per session and match the session-keyed
+// context-watch counter. See lib/context-key.cjs.
 
 // Read stdin JSON to get tool input (Claude Code passes hook data via stdin)
 let stdinData = '';
@@ -20,13 +21,37 @@ process.stdin.setEncoding('utf-8');
 process.stdin.on('data', chunk => { stdinData += chunk; });
 process.stdin.on('end', () => {
   let skillName = 'unknown';
+  let claudeSessionId; // raw Claude Code session_id — used to key temp files
 
   try {
     const hookData = JSON.parse(stdinData);
-    // PostToolUse stdin: { tool: "Skill", tool_input: { skill: "rune:cook", ... }, tool_result: ... }
+    claudeSessionId = hookData.session_id;
+    // PostToolUse stdin covers TWO invocation paths:
+    //   Skill tool: { tool: "Skill", tool_input: { skill: "rune:cook", ... } }
+    //   Task tool:  { tool: "Task",  tool_input: { subagent_type: "rune:cook", ... } }
+    // In Rune most skills run as subagents via Task, so the old Skill-only
+    // capture left skills_used[] empty. Capture both.
+    const toolName = hookData.tool || hookData.tool_name || '';
     const toolInput = hookData.tool_input || {};
-    const raw = toolInput.skill || toolInput.name || '';
-    skillName = raw.replace(/^rune:/, '') || 'unknown';
+    const fromSkill = () => (toolInput.skill || toolInput.name || '').replace(/^rune:/, '') || 'unknown';
+    // Subagent path — only count Rune skills (rune:*); skip generic agents
+    // (general-purpose, Explore, claude, statusline-setup, …) which are not skills.
+    const fromSubagent = () => {
+      const sub = toolInput.subagent_type || '';
+      return /^rune:/.test(sub) ? sub.replace(/^rune:/, '') : 'unknown';
+    };
+    // Branch on TOOL NAME first (authoritative), so a Skill invocation is never
+    // mis-routed by an incidental subagent_type field. Fall back to field-sniffing
+    // only when the tool name is absent.
+    if (toolName === 'Skill') {
+      skillName = fromSkill();
+    } else if (toolName === 'Task' || toolName === 'Agent') {
+      skillName = fromSubagent();
+    } else if (toolInput.skill || toolInput.name) {
+      skillName = fromSkill();
+    } else {
+      skillName = fromSubagent();
+    }
   } catch {
     // Fallback: try env var for backwards compatibility
     const toolInput = process.env.CLAUDE_TOOL_INPUT || '';
@@ -44,6 +69,10 @@ process.stdin.on('end', () => {
     const now = Date.now();
     const ts = new Date(now).toISOString();
 
+    // Session-keyed temp files (match the session-keyed context-watch counter).
+    const metricsFile = path.join(os.tmpdir(), `rune-metrics-${resolveStateKey(claudeSessionId)}.jsonl`);
+    const watchFile = stateFile('rune-context-watch', claudeSessionId);
+
     // Read session ID from context-watch state (shared tmpdir file)
     let sessionId = null;
     try {

package/hooks/pre-tool-guard/index.cjs

@@ -7,10 +7,49 @@
 // - Per-project .rune/privacy.json config (custom patterns + overrides)
 // - Three tiers: ALLOW (silent), WARN (log), BLOCK (exit code 2)
 // - Content-aware: scans first bytes for secret patterns on WARN files
+//
+// Gate-outcome capture:
+// - BLOCK events are appended to .rune/metrics/gate-outcomes.jsonl (best-effort)
+// - passed/bypassed outcomes are NOT captured here (not observable at this layer)
 
 const fs = require('fs');
 const path = require('path');
 
+/**
+ * Append a structured gate-outcome record to .rune/metrics/gate-outcomes.jsonl
+ * relative to process.cwd(). Best-effort: any error is silently swallowed so
+ * that capture NEVER affects the BLOCK decision or exit code.
+ *
+ * @param {string} gate  - Gate name (e.g. "privacy-mesh")
+ * @param {string} outcome - "blocked" (only outcome captured here)
+ * @param {string} detail - Short human-readable reason
+ */
+function appendGateOutcome(gate, outcome, detail) {
+  try {
+    const outDir = path.join(process.cwd(), '.rune', 'metrics');
+    fs.mkdirSync(outDir, { recursive: true });
+    const outFile = path.join(outDir, 'gate-outcomes.jsonl');
+    const entry = JSON.stringify({
+      ts: new Date().toISOString(),
+      gate,
+      outcome,
+      detail: String(detail).slice(0, 200), // cap length; no PII in detail
+    });
+    fs.appendFileSync(outFile, entry + '\n');
+
+    // Bound file to last 500 lines so it never grows unbounded.
+    // Synchronous read-trim-write, fully inside this try/catch — NEVER throws,
+    // NEVER affects the BLOCK decision or exit code.
+    const raw = fs.readFileSync(outFile, 'utf-8');
+    const lines = raw.split('\n').filter(Boolean);
+    if (lines.length > 500) {
+      fs.writeFileSync(outFile, lines.slice(-500).join('\n') + '\n');
+    }
+  } catch {
+    // Capture is best-effort. NEVER throw, NEVER affect exit code.
+  }
+}
+
 // Read tool_input from Claude Code hook stdin
 let input = '';
 process.stdin.setEncoding('utf-8');
@@ -87,6 +126,11 @@ process.stdin.on('end', () => {
 
   const isBlocked = blockPatterns.some((p) => p.test(basename) || p.test(normalized));
   if (isBlocked) {
+    // Append block outcome BEFORE printing/exiting — fail-safe, never affects exit code.
+    // Only "blocked" is captured here; "passed" and "bypassed" are not observable
+    // at this layer and intentionally remain uncaptured (see GAP-1 in governance-collector.js).
+    appendGateOutcome('privacy-mesh', 'blocked', `file matched BLOCK-tier pattern: ${basename}`);
+
     console.log(`\n🚫 [Rune privacy-mesh] BLOCKED: ${filePath}`);
     console.log('  This file matches a BLOCK-tier pattern (private keys, certificates).');
     console.log('  Override: add path to .rune/privacy.json "allow" list if intentional.\n');

package/hooks/session-start/index.cjs

@@ -8,16 +8,10 @@ const os = require('os');
 const cwd = process.cwd();
 const runeDir = path.join(cwd, '.rune');
 
-// Initialize fresh session state (shared between context-watch and metrics-collector)
-const hash = Buffer.from(cwd).toString('base64url').slice(0, 16);
-const counterFile = path.join(os.tmpdir(), `rune-context-watch-${hash}.json`);
-const now = new Date().toISOString();
-const sessionId = `s-${now.slice(0, 10).replace(/-/g, '')}-${now.slice(11, 19).replace(/:/g, '')}`;
-try {
-  fs.writeFileSync(counterFile, JSON.stringify({
-    count: 0, lastWarning: 0, sessionStart: now, sessionId, toolCounts: {}
-  }));
-} catch { /* non-critical */ }
+// The context-watch counter is now keyed by the Claude Code session_id (see
+// hooks/lib/context-key.cjs), so each new session starts with a fresh counter
+// automatically — no explicit reset is needed here. (Previously this block
+// reset a cwd-keyed file, which bled across sessions in the same directory.)
 
 if (fs.existsSync(runeDir)) {
   const stateFiles = [

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rune-kit/rune",
-  "version": "2.18.1",
+  "version": "2.21.0",
   "description": "64-skill mesh for AI coding assistants — runtime auto-discipline via native hooks (Claude/Cursor/Windsurf/Antigravity), 5-layer architecture, 215+ connections, multi-platform compiler. v2.17 adds quarantine L3 for prompt-injection advisory on untrusted external content.",
   "type": "module",
   "bin": {

package/skills/adversary/SKILL.md

@@ -3,7 +3,7 @@ name: adversary
 description: "Pre-implementation red-team analysis. Use when a plan is high-risk, critical path, or expensive to reverse. Challenges plans before code is written — finds edge cases, security holes, scalability bottlenecks, error propagation risks, and integration conflicts. Catches flaws at plan time (10x cheaper than post-implementation)."
 metadata:
   author: runedev
-  version: "0.2.0"
+  version: "0.4.0"
   layer: L2
   model: opus
   group: quality
@@ -68,6 +68,31 @@ Every finding MUST reference the specific plan section, file, or assumption it c
 3. Use `scout` to identify existing code files that the plan will touch or depend on
 4. Identify the plan's core assumptions — what MUST be true for this plan to work?
 
+### Step 0.5: Steelman + Pick a Reasoning Lens
+<MUST-READ path="references/reasoning-modes.md" trigger="before challenging any plan — to steelman the thesis and select the reasoning lens per dimension"/>
+
+Before attacking, **steelman the plan's core thesis** — restate it in its strongest
+form (strip weak framing, supply the strongest implied evidence, name what's genuinely
+good). Attacking a weak paraphrase produces findings the author dismisses with "that's
+not what I meant." The steelman also seeds the Strength Notes section (Step 6).
+
+The 5 dimensions below answer *what* to attack. The 5 **reasoning modes** answer *how*:
+
+| Mode | Core question | Reach for when |
+|------|---------------|----------------|
+| **Red Team** (default) | "How would someone break/exploit/game this?" | auth, payment, user data, public input, perverse incentives. NB: this is *persona framing* (who attacks, their capability/motivation) — it composes with Step 2's attack-surface inventory, not a duplicate of it |
+| **Pre-mortem** | "It's 6 months out and this failed — why?" | migrations, infra, architecture, cascading failure |
+| **Evidence Audit** | "Does the evidence actually support this claim?" | benchmark/"X is faster"/capacity-number justifications |
+| **Dialectic** | "What's the strongest case for the opposite choice?" | tech/vendor/architecture one-way-door decisions |
+| **Socratic** | "What is this plan taking for granted?" | vague scope, consensus-driven plans, thin specs |
+
+Default to **Red Team**. Switch or add a second lens when the plan's shape calls for it
+(signal→mode table + mode mechanics in `references/reasoning-modes.md`). State which lens
+you applied per dimension — don't ask the user to pick. Dialectic's synthesis usually
+produces concrete remediations (likely HARDEN), but maps to REVISE if it exposes a
+structural flaw in the chosen approach; Socratic's surfaced assumptions and Pre-mortem's
+narratives become findings.
+
 ### Step 1: Edge Case Analysis
 
 Challenge the plan's handling of boundary conditions.
@@ -199,6 +224,7 @@ After reporting:
 ## Adversary Report: [feature/plan name]
 - **Plan analyzed**: [path to plan file]
 - **Dimensions checked**: [which of the 5 were relevant]
+- **Reasoning lens**: [Red Team | Pre-mortem | Evidence Audit | Dialectic | Socratic — and why]
 - **Findings**: [count by severity]
 - **Verdict**: REVISE | HARDEN | PROCEED
 
@@ -250,7 +276,7 @@ Trigger: plan involves auth, crypto, payment, or user data handling.
 
 1. **Pre-bundle gate** — emit `context.preview` to `context-engine` first; abort if action=block
 2. **Build context bundle** — see `references/context-bundle-format.md` for exact format
-3. **Dispatch** — emit `oracle.dispatched` signal; route via `session-bridge` detach if target model is opus-class (non-blocking)
+3. **Dispatch** — emit `oracle.dispatched` signal; route via `session-bridge` detach if target model is opus-class (non-blocking). **For genuine architectural independence** (security-critical logic, irreversible ops, a loop the in-mesh model cannot break), prefer a **different-architecture external CLI** (Gemini/Codex) over another Claude instance — a same-family reviewer shares blind spots with the author. Invoke it via the safe transport in `references/cross-model-escalation.md`: explicit per-call user authorization, read-only sandbox, stdin not inline args, binary pre-flight. Never auto-invoke an external CLI in non-interactive contexts — skip and announce.
 4. **Wait for response** — synchronous if model is sonnet-class, polled via `.rune/oracle-pending/<id>.json` if opus-class
 5. **Validate response** — every claim MUST cite file:line. Strip + warn on uncited claims (`oracle.failed` if all claims uncited)
 6. **Emit response** — `oracle.response` carries the validated diagnosis, consumed by `debug`/`fix` to override or refine their current hypothesis
@@ -281,7 +307,7 @@ Trigger: plan involves auth, crypto, payment, or user data handling.
 
 Replies failing this contract are rejected — `oracle.failed` emitted, primary agent continues without second opinion.
 
-See `references/oracle-mode.md` for the full protocol and integration with `debug`/`fix`.
+See `references/oracle-mode.md` for the full protocol and integration with `debug`/`fix`. See `references/cross-model-escalation.md` for the safe external-CLI transport when the second opinion should come from a different model architecture.
 
 ## Constraints
 
@@ -292,6 +318,7 @@ See `references/oracle-mode.md` for the full protocol and integration with `debu
 5. MUST use concrete attack scenarios, not vague warnings ("could be a problem" is NOT a finding)
 6. MUST NOT block on MEDIUM/LOW findings — only CRITICAL and HIGH trigger REVISE verdict
 7. MUST include Strength Notes — adversary finds weaknesses AND acknowledges what's well-designed
+7b. SHOULD steelman the plan's core thesis before challenging it (Step 0.5) — a challenge that only lands against a weaker paraphrase is a weak finding, not a CRITICAL/HIGH. If steelmanning reveals a dimension is genuinely solid, record "No findings after steelman" for that dimension — that satisfies the per-dimension HARD-GATE
 8. (oracle-mode) MUST emit `context.preview` BEFORE building the bundle — abort if context-engine action=block
 9. (oracle-mode) MUST validate every Oracle reply citation against the provided files — reject uncited claims as `oracle.failed`
 
@@ -307,6 +334,8 @@ See `references/oracle-mode.md` for the full protocol and integration with `debu
 | Failure Mode | Severity | Mitigation |
 |---|---|---|
 | Over-challenging — nitpicking every line of the plan | HIGH | Rigor filter: only findings you can justify with specific references. Skip theoretical 3+ condition chains |
+| Strawmanning — attacking a weaker version of the plan than what's written | HIGH | Step 0.5: steelman the thesis first; a challenge that only lands against the weak reading is dropped |
+| One-lens tunnel vision — red-teaming a decision that needed dialectic/evidence-audit | MEDIUM | Step 0.5 signal→mode table: match the reasoning lens to the plan's shape, state which lens you applied |
 | False security alarms — flagging secure patterns as vulnerable | HIGH | Call sentinel for validation before reporting security findings as CRITICAL |
 | Analysis paralysis — too many findings block all progress | MEDIUM | Max 3 CRITICAL + 5 HIGH. If more found, consolidate or prioritize top impact |
 | Missing context — challenging plan without understanding existing codebase | HIGH | Step 0 MUST load existing code context via scout before challenging |
@@ -315,9 +344,13 @@ See `references/oracle-mode.md` for the full protocol and integration with `debu
 | (oracle-mode) Bundle exceeds token cap — caller didn't prune | HIGH | Caller MUST run `context.preview` first; adversary fails fast with `oracle.failed` instead of silently truncating signal |
 | (oracle-mode) Oracle reply has no citations — model improvised | CRITICAL | Reject reply with `oracle.failed`. Primary agent continues without second opinion (better than acting on hallucination) |
 | (oracle-mode) Loop: oracle reply triggers another `agent.stuck` | HIGH | Cap at 1 oracle dispatch per primary-agent stuck cycle. Subsequent stucks must escalate to user |
+| (cross-model) External CLI invoked without authorization or in non-interactive run | CRITICAL | Per-call user authorization required; non-interactive → skip + announce. See `references/cross-model-escalation.md` |
+| (cross-model) Bundle interpolated into shell args — embedded `$(...)` executes | CRITICAL | Always pass via stdin from a temp file; read-only sandbox. Never inline `-p "<bundle>"` |
+| (cross-model) Rubber-stamping the external reviewer's verdict | MEDIUM | Reply is data, not ruling — reconcile against the artifact; classify each finding |
 
 ## Done When
 
+- Plan thesis steelmanned before challenging (Step 0.5) — reasoning lens(es) selected and stated
 - All relevant dimensions analyzed (minimum: edge cases + security + integration)
 - Every finding references specific plan section or codebase file
 - Security-sensitive plans escalated to sentinel (or confirmed not security-relevant)

package/skills/adversary/references/cross-model-escalation.md

@@ -0,0 +1,85 @@
+# Cross-Model Escalation (External CLI Transport)
+
+Oracle-mode's "Dispatch" step (oracle-mode.md §3) is abstract about *how* the bundle reaches a second model. This reference is the concrete, safe transport when that second model is a **locally-installed CLI of a different architecture** (Gemini CLI, Codex CLI, etc.) rather than an in-mesh Anthropic model.
+
+## Why a different architecture
+
+A same-family reviewer shares blind spots with the original author — the same training distribution produces the same wrong intuitions. A colder, different-architecture model is the highest-value second opinion precisely because it fails *differently*. When escalating, **prefer a non-Anthropic CLI over another Claude instance** for the genuine-independence case (security-critical logic, irreversible operations, a loop the in-mesh model cannot break).
+
+This does not replace oracle-mode's in-mesh dispatch — it is the option for when "fresh context" is not enough and you want "fresh *architecture*".
+
+## Safety properties (all load-bearing)
+
+### 1. Explicit per-invocation authorization
+
+**Never invoke an external CLI without the user's explicit yes — every time.** Authorization is per-call, not per-session: the artifact, prompt, and flags change between calls. "User said yes once" does not license the next invocation. In interactive sessions, *offer* the escalation and let the user decide; in non-interactive contexts (CI, `/loop`, scheduled runs) **skip and announce the skip** — never auto-invoke.
+
+### 2. Read-only sandbox
+
+The bundle may itself contain instructions (intentional or accidental prompt injection) that an agentic CLI would otherwise execute against the workspace. Always invoke in a read-only mode:
+
+```bash
+# Codex — read-only sandbox keeps the CLI from writing to your workspace:
+codex exec --sandbox read-only -C <repo-path> - < /tmp/cross-model-prompt.md
+
+# Gemini — '--approval-mode plan' is read-only; '-p ""' triggers non-interactive,
+# prompt read from stdin:
+gemini --approval-mode plan -p "" < /tmp/cross-model-prompt.md
+```
+
+Verify the exact flags against the installed version — CLI syntax drifts across releases. Confirm the invocation with the user before running it.
+
+### 3. stdin, never inline args
+
+Code, markdown, and review prompts routinely contain backticks, `$(...)`, and quote characters. Interpolating the bundle into a shell-quoted argument will either truncate the prompt or **execute embedded shell**. Write the full prompt to a temp file and pipe via stdin (`< /tmp/...`). Never `-p "…<bundle>…"`.
+
+### 4. Pre-flight the binary
+
+`which` passing is not enough — a stale or broken binary can pass `which` and fail on real input:
+
+1. `which gemini` / `which codex` — exists in PATH?
+2. `gemini --version` / `codex --version` — actually runs?
+3. Confirm required auth/env (API keys) is present.
+
+If any step fails: surface the failure explicitly, offer (run manually / try another tool / skip). **Do not silently fall back** to the in-mesh model — the user should know cross-model did not happen.
+
+## What to pass
+
+Pass **ARTIFACT + CONTRACT + adversarial prompt only**. Do NOT pass your own conclusion or hypothesis — handing the reviewer your answer biases it toward agreement. The reviewer must independently decide whether the artifact satisfies the contract.
+
+Adversarial framing (framing decides the answer):
+
+```
+Adversarial review. Find what is wrong with this artifact. Assume the author
+is overconfident. Look for: unstated assumptions, unhandled edge cases, hidden
+coupling or shared state, contract violations, broken conventions, failure
+modes under unexpected input.
+
+Do NOT validate. Do NOT summarize. Find issues, or state explicitly that you
+cannot find any after thorough examination.
+
+ARTIFACT: <paste>
+CONTRACT: <paste>
+```
+
+## Reconcile: output is data, not verdict
+
+The external model's reply is **input to your judgement, not a ruling**. A different-architecture reviewer can be wrong precisely because it lacks your context. Re-read the artifact against each finding and classify (first match wins):
+
+1. **Contract misread** — the reviewer flagged something because the CONTRACT you gave was unclear. Fix the contract, not the code.
+2. **Valid + actionable** — real issue, change the artifact.
+3. **Valid trade-off** — real but cost of fixing exceeds cost of accepting; document it so the user sees the call.
+4. **Noise** — correct under context the reviewer didn't have; note it, move on.
+
+Rubber-stamping the external reviewer is the same failure as ignoring it. If across 2+ cycles the reviewer surfaced substantive findings and you classified *zero* as actionable, you are validating, not doubting — stop and escalate to the user.
+
+## Checklist
+
+- [ ] User explicitly authorized THIS invocation (or: non-interactive → skipped + announced)
+- [ ] Binary pre-flighted (PATH + version + auth)
+- [ ] Read-only sandbox flag set
+- [ ] Prompt delivered via stdin from a temp file — never inline-interpolated
+- [ ] Passed ARTIFACT + CONTRACT only — not your conclusion
+- [ ] Prompt was adversarial ("find issues"), not validating ("is it good")
+- [ ] Findings reconciled against the artifact (classified, not rubber-stamped)
+- [ ] If the CLI was missing/errored → surfaced, not silently swallowed

package/skills/adversary/references/reasoning-modes.md

@@ -0,0 +1,95 @@
+# Reasoning Modes — 5 Lenses for Challenging a Plan
+
+adversary's 5 **dimensions** (edge cases, security, scalability, error propagation,
+integration) answer *what* to attack. These 5 **reasoning modes** answer *how* to
+attack — the cognitive lens you bring to each dimension. They are orthogonal: any
+dimension can be examined through any lens, and the right lens depends on the plan's
+shape and the kind of weakness most likely to hide in it.
+
+Default lens is **Red Team** (adversary's native mode). Escalate or switch when the
+signals below fire. You do not need user input to pick a lens — infer it from the plan
+and the dimension, state which lens you applied, and move on.
+
+## The 5 Modes
+
+| Mode | Core question | Best for | Output shape |
+|------|---------------|----------|--------------|
+| **Red Team** | "If someone wanted to break, exploit, or game this, how?" | Security, abuse, perverse incentives, business-logic loopholes | Adversary persona → attack vector → defense (the *persona framing*, distinct from oracle-mode's cross-model second-opinion dispatch and from Step 2's attack-surface inventory — Red Team supplies the WHO, Step 2 the WHERE) |
+| **Pre-mortem** | "It's 6 months out and this failed. Why?" | Architecture, infra, migrations, anything with cascading failure | Specific failure narrative → consequence chain → early-warning sign → mitigation |
+| **Evidence Audit** | "Does the evidence actually support this claim?" | Plans justified by benchmarks, "X is faster", capacity assumptions | Extracted claim → falsification criterion → evidence-quality verdict |
+| **Dialectic** | "What's the strongest case for the opposite choice?" | Technology/architecture decisions, "we chose X over Y" | Steelmanned thesis → strongest antithesis → synthesis (a better plan) |
+| **Socratic** | "What is this plan taking for granted?" | Vague scope, consensus-driven plans, unexamined "obviously" | Probing questions grouped by theme — surfaces hidden assumptions |
+
+## Picking the lens (signal → mode)
+
+| Signal in the plan | Switch to |
+|--------------------|-----------|
+| Auth / payment / user-data / multi-tenant / public input | **Red Team** |
+| DB migration, service mesh, infra change, "at scale it will…" | **Pre-mortem** |
+| "benchmarks show", "X is faster", "this saves N hours", capacity numbers | **Evidence Audit** |
+| "we picked X over Y", framework/vendor choice, one-way-door decision | **Dialectic** |
+| Vague terms ("scalable", "real-time", "robust"), "everyone agrees", thin spec | **Socratic** |
+
+Domain defaults when no single signal dominates: Security → Red Team · Infra/Architecture
+→ Pre-mortem · Data/Analytics → Evidence Audit · Business/strategy → Dialectic ·
+Product/UX → Socratic.
+
+## Steelman First (applies to every mode)
+
+Before challenging, restate the plan's core thesis in its **strongest** form. An
+adversary that attacks a weak paraphrase of the plan produces findings the author can
+dismiss ("that's not what I meant"). Steelmanning earns the right to challenge.
+
+1. **Strip weak framing** — reduce the plan to its core claim ("microservices" →
+   "independent deploy + scale of components accelerates 4 teams on different release cycles").
+2. **Supply the strongest evidence** the plan implied but didn't state.
+3. **Name what's genuinely good** — this becomes the Strength Notes section.
+4. Then attack *that* version. If your challenge only lands against a weaker reading,
+   it isn't a finding.
+
+Checklist: Have I made the position stronger, not weaker? Would the author recognize
+this as their view (or better)? Am I attacking this version, not an easier one?
+
+## Mode mechanics (just enough to apply)
+
+**Red Team** — Build a *specific* adversary persona (role, motivation, capability,
+access, constraints), not a generic "attacker". Specific personas → actionable vectors.
+E-commerce → fraudster (coupon abuse, fake returns); SaaS → free-tier abuser
+(multi-accounting, rate-limit evasion); API → scraper. Map each persona's vector to the
+plan's entry points, rank by likelihood × impact, propose a concrete defense.
+
+**Pre-mortem** — Assume failure as the starting point (bypasses optimism bias). A
+narrative must be specific: a named trigger, a number/threshold, the chain of events,
+who's affected, and the underlying wrong assumption. "It didn't scale" is not a
+narrative; "at 50K concurrent users the connection pool exhausted, cascading timeouts
+tripped the circuit breaker, rejecting all requests for 4 min at peak" is. Trace ≥2
+orders of consequence. Identify the early-warning sign — the thing you'd see *before*
+the failure.
+
+**Evidence Audit** — Extract the plan's claims (causal / predictive / comparative /
+quantitative — often implicit). For each, write the falsification criterion: what
+observation would prove it false? Then judge evidence quality (pilot vs production,
+sample representativeness, correlation vs causation) and surface competing explanations.
+"Migrating to K8s cuts deploy time 60%" hides three claims: pilot is representative, K8s
+is the *cause*, 60% persists at scale. Audit each.
+
+**Dialectic** — Build the antithesis by asking "if a smart, informed person disagreed,
+what's their best argument?" Sources: opposing trade-off, hidden cost, an alternative
+that solves the same problem cheaper ("modular monolith gets 80% at 20% cost"),
+precedent ("Company X reverted after 2 years"), an unserved stakeholder. Don't stop at
+the clash — drive to **synthesis**: a revised plan incorporating the best of both. This
+maps directly to adversary's HARDEN verdict.
+
+**Socratic** — Ask, don't argue. Categories: definitional ("when you say 'scalable', 10x
+or 1000x?"), evidential ("what data shows users want this?"), logical ("does caching
+*necessarily* improve UX?"), perspective-shifting ("how would the on-call engineer see
+this architecture?"), consequential ("what does this look like in 2 years?"). Each good
+question creates an "I hadn't thought about that" — surfaced assumptions become findings.
+
+## Sequencing (optional)
+
+Some plans benefit from two lenses in order: Dialectic → Pre-mortem (decide the
+approach, then stress its failure modes); Evidence Audit → Socratic (test the claims,
+then probe what's still assumed); Red Team → Pre-mortem (find the exploit, then trace
+its blast radius). Don't run more than two — adversary's job is a sharp report, not an
+exhaustive philosophy seminar.

package/skills/autopsy/SKILL.md

@@ -174,6 +174,45 @@ Generated: [date]
 
 Call `rune:journal` to record that autopsy ran, the overall health score, and the surgery queue.
 
+### Step 5b — Emit comprehension.json
+
+Write `.rune/comprehension.json` conforming to `compiler/schemas/comprehension.schema.json`.
+This is ADDITIVE — do not modify RESCUE-REPORT.md or any other output.
+
+Populate from the module analysis already completed in Steps 1–4:
+
+```json
+{
+  "project": "<project name>",
+  "generated_at": "<ISO 8601 timestamp>",
+  "source": "autopsy",
+  "health_score": <overall score 0-100 from Step 3>,
+  "layers": [
+    { "id": "<layer-id>", "name": "<human name>", "color": "<code|service|data|domain|docs|infra|concept>" }
+  ],
+  "domains": [],
+  "modules": [
+    {
+      "id": "<relative file path>",
+      "name": "<module name>",
+      "layer": "<layer id>",
+      "type": "file",
+      "complexity": "<simple|moderate|complex — map from health score: 80+=simple, 60-79=moderate, <60=complex>",
+      "files": 1,
+      "summary": "<one-line health finding — e.g. 'Score 42/100 — high cyclomatic complexity, no tests'>"
+    }
+  ],
+  "edges": []
+}
+```
+
+Rules:
+- `modules[]` — include ALL modules scored in Step 3 (this is the full health inventory, not just entry points).
+- `layers[]` — derive from the project's architectural layers detected by scout.
+- `health_score` — MUST be the weighted overall score computed in Step 3, not an estimate.
+- `edges[]` — leave empty; autopsy does not trace cross-file dependencies (that is the visualizer's job).
+- Overwrite any existing `.rune/comprehension.json` — this is a generated emit, not human-written content.
+
 ### Step 6 — Report
 
 Output a summary of the findings:
@@ -268,6 +307,7 @@ Known failure modes for this skill. Check these before declaring done.
 - All major modules scored across all 6 dimensions
 - Git archaeology run (hotspots, stale files, dead code candidates identified)
 - RESCUE-REPORT.md written to project root with Mermaid dependency diagram
+- .rune/comprehension.json written with health_score populated + all scored modules in modules[] conforming to comprehension.schema.json
 - journal called with health score and surgery queue
 - Autopsy Report emitted with overall health tier and top-3 issues
 
@@ -279,6 +319,7 @@ Known failure modes for this skill. Check these before declaring done.
 | RESCUE-REPORT.md | Markdown + Mermaid | project root |
 | Surgery queue (priority order) | Ordered list | RESCUE-REPORT.md |
 | Git archaeology findings | Bash output + summary | inline |
+| Comprehension graph | JSON | `.rune/comprehension.json` |
 | Journal entry | Text | via `journal` L3 |
 
 ## Cost Profile