peaks-loop 4.0.0-beta.8 → 4.0.1

package/skills/peaks-code/SKILL.md

@@ -44,107 +44,88 @@ This skill is the **primary surface**. The `peaks <cmd>` CLI is **auxiliary**
 
 **Peaks-Loop Code is an orchestrator, NOT an implementer. You MUST NOT write, edit, or modify any application source code directly.** Every code change goes through `peaks-code → RD → QA → verdict`. **If you catch yourself about to write code, STOP.** Hand off to RD. Before declaring workflow complete, run `peaks workflow verify-pipeline --rid <rid> --project <repo> --json`.
 
-## Peaks-Loop Startup sequence (MANDATORY — execute in order)
-
-### Peaks-Loop Slice 011 — workspace consolidate + session checkpoint/resume
-
-`peaks workspace consolidate` is the slice-011 umbrella primitive. `peaks session checkpoint` (context-overflow defense) and `peaks session resume` surface as Step 0.75 + Step N. See `references/cross-date-session-check.md`.
-
-### Peaks-Loop Step 0.75: Resume from checkpoint (BLOCKING on same-day re-invocation)
-
-When a NEW conversation opens on a session whose `lastActivity` is from today AND `.peaks/_runtime/<sessionId>/checkpoints/` has `*.json`, surface via `peaks session info --active --json` + `peaks session resume --from <path> --project <repo>`. Prompt via `AskUserQuestion` (resume / fresh); if "resume", prepend the block. Step 0.75 is no-op on precondition fail. See `references/checkpoint-resume.md`.
-
-### Peaks-Loop Step N: Periodic checkpoint (auto-fire, no user action)
-
-Proactive context-overflow defense. CLI: `peaks session checkpoint [--reason <r>] [...flags]`. Fire `--reason periodic` every 20 tool calls (G1 hard-coded), `--reason artifact-written` per PRD/RD/QA/TXT write. See `references/periodic-checkpoint.md` (otherwise `tests/unit/code/checkpoint-periodic-frequency.test.ts` fails).
-
-### Peaks-Loop Step 0.6: Audit + Goal (NEW)
-
-Invoke peaks-audit after need expressed; store approved goal at `.peaks/_runtime/<sessionId>/audit-goal/<rid>.json`. **All autonomous work requires approved goal.** → `references/audit-goal-gate.md`.
-
-### Peaks-Loop Step N+1: Final Review (NEW)
-
-After autonomous work (RD, QA, security, perf), invoke peaks-final-review for 4-dim evidence. All 4 pass → final delivery; else loop back. See `references/final-review-gate.md`.
-
-### Peaks-Loop Step N+2: Main-session context monitor (D6 + slice 2026-07-02)
+## 24h mode (orchestrator flag, NOT a new skill)
 
-After every 4th tool call, probe via `peaks code context-now --project <repo> --json`. Thresholds: 50% / **0.85 pre-compact / 0.95 red-line** (v2.13.0). **In Job mode ≥ 0.85 is MANDATORY auto-compact** (`peaks session auto-compact --execute`). Pass `--enforce-job-mode` for single-rid. **≥ 0.95** red line: next Bash/Task fires `peaks session auto-compact-hook`. **Karpathy §4 exception**: compact red line keeps runner alive — zero-intervention wins; LLM MUST NOT ask user to run `/compact`. Honor `--in-flight-batch` (D6.e).
+24h mode is a *flag* the orchestrator flips, not a sibling skill. See `.peaks/memory/2026-07-28-peaks-code-loop-skill-proposal.md` for the RL-8 tension analysis. State machine via `peaks session 24h-mode {state,transition,attempts,reset}`; snapshot at `.peaks/_runtime/<sessionId>/24h-state.json` (read-only for peaks-code).
 
-### Peaks-Loop Step 0: Anchor the workflow (MANDATORY FIRST ACTIONS — no bail-out)
+**5 auto-engage triggers:** T1 user NL keyword (`24h / 通宵 / 不计成本 / 不停机 / ...`) / T2 ≥30 active slices + ≥6h wall-clock / T3 ≥3 monotonic-guard fires + ≥10 slices remaining / T4 session gap ≥4h / T5 ≥3 active slices for restart. T3+T4 auto-engage 24H_ACTIVE; T1/T2/T5 surface for LLM judgement.
 
-Run `peaks workspace init` + `peaks skill presence:set peaks-code` BEFORE any analysis, role handoff, or mode-selection question. Even "分析下这个项目" / "看一下代码" / one-line questions anchor first.
+**3 decision buckets:** A (T3/T4, auto-engage, no brainstorming gate) / B (non-T3/T4, runbook brainstorming sub-step) / C (T1/T2/T5, surface `peaks session 24h-mode transition --state USER_CONFIRM`).
 
-→ see `references/anchoring-and-session-info.md` for the full Step 0 contract + session-conflict resolution.
+**Integration surfaces:** `peaks code run --24h` / `peaks dashboard long-run --since 24h` / `peaks session 24h-mode state|transition|attempts|reset`.
 
-#### Step 0 bypass — Claude Code [Fact-Forcing Gate] (slice 2.0.1-bug3)
+**Red lines (peaks-code side):**
+- No auto-compact prose ban: never write "ask the user to compact" / "prompt the user to run `/compact`" / "the user should run `peaks compact auto` manually" / "the user is responsible for context management" / legacy 50/75/90 percent tiers. **0.85 / 0.95 contract is mandatory.**
+- SquabbyZ sole-author rule: no `Co-Authored-By: Claude/Anthropic` trailer.
+- 24h mode is a flag on `peaks-code`; MUST NOT introduce a sibling `peaks-24h` skill or competing top-level verb.
 
-`peaks workspace init` materializes `.claude/settings.local.json` (a PreToolUse hook allow-list for `.peaks/**` paths and `peaks <subcommand>` Bash) so the [Fact-Forcing Gate] does not block Step 0. Pass `--no-claude-hooks` to opt out.
+## 24h mode spill/hydrate (opt-in experimental, rid-032)
 
-→ see `references/anchoring-and-session-info.md` for the full bypass contract, recovery flow, and anti-bail-out rule.
+When 24h mode is active and an in-flight sub-agent batch is detected, the LLM MAY persist its current turn context to disk through the `session spill-demo` helper. Creates a `SpillRecord` in `.peaks/_runtime/<sessionId>/spill/`. Round-trip is idempotent; existing in-flight deferral still works without spill/hydrate. **Opt-in experimental** — not required.
 
-### Peaks-Loop Step 0.7: Detect unfinished work and offer resume (BLOCKING on first invocation per session)
+## Peaks-Loop Superpowers 协作边界 (BRIDGE — MANDATORY, effective 2026-07-24)
 
-After Step 0, run the resume-detection probe; surface via `AskUserQuestion` if a slice is in flight. **v3.1.2 resume rule:** if `.peaks/_runtime/<sessionId>/job/<jid>/progress.json` exists, read FIRST and surface `Next: slice #N of M`. **v2.11.0 D7 override:** if user just `/compact`ed, run `peaks code post-compact-detect --project <repo> --json` FIRST; `shouldAutoResume: true` skips AskUserQuestion. → `references/resume-detection.md`.
+Pins the boundary between `peaks-code` and the **superpowers** skill family (`brainstorming`, `writing-plans`, `executing-plans`, `subagent-driven-development`, `dispatching-parallel-agents`, `verification-before-completion`, `test-driven-development`, `systematic-debugging`, `requesting-code-review`, `receiving-code-review`, `using-superpowers`, `using-git-worktrees`, `finishing-a-development-branch`). Closed under slice 2026-07-24-peaks-code-bridge-002-rootcause.
 
-### Peaks-Loop Step 0.55: 1.x → 2.0 detection (BLOCKING on first invocation per session, when the project is not on a 2.0 layout)
+- superpowers skills are **reference material**, not workflows peaks-code runs. They may NOT auto-replace peaks-rd, peaks-qa, peaks-ui, peaks-sc, or peaks-txt.
+- When `superpowers:brainstorming` or `superpowers:writing-plans` is suggested, peaks-code MUST: (1) run as a **reference** to seed its own PRD/RD artefacts, (2) re-author as a peaks-rd PRD under `.peaks/_runtime/<sessionId>/rd/requests/<rid>.md`, (3) continue peaks-code's 11-step sequence from Step 3 — never the superpowers plan execution.
+- `superpowers:writing-plans` / `superpowers:executing-plans` are **NOT** dispatched directly. peaks-rd is the only authoritative planner/executor pair.
+- Any peaks-managed hook entry emitted by `peaks hooks install` MUST originate from `src/services/hooks/*.sh` in the peaks-loop repo. LLM-improvised hook scripts are forbidden (001-bridge root cause).
+- Before any LLM edit to `~/.claude/skills/<skill>/*`, verify the path is a junction (`fsutil reparsepoint query` on Windows / `readlink` on POSIX). If it is a real directory, STOP and re-route via `peaks skill sync` after a junction rebuild — never write to a real directory (would pollute the npm sync chain).
+- Mandatory closure: every peaks-code request MUST finish `peaks request transition` through `spec-locked → implemented → qa-handoff → handed-off` plus `peaks memory extract`. Half-finished state files are treated as pollution and the LLM MUST NOT exit without a transition note.
 
-After Step 0.7 returns "fresh", run `peaks upgrade --detect-1x --project <root> --json`. If `isOneX: true`, surface `AskUserQuestion`. → `references/step-0-55-1x-detection.md`.
+**Self-check (read before any tool call):** *Is the tool I am about to call a superpowers auto-runner, or a peaks-rd / peaks-qa sub-agent dispatch?* If it would short-circuit peaks-rd, STOP and dispatch via `peaks sub-agent dispatch rd`.
 
-### Peaks-Loop Step 0.8 — Job 启动 (BLOCKING on LLM judgement — v3.1.1 patch + v3.1.2 mechanical gates)
+## Worktree governance (3-layer design, locked 2026-07-29)
 
-> **CLI reality check (D-001 sediment, 2026-07-09):** The CLI surface has changed since this section was last verified. The actual command is **`peaks job init --job-id <jid> --slice-list <list> --main-loop-strategy <single|rotating> [--parallelism-hint <serial|llm-decides>] [--exit-policy <strict|best-effort>] [--project <repo>]`**. The legacy `peaks code detect-job --is-job/--suggested-job-id/--confidence` form described below is **no longer present** in 4.0.0-beta.6. If you find `--is-job` rejected, fall back to `peaks job init`.
+> **npm-contract boundary.** Editing this file in `peaks-loop` source propagates to every consumer project on `npm install`. The 3-layer design is binding; downstream projects MAY extend Layer 2 with their own `peaks worktree auth grant` reasons but MUST NOT widen Layer 3's deny list outside the upstream `SUPERPOWERS_DENIED_SKILLS` constant. Full design, sub-agent contract, operator runbook → `references/worktree-governance.md`.
 
-The CLI is a **recorder + gate** for job-shape (the LLM judges). LLM calls `peaks job init --job-id <jid> --slice-list <list> --main-loop-strategy <single|rotating>` (with `--caller-id <id>` and `--project <repo>` in non-Claude-Code environments), which writes `.peaks/_runtime/<sessionId>/job/<jid>/state.json` and emits a `[job-event] {kind: job-started, jobId, total, strategy}` line. Downstream steps call `peaks job status --job-id <jid>` to read state.
+- **L1 — sub-agent system prompt** (`MUST NOT` on superpowers chain in dispatch templates; weakest, prose-only).
+- **L2 — hook + lifecycle gate** (`peaks hooks install` → `peaks gate enforce` → `evaluateWorktreeAuth`; 5 deny codes `REQUIRED / EXPIRED / REQUEST_MISMATCH / CONSUMED / FILE_INVALID`).
+- **L3 — IDE `permissions.deny`** (Claude Code refuses Skill BEFORE LLM sees it; strongest layer).
 
-**Hard rule (v3.1.1 red-line #10):** LLM MUST NOT skip the job-init call. If `peaks job status` reports `done: 0` and the slice work has begun, the LLM forgot to initialize — re-call `peaks job init` immediately.
+Sub-agents MUST NOT use raw `git worktree add`. The only authorized path is `peaks worktree spawn --rid <rid> --ttl <duration> --purpose <text>` (fall back to L2 hook gate + manual `peaks worktree auth grant` until rid-L2-extended ships). Sub-agents MUST write artifacts under `.peaks/_runtime/<sessionId>/<role>/requests/` in MAIN (`--project .`), not in a worktree. See `references/worktree-governance.md`.
 
-> **D-003 sediment (2026-07-09):** The historical `JOB_SHAPE_NOT_DECIDED` exception thrown by `read-job-shape` is no longer wired in 4.0.0-beta.6. The current CLI uses `peaks job status` which reports a passive `done: 0` instead of throwing. Both behaviors enforce the same intent (no work may begin before init) but the failure mode is a soft warning rather than a hard exception. LLM should treat `done: 0` after Step 0.8 as a recoverable miss, not an unrecoverable error.
-
-**v3.1.2 mechanical gates** (recorder-only was bypassed twice):
-
-PreToolUse hook on `peaks code gate-step-08`; size-fear ban on `peaks code emit-handoff`; forced auto-compact at ≥ 0.85 in Job mode; on-disk slice progress via `peaks job checkpoint` (canonical reader `peaks job progress --job-id <jid>`). Full mechanics (judgement criteria, hook table, backup-regex rationale, hook wiring) at `references/step-0-8-gate.md`.
-
-### Peaks-Loop Step 0.81 — per-slice 收尾
-
-After commit: `peaks job checkpoint --slice-id <rid> --state done --commit-sha $(git rev-parse HEAD)` → `peaks job status` → loop (remaining>0 → Step 1; ==0 → Step 8/9/10/11; blocked → Step 0.85).
-
-### Peaks-Loop Step 0.85 — slice 阻塞处理
-
-Trigger: `repair-status` atCap=true, context-now red-line ≥5min, or `subagent-cleanup` fails twice. Action: `peaks job block --slice-id <rid> --reason "<reason>"` then STOP.
-
-### Peaks-Loop Step 0.86 — main session rotation
-
-Active in rotating mode; fires every `rotateEvery` slices or via `peaks job rotate-now`. Sequence: cycle-summary → checkpoint rotate-marker → `peaks session rotate` → resume via `peaks session resume --job-id <jid>`.
-
-### Peaks-Loop Step 0.87 — sub-agent cleanup gate
-
-After every `peaks sub-agent dispatch --batch-id <id>` inside a Job, BEFORE next slice checkpoint: `peaks job subagent-cleanup --job-id <jid> --batch-id <id> --force`. Non-zero → block.
+## Peaks-Loop Startup sequence (MANDATORY — execute in order)
 
-→ see `references/job-loop.md` for state machine, visibility, rotation cadence, cross-day recovery, 9 red lines.
+Full content extracted to **`references/startup-sequence.md`** (Steps 0 / 0.5-0.87 / 1 / 2 / 2.3 / 2.5 / N / N+1 / N+2 + sub-agent sharing + boundaries). Read that file in full at session start; the sequence is MANDATORY.
 
-### Peaks-Loop Step 1: Mode selection
+## Peaks-Loop Step 0.8 — Job-shape detection (BLOCKING on LLM judgement)
 
-Use `AskUserQuestion` with `Full auto (Recommended)` first when user did not name a profile OR skill presence is stale (run `peaks skill presence:check-stale --project <path> --json` first; `stale: true` ⇒ re-ask). → `references/mode-selection.md`, `references/fast-mode.md`, `references/mode-selection-with-stale-presence.md`.
+> **BLOCKING on LLM judgement.** Before Step 1 mode selection, Code MUST surface a Job-shape decision via `peaks code detect-job` and persist it to `.peaks/_runtime/<sessionId>/job-shape.json`. The CLI is a recorder + gate — the LLM makes the judgement; downstream steps call `read-job-shape` and refuse if missing. See `references/step-0-8-gate.md` for the full contract. Skipping `peaks code detect-job` blocks the workflow at the next `read-job-shape` call (`JOB_SHAPE_NOT_DECIDED`).
 
-### Peaks-Loop Step 2: Re-set skill presence with the chosen mode
+**v3.1.2 mechanical gates** (must be un-bypassable):
+1. **PreToolUse hook — `peaks code gate-step-08`.** Installed by `peaks workspace init` on the `Bash` matcher; checks `job-shape.json` presence + fail-closed backup regex. If `job-shape.json` AND `progress.json` exist, surfaces `Next: slice #N of M (<currentSlice>)` so the LLM cannot wake up cold.
+2. **Size-fear ban — `peaks code emit-handoff`.** Refuses to emit a final handoff while `remaining > 0` under Job mode. Pass `--force-under-job` only with explicit user approval.
+3. **On-disk slice progress — `peaks job progress`.** `peaks job checkpoint --state done` writes `progress.json`. `peaks job progress --job-id <jid> [--allow-missing]` is the canonical reader.
+4. **Forced auto-compact — `--enforce-job-mode`.** `peaks code context-now --enforce-job-mode` returns `action: 'auto-compact-now'` at ≥ 0.85. **Job mode at ≥ 0.85 is MANDATORY auto-compact** — Code MUST call `peaks compact auto --execute` without confirmation.
 
-Re-run `peaks skill presence:set peaks-code --mode <mode-value> --gate startup`. Install statusline on first run (`peaks statusline install`). → `references/skill-presence-and-title.md`.
+**Step 0.7 resume rule (read-FIRST):** on resume, `peaks code gate-step-08` reads `progress.json` first and surfaces `Next: slice #N of M (<currentSlice>)` so the orchestrator picks up at the right slice without re-reading the artifact tree.
 
-### Peaks-Loop Step 2.3: Load project memory (durable, LLM-authored memories)
+### Peaks-Loop Step N+2: Auto-compact at the warning line (v2.13.0 zero-pause contract)
 
-Run `peaks project memories --project <repo> --json` to read decisions / conventions / modules / rules / lessons from `.peaks/memory`. → `references/project-memory-loading.md`.
+> **Zero-pause contract.** When context usage crosses the pre-compact threshold, peaks-loop **automatically fires `peaks compact auto --execute` — the LLM does NOT prompt the user to run `/compact` manually**. Stale prose that says "ask the user to compact" silently stalls the workflow. The v2.13.0 contract makes auto-compact a system responsibility, not a user action.
 
-### Peaks-Loop Step 2.5: Set session title
+**Thresholds (v2.13.0, replacing legacy 50/75/90):**
 
-Extract a short title from the user's first request (8-20 Chinese chars or 4-10 English words). Run `peaks session title <sessionId> "<title>" --json`. Skip if a title is already set. → `references/skill-presence-and-title.md` (same file as Step 2). D-002: sid is positional, NOT `--session-id` flag (rejected with `error: unknown option`).
+| ratio zone | zone name | action |
+|---|---|---|
+| `< 0.85` | normal | skip — LLM keeps working |
+| `0.85 ≤ ratio < 0.95` | **pre-compact zone** | `peaks compact auto --execute` fires **automatically** (deferred only when in-flight sub-agent batch is running; fires the moment the batch lands). The LLM does not prompt the user. |
+| `ratio ≥ 0.95` | **red-line (Karpathy §4)** | synchronous gate — `peaks compact auto --execute` invoked immediately; `peaks code context-now` returns `action: 'red-line'` and refuses to advance until ratio drops below 0.85. **Karpathy §4 automatic exception** — LLM cannot opt out. |
 
-## Sub-agent session sharing (MANDATORY — one conversation = one sid)
+**Probe primitive (single source of truth):** `peaks code context-now --json`. Do NOT use `peaks context check --prompt-size` (deprecated, will silently under-report ratio). Returns `{ ratio, action: 'ok' | 'soft-warn' | 'auto-compact-now' | 'red-line' }` — Code reads `action` and dispatches `peaks compact auto --execute` on `auto-compact-now` or `red-line` without user confirmation.
 
-When peaks-code dispatches a sub-agent (peaks-rd, peaks-qa, peaks-ui, peaks-txt, peaks-sc), the prompt MUST include the parent's sid. The sub-agent MUST NOT call `peaks workspace init` (would orphan the parent's binding).
+**Enforcement layers (defense in depth):**
+1. `src/services/code/auto-compact-orchestrator.ts` — `evaluateAutoCompactDecision` default-returns `shouldCompact: true` for both `pre-compact` and `red-line`. Only deferral is `inFlightBatch.hasInFlightBatch` (D6.e); no LLM/human approval branch.
+2. `--enforce-job-mode` (v3.1.2) — Job mode elevates ≥0.85 to MANDATORY regardless of in-flight batch.
+3. `peaks code gate-step-08` (PreToolUse hook) — surfaces `auto-compact-now` on every Bash call when ratio is in the zone, so the LLM cannot wake up cold and forget.
+4. Karpathy §4 exception: `peaks compact auto --execute` is fired *by the orchestrator*, not by the user. If you find yourself about to write "ask the user to compact" / "prompt the user to run `/compact`", STOP — that is the regression.
 
-## Boundaries
+**Anti-pattern (DO NOT introduce):** any of these strings in skills/* or comments signals the zero-pause contract has been broken:
+- "ask the user to compact" / "prompt the user to run `/compact`" / "the user should run `peaks compact auto` manually" / "the user is responsible for context management" / legacy mid/seventy-five/ninety percent tiers (current is 0.85 / 0.95).
 
-Peaks-Loop Code may identify scenarios, recommend profiles, coordinate role skills via artifacts, coordinate project memory extraction, request user confirmation at risk/commit boundaries. MUST NOT silently install hooks / create agents / enable MCP / modify Claude settings / create GitHub repos / bypass role-skill artifacts. → `references/boundaries.md`.
+If the prose audit (`peaks audit red-lines`) flags any of the above, the slice is **blocked** until the prose is rewritten.
 
 ## CLI Drift Index (sediment 2026-07-09)
 
@@ -249,40 +230,4 @@ Three CLI primitives: `peaks sub-agent share / shared-read / await` (last-write-
 
 ## References
 
-Index of every `references/` file. Read on demand.
-
-| File | Coverage |
-|---|---|
-| `references/dag-orchestrator.md` | DAG-aware sub-agent dispatch. |
-| `references/a2a-artifact-mapping.md` | A2A artifact-path mapping. |
-| `references/anchoring-and-session-info.md` | Step 0 + session-conflict. |
-| `references/artifact-contracts.md` | Sub-agent handoff contracts. |
-| `references/boundaries.md` | Code's do / don't list. |
-| `references/browser-workflow.md` | Browser workflow (Playwright MCP). |
-| `references/codegraph-orchestration.md` | Codegraph role handoff. |
-| `references/command-migration.md` | Legacy command migration. |
-| `references/completion-handoff.md` | Completion handoff. |
-| `references/context-governance.md` | G7-G9 sub-agent thresholds. |
-| `references/external-references.md` | 3rd-party inventory + lifecycle. |
-| `references/external-skill-invocation.md` | External skill invocation. |
-| `references/existing-system-extraction.md` | Legacy project extraction. |
-| `references/frontend-only-mode.md` | Frontend-only mode + mocks. |
-| `references/gstack-integration.md` | GStack → Peaks mapping. |
-| `references/headroom-integration.md` | Headroom-ai compression. |
-| `references/local-artifact-workspace.md` | Workspace tree + root-prohibition. |
-| `references/micro-cycle.md` | RD micro-cycle + repair loop. |
-| `references/mode-selection.md` | Step 1 mode + `--mode`. |
-| `references/playwright-mcp-multi-terminal.md` | Multi-terminal Playwright MCP. |
-| `references/project-memory-loading.md` | Step 2.3 memories. |
-| `references/project-scan-checklist.md` | Pre-RD scan + template. |
-| `references/quality-gate-cheatsheet.md` | 5 CLI commands. |
-| `references/refactor-mode.md` | Refactor mode + red lines. |
-| `references/resume-detection.md` | Step 0.7 unfinished-work. |
-| `references/runbook.md` | End-to-end CLI sequence. |
-| `references/job-loop.md` | Step 0.8 / 0.81 / 0.85 / 0.86 / 0.87 deep-dive. |
-| `references/skill-presence-and-title.md` | Step 2 + Step 2.5. |
-| `references/standards-preflight.md` | Standards preflight. |
-| `references/sub-agent-dispatch.md` | IDE-agnostic dispatch. |
-| `references/swarm-dispatch-contract.md` | Swarm fan-out gate + shape. |
-| `references/workflow-gates-and-types.md` | Type classification + 7 gates. |
-| `references/workflow.md` | Workflow flow + transitions. |
+Index of every `references/` file. Read on demand. The 35 reference files are listed in `references/references-index.md` (auto-generated, kept outside the SKILL.md byte cap). Top-5 by usage: `runbook.md`, `sub-agent-dispatch.md`, `micro-cycle.md`, `worktree-governance.md`, `workflow-gates-and-types.md`.

package/skills/peaks-code/references/boundaries.md

@@ -18,4 +18,18 @@ Peaks-Loop Code must not silently:
 - create GitHub repositories;
 - bypass role-skill artifacts.
 
-Use the Peaks-Loop CLI for runtime side effects.
+Use the Peaks-Loop CLI for runtime side effects.
+
+## Superpowers red lines (effective 2026-07-24, slice 2026-07-24-peaks-code-bridge-002-rootcause)
+
+`peaks-code` coordinates with the **superpowers** skill family but never lets it override peaks-loop governance:
+
+- `superpowers:brainstorming` / `superpowers:writing-plans` — **reference only**. Output (brainstorm / plan) MUST be re-authored as a `peaks-rd` PRD/RD artefact under `.peaks/_runtime/<sessionId>/rd/requests/<rid>.md` before any peaks-code step continues. `superpowers:writing-plans` upstream SKILL.md is **not edited** (it is owned by superpowers and silently overwritten on `claude install skill superpowers:writing-plans`).
+- `superpowers:executing-plans` / `superpowers:subagent-driven-development` — **forbidden** as direct runners. peaks-rd is the only authoritative planner + executor pair in the peaks-loop governance surface. Dispatching either one to replace peaks-rd is a governance violation and the LLM MUST stop.
+- `superpowers:test-driven-development` / `superpowers:verification-before-completion` / `superpowers:systematic-debugging` — **reference only**. peaks-qa owns TDD, verification gates, and bug triage. The superpowers versions inform method selection; they are not dispatched in place of `peaks sub-agent dispatch qa`.
+- `superpowers:dispatching-parallel-agents` — superseded by `peaks sub-agent dispatch --from-dag` (peaks-loop DAG-aware fan-out). Use the peaks primitive.
+- `superpowers:using-git-worktrees` / `superpowers:using-superpowers` — informational. peaks-loop has its own workspace conventions (`.peaks/_runtime/<sessionId>/<role>/...` two-axis gitignored tree). Do not adopt superpowers' bare worktree conventions for peak-* work.
+- `superpowers:finishing-a-development-branch` — informational. peaks-loop finishes via `peaks request transition` + `peaks memory extract`.
+- `superpowers:requesting-code-review` / `superpowers:receiving-code-review` — informational. peaks-loop review channels are `peaks-reviewer` (v2.14.0 G4 third-party reviewer) + karpathy-reviewer (RD-side fanout) + karpathy-5way-fanout guard test.
+
+If a user explicitly asks for "the superpowers plan flow" inside a peaks-code request, the answer is: brainstorm/plan via superpowers as references, then re-author through `peaks sub-agent dispatch rd` and continue peaks-code's 11-step sequence from Step 3.

package/skills/peaks-code/references/cron-scheduler-deployment.md

@@ -0,0 +1,313 @@
+# peaks-cron-scheduler deployment guide
+
+> **Slice 2026-07-29-worktree-l2-extended Part 20.** Companion to
+> the scheduler implementation in
+> `src/cli/commands/cron-scheduler-commands.ts`. This file
+> ships the install recipe operators actually run.
+
+## What the scheduler does
+
+`peaks cron-scheduler` is a long-running background process
+that wakes up once per minute and runs any task in
+`.peaks/cron/schedule.json` whose `intervalMs` has elapsed
+since the last run. Built-in tasks include `lease-gc-daily`
+(24h interval; sweeps orphan worktree leases). See
+`peaks cron init` to bootstrap the schedule.
+
+## Quick start (manual)
+
+```sh
+# 1. Initialize the schedule (idempotent)
+peaks cron init --project .
+
+# 2. Start the scheduler as a detached background process
+peaks cron-scheduler start --project .
+
+# 3. Confirm it is alive
+peaks cron-scheduler status --project .
+
+# 4. Trigger a one-shot run if you need it
+peaks cron-scheduler run-once --project .
+
+# 5. Stop the scheduler (SIGTERM)
+peaks cron-scheduler stop --project .
+```
+
+The pid is written to `.peaks/cron/scheduler.pid` so
+`stop` and `status` can find the process without operator
+guesswork. If the pid file is stale, `stop` removes it
+unconditionally (the `isPidAlive` check filters dead entries).
+
+## Windows service install (NSSM)
+
+The scheduler is a normal CLI process. NSSM (the Non-Sucking
+Service Manager) is the recommended wrapper for running it
+as a real Windows service that auto-restarts on crash.
+
+```sh
+# 1. Download NSSM (https://nssm.cc/) and put nssm.exe on PATH.
+
+# 2. Install the service. NSSM is happy with node + script
+#    args, so the same call works on Windows + POSIX.
+nssm install peaks-cron-scheduler "C:\\Program Files\\nodejs\\node.exe" \
+  "C:\\Users\\<you>\\.claude\\skills\\peaks-loop\\bin\\peaks.js" \
+  "cron-scheduler" "start" "--project" "C:\\path\\to\\peaks-project"
+
+# 3. Set the working directory (NSSM inherits the install
+#    caller's cwd by default; that may not be the project).
+nssm set peaks-cron-scheduler AppDirectory "C:\\path\\to\\peaks-project"
+
+# 4. Set environment variables (if needed for proxies / mirrors).
+nssm set peaks-cron-scheduler AppEnvironmentExtra "PEAKS_HOME=C:\\Users\\<you>\\.peaks"
+
+# 5. Configure auto-restart on crash.
+nssm set peaks-cron-scheduler AppExit Default Restart
+nssm set peaks-cron-scheduler AppRestartDelay 5000
+
+# 6. Start the service.
+nssm start peaks-cron-scheduler
+
+# 7. Verify.
+nssm status peaks-cron-scheduler
+peaks cron-scheduler status --project .
+```
+
+The same NSSM recipe works on POSIX (use `nssm` from your
+distro's package manager) — NSSM runs the same commands on
+both Windows and Linux. The pid-file pattern is the same.
+
+## Logs
+
+`peaks-cron-scheduler.js` writes to its own stdout/stderr;
+NSSM captures them to the Windows Event Log when the
+service is running. For a debug session, run the scheduler
+in the foreground:
+
+```sh
+node bin/peaks.js cron-scheduler start --project .  # will not detach; use a tmux/foreground
+```
+
+(This is not the production path — the production path is
+`peaks cron-scheduler start` which uses detached spawn and
+returns immediately. The detached flag means the parent can
+exit cleanly without the child.)
+
+## Troubleshooting
+
+- **"scheduler.pid stale"** — `stop` removes the pid file
+  unconditionally. Restart with `start`.
+- **"no lease lease lease-id"** — the schedule was created
+  with `peaks cron init` but the user's `.peaks/cron/` is
+  read-only. Check filesystem permissions.
+- **"docker not found"** — the scheduler runs shell commands
+  via `execSync`. If a task is `docker rm --force ...` and
+  docker is missing, the task fails (the scheduler does not
+  crash — it logs and continues to the next tick).
+
+## When NOT to use this scheduler
+
+- **Production with strict timing** — peaks-cron is a
+  best-effort CLI scheduler, not a real cron daemon. For
+  mission-critical periodic work, use the OS cron / systemd
+  timer / Windows Task Scheduler to invoke
+  `peaks cron-scheduler run-once --project .` on a precise
+  interval. The OS scheduler is reliable; the in-process
+  scheduler is portable.
+- **Multi-tenant** — peaks-cron runs all tasks in the
+  schedule.json in a single process. If two users have
+  conflicting lease-gc schedules, the in-process scheduler
+  will collide. The OS scheduler + per-tenant
+  `peaks cron-scheduler run-once` is the right shape.
+
+## Source pointer
+
+The CLI surface lives in
+`src/cli/commands/cron-scheduler-commands.ts`. The pure
+`runSchedulerLoop` function is the async loop; `start` /
+`stop` / `status` are thin shells around pid-file
+management.
+
+---
+
+# Appendix A — NSSM (Non-Sucking Service Manager) detailed install
+
+> **Slice 2026-07-29-rid-prose-only-sweep Part 39.** This
+> appendix is the operator-focused, step-by-step NSSM install
+> recipe for `peaks-cron-scheduler` on Windows. NSSM wraps any
+> long-running process as a real Windows service that starts at
+> boot, restarts on crash, and writes to the Windows Event Log.
+
+## Why NSSM (not Windows Task Scheduler)
+
+Windows Task Scheduler can run `peaks-cron-scheduler start`
+on a schedule, but it does not manage the long-running process:
+if `node` crashes, Task Scheduler will not restart it until
+the next trigger. NSSM (and node-windows, a Node-native
+alternative) treat the process as a service with auto-restart.
+
+## Install NSSM
+
+Download NSSM from <https://nssm.cc/> (the official site
+hosts the binary). NSSM is a single `nssm.exe` (~50 KB); put
+it on PATH (e.g. `C:\Windows\System32` or a custom dir).
+
+For a 64-bit Windows host, NSSM ships 32-bit and 64-bit
+binaries in the same zip — use `win64\nssm.exe`. The 32-bit
+binary works for 32-bit services; the 64-bit binary is the
+default for modern systems.
+
+```sh
+# Verify NSSM is on PATH and reports its version
+nssm version
+# NSSM 2.24, 64-bit
+```
+
+If `nssm` is not on PATH, the install will fail with
+`'nssm' is not recognized`. The peaks-cron-scheduler NSSM
+install does not put NSSM on PATH for the operator; it
+expects NSSM to be installed first.
+
+## Install the service
+
+```sh
+# 1. Install the service. NSSM is happy with `node` + script
+#    args, so the same call works on Windows + POSIX.
+nssm install peaks-cron-scheduler "C:\Program Files\nodejs\node.exe" \
+  "C:\Users\<you>\.claude\skills\peaks-loop\bin\peaks.js" \
+  "cron-scheduler" "start" "--project" "C:\path\to\peaks-project"
+
+# 2. Set the working directory (NSSM inherits the install
+#    caller's cwd by default; that may not be the project).
+nssm set peaks-cron-scheduler AppDirectory "C:\path\to\peaks-project"
+
+# 3. Set environment variables (if needed for proxies / mirrors).
+nssm set peaks-cron-scheduler AppEnvironmentExtra "PEAKS_HOME=C:\Users\<you>\.peaks"
+
+# 4. Configure auto-restart on crash.
+nssm set peaks-cron-scheduler AppExit Default Restart
+nssm set peaks-cron-scheduler AppRestartDelay 5000
+
+# 5. Set log file paths (NSSM redirects stdout/stderr).
+nssm set peaks-cron-scheduler AppStdoutCreationDisposition 4   # OPEN_ALWAYS
+nssm set peaks-cron-scheduler AppStderrCreationDisposition 4
+nssm set peaks-cron-scheduler AppStdout "C:\path\to\logs\peaks-cron-scheduler.out.log"
+nssm set peaks-cron-scheduler AppStderr "C:\path\to\logs\peaks-cron-scheduler.err.log"
+nssm set peaks-cron-scheduler AppRotateFiles 1                   # rotate on size
+nssm set peaks-cron-scheduler AppRotateBytes 10485760              # 10 MB per file
+
+# 6. Start the service.
+nssm start peaks-cron-scheduler
+```
+
+The same NSSM recipe works on POSIX (use `nssm` from your
+distro's package manager) — NSSM runs the same commands on
+both Windows and Linux. The pid-file pattern is the same.
+
+## Verify
+
+```sh
+# 1. NSSM-level status
+nssm status peaks-cron-scheduler
+# SERVICE_RUNNING
+
+# 2. peaks-level status (peaks-cli reads the pid file)
+peaks cron-scheduler status --project C:\path\to\peaks-project
+# {
+#   "data": {
+#     "alive": true,
+#     "pid": 12345,
+#     "scheduleEntries": 1,
+#     "dueTaskCount": 0
+#   }
+# }
+
+# 3. Force a one-shot to verify the schedule is reachable
+peaks cron-scheduler run-once --project C:\path\to\peaks-project
+# {
+#   "data": {
+#     "ran": 1,
+#     "records": [{ ... }]
+#   }
+# }
+```
+
+If `nssm status` reports `SERVICE_STOPPED`, the service
+crashed on startup. Check the log file at
+`<AppStderr>` (typically `C:\path\to\logs\peaks-cron-scheduler.err.log`).
+The most common cause is `nssm` not finding the node binary
+at `<AppStdout>` — verify with
+`nssm get peaks-cron-scheduler AppStdout` + `AppParameters`.
+
+## Uninstall
+
+```sh
+# 1. Stop the service
+nssm stop peaks-cron-scheduler
+
+# 2. Remove the service registration
+nssm remove peaks-cron-scheduler confirm
+
+# 3. (Optional) Remove the log files
+rm "C:\path\to\logs\peaks-cron-scheduler.out.log"
+rm "C:\path\to\logs\peaks-cron-scheduler.err.log"
+
+# 4. (Optional) Remove the cron-schedule state
+#    Note: the peaks-cli schedule lives under .peaks/cron/ and
+#    is NOT in NSSM. Removing NSSM does not affect the schedule.
+peaks cron list --project C:\path\to\peaks-project
+```
+
+If the service refuses to stop, escalate:
+`taskkill /F /IM node.exe /FI "WINDOWTITLE eq peaks-cron-scheduler*"`
+or `nssm set peaks-cron-scheduler AppStopMethodSkip 0` to
+force NSSM to honor `Ctrl+C` instead of `WM_CLOSE`.
+
+## Troubleshooting
+
+- **"nssm: command not found"** — NSSM is not on PATH.
+  Install it (see `Install NSSM` above) and re-run the
+  `nssm install` command.
+- **"SERVICE_PAUSED" on startup** — Windows Defender or
+  another AV is blocking the binary. Add the node binary
+  to the AV exclusion list or sign the peaks-cli install.
+- **Service runs but no log lines** — the AppStdout path is
+  wrong, or the directory is not writable. NSSM needs the
+  AppStderr file's parent directory to exist before
+  service start. `mkdir -p` the log dir before
+  `nssm start`.
+- **Auto-restart not firing** — `AppExit Default Restart`
+  is set, but Windows also has a per-process recovery
+  policy (`sc failure` for native services). For NSSM,
+  `AppRestartDelay` is in milliseconds; 5000 is the
+  default. 0 means "restart immediately", which can cause
+  a crash loop if the underlying issue is fatal.
+- **Schedule has tasks but they don't fire** — verify
+  the schedule file is reachable by the service user
+  (the user the service runs as, not your interactive
+  user). `peaks cron list` from the interactive shell
+  may show entries that the service user cannot see
+  (different HOME / different `PEAKS_HOME` env).
+
+## Production checklist
+
+- [ ] NSSM installed on PATH
+- [ ] Node.js installed at the path NSSM is configured for
+- [ ] peaks-loop installed at the path NSSM is configured for
+- [ ] Project root has a populated `.peaks/cron/schedule.json`
+      (run `peaks cron init` from the project dir first)
+- [ ] Log directory exists and is writable by the service user
+- [ ] `nssm status peaks-cron-scheduler` reports `SERVICE_RUNNING`
+- [ ] `peaks cron-scheduler status` reports `alive: true`
+- [ ] `peaks cron-scheduler run-once` runs the lease-gc-daily
+      task without error
+- [ ] Service survives a reboot (`shutdown /r` then
+      `nssm status peaks-cron-scheduler`)
+
+## Related memory
+
+- [[2026-07-29-worktree-l2-extended-part15]] — peaks-cron
+  init / list / run / peaks-cron-scheduler start (Part 15)
+- [[2026-07-29-worktree-l2-extended-part20]] — first pass
+  NSSM recipe (Part 20)
+- [[2026-07-29-worktree-l2-extended-part14]] — peaks-cron
+  schedule.json shape + built-in `lease-gc-daily` task

package/skills/peaks-code/references/external-skill-invocation.md

@@ -70,3 +70,30 @@ When a skill body adds a new external reference, it must include the equivalent
 3. add the capability discovery clause, the reference-only qualifier, the do-not-execute clause, and the Peaks-authoritative gate to that section;
 4. for MCP servers, point the LLM at the tool-list self-check (its own `mcp__<server>__*` namespace) instead of describing manual `~/.claude/settings.json` edits;
 5. rerun the audit.
+
+## Superpowers transition contract (effective 2026-07-24, slice 2026-07-24-peaks-code-bridge-002-rootcause)
+
+`peaks-code` cooperates with the **superpowers** skill family under the following contract. This contract sits alongside Stage 1–3 above and is binding on every peaks-code dispatch.
+
+### Trigger
+
+When the user (or the active IDE skill picker) suggests invoking `superpowers:brainstorming`, `superpowers:writing-plans`, `superpowers:executing-plans`, or any other superpowers skill during a peaks-code request, the LLM MUST apply the transition steps below before continuing the peaks-code 11-step sequence.
+
+### Transition steps (binding)
+
+1. **Discovery** — confirm the superpowers skill is present via the LLM's own tool list / `peaks capabilities --source access-repo --json`. If absent, surface the install command (`claude install skill superpowers:<skill>`) and stop until the user installs.
+2. **Reference-only invocation** — invoke the superpowers skill as **reference material**. The output (a brainstorming map, a plan, a TDD recipe, etc.) is read; it is not executed as the workflow body. Quote the methods/surfaces the peaks-rd plan borrows; never persist or "execute" the superpowers output verbatim.
+3. **Re-author through peaks-rd** — re-author the borrowed plan as a peaks-rd artefact at `.peaks/_runtime/<sessionId>/rd/requests/<rid>.md`. peaks-rd owns the slice contract, the rollback plan, and the test plan. The superpowers output may inform the prose; it does not replace the peaks-rd envelope.
+4. **Continue peaks-code** — from Step 3 (sub-agent fan-out) onward. Do NOT call `superpowers:executing-plans` or `superpowers:subagent-driven-development` to run the resulting plan; use `peaks sub-agent dispatch rd` / `peaks sub-agent dispatch qa` instead.
+5. **Do not edit upstream** — the `superpowers:writing-plans` and `superpowers:brainstorming` upstream SKILL.md files are owned by the superpowers npm/Claude-Code skill distribution. Any direct edit is silently overwritten on the next `claude install skill superpowers:<skill>` refresh. If a user-facing bridge is needed, place it in `peaks-code/SKILL.md` (BRIDGE chapter), `peaks-code/references/runbook.md` (Step 2.7), `peaks-code/references/boundaries.md` (superpowers red lines), and this file (transition contract).
+6. **Mandatory closure** — when the request is complete, run `peaks request transition` through `spec-locked → implemented → qa-handoff → handed-off` and `peaks memory extract`. A half-finished state file under `.peaks/_runtime/<sessionId>/` is treated as pollution.
+
+### What peaks-code MUST NOT do
+
+- Dispatch `superpowers:executing-plans` or `superpowers:subagent-driven-development` to replace peaks-rd or peaks-qa.
+- Adopt superpowers' bare worktree convention (`~/.claude/worktrees/<branch>/`) inside peaks-code requests; peaks-loop uses `.peaks/_runtime/<sessionId>/<role>/...` (gitignored) and the active junction at `~/.claude/skills/peaks-*`.
+- Hand-author hook scripts at `~/.claude/skills/peaks-code/hooks/*`. Hook source MUST come from `src/services/hooks/*.sh` in the peaks-loop repo, distributed via `peaks hooks install` (which itself respects the existing `peaks gate enforce` entry and is append-only).
+
+### Phrase the audit looks for
+
+When a peaks-code skill body mentions a superpowers skill by name, the body MUST include all four: a "reference only" qualifier, a "do not auto-run" clause, a "re-author through peaks-rd" clause, and a "Peaks artefacts remain authoritative" clause. The `tests/unit/skills/peaks-code-superpowers-bridge.test.ts` guard test enforces this on every peaks-* SKILL.md.