continuous-improvement 3.8.0 → 3.9.2

package/skills/wild-risa-balance.md

@@ -1,191 +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
+---
+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

package/skills/worktree-safety.md

@@ -0,0 +1,66 @@
+---
+name: worktree-safety
+tier: "2"
+description: "Enforces Law 4 (Verify Before Reporting) of the 7 Laws of AI Agent Discipline. Pre-dispatch invariant: validate worktree root before any source-writing tool call. Catches missing .git, fallback path-only creation, stale leases, foreign-session ownership, and non-worktree git operations before they corrupt history."
+origin: continuous-improvement
+---
+
+# Worktree Safety Skill
+
+A pre-dispatch invariant. Before any tool call that writes source files or runs git, validate that the current working directory is a registered worktree with a healthy `.git`, owned by this session, on the expected branch.
+
+## When to Use
+
+- Before every Edit / Write / Bash that touches source code in a multi-worktree session.
+- Before any `git` command in an auto-loop.
+- After any pause/resume — CWD may have drifted, the worktree may have been pruned, the lease may have expired.
+- When the verification ladder reports a class-`worktree` failure (see `recovery-classification`).
+
+## Why This Skill Exists
+
+GSD-2's [CONTEXT.md](https://github.com/gsd-build/gsd-2/blob/main/CONTEXT.md) names "Worktree Safety" as one of four runtime invariant modules. Common failure modes it catches:
+
+- **Units dispatch into ghost / invalid worktree roots** — `.git` missing, fallback path-only creation, the worktree was pruned but the loop kept its handle.
+- **Health checks unit-specific instead of lifecycle-wide** — earlier units (sketch, plan) write into invalid roots before any check runs.
+- **Brittle exit / merge signals** — relying on artifact presence instead of authoritative branch and commit state.
+- **Parallel actors mutating the working tree of a worktree they don't own** — a known hazard on this host (see `feedback_parallel_actor.md`).
+
+The continuous-improvement repo runs on Windows + Git Bash with `autocrlf=true` and a parallel-actor expectation, both of which make weak worktree handling expensive.
+
+## The Five-Check Envelope
+
+Before any source-writing call, verify all five. Fail closed on any miss.
+
+1. **Root validity** — `git rev-parse --show-toplevel` resolves; the resolved path matches CWD after symlink-safe canonicalization.
+2. **`.git` presence** — `.git` exists (file pointer for worktrees, directory for primary checkout). A missing or unreadable `.git` is an immediate stop.
+3. **Worktree registration** — `git worktree list` includes the resolved root with no `prunable` flag. Prunable worktrees can be deleted by another process at any moment.
+4. **Branch alignment** — current branch matches the lease ledger; `HEAD` is not detached unless the unit explicitly asked for detached state.
+5. **Lease ownership** — the session ID in `.git/worktrees/<name>/lease` (or your equivalent ledger) matches this session. Stale or foreign leases block the call.
+
+Output a single fenced block before any source-writing dispatch:
+
+```
+worktree-safety (resolved):
+  root:          d:/Ai/ci-wt-skill-trio  (matches CWD, canonicalized)
+  .git:          file pointer → /shared/.git/worktrees/skill-trio  (present)
+  registration:  listed in `git worktree list` (not prunable)
+  branch:        feat/verification-ladder-skill-trio  (matches lease)
+  lease:         owned by session 4f2a (this session)  → CLEAR
+```
+
+If any line is non-`CLEAR`, dispatch is blocked and the failure routes to `recovery-classification` as class `worktree`.
+
+## Anti-Patterns
+
+- **Per-tool checks, not lifecycle checks.** Validating only at execute-task lets sketch / plan / research units write into invalid roots first.
+- **Trusting CWD.** A `process.chdir` (or operator `cd`) in another loop iteration can leave CWD pointing at a pruned worktree. Re-resolve every time; do not cache.
+- **Fallback-to-primary on worktree miss.** Silently writing to the primary checkout when the worktree is broken is the worst recovery — it corrupts the wrong branch with no audit trail.
+- **Skipping lease ownership.** Two sessions in the same worktree race on every commit. The lease is the authoritative single-writer signal; do not skip it because "it's only one session" — that assumption breaks the moment a parallel actor appears.
+- **Allowing detached HEAD silently.** A detached HEAD is sometimes legitimate (bisect, snapshot read), but every check must name whether detached is expected for this unit.
+
+## Pairs With
+
+- [verification-loop](verification-loop.md) — runs as a pre-Phase-0 invariant; the resolved-safety block fires before the resolved-ladder block.
+- [state-reconciliation](state-reconciliation.md) — both fire before dispatch; safety runs first because reconciliation depends on a valid worktree root.
+- [recovery-classification](recovery-classification.md) — any non-`CLEAR` line routes here as class `worktree`.
+- [gateguard](gateguard.md) — gateguard fires at the tool boundary; worktree-safety is the lifecycle counterpart that runs before tool dispatch is even considered.

package/templates/insights-claude-md.md

@@ -0,0 +1,91 @@
+# insights-claude-md.md — paste-in CLAUDE.md blocks
+
+The four blocks below originate from the 28-day Claude Code usage report (`usage-data/report.html`, "Suggested CLAUDE.md Additions" section). Each block targets a recurring friction class the report flagged:
+
+- **Verification Discipline** — sessions where typecheck/test was skipped or run from the wrong CWD
+- **Environment Notes** — Windows + Git Bash + PowerShell mismatches that cost retries
+- **Think Before Acting** — sessions where edits started before grounding was complete
+- **Git & Deploy Workflow** — merge declared "done" while the deploy provider was still on a stale commit
+
+The discipline behavior is already encoded as continuous-improvement skills (`gateguard`, `workspace-surface-audit`, `verification-loop`, `deploy-receipt`). These blocks are the *project-local* CLAUDE.md text — the per-repo reminder that lives where developers actually look when they read `CLAUDE.md`. Skills enforce; CLAUDE.md communicates.
+
+## How to use this file
+
+1. Open the target project's `CLAUDE.md`.
+2. Pick the blocks that apply to that project (TypeScript projects probably want all four; library-only projects can skip the deploy block).
+3. Paste them under existing sections or as new top-level sections.
+4. Adjust placeholders — the report's wording is opinionated. `pnpm` is just an example; if the project uses `npm` or `yarn` or `bun`, swap it. If the project's deploy target is not Railway or Cloudflare, swap those names. The structure stays; the specifics adapt.
+5. Optionally lock the section headings under `bin/check-docs-substrings.mjs` so a wholesale CLAUDE.md rewrite doesn't silently drop the discipline contract.
+
+The blocks are paste-in markdown — copy them verbatim into your project's CLAUDE.md.
+
+---
+
+## Block 1 — Verification Discipline
+
+Paste under a "Working norms" or "Coding standards" section. Adjust `pnpm` → your package manager.
+
+```markdown
+## Verification Discipline
+- Always run `pnpm typecheck` and `pnpm test` after code changes before declaring done
+- Run verification commands from the repo root; verify CWD with `pwd` if a previous command may have changed it
+- Never claim 'verified' or 'done' without showing the passing output
+```
+
+Why this block: the report flagged sessions where Claude either skipped typecheck/test until the operator prompted, or ran `tsc` from `frontend/` and incorrectly concluded deps weren't installed. The CWD line addresses the second failure mode directly.
+
+## Block 2 — Environment Notes
+
+Paste under a "Local development" or "Environment" section. Adjust the shell + tool list to match the project's actual setup.
+
+```markdown
+## Environment Notes
+- Shell is Git Bash on Windows; do NOT use `jq` (not installed) — use PowerShell or node/python for JSON parsing
+- Be careful with bash quoting in curl/psql commands; prefer heredocs or files over inline single-quoted JSON
+- CLAUDE.md is case-sensitive on some filesystems — always use uppercase
+```
+
+Why this block: the report flagged repeated jq-not-installed retries, shell-quoting failures on curl/psql, and a Windows case-sensitivity issue with `CLAUDE.md` vs `claude.md`. If your environment is different (macOS + zsh, Linux + bash, WSL2), rewrite this block to name *your* environment's grain — the goal is to surface the per-project gotchas before the agent re-discovers them at a cost of one wasted retry each.
+
+## Block 3 — Think Before Acting
+
+Paste near the top of CLAUDE.md, ideally above any task-specific instructions.
+
+```markdown
+## Think Before Acting
+- For any non-trivial request, produce a short plan before editing files
+- When the user references prior work (e.g. 'the Finnhub stuff'), verify it exists in the repo before acting on the assumption
+- Use TDD for new features: write failing test, then code, then verify
+```
+
+Why this block: the operator literally had to type "you need to think before u response" mid-session, and a separate session was wasted verifying nonexistent "Finnhub work" that was only used as a framework analogy. The first bullet generalizes the "plan first" rule from the global CLAUDE.md; the second is project-local — if your project has its own analogy-vs-real-code traps, name them here.
+
+## Block 4 — Git & Deploy Workflow
+
+Paste under a "Git workflow" or "Release process" section. Adjust the deploy provider names to match your project.
+
+```markdown
+## Git & Deploy Workflow
+- Never push directly to main — use PR workflow; harness will block direct pushes
+- After merging, verify Railway/Cloudflare actually picked up the commit before declaring deploy complete
+- For production POSTs and wrangler tail, expect harness blocks and surface them as caveats requiring user action
+```
+
+Why this block: multiple sessions hit "Railway deploy didn't pick up the latest commit" or "harness blocked merge-to-main / production POST / wrangler" — pre-emptive awareness saves retry cycles. The second bullet is what `deploy-receipt` enforces in-tooling; this CLAUDE.md text makes the same expectation visible to humans reviewing PRs.
+
+If your project deploys somewhere other than Railway or Cloudflare, swap those names. If your project does NOT auto-deploy from main (library-only / package-published), drop the second bullet entirely — receipt verification doesn't apply.
+
+---
+
+## Companion skills (already installed if you have continuous-improvement)
+
+Each block has a corresponding skill that enforces the rule when an agent is in the loop. Pasting the block tells humans the rule; installing the skill makes the agent obey it.
+
+| Block | Companion skill |
+|---|---|
+| Verification Discipline | `verification-loop` (per-project ladder via `.claude/verify-ladder.json`) |
+| Environment Notes | `workspace-surface-audit` (records environment grain at session start) |
+| Think Before Acting | `gateguard` (blocks Edit/Write/Bash before grounding) |
+| Git & Deploy Workflow | `deploy-receipt` (verifies deployed SHA + healthcheck before declaring done) |
+
+If you want both layers (CLAUDE.md text + skill enforcement), paste the block AND keep the skill installed. If you only want one, the skill is the higher-fidelity surface — it runs at the tool boundary and cannot be skipped by an agent that didn't read the markdown.

package/templates/verify-ladder.example.json

@@ -9,39 +9,52 @@
     "Three starter shapes are provided below — pick one, delete the others, then trim."
   ],
 
+  "_synthetic_checks_doc": [
+    "synthetic_checks names a directory (relative to the repo root) containing",
+    "*.synthetic.{sh,mjs,ts,py} files. Each file is invoked once after deploy-receipt",
+    "reports COMPLETE, with BASE_URL + BASELINE_URL + EXPECTED_SHA env vars set.",
+    "Exit 0 = production matches baseline; non-zero = drift, stdout is the diff.",
+    "Set to null to skip; set to a different path (e.g. 'infra/synthetic/') to relocate.",
+    "See synthetic-checks/README.md for the full contract."
+  ],
+
   "_typescript_node_example": {
-    "build":          "npm run build",
-    "typecheck":      "npx tsc --noEmit",
-    "lint":           "npm run lint",
-    "test":           "npm test",
-    "security":       "npm audit --audit-level=high",
-    "deploy_receipt": null
+    "build":            "npm run build",
+    "typecheck":        "npx tsc --noEmit",
+    "lint":             "npm run lint",
+    "test":             "npm test",
+    "security":         "npm audit --audit-level=high",
+    "deploy_receipt":   null,
+    "synthetic_checks": null
   },
 
   "_rust_cargo_example": {
-    "build":          "cargo build --release",
-    "typecheck":      "cargo check --all-targets",
-    "lint":           "cargo clippy --all-targets -- -D warnings",
-    "test":           "cargo test --all-features",
-    "security":       "cargo audit",
-    "deploy_receipt": null
+    "build":            "cargo build --release",
+    "typecheck":        "cargo check --all-targets",
+    "lint":             "cargo clippy --all-targets -- -D warnings",
+    "test":             "cargo test --all-features",
+    "security":         "cargo audit",
+    "deploy_receipt":   null,
+    "synthetic_checks": null
   },
 
   "_python_uv_example": {
-    "build":          null,
-    "typecheck":      "uv run pyright",
-    "lint":           "uv run ruff check .",
-    "test":           "uv run pytest",
-    "security":       "uv run pip-audit",
-    "deploy_receipt": null
+    "build":            null,
+    "typecheck":        "uv run pyright",
+    "lint":             "uv run ruff check .",
+    "test":             "uv run pytest",
+    "security":         "uv run pip-audit",
+    "deploy_receipt":   null,
+    "synthetic_checks": null
   },
 
   "_cloudflare_worker_example": {
-    "build":          "npm run build",
-    "typecheck":      "npx tsc --noEmit",
-    "lint":           "npm run lint",
-    "test":           "npm test",
-    "security":       "npm audit --audit-level=high",
-    "deploy_receipt": "npx wrangler deployments list --json"
+    "build":            "npm run build",
+    "typecheck":        "npx tsc --noEmit",
+    "lint":             "npm run lint",
+    "test":             "npm test",
+    "security":         "npm audit --audit-level=high",
+    "deploy_receipt":   "npx wrangler deployments list --json",
+    "synthetic_checks": "synthetic-checks/"
   }
 }