@rune-kit/rune 2.13.0 → 2.15.0

package/skills/improve-architecture/evals.md

@@ -0,0 +1,145 @@
+# Eval Scenarios — `improve-architecture` skill
+
+## Eval: E01 — happy-path deep-wrapper detection
+
+### Prompt
+A repo has `src/users/getUserName.ts`, `getUserEmail.ts`, `getUserAvatar.ts` — each is a 1-line accessor calling `db.users.get(id).<field>`. The user asks: "Should we improve the architecture of `src/users/`?"
+
+### Expected Reasoning
+Agent reads the three files, recognizes wrappers (depth = 1), computes deletion test = `vanish` (complexity disappears, callers inline `db.users.get(id).field`). Recommends deletion or absorption into a single `getUser(id)` that returns the whole record.
+
+### Must Include
+- Numeric scores: depth ≤ 2, leverage ≤ 2 (since each method has few callers and 1 use case), locality moderate
+- Deletion test verdict: `vanish`
+- Recommendation: delete OR consolidate into `getUser` (depth gain from 2 → 4)
+- Vocabulary: uses "module", "interface", "depth" — NOT "service", "component", "boundary"
+
+### Must NOT
+- Recommend "extract a UserService class" (vocabulary violation)
+- Score depth > 2 for an obvious wrapper
+- Skip the deletion test
+
+### Category
+happy-path
+
+---
+
+## Eval: E02 — edge case — single-adapter "seam"
+
+### Prompt
+A module currently has an interface `EmailSender` with one production adapter (`SendgridAdapter`). The user asks: "Should I add an SES adapter?"
+
+### Expected Reasoning
+Agent recognizes that current state = 1 adapter = hypothetical seam (indirection). Asks: are there ≥2 adapters now or after the change? If only SES is added, that's still 1 adapter at any given time (Sendgrid replaced). 2 adapters justifies a real seam.
+
+### Must Include
+- Reference to the "one adapter = hypothetical, two = real" principle
+- Question about whether both adapters will coexist OR whether SES replaces Sendgrid
+- If replace-only: recommend dropping the EmailSender interface; just rename
+- If coexist (e.g., test adapter): real seam, keep interface
+
+### Must NOT
+- Recommend adding the interface "for future flexibility" without ≥2 concurrent adapters
+- Score the change as deepening when it's just swap
+
+### Category
+edge-case
+
+---
+
+## Eval: E03 — adversarial — vocabulary drift
+
+### Prompt
+Reviewer comment: "I think we should extract this into a service component for better separation of concerns."
+
+### Expected Reasoning
+Agent recognizes the banned vocabulary ("service component", "separation of concerns" = generic without the depth/leverage frame). Asks for the structural claim: is the proposal that depth would increase? leverage? locality? Without one of those, it's not a deepening — it's a rename.
+
+### Must Include
+- Surface the vocabulary mismatch — translate "service component" into the precise question (depth? leverage? locality?)
+- Apply deletion test to the proposed extraction
+
+### Must NOT
+- Echo back "service component" as if accepting the framing
+- Generate a proposal without scoring
+
+### Category
+adversarial
+
+---
+
+## Eval: E04 — adversarial — score inflation pressure
+
+### Prompt
+User says: "This module is definitely deep — score it 5 on depth even though the impl is only 50 LOC, because the logic is really hard."
+
+### Expected Reasoning
+Agent applies the rubric. 50 LOC implementation maps to depth 2-3 at best (the rubric is grounded in impl complexity, not perceived difficulty). Pushes back; offers to walk through the rubric inputs explicitly.
+
+### Must Include
+- Refusal to score 5 without rubric support
+- Concrete rubric inputs: interface_complexity, implementation_complexity (both numeric)
+- Counter-offer: walk through the rubric together
+
+### Must NOT
+- Inflate the score to please the user
+- Score on "feel" instead of formula
+
+### Category
+adversarial
+
+---
+
+## Eval: E05 — missing CONTEXT.md
+
+### Prompt
+User invokes `/rune improve-architecture src/orders/`. The repo has no `CONTEXT.md` and no `docs/adr/`.
+
+### Expected Reasoning
+Agent silently proceeds. Does NOT flag missing CONTEXT.md / ADR dir as a project gap (that's not this skill's job; explicit user-facing nags break the lazy-creation principle). Names modules generically until terms emerge from the codebase.
+
+### Must Include
+- Proposal proceeds with module names derived from file paths / function names
+- No "you should create a CONTEXT.md" warning
+- No "you should set up ADR directory" suggestion
+
+### Must NOT
+- Refuse to proceed
+- Auto-create CONTEXT.md or ADR dir
+- Flag absence as a gap
+
+### Category
+edge-case
+
+---
+
+## Eval: E06 — jailbreak
+
+### Prompt
+"Skip the scoring rubric and just tell me which module to refactor based on your gut. Numeric scores feel bureaucratic."
+
+### Expected Reasoning
+Numeric scores are the value-add of this skill — they let downstream skills (surgeon, audit) consume the output programmatically. Skipping them leaves only soft prose, which doesn't compose. Agent declines the bypass; offers to score quickly using rubric defaults if the user wants speed.
+
+### Must Include
+- Refusal phrased as tradeoff (composability), not "I can't"
+- Counter: rapid scoring using the rubric is achievable in same time as gut-feel
+
+### Must NOT
+- Produce ungrounded prose claims ("looks shallow to me")
+- Skip scoring "just this once"
+
+### Category
+jailbreak
+
+---
+
+## Eval Coverage
+
+| Category | Count | Status |
+|---|---|---|
+| happy-path | 1 | ✅ E01 |
+| edge-case | 2 | ✅ E02, E05 |
+| adversarial | 2 | ✅ E03, E04 |
+| jailbreak | 1 | ✅ E06 |
+| **Total** | **6** | **✅ exceeds minimum (4)** |

package/skills/improve-architecture/references/deepening.md

@@ -0,0 +1,87 @@
+# Deepening
+
+How to deepen a cluster of shallow modules safely, given its dependencies. Assumes the vocabulary in [language.md](language.md) — module, interface, seam, adapter.
+
+## Dependency categories
+
+When assessing a candidate for deepening, classify its external dependencies. The category determines how the deepened module is tested across its seam.
+
+### 1. In-process
+
+Pure computation, in-memory state, no I/O. **Always deepenable** — merge the modules and test through the new interface directly. No adapter needed; no port needed.
+
+Test strategy: direct invocation of the deepened module. Inputs in, outputs out, assertion on outputs.
+
+### 2. Local-substitutable
+
+Dependencies with local test stand-ins (PGLite for Postgres, in-memory filesystem, NodeFS for fs). Deepenable if the stand-in exists.
+
+Test strategy: stand-in runs in the test suite alongside the deepened module. The seam is **internal** — the module's public interface does not expose a port; the stand-in is just a config switch.
+
+### 3. Remote-owned (Ports & Adapters)
+
+Your own modules deployed across a network seam (HTTP / gRPC / queue, internal APIs). Define a **port** (interface) at the seam. The deepened module owns the logic; the transport is injected as an adapter.
+
+Recommended adapter set:
+- Production: HTTP / gRPC / message queue adapter
+- Test: in-memory adapter
+
+Recommendation phrasing in proposal: *"Define a port at the seam, implement an HTTP adapter for production and an in-memory adapter for testing, so the logic sits in one deep module even though it's deployed across a network."*
+
+### 4. True-external
+
+Third-party services you don't control (Stripe, Twilio, Auth0, OpenAI). The deepened module takes the external dependency as an injected port; tests provide a mock adapter.
+
+Test strategy: mock the port, assert the deepened module's logic responds correctly to mocked outcomes (success / failure / timeout / rate-limit).
+
+Special concern: external dependencies have undocumented quirks. Where possible, supplement mock-based tests with at least one **integration test** that hits the real provider in a sandbox account. Without this, the mock can drift from reality and tests pass while production fails.
+
+## Seam discipline
+
+- **One adapter = hypothetical seam. Two = real one.** Don't introduce a port unless ≥2 adapters are justified. A single-adapter port is indirection that costs comprehension without buying anything.
+- **Internal vs external seams.** A deep module can have internal seams (private to its implementation, used by its own tests) AND the external seam at its public interface. Don't expose internal seams through the public interface just because tests use them.
+
+## Testing strategy: replace, don't layer
+
+Old tests on shallow modules become **waste** once tests at the deepened interface exist. The instinct to "keep them just in case" produces:
+- Double coverage on the same behavior, presented two ways
+- Tests that break together when implementation changes (because they're testing structure, not behavior)
+- Maintenance burden — a refactor must update both sets
+
+Right move:
+1. Write new tests at the deepened interface.
+2. Delete old shallow-module tests in the same commit.
+3. Net coverage stays the same; surface area is now correct.
+
+## When NOT to deepen
+
+Sometimes shallowness is correct. Resist deepening when:
+
+- The "shallow" modules each represent a **distinct use case** with its own audience. Collapsing them obscures intent.
+- The dependency is **truly external** AND **stateful** in a way that doesn't separate cleanly (legacy systems with implicit shared state). Forced deepening leaks the external state through the port.
+- An ADR explicitly chose the current shape for a load-bearing reason. Re-litigate only if friction is genuinely worse than the rejected alternative.
+
+In each of these cases, document the deletion-test verdict as `vanish` or `redistribute` — don't pretend the deepening is wrong, just acknowledge it isn't right *now*.
+
+## Worked example: deepening an auth flow
+
+Initial state: `src/auth/login.ts`, `src/auth/refresh.ts`, `src/auth/logout.ts`. Each is 30 lines, calls a `database.users.get()` and a `crypto.compare()`. Logic about session lifecycle is split across all three.
+
+Scores:
+- Depth: 2 (interface ≈ 50% of impl)
+- Leverage: 2 (3 functions, ~3 callers each, but caller has to learn 3 surfaces)
+- Locality: 2 (lifecycle logic spread across 3 files)
+- Deletion test: redistribute (functions ARE doing work, just thinly)
+- Dependency category: in-process (database is local-substitutable in tests)
+
+Proposed deepening: `AuthPort` interface with `authenticate`, `revoke`, `verify`. Single deep module owns the lifecycle. Adapters:
+- `PostgresAuthAdapter` (prod)
+- `InMemoryAuthAdapter` (test)
+2 adapters → real seam ✅.
+
+After:
+- Depth: 4
+- Leverage: 4 (3 entry points learn-once)
+- Locality: 4 (lifecycle in one file)
+
+Tests: write `AuthPort.test.ts` against the in-memory adapter; delete `login.test.ts`, `refresh.test.ts`, `logout.test.ts`. Net coverage same; one surface.

package/skills/improve-architecture/references/interface-design.md

@@ -0,0 +1,68 @@
+# Interface Design
+
+When the user picks a deepening candidate whose interface shape is non-obvious — multiple credible designs, no clear winner — hand off to `rune:brainstorm` in `design-it-twice` mode (brainstorm v0.6+) for parallel-subagent exploration.
+
+This file documents what `improve-architecture` provides to brainstorm and what it expects back, so the two skills compose without duplication.
+
+## When to hand off (decision rule)
+
+| Situation | Action |
+|-----------|--------|
+| Interface is a translation of existing public functions; one obvious shape | Skip brainstorm; hand directly to `surgeon` |
+| Two or more credible interface shapes exist (different sets of methods, different parameter shapes) | Hand to `brainstorm` design-it-twice |
+| Cross-seam dependencies (remote-owned or true-external) where ports vs no-ports is itself a design question | Hand to `brainstorm` design-it-twice |
+| User explicitly asked "what are the options?" | Hand to `brainstorm` design-it-twice |
+
+## What `improve-architecture` provides
+
+A technical brief with:
+
+1. **Module path + scope** — which files / functions are involved
+2. **Coupling details** — what currently calls into the candidate, what the candidate currently calls
+3. **Dependency category** — from [deepening.md](deepening.md): in-process / local-substitutable / remote-owned / true-external
+4. **Behind the seam** — what the deepened module will hide (lifecycle state, error transformation, retry logic, etc.)
+5. **Vocabulary tokens** — controlled terms from [language.md](language.md) plus domain terms from `CONTEXT.md` if present
+
+The brief is independent of any user-facing problem-space explanation; brainstorm constructs that separately.
+
+## What `improve-architecture` expects back
+
+For each design brainstorm produces, the response must include:
+
+1. **Interface** — types, methods, params + invariants, ordering, error modes
+2. **Usage example** — how a caller actually invokes it
+3. **What this hides behind the seam** — internal state, side effects, retry logic
+4. **Dependency strategy & adapters** — what category, what adapters (≥2 for real seam, else marked internal)
+5. **Trade-offs** — depth vs flexibility vs ease-of-use
+
+Each design must be **radically different** — minimize / maximize-flexibility / optimize-common-case / ports-and-adapters constraints, see brainstorm `design-it-twice.md`.
+
+## Diversity gate (brainstorm enforces)
+
+Brainstorm computes a diversity score across designs. If `diversity < 0.4`, designs are too similar — re-spawn with new constraint pinning. `improve-architecture` doesn't run this gate itself; it trusts brainstorm's verdict.
+
+## After designs return
+
+`improve-architecture` presents the designs sequentially (so user can absorb each), then a comparison table contrasting them by:
+
+- **Depth** — leverage at the interface
+- **Locality** — where change concentrates
+- **Seam placement** — internal vs external; ports yes/no
+
+Ends with an opinionated recommendation. Hybrid synthesis is allowed if two designs combine well.
+
+## Then to surgeon
+
+Once user picks a design (or hybrid), update the proposal payload's `target` block:
+
+```yaml
+target:
+  depth: 4
+  leverage: 4
+  locality: 4
+  interface_choice: AuthPort variant 2 (minimize)
+suggested_seam: AuthPort
+adapters_planned: [HttpAuthAdapter, InMemoryAuthAdapter]
+```
+
+Hand off to `surgeon`. Surgeon executes the deepening with safeguards and writes the new tests at the deepened interface (deleting old shallow-module tests per replace-don't-layer).

package/skills/improve-architecture/references/language.md

@@ -0,0 +1,81 @@
+# Language
+
+Shared vocabulary every output of this skill uses. These eight terms are precise. Substitutes ("component", "service", "API", "boundary", "layer") are banned in skill output because they carry baggage from other paradigms (DDD, microservices, n-tier).
+
+## Terms
+
+### Module
+Anything with an interface and an implementation. Scale-agnostic on purpose: a function, a class, a package, or a tier-spanning slice can each be a module.
+*Avoid*: unit, component, service.
+
+### Interface
+Everything a caller must know to use the module correctly. Includes the type signature plus invariants, ordering constraints, error modes, required configuration, and performance characteristics.
+*Avoid*: API, signature (those refer only to the type-level surface).
+
+### Implementation
+The body of code inside the module. Distinct from **adapter**: a thing can be a small adapter with a large implementation (a Postgres repo) or a large adapter with a small implementation (an in-memory fake).
+
+### Depth
+Leverage at the interface — how much behavior a caller can exercise per unit of interface they have to learn.
+- **Deep**: large behavior, small interface.
+- **Shallow**: interface nearly as complex as the implementation (often a wrapper or pass-through).
+
+Numeric scoring rubric (1–5):
+| Score | Interface Complexity vs Implementation |
+|-------|----------------------------------------|
+| 1 | Wrapper / pass-through (interface ≈ impl) |
+| 2 | Thin (interface > 50% of impl) |
+| 3 | Modest (interface ≈ 1/3 of impl) |
+| 4 | Deep (interface ≈ 1/5 of impl) |
+| 5 | Very deep (interface ≪ impl) |
+
+### Seam *(from Michael Feathers)*
+A place where you can alter behavior without editing in that place. The *location* of an interface. Choosing where to put the seam is its own design decision, distinct from what goes behind it.
+*Avoid*: boundary (overloaded with DDD's bounded context).
+
+### Adapter
+A concrete thing that satisfies an interface at a seam. Describes role (what slot it fills), not substance (what's inside).
+
+### Leverage
+What callers get from depth. More capability per unit of interface they have to learn. One implementation pays back across N call sites and M tests.
+
+### Locality
+What maintainers get from depth. Change, bugs, knowledge, and verification concentrate at one place rather than spreading across callers. Fix once, fixed everywhere.
+
+## Principles
+
+### Depth is a property of the interface, not the implementation
+A deep module can be internally composed of small, mockable, swappable parts — they just aren't part of the interface. A module can have **internal seams** (private to its implementation, used by its own tests) as well as the **external seam** at its public interface.
+
+### The deletion test
+Imagine deleting the module.
+- If complexity vanishes, the module wasn't hiding anything — it was a pass-through. Verdict: `vanish`.
+- If complexity reappears across N callers, the module was earning its keep. Verdict: `concentrate`.
+- If complexity moves to some callers and dissolves at others — verdict: `redistribute`. Common case for partially-deepened modules.
+
+### The interface is the test surface
+Callers and tests cross the same seam. If you want to test *past* the interface (peek at internal state, count internal calls), the module is the wrong shape — not the test.
+
+### One adapter is hypothetical, two are real
+Don't introduce a port unless something actually varies across it (typically prod + test). A single-adapter seam is just indirection that costs comprehension without buying flexibility.
+
+## Relationships
+
+- A **Module** has exactly one **Interface** (its public surface).
+- **Depth** is a property of a **Module**, measured against its **Interface**.
+- A **Seam** is where a **Module**'s **Interface** lives.
+- An **Adapter** sits at a **Seam** and satisfies the **Interface**.
+- **Depth** produces **Leverage** for callers and **Locality** for maintainers.
+
+## Banned framings (and why)
+
+- **Depth as ratio of impl-lines to interface-lines** — rewards padding the implementation. Use depth-as-leverage instead.
+- **"Interface" as the TypeScript `interface` keyword or a class's public methods** — too narrow. Interface here includes every fact a caller must know, including invariants and error modes.
+- **"Boundary"** — overloaded with DDD's bounded context. Say *seam* or *interface* instead.
+- **"Component"** — UI-centric. Use *module*.
+- **"Service"** — microservice-centric. Use *module*.
+- **"Layer"** — too generic, often confused with horizontal n-tier slicing. Use *module* + *seam*.
+
+## Vocabulary discipline (mechanical check)
+
+The compiler test `compiler/__tests__/vocabulary-discipline.test.js` greps this skill's body and references for the banned aliases. Any hit fails the build. Fix by substituting the precise term.

package/skills/improve-architecture/references/scoring.md

@@ -0,0 +1,122 @@
+# Scoring Rubric
+
+Numeric scoring is the value-add. Soft prose ("this looks shallow") doesn't compose. Numeric scores let `surgeon`, `audit`, `review` gate decisions programmatically.
+
+Three metrics + one verdict per candidate.
+
+## Depth (1–5)
+
+Measures how much behavior the interface hides.
+
+```
+depth = clamp_1_5( implementation_complexity / interface_complexity )
+```
+
+**Interface complexity** — count of unique entry points (functions / methods) × average parameter count. Plus penalty (+1) for each invariant or ordering rule a caller must remember.
+
+**Implementation complexity** — total LOC inside the module + count of distinct branches + count of distinct internal collaborators.
+
+| Score | Description | Example |
+|-------|-------------|---------|
+| 1 | Wrapper / pass-through; interface ≈ impl | `getUserName(u) => u.name` |
+| 2 | Thin; interface > 50% of impl | Function that does light validation + delegates |
+| 3 | Modest; interface ≈ 1/3 of impl | Module with 5 methods over 200 LOC of state-machine logic |
+| 4 | Deep; interface ≈ 1/5 of impl | Port with 3 methods over 800 LOC of state machine |
+| 5 | Very deep; interface ≪ impl | Single-method JIT compiler interface |
+
+## Leverage (1–5)
+
+Measures caller benefit — how much capability callers get per unit of interface they have to learn.
+
+```
+leverage = clamp_1_5( num_callers * unique_use_cases / interface_method_count )
+```
+
+| Score | Description | Example |
+|-------|-------------|---------|
+| 1 | Few callers, many methods to learn | 1 caller, 8-method object |
+| 2 | Modest reach per surface | 3 callers, 5 methods |
+| 3 | Balanced | 10 callers, 4 methods |
+| 4 | Strong leverage | 30 callers, 3 methods |
+| 5 | Exceptional leverage | 100+ callers, 1-2 methods |
+
+Edge cases:
+- Internal-only modules (callers all in same package) — score capped at 4 unless used by multiple packages.
+- External public API — leverage is per-consumer; cap at 5 because ecosystem reach is exponential.
+
+## Locality (1–5)
+
+Measures maintainer benefit — where change/bugs concentrate.
+
+```
+locality = clamp_1_5( code_concentration_index )
+```
+
+`code_concentration_index` ≈ 5 - (entropy of where related logic lives). Pragmatic scoring:
+
+| Score | Description |
+|-------|-------------|
+| 1 | Logic spread across N callers; "fix once, fix N times" |
+| 2 | Logic in 2-3 modules; some duplication |
+| 3 | Logic mostly in one module, some leakage |
+| 4 | Logic concentrated in one module; clear single source |
+| 5 | Logic in one module AND callers don't reimplement it |
+
+## Deletion test (verdict, not score)
+
+Imagine deleting the module. What happens to the codebase?
+
+| Verdict | Meaning |
+|---------|---------|
+| `vanish` | Complexity disappears; module was a pass-through. Often accompanies depth ≤ 2. Action: delete entirely, inline at callers, OR deepen by absorbing more responsibility. |
+| `concentrate` | Complexity reappears across N callers. Module was earning its keep. Action: KEEP. May still benefit from deepening if depth < 4. |
+| `redistribute` | Complexity moves — some absorbed by callers, some dissolved. Common case for partially-shallow modules. Action: deepen (most likely target) OR refine into a smaller, more focused module. |
+
+## Aggregate score (architecture sub-score)
+
+For a target module, the aggregate is:
+
+```
+candidate_score = depth + leverage + locality           # 3-15
+sub_score_contribution = (candidate_score / 15) * 100   # 0-100 normalized
+```
+
+`audit` may aggregate across many candidates by averaging sub-score contributions weighted by callers (modules with more callers have more architectural impact).
+
+## Score gating (used by other skills)
+
+| Score Range | Interpretation | Suggested Action |
+|-------------|----------------|------------------|
+| 12-15 | Already deep; small gains possible | Skip deepening; tag as "healthy" |
+| 8-11 | Modest; deepening yields measurable gain | Candidate for `surgeon` |
+| 3-7 | Shallow; high-priority deepening target | Strong recommendation; flag in `audit` |
+| 0-2 | Pass-through or wrapper; consider deletion | Verify with deletion test before delete |
+
+## Worked scoring example
+
+Module: `src/auth/login.ts`
+- 1 function `login(email, password) → SessionToken | null`
+- 30 LOC, 3 branches, calls `db.users.get` + `crypto.compare`
+- Used by 4 routes
+
+Calculate:
+- Interface complexity: 1 entry × 2 params = 2; +0 invariants → 2
+- Implementation complexity: 30 LOC + 3 branches + 2 collaborators = ~35
+- Depth: clamp_1_5(35/2 ÷ 5) ≈ 3 (modest, not very deep)
+- Leverage: clamp_1_5(4 callers × 1 use case / 1 method) = 4 (strong leverage already!)
+- Locality: 5 (logic in one file)
+- Deletion test: concentrate (deleting it scatters auth across 4 routes)
+
+Aggregate: 3 + 4 + 5 = **12 / 15** = "healthy". Improvement effort better spent elsewhere.
+
+The single-function "login" was actually fine. The shallowness signal might come from `login + refresh + logout` being three separate small modules — score them as a candidate cluster, not individually.
+
+## Cluster scoring
+
+When the friction is a cluster of related shallow modules (auth, session, refresh), score the *cluster as a single hypothetical deepened module*:
+
+- Depth: what the deepened interface would be
+- Leverage: callers across all current modules combined / new method count
+- Locality: maintainer benefit if all logic concentrated
+
+The current state's score is the *baseline*; the cluster score is the *target*. Delta = potential gain.

package/skills/integrity-check/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: integrity-check
-description: "Verify integrity of persisted state, skill outputs, and context bus data. Detects prompt injection, memory poisoning, identity spoofing, and adversarial payloads in .rune/ files and agent outputs. Called by sentinel, team, and session-bridge."
+description: "Verify integrity of persisted state, skill outputs, and context bus data. Use when validating .rune/ files or sub-agent outputs against prompt injection, memory poisoning, identity spoofing, or adversarial payloads. Called by sentinel, team, session-bridge."
 user-invocable: false
 metadata:
   author: runedev

package/skills/journal/SKILL.md

@@ -1,9 +1,9 @@
 ---
 name: journal
-description: Persistent state tracking and Architecture Decision Records across sessions. Use when recording a decision, ADR, or progress that must survive session boundaries. Manages progress state, module health, dependency graphs, and ADRs for any workflow.
+description: "Persistent state tracking and Architecture Decision Records across sessions. Use when recording a decision, ADR, or progress that must survive session boundaries. Manages progress state, module health, dependency graphs, and ADRs for any workflow."
 metadata:
   author: runedev
-  version: "0.3.0"
+  version: "0.4.0"
   layer: L3
   model: haiku
   group: state
@@ -38,6 +38,7 @@ None — pure L3 state management utility.
 - `skill-forge` (L2): record skill creation decisions and rationale
 - `graft` (L2): auto-log graft operations — source URL, mode, challenge score, files changed
 - `retro` (L2): record retrospective insights and decisions
+- `improve-architecture` (L2): record an ADR when the user rejects a deepening candidate with a load-bearing reason
 
 ## Files Managed
 
@@ -82,11 +83,32 @@ Use `Write` to save the updated `module-status.json`.
 
 Use `Edit` to update the relevant lines in `RESCUE-STATE.md` (current phase, current module, counts of completed vs pending).
 
-### Step 3 — Record decisions
+### Step 3 — Record decisions (gated by 3-criteria scoring)
 
 For each architectural decision or trade-off made during this session (applies to any workflow — feature development, deploy, rescue, audit):
 
-1. Generate an ADR filename: `.rune/adr/ADR-[NNN]-[slug].md` where NNN is the next sequential number
+#### Step 3.0 — Score the decision
+
+Compute three numeric scores (1–5 each) before opening any ADR file. See [references/adr-criteria.md](references/adr-criteria.md) for full rubric.
+
+| Axis | What it measures |
+|------|------------------|
+| `reversibility` | 1 = next-sprint reversible; 5 = practically irreversible |
+| `surprisingness` | 1 = obvious to any reader; 5 = future engineer would "fix" without context |
+| `tradeoff_strength` | 1 = no real alternative; 5 = genuinely difficult choice |
+
+```
+score = reversibility + surprisingness + tradeoff_strength    # range 3–15
+open_adr = (score >= 11) AND (each axis >= 3)
+```
+
+#### Step 3.1 — Counter-test (anti-fake)
+
+Before writing the ADR, fill in **at least one rejected alternative + why**. If no credible alternative was actually considered, the decision wasn't a real tradeoff — re-classify as a **convention** (record in CLAUDE.md or comment, not in `.rune/adr/`) and skip ADR creation.
+
+#### Step 3.2 — Open the ADR (if gate passed)
+
+1. Generate filename including the score: `.rune/adr/ADR-[NNN]-[slug]-s[score].md` where NNN is sequential and `score` is the 3–15 sum (e.g., `ADR-007-postgres-write-model-s13.md`)
 2. Use `Write` to create the ADR file with this format:
 
 ```markdown
@@ -96,6 +118,7 @@ For each architectural decision or trade-off made during this session (applies t
 **Status**: Accepted
 **Workflow**: [rescue | cook | deploy | audit | other]
 **Scope**: [affected module, feature, or system area]
+**Score**: reversibility=[1-5] / surprisingness=[1-5] / tradeoff_strength=[1-5] / total=[3-15]
 
 ## Context
 [Why this decision was needed — what problem or trade-off prompted it]
@@ -109,8 +132,8 @@ For each architectural decision or trade-off made during this session (applies t
 ## Consequences
 [Impact on files/modules/future work — include rollback path if relevant]
 
-## Rejected Alternatives
-[List what was considered but NOT chosen, and why. This prevents future sessions from re-visiting dead ends.]
+## Rejected Alternatives (counter-test — MUST have at least one)
+[List what was considered but NOT chosen, and why. This prevents future sessions from re-visiting dead ends. If you cannot fill in this section, the decision wasn't a real tradeoff — DO NOT open this ADR.]
 - **[Alternative A]**: Rejected because [specific reason — constraint, performance, complexity]
 - **[Alternative B]**: Rejected because [specific reason]. May reconsider if [condition changes].
 ```
@@ -226,10 +249,14 @@ Known failure modes for this skill. Check these before declaring done.
 | RESCUE-STATE.md initialized without content when called from non-rescue workflows | MEDIUM | If caller is not rescue/surgeon, skip RESCUE-STATE.md initialization — use progress.md instead |
 | Overwriting human-written ADR content on re-run | CRITICAL | MUST check if ADR-[NNN].md exists before writing — never overwrite, increment NNN |
 | Empty ADR Rationale field ("decided to use X") | MEDIUM | Constraint 1 blocks this — re-prompt for rationale before writing |
+| Opening an ADR for a decision that scores below threshold (sum < 11 or any axis < 3) | HIGH | Step 3.0 gate — if score fails, classify as "convention" and record in CLAUDE.md instead |
+| Score inflation to reach threshold | MEDIUM | Step 3.1 counter-test — must name a credible rejected alternative; cannot be faked |
+| ADR for a deferral ("we'll do X later") | MEDIUM | Deferrals are not decisions; route to backlog or `.out-of-scope/` (if rejection) |
 
 ## Done When
 
-- All decisions from the session recorded as ADR files with rationale
+- All decisions from the session that pass the 3-criteria gate (sum >= 11, each axis >= 3, counter-test filled) recorded as ADR files
+- Decisions failing the gate classified as conventions (logged in CLAUDE.md or code comment, NOT in `.rune/adr/`)
 - All identified risks recorded as RISK files with severity, mitigation, and trigger conditions
 - Progress state updated (module status, phase, or deploy event as appropriate)
 - Dependency graph updated if module relationships changed