@rune-kit/rune 2.13.0 → 2.15.0

package/skills/context-pack/references/durability-rules.md

@@ -0,0 +1,109 @@
+# Durability Rules — Why Briefs Rot, How to Stop It
+
+A subagent receives a context packet. A day later, after a refactor, that packet's file paths point to renamed files, line numbers point to shifted code, and "the function in `src/auth/login.ts:42`" no longer exists. The subagent burns tokens grepping to recover or — worse — generates hallucinated edits matching the stale brief.
+
+The fix is to write briefs that describe **types and contracts**, which survive moves, instead of **paths and line numbers**, which don't.
+
+## The 5 rules
+
+### 1. Behavioral over procedural
+
+Describe what the system *does*, not *where* the code lives.
+
+| ❌ Bad | ✅ Good |
+|--------|---------|
+| "Open `src/handlers/login.ts` and modify line 42" | "When a login fails 5 times, the rate limiter should reject the next attempt with a 429 response and a `Retry-After` header" |
+| "Add the field to the type at `src/types.ts:18`" | "The `LoginInput` type should accept an optional `device_id: string`" |
+| "Refactor the function around line 150 in `main.ts`" | "Extract the password-hashing path into its own module so it can be tested independently" |
+
+### 2. Type names over file paths in narrative
+
+When you must reference code in narrative prose, refer to **type names, function names, or contracts** — not file paths.
+
+| ❌ Bad | ✅ Good |
+|--------|---------|
+| "Update the function in `src/auth/`" | "Update the `authenticate` method on `AuthService`" |
+| "Modify `src/db/migrations/0042.sql`" | "The new migration should add a `device_id` column to the `sessions` table, nullable, with a default of `NULL`" |
+
+File paths may appear in a clearly-marked `### Files Touched` table — never in narrative prose.
+
+### 3. Type Surface section
+
+Add a `### Type Surface` section listing the contracts that *won't* change even if files do. This is the durable spine of the brief.
+
+```markdown
+### Type Surface (durable)
+- `LoginInput { email: string; password: string; device_id?: string }` — payload accepted by the login route
+- `AuthService.authenticate(input: LoginInput): Result<Session, AuthError>` — primary contract
+- `AuthError = "invalid_credentials" | "rate_limited" | "account_locked"` — error union the caller switches on
+```
+
+If a file gets renamed but `AuthService.authenticate` keeps its shape, the brief still applies. If the contract changes, the brief is invalidated — that's a feature, not a bug.
+
+### 4. Out of scope is mandatory
+
+Every brief includes `### Out of scope`. Receivers expand into adjacent work without this anchor. Empty list is fine *if explicitly empty* (`### Out of scope\n- (none)`); missing section is rejected by completion-gate.
+
+```markdown
+### Out of scope
+- Changing the rate-limit window (currently 1 hour — keep it)
+- Touching the audit log writer (separate ticket)
+- Anything in `src/billing/` — different domain
+```
+
+### 5. Behavioral verbs in acceptance criteria
+
+Each acceptance criterion must start with a verb from the whitelist:
+
+```
+accepts, rejects, produces, notifies, persists, retries, times-out, validates,
+returns, dispatches, redirects, throws, logs, increments, decrements, retrieves
+```
+
+Banned verb-less constructs ("the field should be present", "the type is exported") describe shape, not behavior.
+
+| ❌ Bad | ✅ Good |
+|--------|---------|
+| "The new field should exist" | "Persists the device_id when login succeeds" |
+| "An error type should be defined" | "Returns AuthError 'rate_limited' when 5 failures occur within 1 hour" |
+
+## Smell tests (mechanical regex gates)
+
+`context-pack` Phase 4.5 runs these regex against the packet body before emit. Any BLOCK-tier hit fails the gate.
+
+| Regex | Tier | Reason |
+|-------|------|--------|
+| `\b\S+\.[a-z]{1,4}:\d+\b` | BLOCK | file:line reference (e.g., `login.ts:42`) — line numbers go stale |
+| `^- \S*[\\/]\S+\.(ts\|js\|py\|go\|rs\|java)\b` (in non-`Files Touched` sections) | BLOCK | Path-only bullet in narrative |
+| `\b(line \|on line )\d+\b` | BLOCK | "line 42" / "on line 100" |
+| `\b(src\|lib\|app)/\S+` (in narrative paragraphs) | WARN | Path mention; check if it's in the right section |
+
+Whitelist for `### Files Touched` table — paths there must include the type/function name in parens for durability:
+
+```
+- `src/auth/login.ts` (LoginInput, AuthService.authenticate) — the route handler
+```
+
+Without the parens annotation, even the table entry is too brittle.
+
+## When durability rules can be relaxed
+
+Two narrow exceptions:
+
+1. **Single-cycle short tasks** (<300 tokens, <3 files) — the brief lives only as long as one cycle, and the receiving agent will execute immediately. Type Surface section becomes optional.
+2. **Bug-fix briefs with concrete repro** — sometimes the bug *is* on a specific line of a specific file as it exists right now. In that case, paths may appear in narrative IF accompanied by the type/function name. Example: *"In `AuthService.authenticate` (currently `src/auth/service.ts`), the comparison uses `<` instead of `<=`."*
+
+The rules above are defaults; the exceptions are explicit and rare. When in doubt, follow the rules.
+
+## Self-check before emit
+
+```
+[ ] Every narrative reference uses type/function names, not file paths
+[ ] Type Surface section lists contracts that won't change with file moves
+[ ] Out of scope section exists (even if "(none)")
+[ ] Every Acceptance Criterion starts with a behavior verb
+[ ] No file:line references appear anywhere
+[ ] Files Touched table entries have (Type, function) annotations
+```
+
+If any check fails, fix before the receiving agent gets the packet. A stale brief is worse than no brief at all.

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)
 
@@ -384,6 +384,7 @@ If the coder model needs info from other phases, it's in the Cross-Phase Context
 4. Run tests after each significant change — if fail → debug and fix
    - **Python async** (if async-first flagged): no blocking calls in async functions — `time.sleep` → `asyncio.sleep`, `requests` → `httpx.AsyncClient`, use `asyncio.gather()` for parallel I/O
 5. If stuck → invoke `rune:debug` (max 3 debug↔fix loops). Fixes outside plan scope require user approval (R4).
+   - **Oracle reattach check** — between tasks, glob `.rune/oracle-pending/*.json`. For any record with `status=pending`, invoke `session-bridge --reattach <sessionId>`. If `complete` → consume the response (route to debug/fix per `sourceSkill`). If `pending` → continue with next independent task. If `failed` → continue without second opinion.
 6. **Re-plan check** — evaluate before Phase 5: max debug loops hit? out-of-scope files changed? new dep changes approach? user scope change? If any fire → invoke `rune:plan` with delta context, get user approval before resuming.
 7. **Approach Pivot Gate** — if re-plan ALSO fails:
 

package/skills/db/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: db
-description: Database workflow specialist. Generates migration files with rollback scripts, detects breaking schema changes, and validates query parameterization.
+description: "Database workflow specialist. Generates migration files with rollback scripts, detects breaking schema changes, and validates query parameterization."
 metadata:
   author: runedev
   version: "0.2.0"

package/skills/debug/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: debug
-description: Root cause analysis for bugs and unexpected behavior. Traces errors through code, uses structured reasoning, and hands off to fix when cause is found. Core of the debug↔fix mesh.
+description: "Root cause analysis for bugs and unexpected behavior. Traces errors through code, uses structured reasoning, and hands off to fix when cause is found. Core of the debug↔fix mesh."
 metadata:
   author: runedev
   version: "1.1.0"
@@ -8,8 +8,8 @@ metadata:
   model: sonnet
   group: development
   tools: "Read, Bash, Glob, Grep"
-  emit: bug.diagnosed
-  listen: tests.failed
+  emit: bug.diagnosed, agent.stuck
+  listen: tests.failed, oracle.response
 ---
 
 # debug
@@ -21,7 +21,9 @@ 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:
-- Escalate to `rune:problem-solver` for structured 5-Whys or Fishbone analysis
+- Emit `agent.stuck` signal — `scout` zoom-out mode surfaces broader module map (structural pivot); `adversary` oracle-mode dispatches a stateless second-model pass (semantic pivot); both fire in parallel
+- If `oracle.response` arrives with confidence=high and cites file:line, treat as new hypothesis H_oracle and test directly (skip 3-cycle gate — it's externally validated)
+- Otherwise, 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
 </HARD-GATE>
@@ -45,6 +47,7 @@ If root cause cannot be identified after 3 hypothesis cycles:
 - `browser-pilot` (L3): capture browser console errors, network failures, visual bugs
 - `sequential-thinking` (L3): multi-variable root cause analysis
 - `neural-memory` (L3): after root cause found — capture error pattern for future recognition
+- `adversary` (L2): on `agent.stuck` — oracle-mode dispatches stateless second-model pass to break confirmation-bias loop (parallel with scout zoom-out)
 
 ## Called By (inbound)
 

package/skills/dependency-doctor/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: dependency-doctor
-description: Dependency health management. Detects package manager, checks outdated packages and vulnerabilities, and produces a prioritized update plan.
+description: "Dependency health management. Detects package manager, checks outdated packages and vulnerabilities, and produces a prioritized update plan."
 metadata:
   author: runedev
   version: "0.2.0"

package/skills/design/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: design
-description: Design system reasoning. Maps product domain to style, palette, typography, and platform-specific patterns. Generates .rune/design-system.md as the shared design contract for all UI-generating skills.
+description: "Design system reasoning. Maps product domain to style, palette, typography, and platform-specific patterns. Generates .rune/design-system.md as the shared design contract for all UI-generating skills."
 metadata:
   author: runedev
   version: "0.5.0"

package/skills/doc-processor/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: doc-processor
-description: Generate and parse office documents — PDF, DOCX, XLSX, PPTX, CSV. Pure format utility for creating reports, exporting data, and processing uploaded documents.
+description: "Generate and parse office documents — PDF, DOCX, XLSX, PPTX, CSV. Use when creating reports, exporting tabular data, or processing uploaded office files. NOT for project documentation (use docs)."
 metadata:
   author: runedev
   version: "0.2.0"

package/skills/docs/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: docs
-description: Auto-generate and maintain project documentation. Creates README, API docs, architecture docs, changelogs, and keeps them in sync with code changes. The "docs are never outdated" skill.
+description: "Auto-generate and maintain project documentation. Creates README, API docs, architecture docs, changelogs, and keeps them in sync with code changes. The \"docs are never outdated\" skill."
 metadata:
   author: runedev
   version: "0.3.0"

package/skills/docs-seeker/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: docs-seeker
-description: Find documentation for APIs, libraries, and error messages. Looks up official docs, changelog entries, and migration guides.
+description: "Find documentation for APIs, libraries, and error messages. Looks up official docs, changelog entries, and migration guides."
 metadata:
   author: runedev
   version: "0.2.0"

package/skills/fix/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: fix
-description: Apply code changes and fixes. Writes implementation code, applies bug fixes, and verifies changes with tests. Core action hub in the development mesh.
+description: "Apply code changes and fixes. Writes implementation code, applies bug fixes, and verifies changes with tests. Core action hub in the development mesh."
 metadata:
   author: runedev
   version: "1.0.0"
@@ -8,8 +8,8 @@ metadata:
   model: sonnet
   group: development
   tools: "Read, Write, Edit, Bash, Glob, Grep"
-  emit: code.changed
-  listen: bug.diagnosed, review.issues, preflight.blocked, security.blocked
+  emit: code.changed, agent.stuck
+  listen: bug.diagnosed, review.issues, preflight.blocked, security.blocked, oracle.response
 ---
 
 # fix
@@ -41,6 +41,7 @@ If unsure whether the test is wrong or the implementation is wrong → call `run
 - `hallucination-guard` (L3): verify imports after code changes
 - `scout` (L2): find related code before applying changes
 - `neural-memory` (L3): after fix verified — capture fix pattern (cause → solution)
+- `adversary` (L2): on `agent.stuck` after 2+ failed attempts — oracle-mode dispatches stateless second-model pass to break confirmation-bias loop
 
 ## Called By (inbound)
 
@@ -142,6 +143,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. `scout` zoom-out mode (structural pivot) and `adversary` oracle-mode (semantic pivot via stateless second-model dispatch) both listen and fire in parallel. If `oracle.response` arrives with confidence=high, apply its recommended edit (still routes through normal validation gates).
 
 **Reset conditions:** WTF-likelihood resets to 0% when:
 - User explicitly says "continue fixing"

package/skills/git/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: git
-description: Specialized git operations — semantic commits, PR descriptions, branch management, conflict resolution guidance. Replaces ad-hoc git commands with a dedicated, convention-aware utility.
+description: "Specialized git operations — semantic commits, PR descriptions, branch management, conflict resolution guidance. Replaces ad-hoc git commands with a dedicated, convention-aware utility."
 metadata:
   author: runedev
   version: "0.3.0"

package/skills/hallucination-guard/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: hallucination-guard
-description: Verify AI-generated imports, API calls, and packages actually exist. Catches phantom functions, non-existent packages, and slopsquatting attacks.
+description: "Verify AI-generated imports, API calls, and packages actually exist. Use when finishing AI-generated code that introduces new imports or external API calls — auto-fires after fix/cook to catch phantom functions, non-existent packages, and slopsquatting attacks."
 metadata:
   author: runedev
   version: "0.3.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.