continuous-improvement 3.1.0 → 3.9.1

package/plugins/continuous-improvement/skills/token-budget-advisor/SKILL.md

@@ -0,0 +1,136 @@
+---
+name: token-budget-advisor
+tier: "2"
+description: >-
+  Enforces Law 2 (Plan Is Sacred) of the 7 Laws of AI Agent Discipline by
+  making token-budget tradeoffs explicit before the response is composed.
+  Offers the user an informed choice about how much response depth to
+  consume before answering. Use this skill when the user explicitly
+  wants to control response length, depth, or token budget.
+  TRIGGER when: "token budget", "token count", "token usage", "token limit",
+  "response length", "answer depth", "short version", "brief answer",
+  "detailed answer", "exhaustive answer", "respuesta corta vs larga",
+  "cuántos tokens", "ahorrar tokens", "responde al 50%", "dame la versión
+  corta", "quiero controlar cuánto usas", or clear variants where the
+  user is explicitly asking to control answer size or depth.
+  DO NOT TRIGGER when: user has already specified a level in the current
+  session (maintain it), the request is clearly a one-word answer, or
+  "token" refers to auth/session/payment tokens rather than response size.
+origin: community
+---
+
+# Token Budget Advisor (TBA)
+
+Intercept the response flow to offer the user a choice about response depth **before** the agent answers.
+
+## When to Use
+
+- User wants to control how long or detailed a response is
+- User mentions tokens, budget, depth, or response length
+- User says "short version", "tldr", "brief", "al 25%", "exhaustive", etc.
+- Any time the user wants to choose depth/detail level upfront
+
+**Do not trigger** when: user already set a level this session (maintain it silently), or the answer is trivially one line.
+
+## How It Works
+
+### Step 1 — Estimate input tokens
+
+Use the repository's canonical context-budget heuristics to estimate the prompt's token count mentally.
+
+Use the same calibration guidance as [context-budget](../context-budget/SKILL.md):
+
+- prose: `words × 1.3`
+- code-heavy or mixed/code blocks: `chars / 4`
+
+For mixed content, use the dominant content type and keep the estimate heuristic.
+
+### Step 2 — Estimate response size by complexity
+
+Classify the prompt, then apply the multiplier range to get the full response window:
+
+| Complexity   | Multiplier range | Example prompts                                      |
+|--------------|------------------|------------------------------------------------------|
+| Simple       | 3× – 8×          | "What is X?", yes/no, single fact                   |
+| Medium       | 8× – 20×         | "How does X work?"                                  |
+| Medium-High  | 10× – 25×        | Code request with context                           |
+| Complex      | 15× – 40×        | Multi-part analysis, comparisons, architecture      |
+| Creative     | 10× – 30×        | Stories, essays, narrative writing                  |
+
+Response window = `input_tokens × mult_min` to `input_tokens × mult_max` (but don’t exceed your model’s configured output-token limit).
+
+### Step 3 — Present depth options
+
+Present this block **before** answering, using the actual estimated numbers:
+
+```
+Analyzing your prompt...
+
+Input: ~[N] tokens  |  Type: [type]  |  Complexity: [level]  |  Language: [lang]
+
+Choose your depth level:
+
+[1] Essential   (25%)  ->  ~[tokens]   Direct answer only, no preamble
+[2] Moderate    (50%)  ->  ~[tokens]   Answer + context + 1 example
+[3] Detailed    (75%)  ->  ~[tokens]   Full answer with alternatives
+[4] Exhaustive (100%)  ->  ~[tokens]   Everything, no limits
+
+Which level? (1-4 or say "25% depth", "50% depth", "75% depth", "100% depth")
+
+Precision: heuristic estimate ~85-90% accuracy (±15%).
+```
+
+Level token estimates (within the response window):
+- 25%  → `min + (max - min) × 0.25`
+- 50%  → `min + (max - min) × 0.50`
+- 75%  → `min + (max - min) × 0.75`
+- 100% → `max`
+
+### Step 4 — Respond at the chosen level
+
+| Level            | Target length       | Include                                             | Omit                                              |
+|------------------|---------------------|-----------------------------------------------------|---------------------------------------------------|
+| 25% Essential    | 2-4 sentences max   | Direct answer, key conclusion                       | Context, examples, nuance, alternatives           |
+| 50% Moderate     | 1-3 paragraphs      | Answer + necessary context + 1 example              | Deep analysis, edge cases, references             |
+| 75% Detailed     | Structured response | Multiple examples, pros/cons, alternatives          | Extreme edge cases, exhaustive references         |
+| 100% Exhaustive  | No restriction      | Everything — full analysis, all code, all perspectives | Nothing                                        |
+
+## Shortcuts — skip the question
+
+If the user already signals a level, respond at that level immediately without asking:
+
+| What they say                                      | Level |
+|----------------------------------------------------|-------|
+| "1" / "25% depth" / "short version" / "brief answer" / "tldr"  | 25%   |
+| "2" / "50% depth" / "moderate depth" / "balanced answer"        | 50%   |
+| "3" / "75% depth" / "detailed answer" / "thorough answer"       | 75%   |
+| "4" / "100% depth" / "exhaustive answer" / "full deep dive"     | 100%  |
+
+If the user set a level earlier in the session, **maintain it silently** for subsequent responses unless they change it.
+
+## Precision note
+
+This skill uses heuristic estimation — no real tokenizer. Accuracy ~85-90%, variance ±15%. Always show the disclaimer.
+
+## Examples
+
+### Triggers
+
+- "Give me the short version first."
+- "How many tokens will your answer use?"
+- "Respond at 50% depth."
+- "I want the exhaustive answer, not the summary."
+- "Dame la version corta y luego la detallada."
+
+### Does Not Trigger
+
+- "What is a JWT token?"
+- "The checkout flow uses a payment token."
+- "Is this normal?"
+- "Complete the refactor."
+- Follow-up questions after the user already chose a depth for the session
+
+## Source
+
+Standalone skill from [TBA — Token Budget Advisor for Claude Code](https://github.com/Xabilimon1/Token-Budget-Advisor-Claude-Code-).
+Original project also ships a Python estimator script, but this repository keeps the skill self-contained and heuristic-only.

package/plugins/continuous-improvement/skills/verification-loop/SKILL.md

@@ -0,0 +1,224 @@
+---
+name: verification-loop
+tier: "1"
+description: "Enforces Law 4 (Verify Before Reporting) of the 7 Laws of AI Agent Discipline. A comprehensive verification system for agent coding sessions covering build, types, lint, tests, security, and diff with a PASS/FAIL report."
+origin: continuous-improvement
+---
+
+# Verification Loop Skill
+
+A comprehensive verification system for agent coding sessions.
+
+## When to Use
+
+Invoke this skill:
+- After completing a feature or significant code change
+- Before creating a PR
+- When you want to ensure quality gates pass
+- After refactoring
+
+## Verification Phases
+
+### Phase 0: Resolve the Ladder
+
+Every project has its own actual invocation for build / typecheck / lint / test / security / deploy-receipt. Hardcoding `npm run build` and `npm run test` works when the project happens to use those exact scripts; for everything else (pnpm, yarn, cargo, go, mise, just, custom scripts, monorepos with workspace-scoped commands) it returns "deps not installed" or "config not found" misreads from the wrong invocation. Phase 0 runs first so Phases 1–6 never have to guess.
+
+**Resolution priority** (first match wins):
+
+1. **`.claude/verify-ladder.json` manifest** at the repo root. Schema:
+   ```json
+   {
+     "build":          "npm run build",
+     "typecheck":      "tsc -p tsconfig.json --noEmit",
+     "lint":           "npm run lint",
+     "test":           "npm test",
+     "security":       "npm audit --audit-level=high",
+     "deploy_receipt": "npx wrangler deployments list --json"
+   }
+   ```
+   Any field omitted falls through to step 2 for that field only. A field set to the literal string `null` means "skip this phase for this project."
+2. **Sniff `package.json` `scripts`** for `build`, `typecheck` or `tsc`, `lint`, `test`, `audit` or `security`. Tie-breaker when multiple scripts could match a phase: prefer `verify:<phase>` over `<phase>` over `<phase>:*`. Do NOT pick `test` when `verify:test` exists; the operator's explicit verification surface always wins over the convenience alias.
+3. **Sniff per-language toolchain files** if `package.json` is absent: `Cargo.toml` → `cargo build` / `cargo test`, `go.mod` → `go build ./...` / `go test ./...`, `pyproject.toml` → `pytest` / `ruff check`, `Gemfile` → `bundle exec rspec`, etc.
+4. **Ask the operator** if none of the above resolves the field. Do not invent.
+
+**Output the resolved ladder** as a single fenced block before running any phase, so the operator can spot a wrong resolution before it costs a misread:
+
+```
+verify-ladder (resolved):
+  build:           npm run build
+  typecheck:       npx tsc --noEmit  (sniff: package.json scripts.typecheck)
+  lint:            npm run lint
+  test:            npm test
+  security:        (skipped — no script defined)
+  deploy_receipt:  npx wrangler deployments list --json  (manifest)
+```
+
+Each row shows the resolved command + its source (manifest, sniff, or skipped). The fenced block is the contract surface — every later phase reads from this resolved ladder, never from a hardcoded fallback.
+
+A starter manifest is provided at `templates/verify-ladder.example.json`; copy it to `.claude/verify-ladder.json` and trim per project.
+
+### Phase 1: Build Verification
+Run the `build` command from the resolved ladder. Example for a default Node project:
+```bash
+# Resolved from package.json scripts.build:
+npm run build 2>&1 | tail -20
+```
+
+If build fails, STOP and fix before continuing.
+
+### Phase 2: Type Check
+```bash
+# TypeScript projects
+npx tsc --noEmit 2>&1 | head -30
+
+# Python projects
+pyright . 2>&1 | head -30
+```
+
+Report all type errors. Fix critical ones before continuing.
+
+### Phase 3: Lint Check
+```bash
+# JavaScript/TypeScript
+npm run lint 2>&1 | head -30
+
+# Python
+ruff check . 2>&1 | head -30
+```
+
+### Phase 4: Test Suite
+```bash
+# Run tests with coverage
+npm run test -- --coverage 2>&1 | tail -50
+
+# Check coverage threshold
+# Target: 80% minimum
+```
+
+Report:
+- Total tests: X
+- Passed: X
+- Failed: X
+- Coverage: X%
+
+### Phase 5: Security Scan
+```bash
+# Check for secrets
+grep -rn "sk-" --include="*.ts" --include="*.js" . 2>/dev/null | head -10
+grep -rn "api_key" --include="*.ts" --include="*.js" . 2>/dev/null | head -10
+
+# Check for console.log
+grep -rn "console.log" --include="*.ts" --include="*.tsx" src/ 2>/dev/null | head -10
+```
+
+### Phase 6: Diff Review
+```bash
+# Show what changed
+git diff --stat
+git diff HEAD~1 --name-only
+```
+
+Review each changed file for:
+- Unintended changes
+- Missing error handling
+- Potential edge cases
+
+### Phase 7: Result + Completeness Gate
+
+Phases 1–6 verify mechanism — build green, types clean, tests pass, no secrets, diff intentional. Phase 7 verifies outcome: did the work the operator actually asked for actually land? Mechanism passing while outcome is missing is the most expensive failure mode in this loop, because the green report invites a merge that doesn't deliver.
+
+Two questions, both required to be `Yes`:
+
+**1. Did the stated goal land? Yes/No + evidence.**
+
+The stated goal is the goal as named at task start, not the goal as remembered now. If the operator asked "fix the bug where X happens", evidence is the bug no longer happening (failing test now passes, repro screenshot, manual verification). If they asked "add an admin button", evidence is the button visible and functional in the running UI. Build-green is not evidence of result — it is evidence of mechanism. Don't conflate.
+
+**2. Did every promised step finish? Yes/No + list.**
+
+Enumerate every step you said you would do — the recommendation list, the plan doc, the TodoWrite items, the commit-by-commit roadmap. Mark each Done or Skipped. If any are Skipped, name them and the reason. A "complete" verification with silently skipped promises is a trust violation, not a deliverable.
+
+Both gates are independent: `Yes` on goal alone means a half-complete checklist that may break later; `Yes` on completeness alone means busywork that didn't deliver. Both must be `Yes` — even if the previous six phases all pass — or the work isn't done.
+
+If either is `No`, the verification report goes back to the operator with the explicit gap, not on to PR. The operator decides whether the gap is acceptable to ship as-is or whether more work is required first. Never silently downgrade to "ready" because the mechanism phases looked good.
+
+### Phase 8: Deploy Receipt (auto-deploy projects only)
+
+For repos whose `verify-ladder.json` declares a `deploy_receipt` field — or whose sniff path detects an auto-deploy target (Railway, Cloudflare Workers, Vercel, Netlify, Fly.io) — the verify is not complete until the deployed SHA matches the merge SHA and a healthcheck returns 200. Hand off to the `deploy-receipt` skill (Law 4 deploy-seam companion landed in PR #83) and treat its `Receipt status: COMPLETE` as the gate.
+
+INCOMPLETE receipts move to "Immediate operator action" in the close, never to "ready". Library-only / package-published repos skip this phase entirely (no deploy seam exists).
+
+### Phase 9: Synthetic Checks (production-vs-baseline diff)
+
+Phase 8 confirms the deploy seam. Phase 9 confirms the deployed surface matches the staging baseline on the dimensions that matter — endpoint payload shape, header presence, data freshness, routing correctness. A deploy can land with a matching SHA and a 200 healthcheck and still serve broken responses (stale data sources, dropped headers, regressed payloads). Phase 9 is the gate that catches that.
+
+**When this rung runs:**
+
+- ONLY after Phase 8 reports `Receipt status: COMPLETE`. An INCOMPLETE receipt blocks Phase 9 — fix the receipt gap first, then re-run.
+- ONLY when the resolved ladder declares `synthetic_checks` as a non-null directory path (default: `synthetic-checks/`). A `null` field skips the rung silently. A missing field falls through to the directory sniff: if `synthetic-checks/` exists at the repo root with at least one `*.synthetic.*` file, the rung activates; otherwise it is recorded as "skipped — no synthetic-checks directory found".
+
+**What the runner does:**
+
+1. List every `*.synthetic.{sh,mjs,ts,py}` file in the resolved directory in lexical order.
+2. For each file, set the input env vars: `BASE_URL` (production base from project config), `BASELINE_URL` (staging baseline from project config), `EXPECTED_SHA` (the merge SHA Phase 8 reported COMPLETE), `DEPLOY_BRANCH` (the deploy branch name), `RECEIPT_TIMESTAMP` (ISO-8601 of the receipt).
+3. Invoke the file via the right interpreter (`bash` for `.sh`, `node` for `.mjs`, `tsx` for `.ts`, `python` for `.py`). Files with unrecognized extensions are skipped with a warning.
+4. Capture stdout + stderr + exit code per file. On exit 0, the check passed. On any non-zero exit, the check failed and stdout is the operator-facing diff.
+5. Aggregate: if every file exited 0, Phase 9 is `PASS`. If any file exited non-zero, Phase 9 is `FAIL — synthetic drift on <filenames>` and the captured diffs go into the verification report verbatim (no agent re-summarization).
+
+**Surfacing rule:**
+
+A failed synthetic check surfaces as `INCOMPLETE — synthetic drift` at the same severity as a failed deploy receipt. The merge moves to "Immediate operator action" with the named drift and the diff payload. Do NOT downgrade synthetic drift to "warning" — the rung exists because the report flagged exactly this gap (deploys that look healthy but serve broken responses).
+
+**Anti-patterns specific to this rung:**
+
+- **Smoke checks masquerading as synthetic checks.** A check that only verifies "endpoint returns 200" passes against a stale deploy. Synthetic checks MUST diff production against a baseline.
+- **Hardcoded baseline URLs in the check.** Baseline lives in env (`BASELINE_URL`), not in the file. Hardcoding it breaks the convention and makes per-environment use impossible.
+- **Re-summarizing the diff.** The captured stdout from a failed check is the operator-facing artifact. The agent does not re-write or shorten it.
+- **Treating an absent directory as PASS.** No synthetic-checks directory means the rung is `skipped`, not `PASS`. The operator sees the absence in the resolved ladder.
+
+See `synthetic-checks/README.md` for the file convention, the input/output contract, and a runnable sample (`example-version-endpoint.synthetic.sh`).
+
+## Output Format
+
+After running all phases, produce a verification report:
+
+```
+VERIFICATION REPORT
+==================
+
+Build:        [PASS/FAIL]
+Types:        [PASS/FAIL] (X errors)
+Lint:         [PASS/FAIL] (X warnings)
+Tests:        [PASS/FAIL] (X/Y passed, Z% coverage)
+Security:     [PASS/FAIL] (X issues)
+Diff:         [X files changed]
+Goal landed:  [YES/NO] — <one-line evidence or gap>
+All promised: [YES/NO] — <X of Y steps Done; list any Skipped>
+Deploy:       [COMPLETE/INCOMPLETE/skipped] — <SHA + health summary>
+Synthetic:    [PASS/FAIL/skipped] — <X of Y checks; failed: <filenames>>
+
+Overall:   [READY/NOT READY] for PR
+
+Issues to Fix:
+1. ...
+2. ...
+```
+
+`Overall: READY` requires every line above to pass, including both Phase 7 gates. Mechanism-green plus outcome-`No` is `NOT READY` — surface the gap, do not ship.
+
+## Continuous Mode
+
+For long sessions, run verification every 15 minutes or after major changes:
+
+```markdown
+Set a mental checkpoint:
+- After completing each function
+- After finishing a component
+- Before moving to next task
+
+Run: /verify
+```
+
+## Integration with Hooks
+
+This skill complements PostToolUse hooks but provides deeper verification.
+Hooks catch issues immediately; this skill provides comprehensive review.

package/plugins/continuous-improvement/skills/wild-risa-balance/SKILL.md

@@ -0,0 +1,191 @@
+---
+name: wild-risa-balance
+tier: "2"
+description: Enforces Law 2 (Plan Is Sacred) of the 7 Laws of AI Agent Discipline. Decision-framing lens that pairs WILD generation with RISA execution when emitting recommendation lists. Not a runtime hook.
+origin: continuous-improvement
+---
+
+# WILD / RISA Balance
+
+## When to Use
+
+- Emitting a multi-item recommendation block (≥3 items)
+- Choosing between a safe option and a bold option
+- Reviewing your own plan for over-cautiousness or over-fantasy
+- Pairing with `proceed-with-the-recommendation` to decide which items belong above and below the cut
+
+## The Two Modes
+
+### RISA (Execution)
+
+- **R**ealistic — fits the constraints in front of you
+- **I**mportant — moves a stated goal, not a vanity metric
+- **S**pecific — names files, commands, or owners
+- **A**greeable — the operator can approve it without a meeting
+
+If you only stay in RISA, you ship safe, average results.
+
+### WILD (Creation)
+
+- **W**ild — breaks the default frame
+- **I**maginative — invents an option that did not exist a minute ago
+- **L**imitless — ignores current budget, headcount, or stack
+- **D**isruptive — replaces a workflow rather than tuning it
+
+If you only stay in WILD, you generate cool ideas that never ship.
+
+## The Trap
+
+RISA alone produces a backlog of incremental fixes that never compound. WILD alone produces a graveyard of demos that never reach production. The bigger failure is unconscious switching: drifting into WILD during execution, or drifting into RISA during brainstorming, without naming the switch. Name the mode you are in before you write the next line.
+
+## Switching Deliberately
+
+| Phase                   | Mode  | Why                                                |
+|-------------------------|-------|----------------------------------------------------|
+| Brainstorm              | WILD  | Quantity and range beat early filtering            |
+| Roadmap framing         | WILD  | Frame the bigger bet before scoping it down        |
+| Per-item recommendation | Mixed | Top items can be WILD, baseline items must be RISA |
+| Per-item execution      | RISA  | One thing, verified, shipped                       |
+| Verification            | RISA  | Reality check, no new invention                    |
+| Reflection              | WILD  | Counterfactuals, "what would have been bolder"     |
+
+WILD owns generation phases. RISA owns execution phases. The switch is intentional, not accidental.
+
+## How to Apply in a Recommendation List
+
+When this skill is in play, every recommendation block ships **at least 7 items**, split as:
+
+1. **Top block — WILD pilots: exactly 2 bold items.** Present both; the operator picks at most one to actually run. If you cannot find a second genuinely bold option, stretch — do not pad with a safe item dressed up as wild.
+2. **Bottom block — RISA baseline: at least 5 safe items.** These ship now regardless of the WILD bet. If you cannot reach 5, the surface is under-explored — expand scope before emitting the list.
+3. Within each block, rank descending by impact.
+4. Once the list is composed, wait for the operator's "proceed" signal before invoking `proceed-with-the-recommendation`. Never auto-trigger it. This skill only changes how the list is composed.
+
+Total floor: **2 WILD + 5 RISA = 7 items minimum.** Going above is fine; going below means the skill was not applied.
+
+The point: the operator gets a real WILD/RISA contrast (2 bold bets weighed against a 5-deep trusted baseline), not a flat list where the bold option silently competes with safe ones and loses by default.
+
+## Audience Tiers (beginner vs expert)
+
+Recommendation blocks ship in **two tiers** depending on the operator's signaled level. The 2 WILD + ≥5 RISA floor described above is the **expert** tier. Beginners get a different, lighter shape. The point: under-load for experts and overload for beginners are both failure modes — splitting the format prevents both.
+
+### Tier selection
+
+**Default = expert.** Switch to beginner only when one of these triggers fires:
+
+- **Explicit flag** — the operator types `/beginner` or refers to themselves as a beginner ("for beginner", "as a beginner", "I'm new to this").
+- **Explicit lite framing** — "simple list", "just the top 3", "small list", "short version", "no need for surgical".
+- **Auto-detect heuristic** — the **first message of the thread** contains any of: `beginner`, `new to (this|claude|the system)`, `simple`, `explain like`, `first time`, `i'm just starting`, `i'm learning`. Single-message false positives are acceptable — the operator flips with `/expert` if mismatched.
+
+The operator can override mid-thread: `/expert` switches back to WILD+RISA, `/beginner` switches back to the lite tier. Apply the most recently named tier.
+
+### Beginner tier (lite shape)
+
+When in beginner tier:
+
+- **3 minimum, 5 maximum** items. No padding past 5. Below 3 means there is no recommendation — write `Recommendation: no`.
+- **Goal-driven** — each item names the outcome, not the mechanism. Format: `<verb> <thing> → <observable result>`.
+- **Execution-first** — each item is a concrete next action, not a tradeoff to weigh.
+- **One-shot, iterate from there** — no "surgical change" framing, no phased sequencing, no commit-size gates. Get to a working pass, then improve.
+- **Optimized for the latest Opus model (Opus 4.7 at time of writing)** — assume the model holds the full task in one shot. Do not pre-decompose into micro-steps that fight the model's reasoning depth. Lean on broader, outcome-shaped instructions over fine-grained scripts.
+- Order: descending impact.
+- No WILD/RISA labels. No counts annotation. No tiered tables.
+
+### Expert tier (default for Naim, default in this repo)
+
+The full WILD+RISA structure documented above: ≥7 items, exactly 2 WILD + ≥5 RISA, WILD on top descending, RISA below descending, counts annotated inline.
+
+Each item still leads with the outcome inside both WILD and RISA: `<verb> <thing> → <observable result>`.
+
+### Tier signal in the 3-section close
+
+When Phase 7's three-section close lands, the `## Recommendation` header carries an explicit tier suffix:
+
+- Expert: `## Recommendation (expert)`
+- Beginner: `## Recommendation (beginner)`
+
+The Stop hook regex (`^#+ +Recommendation(?:\s|$)`) already accepts both forms — the suffix is documentation, not a gate. The point is a self-describing audit trail: a future reader (or an instinct scan) can tell which tier was applied without re-deriving it from item count or label presence.
+
+### The "no" escape valve (both tiers)
+
+If neither tier can produce a real recommendation — every candidate item would be padding, or you cannot reach the tier's floor (3 for beginner, 7 for expert) without inventing busywork — write `Recommendation: no` and stop. This applies to **both tiers equally**.
+
+`no` is not absence. It is an explicit signal that the current session or perspective is exhausted on this surface and the operator should switch context: a fresh session (cold prompt cache, no carryover bias), a different specialist agent (different perspective on the same problem), a different framing (re-scoping the goal), or sleep on it. Padding to hit the floor is the failure mode this escape exists to prevent — a flat 3-item beginner list of "review the README, run the tests, commit your changes" is worse than `Recommendation: no` because it disguises an empty thought as work.
+
+When `no` ships, the Phase 7 close header still carries the tier suffix (`## Recommendation (expert)` or `## Recommendation (beginner)`) so the audit trail records which tier exhausted itself, and the body is just the literal `no` on its own line. No tiered tables, no WILD/RISA blocks, no "Want me to: A or B?" closer.
+
+## Proactive Roadmap Surfacing (surface, do not execute)
+
+A "wait for instructions" agent fails by silence — sitting on a known next step (visible roadmap, deferred item from a prior session) until told. A "proactive" agent fails by running that step without being asked. Both lose. Surface bridges them: raise the next step as a recommendation item, never as a fait accompli.
+
+### Trigger conditions
+
+Surface a next step when any of these are true:
+
+- A persistent roadmap names an undone step — MemoryCore `current-session.md`, `docs/plans/*`, `⚠️ Deferred` entries in a project `CLAUDE.md`, or pending operator actions logged in MemoryCore.
+- The current task is finished and a stated session goal implies the next one.
+- The session has drifted from a stated roadmap (asked to do A, but B is now blocked by A's choice).
+- An instinct or memory record predicts a near-term action the operator typically forgets (e.g., "rotate keys before next deploy", "push branch after N commits").
+
+### Hard boundary — surface, do not execute
+
+Surfacing emits the next step as a recommendation item. It does **not** mean running the command, editing the file, or shipping the change. Execution still requires explicit "proceed", "go", "run it", or equivalent. The boundary is non-negotiable:
+
+- Global CLAUDE.md: "If instructions conflict or information is missing, stop and ask."
+- Auto Mode: even in autonomous execution, "anything that deletes data or modifies shared or production systems still needs explicit user confirmation."
+- Trust is asymmetric — one unauthorized "helpful" action costs more than a hundred missed surfacings. Recovery is one-way.
+
+### Format
+
+A surfaced item lives inside the normal RISA block. Mark it inline as `(surfaced — <source>)` so the operator can tell which items came from the roadmap vs. the current request:
+
+```
+RISA baseline — ship regardless (5 of ≥5)
+1. Run remote D1 migration before next deploy → unblocks Close/Cancel admin button. (surfaced — pending operator action since 2026-05-04)
+2. ...
+```
+
+A WILD-tier reframe of the roadmap itself (not a single deferred step, but a re-shape of the whole next phase) goes in the WILD block instead, with the same `(surfaced — <source>)` marker.
+
+### Anti-patterns
+
+- Re-surfacing an item the operator explicitly deferred — once is a reminder, three times is nagging. After one repeat, log the defer reason to memory and stop.
+- Surfacing speculative steps with no source in any roadmap or memory ("you should also consider…" without a citation).
+- Bundling a surface with execution ("I went ahead and started X"). Surface, wait, execute on go.
+- Treating absence of a roadmap as license to invent one — if no roadmap exists and none was requested, ask before drafting.
+
+The point: the operator never has to remember a deferred item, and never has to forgive an unauthorized one. Both at once.
+
+## Integration with the 7 Laws
+
+| Mode | Reinforces                                              | Tempered by              |
+|------|---------------------------------------------------------|--------------------------|
+| RISA | Law 2 (Plan), Law 3 (One Thing), Law 4 (Verify)         | Law 6 (Iterate One Thing) |
+| WILD | Law 1 (Research — broader exploration), Law 5 (Reflect) | Law 6 (Iterate One Thing) |
+
+Both modes pass through Law 6 before execution. WILD without Law 6 is a wishlist. RISA without Law 6 ships safe fixes while the real bottleneck waits.
+
+## Example
+
+```
+Recommendations (descending impact within each block)
+
+WILD pilots — pick at most one (2 of 2)
+1. Replace the current review workflow with a single adversarial pair.
+2. Drop the staging environment in favor of feature-flagged production.
+
+RISA baseline — ship regardless (5 of ≥5)
+1. Add the missing test for the failure path noted in verification.
+2. Rename the ambiguous flag to match its actual behavior.
+3. Backfill the type on the public export that currently widens to `any`.
+4. Wire the existing Stop hook into the new skill's checklist gate.
+5. Update the README mirror so the bundled plugin matches the source skill. (surfaced — verify:skill-mirror gate flagged drift in last CI run)
+```
+
+Total: 7 items (2 WILD + 5 RISA). That is the floor — emit more on either side if the surface warrants it. The fifth RISA item is marked `(surfaced — <source>)` to demonstrate the convention from the Proactive Roadmap Surfacing section: items lifted from a roadmap or memory carry an inline source attribution so the operator can tell roadmap-driven items apart from current-request items.
+
+## Related
+
+- `continuous-improvement` — the 7 Laws card (core skill)
+- `proceed-with-the-recommendation` — execution arm; carries surfaced items across the surface → execute boundary defined in the Proactive Roadmap Surfacing section above
+- `superpowers:brainstorming` — upstream WILD generator
+- `verification-loop` — downstream RISA verifier