pi-dev-team 0.2.0

package/skills/legacy-code/SKILL.md

@@ -0,0 +1,132 @@
+---
+name: legacy-code
+description: Safely modify code that lacks tests. Use whenever tasked with changing code without test coverage — apply characterization tests and dependency-breaking techniques before making any behavioral changes.
+role: worker
+user-invocable: true
+---
+
+# Legacy Code
+
+Role: worker. This command applies characterization-testing and
+dependency-breaking techniques directly to the code under change.
+
+## Overview
+
+Techniques for safely modifying code that lacks tests or has poor structure. Based on the principle that legacy code is code without tests (Michael Feathers' definition) — regardless of age. The goal is to get code under test before changing it, then improve structure incrementally.
+
+## Constraints
+
+- Never change behavior and structure in the same step; refactor under green tests only
+- Write characterization tests before modifying legacy code — not after
+- Prefer the smallest dependency break that gets code under test
+- Do not apply aggressive refactoring without test coverage
+
+## Core Concepts
+
+### Legacy Code Definition
+
+Code without tests. A well-structured 6-month-old codebase with no tests is legacy. A messy 10-year-old codebase with comprehensive tests is not. The presence or absence of tests determines whether you can change code safely.
+
+### The Legacy Code Change Algorithm
+
+1. **Identify change points** — where in the code does the change need to happen?
+2. **Find test points** — where can you observe the effects of the change?
+3. **Break dependencies** — make the code testable without changing its behavior
+4. **Write tests** — characterization tests that lock down existing behavior
+5. **Make changes and refactor** — now that tests protect you, modify behavior and improve structure
+
+### Seams
+
+A seam is a place where behavior can be altered without editing the code under test:
+
+- **Object seams** — use polymorphism to substitute behavior (interfaces, subclasses)
+- **Link seams** — substitute dependencies at the linking/import level (dependency injection, module mocking)
+- **Preprocessing seams** — alter behavior via build configuration, feature flags, or compile-time substitution
+
+### Characterization Tests
+
+Tests that document what the code *actually does*, not what it *should do*. They lock down existing behavior so you can detect unintended changes. Characterization tests answer: "If I make a change here, what breaks?"
+
+## Patterns
+
+### Characterization Test Procedure
+
+1. Find the code area you need to change
+2. Write a test that calls the code and lets it fail to reveal actual output
+3. Update the test assertion to match observed behavior
+4. Repeat until the change area and its immediate dependencies are covered
+5. Use these tests as a safety net — any behavioral change will now show as a test failure
+
+### Finding Test Points (effect reasoning)
+
+Step 2 of the algorithm — *where can you observe the effects of the change?* — is its own skill in tangled code. Before writing tests, reason about effects and place verification where it has leverage. The full method (effect sketches, interception points, pinch points, and the editing-safety techniques — Lean on the Compiler, Preserve Signatures, Single-Goal Editing) is in [`knowledge/legacy-test-strategy.md`](../../knowledge/legacy-test-strategy.md). In brief:
+
+- Trace effects outward from each change point; every place you can detect an effect is an **interception point**.
+- Prefer a **pinch point** — a narrowing where one or two tests sense changes across many methods — to anchor characterization tests, then push verification down to narrow units once the area is malleable (don't let pinch-point tests calcify into mini-integration tests).
+- Ask of any candidate: *"If I break this method, will I sense it here?"*
+
+**Graph-assisted exploration.** Prefer CodeGraph/Repowise over raw `Grep` when identifying change points, tracing effects outward to interception/pinch points, and mapping the dependencies a seam needs to break — a pre-built call graph surfaces callers, callees, and blast radius faster and more completely than text search. See [`knowledge/codegraph-vs-graphify.md`](../../knowledge/codegraph-vs-graphify.md) for tool selection and the fallback contract.
+
+### Dependency Breaking Techniques
+
+The everyday shortlist below covers most cases. The **full 24-technique catalog** (globals/singletons, non-OO seams, hard parameters, monster methods, with seam type and risk for each) lives in [`knowledge/dependency-breaking-techniques.md`](../../knowledge/dependency-breaking-techniques.md) — read it when a break here doesn't present a seam.
+
+| Technique | When to Use | Risk |
+| --- | --- | --- |
+| Extract Interface | Class has a concrete dependency you need to substitute | Low |
+| Extract Method | Long method with embedded logic you need to isolate (safest starting point) | Low |
+| Parameterize Constructor | Class creates its own dependencies internally | Low |
+| Extract and Override Call / Factory Method | A specific call or `new` in a constructor blocks the test | Low–Med |
+| Subclass and Override Method | Need to neutralize or replace specific behavior in tests | Medium |
+| Sprout / Wrap Method or Class | Adding new behavior to untested code (see decision below) | Low–Med |
+| Adapt Parameter | Method depends on a type you can't use in tests | Medium |
+
+### Sprout vs. Wrap Decision
+
+- **Sprout** (new method/class called from existing code): use when the new behavior is an addition that existing code needs to invoke at a specific point. The existing code changes minimally — it gains one call to the new method.
+- **Wrap** (new code that calls existing code): use when existing callers must see the new behavior transparently without modification. The new code sits between callers and the original code.
+
+### Strangler Pattern
+
+Incrementally replace legacy components by routing new behavior through new code while old code remains operational:
+
+1. Identify a bounded area of legacy functionality
+2. Build new implementation alongside the old
+3. Route new requests/features through new code
+4. Gradually migrate existing behavior to new code
+5. Remove old code only when fully replaced and verified
+
+## Output
+
+Report the legacy code analysis: identified change points, test points, dependency breaks needed, characterization test targets, and the recommended refactoring sequence. Be concise — bullet list format; skip background explanation.
+
+## When to Apply
+
+| Situation | Apply? |
+| --- | --- |
+| Modifying code without tests | Yes |
+| Adding behavior to poorly structured code | Yes |
+| Migrating legacy components to new architecture | Yes |
+| Greenfield development | No |
+| Code already well-tested and well-structured | No |
+| Pure deletion of unused code | No |
+
+## Guidelines
+
+1. Never change behavior and structure in the same step. Refactor under green tests only.
+2. Write characterization tests before modifying legacy code. The tests document current behavior, not desired behavior.
+3. Prefer the smallest dependency break that gets code under test. Aggressive refactoring without test coverage creates risk.
+4. Sprout when the new behavior is clearly separable; wrap when existing callers must see the new behavior transparently.
+5. Every dependency break is temporary scaffolding — revisit and clean up once test coverage allows broader refactoring.
+6. If you cannot find a seam, extract method first. Extract Method is the safest starting point for almost any dependency break.
+7. Characterization tests are not a substitute for acceptance tests. They lock behavior; acceptance tests define behavior.
+
+## Integration
+
+- **[Specs](../specs/SKILL.md)** — when modifying legacy code to add new behavior, specify the new behavior first, then use this skill to get existing code under test before implementing
+- **[Hexagonal Architecture](../hexagonal-architecture/SKILL.md)** — dependency breaking techniques move legacy code toward port/adapter separation incrementally
+- **[Quality Gate Pipeline](../quality-gate-pipeline/SKILL.md)** — verify characterization tests match observed behavior (Phase 1); legacy code changes have higher defect risk, apply review-correction with increased scrutiny (Phase 3)
+- **[Mutation Testing](../mutation-testing/SKILL.md)** — after writing characterization tests, use mutation testing to verify those tests catch behavioral changes
+- **[Dependency-Breaking Techniques](../../knowledge/dependency-breaking-techniques.md)** — the full 24-technique catalog (Feathers Part III) behind the shortlist above; consult for globals/singletons, non-OO seams, hard parameters, and monster methods
+- **[Legacy Test Strategy](../../knowledge/legacy-test-strategy.md)** — effect reasoning, effect sketches, interception/pinch points (where to test) and editing-safety techniques (how to edit before tests exist)
+- **[Testability Patterns](../../knowledge/testability-patterns.md)** — constructor injection, Test Data Builder, interface extraction, the Design-for-Testability seam family (Humble Object, Dependency Lookup), and the "I Can't Test This Class" decision flow are the *target design* the dependency breaks scaffold toward; read it when the break needed is a design change rather than a temporary seam insertion

package/skills/mermaid-diagramming/SKILL.md

@@ -0,0 +1,120 @@
+---
+name: mermaid-diagramming
+description: Create Mermaid diagrams using the project's blue-gray theme. Use whenever the user asks to draw a diagram, create a flowchart, visualize a process, document architecture, or add any Mermaid diagram to a markdown file. Trigger on phrases like "draw a diagram", "create a flowchart", "visualize this", "add a mermaid diagram", "document the flow", "sequence diagram", "architecture diagram", or any request to diagram a process or system.
+role: worker
+user-invocable: true
+---
+
+# Mermaid Diagramming
+
+Produce Mermaid diagrams that use the project's blue-gray theme. Every diagram must include the theme init directive as its first line.
+
+## Theme Directive
+
+Paste this as the **first line** inside every ```` ```mermaid ```` block, before the diagram type declaration:
+
+```
+%%{init: {'theme': 'base', 'themeVariables': {'primaryColor': '#dbeafe', 'primaryTextColor': '#1e3a5f', 'primaryBorderColor': '#3b82f6', 'lineColor': '#64748b', 'secondaryColor': '#f1f5f9', 'tertiaryColor': '#e0f2fe', 'background': '#ffffff', 'mainBkg': '#dbeafe', 'nodeBorder': '#2563eb', 'clusterBkg': '#eff6ff', 'clusterBorder': '#bfdbfe', 'titleColor': '#1e3a5f', 'edgeLabelBackground': '#f8fafc'}}}%%
+```
+
+### Palette reference
+
+| Variable | Value | Role |
+|---|---|---|
+| `primaryColor` / `mainBkg` | `#dbeafe` (blue-100) | Default node fill |
+| `secondaryColor` | `#f1f5f9` (slate-100) | Secondary node fill |
+| `tertiaryColor` | `#e0f2fe` (sky-100) | Tertiary / highlight fill |
+| `primaryBorderColor` / `nodeBorder` | `#3b82f6` / `#2563eb` (blue-500/600) | Node border |
+| `clusterBkg` | `#eff6ff` (blue-50) | Subgraph / cluster fill |
+| `clusterBorder` | `#bfdbfe` (blue-200) | Subgraph border |
+| `lineColor` | `#64748b` (slate-500) | Edge / arrow color |
+| `primaryTextColor` / `titleColor` | `#1e3a5f` (dark navy) | Text |
+| `edgeLabelBackground` | `#f8fafc` (slate-50) | Edge label background |
+| `background` | `#ffffff` | Diagram background |
+
+## Rules
+
+1. **Always include the theme directive.** No exceptions — every ```` ```mermaid ```` block in this repo starts with the `%%{init}%%` line.
+2. **One diagram per concept.** If a section needs multiple views, use separate fenced blocks with a heading for each.
+3. **Keep labels short.** Node labels ≤ 6 words. Use subgraphs for grouping, not long labels.
+4. **Decision nodes use `{...}` rhombus shape.** Action nodes use `[...]` rectangles. Terminal/IO nodes use `[/..../]` parallelograms.
+5. **Left-to-right for pipelines, top-to-bottom for hierarchies.** Default to `LR` for data flow; `TD` for org charts, call trees, and phase sequences.
+
+## Diagram Types
+
+### Flowchart — processes and pipelines
+
+```mermaid
+%%{init: {'theme': 'base', 'themeVariables': {'primaryColor': '#dbeafe', 'primaryTextColor': '#1e3a5f', 'primaryBorderColor': '#3b82f6', 'lineColor': '#64748b', 'secondaryColor': '#f1f5f9', 'tertiaryColor': '#e0f2fe', 'background': '#ffffff', 'mainBkg': '#dbeafe', 'nodeBorder': '#2563eb', 'clusterBkg': '#eff6ff', 'clusterBorder': '#bfdbfe', 'titleColor': '#1e3a5f', 'edgeLabelBackground': '#f8fafc'}}}%%
+flowchart LR
+    A[Input] --> B{Valid?}
+    B -->|yes| C[Process]
+    B -->|no| D[Reject]
+    C --> E[Output]
+```
+
+### Sequence — interactions between actors/services
+
+```mermaid
+%%{init: {'theme': 'base', 'themeVariables': {'primaryColor': '#dbeafe', 'primaryTextColor': '#1e3a5f', 'primaryBorderColor': '#3b82f6', 'lineColor': '#64748b', 'secondaryColor': '#f1f5f9', 'tertiaryColor': '#e0f2fe', 'background': '#ffffff', 'mainBkg': '#dbeafe', 'nodeBorder': '#2563eb', 'clusterBkg': '#eff6ff', 'clusterBorder': '#bfdbfe', 'titleColor': '#1e3a5f', 'edgeLabelBackground': '#f8fafc'}}}%%
+sequenceDiagram
+    participant C as Client
+    participant S as Server
+    participant D as Database
+    C->>S: POST /resource
+    S->>D: INSERT row
+    D-->>S: OK
+    S-->>C: 201 Created
+```
+
+### Graph with subgraphs — architecture layers
+
+```mermaid
+%%{init: {'theme': 'base', 'themeVariables': {'primaryColor': '#dbeafe', 'primaryTextColor': '#1e3a5f', 'primaryBorderColor': '#3b82f6', 'lineColor': '#64748b', 'secondaryColor': '#f1f5f9', 'tertiaryColor': '#e0f2fe', 'background': '#ffffff', 'mainBkg': '#dbeafe', 'nodeBorder': '#2563eb', 'clusterBkg': '#eff6ff', 'clusterBorder': '#bfdbfe', 'titleColor': '#1e3a5f', 'edgeLabelBackground': '#f8fafc'}}}%%
+flowchart TD
+    subgraph API["API Layer"]
+        R[Router]
+        M[Middleware]
+    end
+    subgraph Domain["Domain Layer"]
+        S[Service]
+        E[Entities]
+    end
+    subgraph Infra["Infrastructure"]
+        DB[(Database)]
+        Cache[(Cache)]
+    end
+    R --> M --> S --> E
+    S --> DB
+    S --> Cache
+```
+
+### State diagram — lifecycle / state machine
+
+```mermaid
+%%{init: {'theme': 'base', 'themeVariables': {'primaryColor': '#dbeafe', 'primaryTextColor': '#1e3a5f', 'primaryBorderColor': '#3b82f6', 'lineColor': '#64748b', 'secondaryColor': '#f1f5f9', 'tertiaryColor': '#e0f2fe', 'background': '#ffffff', 'mainBkg': '#dbeafe', 'nodeBorder': '#2563eb', 'clusterBkg': '#eff6ff', 'clusterBorder': '#bfdbfe', 'titleColor': '#1e3a5f', 'edgeLabelBackground': '#f8fafc'}}}%%
+stateDiagram-v2
+    [*] --> Pending
+    Pending --> Running : start
+    Running --> Passed : success
+    Running --> Failed : error
+    Passed --> [*]
+    Failed --> [*]
+```
+
+## Procedure
+
+1. Identify the diagram type that best fits the concept (flowchart, sequence, state, ER, etc.).
+2. Draft the structure — nodes, edges, labels — before writing Mermaid syntax.
+3. Open the ```` ```mermaid ```` block with the theme `%%{init}%%` directive on line 1.
+4. Write the diagram type declaration on line 2.
+5. Verify the diagram is syntactically valid (balanced brackets, no duplicate node IDs).
+6. Add the diagram to the markdown file with a heading that explains what it shows.
+
+## Adding a diagram to an existing file
+
+When inserting a diagram into an existing markdown file:
+
+1. Read the file first to understand the document structure and find the right insertion point.
+2. Use a second-level heading (`##`) above the diagram block to name the concept.
+3. Add a one-sentence caption below the closing ```` ``` ```` that describes what the diagram shows — this doubles as alt-text.

package/skills/mutation-night-watch/SKILL.md

@@ -0,0 +1,154 @@
+---
+name: mutation-night-watch
+description: Launch, schedule, and hand off an unattended, LLM-free overnight mutation night-watch run. Use when the user wants a mutation-score baseline waiting each morning without paying LLM cost or blocking a session overnight, says "run mutation testing overnight", "schedule a nightly mutation scan", "set up a mutation night watch", or asks how to get an unattended mutation baseline. Wraps mutation_nightwatch.py — report-only measurement, never generation.
+role: worker
+user-invocable: true
+allowed-tools: Read, Write, Bash(python3 *), Bash(launchctl *), Bash(crontab *), Bash(schtasks *)
+---
+
+# Mutation Night-Watch
+
+<!-- pi-port-notes -->
+## pi port notes
+
+- Where this skill schedules or runs `claude --print`, use `pi --mode json -p --no-session` (or the port's `claude` shim, which is on `PATH` inside pi sessions but not in cron). In a cron entry call `pi` directly.
+<!-- pi-port-notes -->
+
+
+Role: worker. Launches and schedules a report-only measurement run. It never
+generates a test, never invokes an LLM, and never commits — that is the
+`mutation-kill` agent's job, the next morning, reading this skill's output.
+
+> **Naming note.** The skill is named `mutation-night-watch`; its underlying
+> scripts, output directory (`reports/mutation-nightwatch/`), and launchd
+> label use `mutation_nightwatch`/`mutation-nightwatch` — this is an
+> intentional, stable naming split; do not rename the on-disk paths without a
+> migration plan (#1856).
+
+## Why this exists, and how it differs from `mutation-kill`
+
+`mutation-kill` already has two modes: **interactive** (an agent generates
+tests turn by turn) and **`--headless`** (unattended, but every round still
+shells out to `claude --print` — LLM cost and API availability are both in
+the loop). Neither mode is meant to run **overnight with nobody watching**:
+a multi-hour unattended `claude --print` loop is expensive and, on a flaky
+network, silently stalls.
+
+Night-watch is a **third, LLM-free mode**: measurement only. It runs the real
+mutation tool for each detected stack, scores the result with the same
+[`mutation_report.py`](../mutation-testing/scripts/mutation_report.py) the
+rest of the mutation-testing skill family uses, and writes the result where
+`mutation-kill` (or a human) picks it up the next day. It does not replace
+`mutation-kill`'s fixing modes — see [`mutation-testing/SKILL.md`](../mutation-testing/SKILL.md)
+for those.
+
+## Constraints
+
+- **Report-only. Never generation.** The script
+  ([`../mutation-testing/scripts/mutation_nightwatch.py`](../mutation-testing/scripts/mutation_nightwatch.py))
+  has no code path that shells to an LLM. If a stack's tool run mutates a
+  survivor count, that is the mutation tool itself running normally — nothing
+  here writes a test.
+- **Mechanical repair only, never code.** Before measuring, the script runs
+  each stack's package-pin-sync step (`npm ci` when `node_modules` is
+  missing, `dotnet restore`) so a stale dependency tree doesn't fail the
+  whole run on a mechanical break. It never edits a production or test file,
+  and never commits — see the script's `mechanical_repair`.
+- **Detected-but-unscored stacks are reported, not guessed.** pitest (Java)
+  and go-mutesting (Go) are detected but have no `mutation_report.py` parser
+  yet; they show up in the summary as `skipped_no_parser`, never a
+  fabricated score.
+- **Always confirm scope before scheduling a recurring run.** A single ad hoc
+  `--detach` launch needs no extra confirmation beyond what the user already
+  asked for; wiring a scheduler entry (Task Scheduler / launchd / cron) that
+  runs unattended on a recurring cadence is a standing change to the user's
+  machine — confirm the schedule and scope before writing the scheduler
+  config.
+
+## Step 1: Detect and preview scope
+
+Run once without `--detach` on a small scope, or just read the detection
+output, before committing to an overnight run:
+
+```bash
+python3 "${CLAUDE_PLUGIN_ROOT}/skills/mutation-testing/scripts/mutation_nightwatch.py" --repo-root . --no-sleep-inhibit
+```
+
+This prints the run directory and writes `MORNING-SUMMARY.md` +
+`SURVIVORS.json` there and into `reports/mutation-nightwatch/LATEST/`. Read
+the summary's stack table before scheduling a longer, detached run — a stack
+reporting `skipped` (no unique `.sln`, no `stryker-config.json`) or
+`skipped_no_parser` needs attention first, not a repeat overnight run that
+will report the same gap every time.
+
+## Step 2: Launch detached (survives closing the terminal/session)
+
+```bash
+python3 "${CLAUDE_PLUGIN_ROOT}/skills/mutation-testing/scripts/mutation_nightwatch.py" --repo-root . --detach
+```
+
+`--detach` re-execs the script into a new session/process group (POSIX
+`setsid`-equivalent; Windows `DETACHED_PROCESS`) and returns immediately,
+printing the child's PID and its `detached-launch.log` path. The run
+continues after the launching terminal or Claude Code session closes.
+
+While running, the script holds the OS awake for the run's duration:
+`caffeinate -dims` on macOS, `systemd-inhibit --what=sleep:idle` on Linux,
+`SetThreadExecutionState` directly on Windows. When none of those are
+available, the run still proceeds — but `MORNING-SUMMARY.md`'s Notes section
+always carries an explicit `NOTE: sleep inhibition unavailable on <platform>`
+line rather than silently risking a sleep-interrupted run. Treat that NOTE as
+actionable: install the missing tool, or accept the machine may sleep
+mid-run.
+
+## Step 3: Schedule a recurring run (optional)
+
+Per-OS recipes — Task Scheduler, launchd, and cron — live in
+[`references/scheduling.md`](references/scheduling.md). Confirm the cadence
+and scope with the user before writing any of these (see Constraints above);
+they run unattended, indefinitely, until removed.
+
+## Step 4: Morning hand-off
+
+Read `reports/mutation-nightwatch/LATEST/MORNING-SUMMARY.md` first — it
+carries per-stack status, the honest score, and any Notes (sleep inhibition,
+mechanical-repair failures) from the most recent run, regardless of that
+run's timestamped folder name. Both files are refreshed after every module
+completes, not only when the run finishes cleanly — a mid-run kill or
+timeout still leaves whatever finished so far, never nothing. `SURVIVORS.json` alongside it is the
+machine-readable list (`{stack, module, file, line, mutator, change,
+status}` per survivor) — hand it to the `mutation-kill` agent (or triage it
+per [`mutation-testing/SKILL.md`](../mutation-testing/SKILL.md) Step 4)
+rather than re-running the scan to rediscover the same survivors.
+
+A stack reporting `error` in the summary table did not produce a report at
+all this run (tool missing, timed out, or crashed before writing its native
+report) — its prior night's `SURVIVORS.json` entries (if any) are stale, not
+confirmed-fixed; re-run that stack before trusting a "clean" reading.
+
+**Exclude-policy proposal, if present.** When the summary's Notes mention no
+committed `mutation-exclude-policy.json` was found, review
+`reports/mutation-nightwatch/LATEST/EXCLUDE-POLICY-PROPOSAL.json` — its
+`always` entries carry a filename-convention hint (DI wiring, middleware,
+generated code), its `propose_and_ask` entries are signal-only and need a
+human look. Approve what you agree with:
+
+```bash
+python3 "${CLAUDE_PLUGIN_ROOT}/skills/mutation-testing/scripts/mutation_exclude_policy.py" --approve reports/mutation-nightwatch/LATEST/EXCLUDE-POLICY-PROPOSAL.json --repo-root .
+```
+
+This is the only code path that writes the committed policy file — the
+night-watch run itself only ever drafts a proposal, never approves one.
+
+## When not to apply
+
+- No mutation tool is set up yet for any stack → run
+  [`mutation-testing`](../mutation-testing/SKILL.md) interactively first to
+  get one configured and smoke-gated; night-watch only measures, it does not
+  install or configure a tool.
+- The repo is small enough that a mutation run finishes in a few minutes →
+  just run `mutation-testing` directly; detach/sleep-inhibition/scheduling
+  are overhead a short run doesn't need.
+- Java (pitest) or Go (go-mutesting) is the *only* detected stack → night-
+  watch will report `skipped_no_parser`/never invoke the tool; use
+  `mutation-testing` directly for those ecosystems today.

package/skills/mutation-night-watch/references/scheduling.md

@@ -0,0 +1,135 @@
+# Mutation Night-Watch: Scheduling Recipes
+
+> **Naming note.** The skill is named `mutation-night-watch`; its underlying
+> scripts, output directory (`reports/mutation-nightwatch/`), and launchd
+> label use `mutation_nightwatch`/`mutation-nightwatch` — this is an
+> intentional, stable naming split; do not rename the on-disk paths without a
+> migration plan (#1856).
+
+Each recipe runs `mutation_nightwatch.py` **without** `--detach` — the
+scheduler itself already runs the job detached from any interactive session,
+so re-detaching would just orphan a second process. Use `--detach` only for
+an ad hoc manual launch (see [`../SKILL.md`](../SKILL.md) Step 2).
+
+Confirm the cadence and scope with the user before installing any of these —
+each one runs unattended, indefinitely, until removed (see `../SKILL.md`'s
+Constraints).
+
+Substitute:
+
+- `<repo>` — absolute path to the repository root (the project being
+  measured, not the plugin's own install location).
+- `<plugin-root>` — absolute path to the installed dev-team plugin on this
+  machine — get it by running `echo "$CLAUDE_PLUGIN_ROOT"` from an active
+  Claude Code session with the dev-team plugin loaded. Without a session,
+  derive it from `/dev-team:version`'s output (`dev-team@<marketplace>
+  v<version> (scope: <scope>)`): the installed copy lives at
+  `~/.claude/plugins/cache/<marketplace>/dev-team/<version>/`, e.g.
+  `~/.claude/plugins/cache/bfinster/dev-team/12.3.0` for `dev-team@bfinster
+  v12.3.0 (scope: user)`. `${CLAUDE_PLUGIN_ROOT}` itself is a
+  Claude-session-time environment variable and does not exist when a
+  scheduler runs the job outside any Claude session, so these recipes need
+  its resolved value substituted in ahead of time rather than the literal
+  token.
+- `<python>` — an absolute path to the Python 3.10+ interpreter that has the
+  repo's mutation tooling on `PATH` (a venv's `python`, or the system one).
+
+## macOS — launchd
+
+launchd (not cron — cron does not run on a schedule reliably across macOS
+sleep/wake cycles) via a per-user `LaunchAgent`.
+
+`~/Library/LaunchAgents/dev.agentic-dev-team.mutation-nightwatch.plist`:
+
+```xml
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN"
+  "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+  <key>Label</key>
+  <string>dev.agentic-dev-team.mutation-nightwatch</string>
+  <key>ProgramArguments</key>
+  <array>
+    <string><python></string>
+    <string><plugin-root>/skills/mutation-testing/scripts/mutation_nightwatch.py</string>
+    <string>--repo-root</string>
+    <string><repo></string>
+  </array>
+  <key>StartCalendarInterval</key>
+  <dict>
+    <key>Hour</key>
+    <integer>1</integer>
+    <key>Minute</key>
+    <integer>0</integer>
+  </dict>
+  <key>StandardOutPath</key>
+  <string><repo>/reports/mutation-nightwatch/launchd.log</string>
+  <key>StandardErrorPath</key>
+  <string><repo>/reports/mutation-nightwatch/launchd.log</string>
+</dict>
+</plist>
+```
+
+Load/unload:
+
+```bash
+launchctl load ~/Library/LaunchAgents/dev.agentic-dev-team.mutation-nightwatch.plist
+launchctl unload ~/Library/LaunchAgents/dev.agentic-dev-team.mutation-nightwatch.plist
+```
+
+launchd's own scheduling already survives the machine sleeping (it fires on
+the next wake if the fire time was missed); `mutation_nightwatch.py`'s
+`caffeinate`-based `SleepInhibitor` then keeps the machine **awake for the
+run itself** once it starts, so a multi-hour run isn't interrupted mid-way.
+
+## Linux — cron + systemd-inhibit
+
+cron runs the job; the script's own `SleepInhibitor` calls
+`systemd-inhibit` internally, so no extra wrapping is needed in the crontab
+line itself.
+
+`crontab -e`:
+
+```cron
+0 1 * * * <python> <plugin-root>/skills/mutation-testing/scripts/mutation_nightwatch.py --repo-root <repo> >> <repo>/reports/mutation-nightwatch/cron.log 2>&1
+```
+
+Note the redirect is a direct `>>`, not a `| tee` — see
+[`mutation-testing/SKILL.md`](../../mutation-testing/SKILL.md#capturing-run-output-safely)
+for why a `tee` pipeline masks a startup failure's exit code. cron always
+uses `sh`, so this is safe here regardless.
+
+A machine that suspends (a laptop, not a server) needs an additional wake
+trigger — cron does not wake a suspended machine. Pair with `rtcwake` or an
+OS-level wake-on-schedule setting if the target machine sleeps outside of
+process-level idle (systemd-inhibit only blocks *idle* suspend once the
+process is already running, not a deeper suspend triggered before cron fires).
+
+## Windows — Task Scheduler
+
+```powershell
+schtasks /create /tn "MutationNightWatch" /tr "<python> <plugin-root>\skills\mutation-testing\scripts\mutation_nightwatch.py --repo-root <repo>" /sc daily /st 01:00
+```
+
+Task Scheduler's own "Wake the computer to run this task" option (in the
+task's **Conditions** tab, or `/sc daily` plus editing the task afterward via
+`taskschd.msc`) is the Windows equivalent of the launchd/rtcwake concerns
+above — enable it if the target machine sleeps.
+
+`mutation_nightwatch.py` calls `SetThreadExecutionState` directly on Windows
+(no subprocess to hold open, unlike macOS/Linux) to keep the machine awake
+for the run's duration once it starts.
+
+Remove the task:
+
+```powershell
+schtasks /delete /tn "MutationNightWatch" /f
+```
+
+## Every OS: reading the result
+
+Regardless of scheduler, the result lands at
+`<repo>/reports/mutation-nightwatch/LATEST/MORNING-SUMMARY.md` — the stable
+mirror path never changes between runs. See [`../SKILL.md`](../SKILL.md)
+Step 4 for the morning hand-off to `mutation-kill`.