@rune-kit/rune 2.13.0 → 2.14.0

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/journal/SKILL.md

@@ -3,7 +3,7 @@ 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.
 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

package/skills/journal/references/adr-criteria.md

@@ -0,0 +1,109 @@
+# ADR Criteria — When to Open an ADR
+
+ADRs (Architecture Decision Records) are durable. They survive sessions, codebases, and team turnover. That power has a cost: writing one for every minor pick fills the directory with noise, and the genuinely load-bearing decisions get lost.
+
+The ADR gate ensures that every entry in `.rune/adr/` *earned* its place.
+
+## The 3-criteria gate
+
+An ADR is offered only if **all three** are true:
+
+### 1. Hard to reverse (`reversibility`)
+
+Score 1–5: how expensive is it to change your mind later?
+
+| Score | Description |
+|-------|-------------|
+| 1 | Reversible next sprint (one PR, no migration) |
+| 2 | Reversible this quarter (a few PRs, simple migration) |
+| 3 | Significant cost (data migration, multi-PR rollout) |
+| 4 | Quarter-or-more to reverse (schema change, integration rewrite) |
+| 5 | Practically irreversible (architectural commitment, lock-in to vendor) |
+
+### 2. Surprising without context (`surprisingness`)
+
+Score 1–5: how likely is a future reader to wonder "why did they do it this way?"
+
+| Score | Description |
+|-------|-------------|
+| 1 | Obvious — anyone would do it this way |
+| 2 | Common, but with one minor detail |
+| 3 | Mildly unusual — half of practitioners might pick differently |
+| 4 | Strongly counter to common practice |
+| 5 | Rare or counter-intuitive — without explanation, future engineer would "fix" it |
+
+### 3. Real tradeoff (`tradeoff_strength`)
+
+Score 1–5: how credible were the rejected alternatives?
+
+| Score | Description |
+|-------|-------------|
+| 1 | No real alternative — the obvious thing |
+| 2 | One alternative considered briefly |
+| 3 | 2–3 alternatives evaluated; pick was clear |
+| 4 | Multiple credible alternatives; pick required real analysis |
+| 5 | Genuinely difficult choice; reasonable people disagreed |
+
+### Threshold
+
+```
+score = reversibility + surprisingness + tradeoff_strength    # range 3–15
+open_adr = (score >= 11) AND (each axis >= 3)
+```
+
+The "each axis >= 3" rule prevents single-axis cheating. A decision that's hard-to-reverse but obvious AND has no real alternatives (e.g., "we're using SQL for our SQL database") shouldn't be an ADR even if reversibility=5.
+
+## Counter-test (anti-fake)
+
+Before opening an ADR, the agent MUST be able to fill in **rejected alternatives + why**. If the agent can't name at least one credible alternative *that was actually considered*, the decision wasn't a real tradeoff. Re-classify as a "convention" — record it in CLAUDE.md or a comment, not in `.rune/adr/`.
+
+```
+Rejected alternative: PostgreSQL JSON columns
+Why rejected: schema migrations harder; no JSON-path indexing in the version we use; team's tooling stack favors structured columns.
+```
+
+If you can't write that section, don't open the ADR.
+
+## ADR file naming
+
+Filename includes the score, so future reviewers see at a glance why this one was kept:
+
+```
+.rune/adr/ADR-007-postgres-write-model-s13.md
+.rune/adr/ADR-008-event-sourced-orders-s14.md
+```
+
+Format: `ADR-NNN-<slug>-s<score>.md` where `NNN` is the sequential number and `score` is the 3–15 sum.
+
+## What qualifies (examples)
+
+- **Architectural shape**: "We're using a monorepo." "The write model is event-sourced; the read model is projected into Postgres." (s ≈ 12–14)
+- **Integration patterns between modules**: "Ordering and Billing communicate via domain events, not synchronous HTTP." (s ≈ 11–13)
+- **Technology choices that carry lock-in**: database, message bus, auth provider, deployment target — only the ones that would take a quarter to swap out. (s ≈ 11–14)
+- **Boundary-and-scope decisions**: "Customer data is owned by the Customer module; other modules reference it by ID only." The explicit no-s are as valuable as the yes-s. (s ≈ 10–12 — borderline, judge case-by-case)
+- **Deliberate deviations from the obvious path**: "We're using manual SQL instead of an ORM because X." (s ≈ 11–13 — high surprisingness)
+- **Constraints not visible in the code**: "We can't use AWS because of compliance requirements." (s ≈ 11–13)
+- **Rejected alternatives when the rejection is non-obvious**: considered GraphQL, picked REST for subtle reasons. (s ≈ 10–12 — if rejection is documented elsewhere, may not need ADR)
+
+## What does NOT qualify (examples)
+
+- "We chose lodash over underscore." (reversibility ≤ 2; not surprising; weak tradeoff) — s ≈ 5
+- "This function uses async/await instead of Promises." (reversibility 1; not surprising; convention) — s ≈ 3
+- "We're using TypeScript." (reversibility 5; not surprising; obvious for the stack) — s ≈ 7
+- "We deferred dark mode." (this is a deferral, not a decision — goes to backlog or `.out-of-scope/`) — N/A
+
+## When score is 8–10 (borderline)
+
+Don't auto-open. Ask the user: "This decision scores 9/15 — borderline. Do you want it as an ADR, or is a comment in the code sufficient?" Default to the lighter touch.
+
+## Score gaming detection
+
+The score can be inflated, but the counter-test (rejected alternative) cannot be faked without lying about history. If the agent fills out scores ≥ 4 on each axis but can't name a credible rejected alternative, the gate fails and no ADR is opened.
+
+`audit` later cross-references ADR scores — if the average score across `.rune/adr/` files is < 11, it flags "ADR inflation" as a quality concern.
+
+## Convention vs Decision
+
+Decisions are tradeoffs at fork points. **Conventions are choices everyone makes the same way** — naming, formatting, simple defaults. Conventions go in CLAUDE.md or code style guides, not ADRs.
+
+A test: if you can imagine the team coming back next quarter and saying "yeah obvious, of course we did it this way" — it's a convention. If they'd say "wait, why did we do *that*?" — it's a decision and probably qualifies.

package/skills/review/SKILL.md

@@ -60,6 +60,7 @@ Every review MUST cite at least one specific concern, suggestion, or explicit ap
 - `review` → `test` — untested edge case found → test writes it
 - `review` → `fix` — bug found during review → fix applies correction
 - `review` → `scout` — needs more context → scout finds related code
+- `review` → `improve-architecture` — when reviewer flag mentions "shallow", "wrapper", "indirection", or pass-through pattern
 - `review` ← `fix` — complex fix requests self-review
 - `review` → `sentinel` — security-critical code → sentinel deep scan
 

package/skills/review-intake/SKILL.md

@@ -3,11 +3,12 @@ name: review-intake
 description: Use when receiving code review feedback, PR comments, or external suggestions before implementing any changes. Prevents blind implementation, enforces verification-first discipline.
 metadata:
   author: runedev
-  version: "1.1.0"
+  version: "1.2.0"
   layer: L2
   model: sonnet
   group: quality
-  tools: "Read, Glob, Grep"
+  tools: "Read, Write, Edit, Glob, Grep"
+  listen: outofscope.match
 ---
 
 # review-intake
@@ -137,6 +138,24 @@ gh api repos/{owner}/{repo}/pulls/{pr}/comments/{id}/replies \
   -f body="Fixed — [description]"
 ```
 
+### Phase 4.5 — Rejection KB Write (when verdict = OUT OF SCOPE)
+
+For every item with verdict `OUT OF SCOPE`, write a durable record to `.out-of-scope/`. Oral-only rejections leave no trace and force re-litigation in future sessions.
+
+<HARD-GATE>
+Every OUT OF SCOPE verdict MUST produce a `.out-of-scope/<slug>.md` file (or append to an existing one).
+A rejection without a written record is a rejection that didn't happen.
+</HARD-GATE>
+
+**Procedure**:
+
+1. Generate `slug` from the rejected concept (kebab-case, lowercase, max 40 chars, recognizable without opening the file).
+2. Lexical-similarity check: `Glob` `.out-of-scope/*.md`, parse each frontmatter's `concept` + `aliases`, compute overlap with the new slug's tokens. If any existing concept has ≥0.7 overlap → APPEND to that file's `prior_requests` list instead of creating a new one.
+3. If new file: write the format from [`ba/references/out-of-scope-format.md`](../ba/references/out-of-scope-format.md) — YAML frontmatter (concept / aliases / decision: rejected / rejected_at / rejected_by: review-intake / prior_requests / revisit_if) + Markdown body (concept name, "Why out of scope" reasoning, "What would change our mind" signals).
+4. The reasoning MUST be substantive — not "we don't want this" but *why*. Reference project scope, technical constraints, or strategic decisions. Reject deferrals ("we're busy") — those don't belong here.
+
+Only **enhancement** rejections produce `.out-of-scope/` entries. Bug rejections (won't fix because already fixed / not reproducible / not a bug) get a comment on the issue, not a KB file.
+
 ### Phase 6 — IMPLEMENT
 
 Execute in priority order: P0 → P1 → P2 → P3 → P4.
@@ -223,6 +242,9 @@ How to push back:
 | Implementing 4/6 items, leaving 2 unclear | HIGH | HARD-GATE: all-or-nothing comprehension |
 | Performative agreement masking misunderstanding | MEDIUM | Banned phrases list + restate-in-own-words requirement |
 | Fixing tests instead of code to make review pass | HIGH | Defer to `fix` constraints: fix CODE, not TESTS |
+| OUT OF SCOPE verdict with no `.out-of-scope/` file written | HIGH | Phase 4.5 HARD-GATE — oral-only rejections force re-litigation in future sessions |
+| Writing a deferral ("busy this quarter") to `.out-of-scope/` | MEDIUM | Deferrals belong in backlog, not the rejection KB. KB entries must cite durable reasons (scope, tech constraint, strategy) |
+| Creating duplicate `.out-of-scope/` files for the same concept | MEDIUM | Lexical-similarity gate (≥0.7 overlap) — append to existing file's `prior_requests` instead of duplicating |
 
 ## Done When
 
@@ -231,6 +253,7 @@ How to push back:
 - Verdicts assigned (correct/pushback/yagni/defer)
 - Approved items implemented in priority order
 - Tests pass after each individual fix
+- Every OUT OF SCOPE verdict has produced a `.out-of-scope/<slug>.md` file (new or appended)
 - Review Intake Report emitted
 
 ## Returns

package/skills/scout/SKILL.md

@@ -3,12 +3,13 @@ name: scout
 description: "Fast codebase scanner. Use when any skill needs codebase context. Finds files, patterns, dependencies, project structure. Pure read-only — never modifies files."
 metadata:
   author: runedev
-  version: "0.3.0"
+  version: "0.4.0"
   layer: L2
   model: haiku
   group: creation
   tools: "Read, Glob, Grep"
   emit: codebase.scanned
+  listen: agent.stuck
 ---
 
 # scout
@@ -117,6 +118,36 @@ Scout's default is "max 10 file reads" — but the real question is whether addi
 3. Find existing tests with `Glob`: `**/*.test.*`, `**/*.spec.*`, `**/test_*`
 4. Determine test framework: `jest.config.*`, `vitest.config.*`, `pytest.ini`
 
+### Phase 4.5: Zoom-Out Mode
+
+Triggered by `mode="zoom-out"` from the caller, OR auto-triggered by listening on `agent.stuck` signal (emitted by `fix` after 2+ failed attempts on the same file, or by `debug` after 3+ disproved hypothesis cycles).
+
+When activated, scout produces a 3-layer ascent map:
+
+| Layer | What it includes | Cap |
+|-------|------------------|-----|
+| L0 (target) | The stuck file's symbols + immediate imports | unlimited |
+| L1 (siblings) | Files in the same directory + their public exports | 8 files |
+| L2 (callers/neighbors) | Modules that import L0's exports + neighboring modules in the same domain | 8 modules |
+
+Output is a Mermaid diagram, NOT just a file list — visual is the value-add when an agent is stuck.
+
+```mermaid
+graph LR
+  target[src/auth/login.ts]:::stuck
+  target --> dep1[crypto.compare]
+  target --> dep2[db.users.get]
+  caller1[src/routes/auth.ts] --> target
+  caller2[src/middleware/protect.ts] --> target
+  sibling1[src/auth/refresh.ts] -.same-dir.- target
+  sibling2[src/auth/logout.ts] -.same-dir.- target
+  classDef stuck fill:#ff6b6b
+```
+
+**Bounded** — L2 ascent caps at 8 modules. If exceeded, collapse to "showing top 8 by import-frequency". Never blow past the cap silently.
+
+After emitting the map, scout returns to its normal Phase 6 (Generate Report) with the zoom-out section as the primary output.
+
 ### Phase 5: Codebase Map (Optional)
 
 When called by `cook`, `team`, `onboard`, or `autopsy` (skills that need full project understanding), generate a structured codebase map:
@@ -204,6 +235,7 @@ None — pure scanner using Glob, Grep, Read, and Bash tools directly. Does not
 - `docs` (L2): scan codebase structure for documentation generation
 - `logic-guardian` (L2): scan business logic modules for protection mapping
 - `adversary` (L2): scan codebase before red-team analysis
+- `improve-architecture` (L2): re-scan target module + callers when input context is stale
 
 ## Output Format
 

package/skills/surgeon/SKILL.md

@@ -26,17 +26,32 @@ Incremental refactorer that operates on ONE module per session using proven refa
 ## Called By (inbound)
 
 - `rescue` (L1): Phase 2-N SURGERY — one surgery session per module
+- `improve-architecture` (L2): hand-off with proposal payload (depth/leverage/locality target + adapter list) — surgeon executes the deepening
 
 ## Calls (outbound)
 
 - `scout` (L2): understand module dependencies, consumers, and blast radius
 - `safeguard` (L2): if untested module found, build safety net first
+- `improve-architecture` (L2): if no proposal payload provided, request one before refactoring
 - `debug` (L2): when refactoring reveals hidden bugs
 - `fix` (L2): apply refactoring changes
-- `test` (L2): verify after each change
+- `test` (L2): verify after each change (REPLACE old shallow-module tests with deepened-interface tests, don't layer)
 - `review` (L2): quality check on refactored code
 - `journal` (L3): update rescue progress
 
+## Consuming proposal payloads
+
+When invoked by `improve-architecture`, surgeon receives a proposal payload (YAML) containing:
+- `module_path` — target
+- `current` / `target` scores (depth/leverage/locality)
+- `dependency_category` — informs test strategy
+- `suggested_seam` — name of the deepened interface
+- `adapters_planned` — at least 2 adapters means a real seam; surgeon implements all listed
+- `tests_to_replace` — old shallow-module tests; DELETE in same commit as new tests land
+- `tests_to_write_new` — at the deepened interface
+
+Honor the payload. If the payload's `adapters_planned` lists only 1 adapter, push back — single-adapter seam is indirection.
+
 ## Execution Steps
 
 ### Step 1 — Pre-surgery scan

package/skills/test/SKILL.md

@@ -3,7 +3,7 @@ name: test
 description: "TDD test writer. Writes failing tests FIRST (red), then verifies they pass after implementation (green). Covers unit, integration, and e2e tests."
 metadata:
   author: runedev
-  version: "1.2.0"
+  version: "1.3.0"
   layer: L2
   model: sonnet
   group: development
@@ -32,6 +32,15 @@ ROLE BOUNDARY: Test writes TEST FILES only. NEVER modify source/implementation f
 - Do NOT add missing exports to source files
 - If source needs changes → hand off to `rune:fix`. Test's job ends at the test file.
 This separation ensures test never writes code biased toward passing its own tests.
+
+VERTICAL SLICING (Iron Law extension): one test → GREEN → one test → GREEN. Never bulk.
+- bulk_test_count MUST stay <= 1 before the first GREEN in a session
+- After each GREEN, bulk_test_count resets to 0; writing 2+ tests before the next GREEN = HORIZONTAL VIOLATION
+- Each cycle MUST emit a commit pair: `test(scope): <behavior>` + `feat(scope): <behavior>`
+- Claim "I did TDD" is verified by `completion-gate` against `git log --oneline` — no paired commits = REJECTED
+- Horizontal slicing produces tests-of-imagination, not tests-of-behavior. See [references/vertical-tdd.md](references/vertical-tdd.md).
+- Emit signal `tdd.horizontal.violation` when triggered; preflight blocks merge until cycles are unwound.
+Exceptions (narrow, must be documented in test header): retrofitting characterization tests for legacy untested code; spec-driven scaffolding where the contract is external (OpenAPI, wire protocol).
 </HARD-GATE>
 
 ## Instructions
@@ -119,6 +128,34 @@ When writing tests for async Python code:
    - Missing `pytest-asyncio` makes `async def test_*` silently pass as empty coroutines
    - Mixing sync and async fixtures can cause event loop errors
 
+### Phase 3.5: Cycle Discipline (Vertical Slicing Gate)
+
+Before running the new test in Phase 4, count what's about to be added to the working tree:
+
+```
+bulk_test_count = (test files staged + test files unstaged but new) since the last GREEN commit
+```
+
+**Gate**: `bulk_test_count` MUST be exactly 1.
+
+| State | Action |
+|-------|--------|
+| `bulk_test_count == 1` | Proceed to Phase 4 (run RED). |
+| `bulk_test_count >= 2` AND no prior GREEN this session | HORIZONTAL VIOLATION — pause, keep one test, defer the rest. |
+| `bulk_test_count >= 2` AND last GREEN exists in `git log` | HORIZONTAL VIOLATION — same. |
+| `bulk_test_count == 0` | No test to run; this phase is a no-op. |
+
+**Cycle audit log** — append to TEST.md (or create) one line per cycle:
+
+```
+cycle 1 — RED: test_validates_email_rejects_empty | GREEN: validateEmail handles empty | commit: 4f3a1c
+cycle 2 — RED: test_validates_email_requires_at_sign | GREEN: validateEmail checks @ | commit: a92e0d
+```
+
+The audit log is the receipt. `completion-gate` reads it.
+
+When the violation fires, do NOT delete tests automatically — surface to the calling agent: "horizontal slicing detected (N tests before first GREEN). Recommend keeping test K, deferring N-1 to subsequent cycles."
+
 ### Phase 4: Run Tests — Verify They FAIL (RED)
 
 Use `Bash` to run ONLY the newly created test files (not full suite):
@@ -350,6 +387,8 @@ Save eval files as `skills/<name>/evals.md`. Each eval is a numbered scenario (E
 | "It's about spirit not ritual" | Violating the letter IS violating the spirit. Write the test first. |
 | "I mentally tested it" | Mental testing is not testing. Run the command, show the output. |
 | "This is different because..." | It's not. Write the test first. |
+| "I'll batch the tests since they're related" | Batched tests = tests of imagination. Each cycle reacts to the prior. Write one, GREEN it, then the next. |
+| "All five tests are already written, let me just review them with you" | Same fallacy as code-before-test. Keep the first one, defer the others to subsequent cycles. |
 
 ## Advanced: Oracle-Injection E2E Testing
 
@@ -466,6 +505,8 @@ If you catch yourself with ANY of these, delete implementation code and restart
 8. MUST delete implementation code written before tests — Iron Law, no exceptions
 9. MUST show RED phase output (actual failure) — "I confirmed they fail" without output is REJECTED
 10. MUST NOT modify source/implementation files — test writes test files ONLY, hand off source changes to rune:fix
+11. MUST NOT write a 2nd test until the 1st test reaches GREEN — vertical slicing only, bulk_test_count <= 1 enforced
+12. MUST emit commit pair per cycle (`test:` then `feat:`) — git log is the audit trail for "I did TDD" claims
 
 ## Mesh Gates
 
@@ -590,6 +631,10 @@ Known failure modes for this skill. Check these before declaring done.
 | Introducing a new test framework instead of using existing one | MEDIUM | Constraint 6: detect framework first, use project's existing one always |
 | Modifying source files to make tests work | HIGH | Role boundary: test writes test files ONLY — source changes go to rune:fix |
 | Test-only methods leaking into production code | MEDIUM | Anti-Pattern 2 gate: if method only called by tests → move to test utilities |
+| Bulk test writing before first GREEN (horizontal slicing) | CRITICAL | Phase 3.5 gate — bulk_test_count <= 1, defer additional tests to subsequent cycles |
+| Test names describe shape (`returns boolean`, `has property`) instead of behavior | MEDIUM | Scan names for shape-words; rewrite to behavior verbs (accepts/rejects/produces). See [references/test-quality.md](references/test-quality.md) |
+| Mocking internal collaborators in same module | HIGH | System-boundary rule from [references/mocking-policy.md](references/mocking-policy.md) — mock only what you don't own |
+| Layering old shallow-module tests on top of new deepened-interface tests | MEDIUM | After improve-architecture deepens a module, REPLACE tests don't ADD them; one interface = one test surface |
 
 ## Self-Validation
 
@@ -612,6 +657,8 @@ SELF-VALIDATION (run before emitting Test Report):
 - Coverage ≥80% verified via verification
 - Test Report emitted with framework, test count, RED/GREEN status, and coverage
 - Self-Validation: all checks passed
+- Cycle audit trail intact — every RED has a paired GREEN in `git log`, no orphan tests pre-first-GREEN
+- Test names use behavior-words (accepts/rejects/produces/...) not shape-words (returns/has property/is defined)
 
 ## Cost Profile