@rune-kit/rune 2.12.3 → 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

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

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

@@ -3,11 +3,12 @@ name: marketing
 description: Create marketing assets and execute launch strategy. Generates landing copy, social banners, SEO meta, blog posts, and video scripts.
 metadata:
   author: runedev
-  version: "0.5.0"
+  version: "0.6.0"
   layer: L2
   model: sonnet
   group: delivery
   tools: "Read, Write, Edit, Glob, Grep, WebFetch, WebSearch"
+  emit: media.request
 ---
 
 # marketing

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

@@ -1,6 +1,6 @@
 ---
 name: safeguard
-description: Build safety nets before refactoring. Creates characterization tests, boundary markers, config freezes, and rollback points.
+description: Build safety nets before refactoring. Use when running surgeon or any risky refactor that needs a rollback point. Creates characterization tests, boundary markers, config freezes, and rollback points.
 metadata:
   author: runedev
   version: "0.2.0"

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

@@ -3,7 +3,7 @@ name: sentinel-env
 description: Environment-aware pre-flight check. Validates OS, runtime versions, installed tools, port availability, env vars, and disk space BEFORE coding starts. Prevents "works on my machine" failures. Like sentinel but for the environment, not the code.
 metadata:
   author: runedev
-  version: "0.2.0"
+  version: "0.3.0"
   layer: L3
   model: haiku
   group: validation
@@ -117,25 +117,36 @@ Detect and verify tools the project depends on:
    - `Grep` for `subprocess.run(`, `child_process.exec(`, `Deno.Command(` → project invokes external CLI
    - `Read` README/docs for "requires X installed" or "depends on X"
 
-   For each detected hard dependency:
-   ```bash
-   # Verify the tool exists on PATH
-   which <tool-name> 2>/dev/null || echo "MISSING: <tool-name>"
-   # If found, check version
-   <tool-name> --version 2>/dev/null
-   ```
+   For each detected hard dependency, apply the **9-tier binary detection** below — checking only `which`/`where` is insufficient and produces the largest category of "works on my machine" false-negatives (user has binary installed but PATH is stale, or installed via a package manager that didn't register it, or installed as a desktop app with a bundled binary).
+
+   **9-Tier Binary Detection** (stop at first hit):
+
+   | Tier | Source | Catches |
+   |------|--------|---------|
+   | 1 | Explicit `--<tool>-bin <path>` flag | CI, automation, manual override |
+   | 2 | Skill-specific env var `<SKILL>_<TOOL>_BIN` | Per-project pinning |
+   | 3 | Tool-family env var `<TOOL>_APP_BIN` | Ecosystem conventions |
+   | 4 | Generic tool env var `<TOOL>_BIN` | Legacy overrides |
+   | 5 | Platform desktop-app bundle (macOS `.app/Contents/Resources`, Windows `%LOCALAPPDATA%\Programs`, Linux `/opt`) | Desktop app users (~40% of population) |
+   | 6 | PATH lookup (`which`/`where.exe`) | Standard shell users |
+   | 7 | Package manager global bin (`npm config get prefix`, `pnpm`, `pipx --list`, `cargo install --root`) | npm-global on Windows (PATH oversight) |
+   | 8 | Platform common directories (`~/.local/bin`, `~/.npm-global/bin`, Homebrew, `%APPDATA%\npm`, `%LOCALAPPDATA%\Microsoft\WindowsApps`, `%ProgramFiles%\nodejs`) | Manual installers |
+   | 9 | Platform release archive names (e.g., `codex-x86_64-unknown-linux-musl`, `<tool>-aarch64-apple-darwin`) | Release-tarball downloaders |
 
    **Verdict:**
-   - Tool found on PATH → PASS (log version)
-   - Tool NOT found → **BLOCK** with clear install instructions per OS:
+   - Tool found via any tier → PASS (log which tier + version)
+   - Tool NOT found → **BLOCK** with per-OS install guidance:
      ```
-     [ENV-XXX] Required tool '<tool>' not found on PATH
+     [ENV-XXX] Required tool '<tool>' not found (9-tier lookup exhausted)
        → Debian/Ubuntu: sudo apt install <tool>
-       → macOS: brew install <tool>
+       → macOS: brew install <tool> (or desktop app: <URL>)
        → Windows: winget install <tool> (or choco install <tool>)
-       → Manual: <download URL if known>
+       → Any platform: npm install -g <package> (if Node tool)
+       → Manual: <download URL>
+       → Pin explicitly: export <TOOL>_BIN=/path/to/binary
      ```
    - This prevents the entire class of "it worked in CI but not locally" failures where `subprocess.run()` silently fails
+   - Reference implementation: `scripts/codex_imagen_bridge.mjs` in `@rune-pro/media` ports this pattern
 
 ### Step 4: Port Availability Check