@rune-kit/rune 2.12.3 → 2.14.0

package/skills/cook/SKILL.md

@@ -361,12 +361,12 @@ If the coder model needs info from other phases, it's in the Cross-Phase Context
 
 1. Mark Phase 3 as `in_progress`
 2. **Eval definitions** (Full/Critical rigor only): Before writing tests, define capability evals (pass@k) and regression evals (pass^k) in `.rune/evals/<feature>.md`. Capability evals test "can the system do this new thing?" — regression evals test "did we break existing behavior?" Skip for Fast/Standard rigor levels.
-3. Write test files based on the plan — cover primary use case + edge cases; tests MUST be runnable
+3. Write ONE test for the next behavior — vertical slicing required, see `rune:test` `references/vertical-tdd.md`. Bulk-writing tests = horizontal violation, blocks Phase 4
 4. **Python async pre-check** (if async-first Python flagged in Phase 1): verify `pytest-asyncio` is installed and `asyncio_mode = "auto"` is in `pyproject.toml` — if missing, warn user before writing async tests
-5. Run tests to verify they FAIL — expected: RED because implementation doesn't exist yet
-6. Mark Phase 3 as `completed`
+5. Run the test to verify it FAILS — expected: RED because implementation doesn't exist yet
+6. Mark Phase 3 as `completed` (one cycle); Phase 4 implements that one cycle, then loop returns here for the next test
 
-**Gate**: Tests MUST exist and MUST fail. If tests pass without implementation → tests are wrong, rewrite them.
+**Gate**: Test MUST exist and MUST fail. If test passes without implementation → test is wrong, rewrite. If 2+ tests staged before any GREEN → `tdd.horizontal.violation` signal, unwind to one test.
 
 ## Phase 4: IMPLEMENT (TDD Green)
 

package/skills/debug/SKILL.md

@@ -8,7 +8,7 @@ metadata:
   model: sonnet
   group: development
   tools: "Read, Bash, Glob, Grep"
-  emit: bug.diagnosed
+  emit: bug.diagnosed, agent.stuck
   listen: tests.failed
 ---
 
@@ -21,6 +21,7 @@ Root cause analysis ONLY. Debug investigates — it does NOT fix. It traces erro
 <HARD-GATE>
 Do NOT fix the code. Debug investigates only. Any code change is out of scope.
 If root cause cannot be identified after 3 hypothesis cycles:
+- Emit `agent.stuck` signal — `scout` zoom-out mode may surface the broader module map that's hiding the root cause
 - Escalate to `rune:problem-solver` for structured 5-Whys or Fishbone analysis
 - Or escalate to `rune:sequential-thinking` for multi-variable analysis
 - Report escalation in the Debug Report with all evidence gathered so far

package/skills/fix/SKILL.md

@@ -8,7 +8,7 @@ metadata:
   model: sonnet
   group: development
   tools: "Read, Write, Edit, Bash, Glob, Grep"
-  emit: code.changed
+  emit: code.changed, agent.stuck
   listen: bug.diagnosed, review.issues, preflight.blocked, security.blocked
 ---
 
@@ -142,6 +142,7 @@ When fix is called repeatedly (e.g., by cook Phase 4, or iterative fix loops), t
 **Thresholds:**
 - **>20% WTF-likelihood**: STOP fixing. Report current state to cook/user with: "Quality decay detected — continued fixes risk introducing more bugs than they resolve. {N} fixes applied, {score}% risk. Recommend: commit current progress, re-assess remaining issues."
 - **Hard cap: 30 fixes per session** — regardless of score. After 30, STOP and report.
+- **2+ consecutive fixes on the same file all failed**: emit `agent.stuck` signal (listened by `scout` zoom-out mode). Receiving agents may zoom out to the surrounding module map to recover bigger-picture context.
 
 **Reset conditions:** WTF-likelihood resets to 0% when:
 - User explicitly says "continue fixing"

package/skills/graft/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: graft
-description: "Clone, port, or convert features from any GitHub repo into your project. Understand before copy, challenge before implement. 4 modes: port (rewrite), compare (analysis), copy (transplant), improve (copy + optimize)."
+description: "Clone, port, or convert features from any GitHub repo into your project. Use when stealing patterns from external repos or porting proven code. Understand before copy, challenge before implement. 4 modes: port (rewrite), compare (analysis), copy (transplant), improve (copy + optimize)."
 metadata:
   author: runedev
   version: "0.2.0"

package/skills/improve-architecture/SKILL.md

@@ -0,0 +1,275 @@
+---
+name: improve-architecture
+description: "Find architectural friction in a codebase and propose deepening opportunities. Use when user wants to improve architecture, find refactor candidates, consolidate shallow modules, or make a codebase more testable. Outputs scored proposals (depth/leverage/locality) that surgeon and review can consume."
+metadata:
+  author: runedev
+  version: "0.1.0"
+  layer: L2
+  model: opus
+  group: quality
+  tools: "Read, Glob, Grep"
+  emit: architecture.shallow.flagged, architecture.deletion.passed
+  listen: codebase.scanned
+---
+
+# improve-architecture
+
+## Purpose
+
+Surface architectural friction in a codebase and propose **deepening opportunities** — refactors that turn shallow modules into deep ones. Output is structured (numeric scores + JSON proposal payloads) so `surgeon`, `review`, and `audit` can consume it programmatically without re-reading the codebase.
+
+The goal is **testability and AI-navigability**: a deep module presents a small interface that hides large machinery, so tests target one surface and future agents can reason about the system without traversing N small wrappers.
+
+## Vocabulary (controlled — use exactly)
+
+These eight terms have precise meanings. Banned aliases: "boundary" (overloaded with DDD), "component" (UI-specific), "service" (microservice-specific), "layer" (too generic). See [references/language.md](references/language.md) for full definitions.
+
+- **Module** — anything with an interface and an implementation (function, class, package, slice).
+- **Interface** — everything a caller must know to use the module: types, invariants, ordering, error modes, config.
+- **Implementation** — the code inside.
+- **Depth** — leverage at the interface; large behavior behind a small interface.
+- **Seam** — where an interface lives; place behavior can be altered without editing in place.
+- **Adapter** — concrete thing satisfying an interface at a seam.
+- **Leverage** — what callers get from depth.
+- **Locality** — what maintainers get from depth.
+
+## Triggers
+
+- Called by `cook` Phase 5 (quality gate) when refactor signals appear in scout output
+- Called by `surgeon` before any deepening session — produces the proposal surgeon executes
+- Called by `audit` to compute the architecture sub-score
+- Called by `review` when a reviewer flag mentions "shallow", "wrapper", "indirection"
+- Manual: `/rune improve-architecture <module-path>`
+
+## Calls (outbound)
+
+- `scout` (L2): re-scan target module + callers when input context is stale
+- `brainstorm` (L2): when the deepened module needs a new interface, hand off in `design-it-twice` mode (see brainstorm v0.6+)
+- `journal` (L3): record an ADR if the user rejects a candidate with a load-bearing reason
+
+## Called By (inbound)
+
+- `cook` (L1): Phase 5 quality gate
+- `surgeon` (L2): pre-refactor input; consumes the proposal payload
+- `audit` (L2): Phase 4 architecture sub-score
+- `review` (L2): when shallow-module flag fires during review
+- User: manual invocation
+
+## Cross-Hub Connections
+
+- `improve-architecture` → `surgeon` — proposal payload feeds surgeon's deepening session
+- `improve-architecture` ↔ `brainstorm` — when interface needs design-it-twice exploration
+- `improve-architecture` → `audit` — emits architecture sub-score
+- `improve-architecture` → `journal` — records ADRs for rejected candidates with load-bearing reasons
+
+## Inputs
+
+- Required: target module path (e.g. `src/auth/`) OR signal `codebase.scanned` from a recent scout pass
+- Optional: existing `CONTEXT.md` (domain glossary, used to name modules in their domain language)
+- Optional: `docs/adr/` directory (existing ADRs that constrain proposals — do not re-litigate)
+
+## Executable Steps
+
+### Step 1 — Read existing context
+
+Read in order, silently skipping any that don't exist:
+
+1. `CONTEXT.md` (or `CONTEXT-MAP.md` + per-bounded-context `CONTEXT.md`)
+2. Relevant `docs/adr/` files
+3. The target module's source files (use `Glob` to enumerate, cap at 30 files)
+4. Direct callers of the module (grep for imports / require / use)
+
+If `CONTEXT.md` is missing, do not flag it — treat as "no domain glossary yet". If an ADR contradicts a candidate you're forming, mark it and only surface the candidate if the friction is genuine enough to warrant ADR revision.
+
+### Step 2 — Score the candidate(s)
+
+For each candidate module, compute three numeric scores (1–5) and one verdict (enum):
+
+| Metric | Formula / Rubric |
+|--------|------------------|
+| **Depth** | `clamp_1_5(implementation_complexity / interface_complexity)` — 1 = shallow wrapper, 5 = small interface hides large machine |
+| **Leverage** | `clamp_1_5(num_callers * unique_use_cases / interface_method_count)` — 1 = thin caller benefit, 5 = many callers, fewer methods to learn |
+| **Locality** | `clamp_1_5(code_concentration_index)` — 1 = logic spread across N callers, 5 = logic concentrated in one place |
+| **Deletion test** | enum: `vanish` (was pass-through) \| `concentrate` (was earning keep) \| `redistribute` (mixed) |
+
+Rubric details and edge cases: see [references/scoring.md](references/scoring.md).
+
+### Step 3 — Classify dependencies
+
+For each candidate's external dependencies, classify into one of four categories. The category determines test strategy:
+
+| Category | Definition | Test Strategy |
+|----------|------------|---------------|
+| `in-process` | Pure computation, in-memory state, no I/O | Test through deepened interface directly |
+| `local-substitutable` | Has local test stand-in (PGLite, in-memory FS) | Use stand-in in tests; no port at module seam |
+| `remote-owned` | Your own module deployed across a network seam | Define a port; in-memory adapter for tests, HTTP adapter for prod |
+| `true-external` | Third-party (Stripe, Twilio) | Inject as port; mock adapter in tests |
+
+Full doctrine in [references/deepening.md](references/deepening.md).
+
+### Step 4 — Apply seam discipline
+
+Before recommending a port:
+
+- **One adapter = hypothetical seam. Two adapters = real seam.** Don't introduce a port unless ≥2 adapters are justified (typically prod + test).
+- Single-adapter "seams" are flagged "indirection-only" and dropped from the proposal.
+- Internal seams (private to the implementation) MAY exist for the deepened module's own tests; they don't appear in the public interface.
+
+### Step 5 — Emit proposal payload
+
+For each surviving candidate, produce a structured proposal in YAML:
+
+```yaml
+architecture.proposal:
+  module_path: src/auth/
+  current:
+    depth: 2
+    leverage: 3
+    locality: 2
+    deletion_test: redistribute
+  target:
+    depth: 4
+    leverage: 4
+    locality: 4
+  dependency_category: remote-owned
+  suggested_seam: AuthPort
+  adapters_planned: [HttpAuthAdapter, InMemoryAuthAdapter]   # 2 = real seam ✅
+  tests_to_replace: [auth/login.test.ts, auth/session.test.ts]
+  tests_to_write_new: [auth/AuthPort.test.ts]
+  domain_terms_used: [Customer, Session]   # from CONTEXT.md if present
+  adr_conflicts: []
+```
+
+### Step 6 — Present candidates to user
+
+Numbered list, each candidate showing:
+- **Files involved** — file paths (+ key types/exports for durability)
+- **Problem** — friction in the current architecture, in vocab terms (depth/leverage/locality)
+- **Solution** — plain English, naming the deepened module by its domain term if `CONTEXT.md` provides one
+- **Benefits** — leverage gain (caller-side) + locality gain (maintainer-side) + test surface change
+- **Score delta** — current → target
+
+Do NOT propose interfaces yet. Ask: "Which candidate to explore?"
+
+### Step 7 — On user pick
+
+When user picks a candidate, hand off:
+- To `brainstorm` in `design-it-twice` mode if the new interface is non-obvious (multiple credible shapes)
+- To `surgeon` with the proposal payload otherwise
+
+If user rejects a candidate with a load-bearing reason ("we don't want to centralize auth because of compliance audit isolation"), offer to record an ADR via `journal` (only if `score >= 11` per journal v0.4 criteria).
+
+## Output Format
+
+```
+## Architecture Improvement Report
+
+### Target
+- **Path**: src/auth/
+- **CONTEXT.md present**: yes / no
+- **ADRs reviewed**: 3 (none conflicting)
+
+### Candidates
+
+#### 1. Auth port consolidation (depth 2 → 4)
+- **Files**: src/auth/login.ts, src/auth/session.ts, src/auth/middleware.ts
+- **Problem**: 3 shallow modules each handle one HTTP-flavored verb; logic about `Customer` identity is split across all three (locality = 2)
+- **Solution**: collapse into AuthPort exposing `authenticate`, `revoke`, `verify` — 3 methods, deep impl
+- **Benefits**: callers learn 3 methods instead of N free functions; auth logic concentrated; tests target the port
+- **Score delta**: depth 2→4, leverage 3→4, locality 2→4
+- **Deletion test**: redistribute (current modules ARE doing work, just spread)
+
+#### 2. ...
+
+### Recommendation
+Candidate 1 — strongest leverage gain. Hand off to `brainstorm` design-it-twice for the AuthPort shape (3 credible alternatives), then `surgeon`.
+
+### Architecture sub-score
+- Current: 58/100
+- Projected after candidate 1: 78/100
+```
+
+## Returns
+
+| Artifact | Format | Location |
+|----------|--------|----------|
+| Architecture Improvement Report | Markdown | inline |
+| Proposal payloads | YAML | inline (per candidate) |
+| Architecture sub-score | integer 0-100 | inline + emitted to audit |
+| ADR draft (if user rejects with load-bearing reason) | Markdown | `.rune/adr/ADR-NNN-<slug>-s<score>.md` via journal |
+
+## Constraints
+
+1. MUST use the 8 controlled vocabulary terms exactly — no aliases ("boundary", "component", "service", "layer" are banned in skill output)
+2. MUST include numeric scores (depth/leverage/locality 1-5 each) on every candidate — soft prose claims are rejected
+3. MUST apply deletion test verdict — "vanish" candidates may be removed entirely; "concentrate" candidates are deepening targets
+4. MUST apply two-adapter rule — single-adapter seams are flagged "indirection-only" and dropped
+5. MUST NOT propose interfaces in the same step as candidate selection — present candidates first, hand to brainstorm Design-It-Twice if interface is non-obvious
+6. MUST silently skip missing `CONTEXT.md` / ADR directory — do not flag as project gap
+7. MUST emit JSON-shaped proposal payload — downstream skills (surgeon) consume it programmatically
+
+## Sharp Edges
+
+| Failure Mode | Severity | Mitigation |
+|---|---|---|
+| Recommending a deepening that contradicts a documented ADR | HIGH | Step 1 reads ADRs; if conflict, surface only if friction is real enough to revise the ADR |
+| Single-adapter seam slips into proposal | HIGH | Step 4 rule — drop or downgrade to "internal seam" |
+| Vocabulary drift (using "boundary"/"component"/"service") | MEDIUM | Constraint 1 + linter pass in compiler/__tests__/vocabulary-discipline.test.js |
+| Score inflation to make weak candidate look strong | HIGH | Each metric has rubric in scoring.md; judges show formula inputs |
+| Missing CONTEXT.md domain terms — generic naming ("AuthService") | MEDIUM | If CONTEXT.md exists, names MUST come from it; otherwise OK |
+| Proposing interface in same pass as candidates | MEDIUM | Step 6 hard-stops at candidate list; interface design = brainstorm Design-It-Twice |
+| User rejects all candidates → no ADR recorded → next session re-litigates | MEDIUM | If reason is load-bearing AND score >= 11, offer journal ADR write |
+
+## Self-Validation
+
+```
+SELF-VALIDATION (run before emitting Report):
+- [ ] Every candidate has depth + leverage + locality scores (1-5 each)
+- [ ] Every candidate has deletion-test verdict (vanish | concentrate | redistribute)
+- [ ] Every candidate names a dependency category (in-process | local-substitutable | remote-owned | true-external)
+- [ ] No banned vocabulary (grep candidate text for: boundary, component, service, layer in narrative)
+- [ ] No interfaces drafted yet — that's brainstorm's job
+- [ ] CONTEXT.md domain terms used if file present
+- [ ] Each adapter list has >=2 entries OR seam is marked "internal-only"
+IF ANY check fails → fix before reporting done.
+```
+
+## Done When
+
+- Target module read + callers mapped
+- ≥1 candidate scored on all 3 axes + deletion test
+- Proposal payload(s) emitted in valid YAML
+- Architecture sub-score computed (0-100)
+- User has either picked a candidate (handed to brainstorm/surgeon) or rejected with reason (ADR offered)
+- Report emitted with vocabulary discipline intact
+
+## Cost Profile
+
+~3000-7000 tokens input (codebase scan), ~2000-4000 tokens output (analysis + proposals). Opus model — architectural reasoning depth is the value. Called at most once per `audit` session, on-demand from `cook` / `surgeon`.
+
+## Chain Metadata
+
+```yaml
+chain_metadata:
+  skill: "rune:improve-architecture"
+  version: "0.1.0"
+  status: "[DONE]"
+  domain: "[module path scored]"
+  exports:
+    architecture_subscore: 0-100
+    candidates: [{ module, depth, leverage, locality, verdict }]
+    proposal_payloads: [<yaml-per-candidate>]
+  suggested_next:
+    - skill: "rune:brainstorm"
+      mode: "design-it-twice"
+      reason: "Top candidate has multiple credible interface shapes — need diverse exploration before commit"
+      consumes: ["proposal_payloads"]
+    - skill: "rune:surgeon"
+      reason: "User picked candidate; interface shape is obvious; ready for deepening session"
+      consumes: ["proposal_payloads"]
+    - skill: "rune:journal"
+      reason: "User rejected candidate with load-bearing reason; record ADR (score >=11)"
+      consumes: ["candidates", "rejection_reason"]
+```
+
+**Scope guardrail**: improve-architecture proposes and scores. It NEVER edits code. Refactor execution belongs to `surgeon`. Interface exploration belongs to `brainstorm` Design-It-Twice mode.

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).