peaks-loop 4.0.0-beta.9 → 4.0.1

package/skills/bee/peaks-security-audit/SKILL.md

@@ -1,5 +1,6 @@
 ---
 name: peaks-security-audit
+visibility: internal
 description: Independent security audit skill. Reads the immutable peaks-prd handoff + the project-level security-template.md, performs an OWASP Top-10 + 8-dimension threat model audit, and writes a structured envelope to `.peaks/_runtime/<sessionId>/audit/security-<rid>.md`. Decoupled from peaks-rd 5-way fan-out per slice v2.12.0 (Group A, Tier 2). Use when the slice introduces authn/authz, secrets, input validation, path/filesystem trust, SQL/NoSQL injection, XSS/content injection, dependency supply chain, or external API surface changes.
 metadata:
   appliesTo: peaks-loop v2.12.0+
@@ -165,3 +166,19 @@ The `peaks-rd` aggregator picks up the artifact from
   template, or the diff under audit. It only writes a new audit artifact.
 - **#4 Goal-Driven Execution** — every audit output references a
   verifiable handoff goal via the `handoffHash` field.
+
+## L2 surface reference (post rid-l2-extended)
+
+For slices that touch the L2 surface, the canonical CLIs are:
+- `peaks worktree {spawn,renew,list,gc,lease-status,release}` — lease lifecycle (Part 1-2)
+- `peaks sub-agent dispatch --isolation worktree|container` — auto-spawns a lease (Part 2.C + Part 8 contract)
+- `peaks container {spawn,release}` — L4 container runtime (Part 12, docker)
+- `peaks lease-metrics [--rate] [--all-sessions]` — per-kind counts + leak rate (Part 4-5)
+- `peaks lease-stats` — project-wide summary (Part 6)
+- `peaks cron {init,list,run}` + `peaks cron-scheduler start` — periodic lease gc (Part 14-15)
+- `peaks audit red-lines --project .` — 119 catalog red-lines / 86+ cli-backed enforcers / 0 prose-only (Part 13)
+
+Verify the surface (no need to re-derive):
+1. `peaks audit red-lines --project .` reports `proseOnly: 0` for any shipped L2 surface.
+2. `peaks lease-metrics --rate` after a clean run reports `estimatedLeaked: 0`.
+3. `peaks worktree list` returns 0 active leases after a clean run.

package/skills/bee/peaks-txt/SKILL.md

@@ -307,3 +307,19 @@ The TXT handoff summarizes the slice by listing the artifact metas + the share e
 
 Same G9 threshold table. TXT handoff messages can grow large when the slice has many batches; use `--use-headroom` proactively for handoff prompts > 50%.
 
+
+## L2 surface reference (post rid-l2-extended)
+
+For slices that touch the L2 surface, the canonical CLIs are:
+- `peaks worktree {spawn,renew,list,gc,lease-status,release}` — lease lifecycle (Part 1-2)
+- `peaks sub-agent dispatch --isolation worktree|container` — auto-spawns a lease (Part 2.C + Part 8 contract)
+- `peaks container {spawn,release}` — L4 container runtime (Part 12, docker)
+- `peaks lease-metrics [--rate] [--all-sessions]` — per-kind counts + leak rate (Part 4-5)
+- `peaks lease-stats` — project-wide summary (Part 6)
+- `peaks cron {init,list,run}` + `peaks cron-scheduler start` — periodic lease gc (Part 14-15)
+- `peaks audit red-lines --project .` — 119 catalog red-lines / 86 cli-backed enforcers / 51 discovered (Part 13)
+
+Verify the surface (no need to re-derive):
+1. `peaks audit red-lines --project .` reports `proseOnly: 0` for any shipped L2 surface.
+2. `peaks lease-metrics --rate` after a clean run reports `estimatedLeaked: 0`.
+3. `peaks worktree list` returns 0 active leases after a clean run.

package/skills/bee/peaks-txt/test-prompts.json

@@ -0,0 +1,12 @@
+[
+  {
+    "id": 1,
+    "prompt": "本次 peaks-code 实战发现了 Feishu 登录、前端 mock 联调、浏览器可见 E2E 和本地 .peaks 产物的使用习惯，需要沉淀给后续 session。",
+    "expected": "Peaks TXT 在 .peaks/_runtime/<session-id>/txt/skill-usage-lessons.md 和 context-capsule.md 中记录规则、原因、影响技能、未来应用方式和是否适合 memory extraction，不保存 secrets、登录态、PII 或原始浏览器数据。"
+  },
+  {
+    "id": 2,
+    "prompt": "流程被打断，需要下个 session 接着做。",
+    "expected": "输出紧凑 capsule：模式、已验证决策、artifact paths、标准变更、开放问题、下一步，不复述完整日志。"
+  }
+]

package/skills/bee/peaks-ui/SKILL.md

@@ -130,12 +130,10 @@ peaks request show <request-id> --role prd --project <repo> --json   # read link
 
 # 2. ensure Playwright MCP is available for the visible browser check
 # Slice #016: peaks-loop no longer manages MCP install. The LLM checks
-# its own tool list for any Playwright MCP entry in the LLM tool list. If absent, the
-# LLM tells the user the install command (`claude mcp add playwright
+# its own tool list for any Playwright MCP entry. If absent, the LLM
+# tells the user the install command (`claude mcp add playwright
 # -- npx @playwright/mcp@latest` in Claude Code) and reports the gate
-# as blocked. Do NOT silently downgrade to screenshots-only, manual
-# steps, or other tools. Do NOT route through chrome-devtools-mcp as a
-# browser-launch substitute (it cannot launch a browser of its own).
+# as blocked. Do NOT silently downgrade or route through chrome-devtools-mcp.
 
 # 3. read project-scan for component library and CSS framework context
 #    check .peaks/project-scan/project-scan.md (blocking if missing for existing projects)
@@ -148,32 +146,24 @@ peaks request show <request-id> --role prd --project <repo> --json   # read link
 #    See "Prototype fidelity gate" section for the full decision tree.
 
 # 5. drive the running page or prototype through Claude Code MCP tools
-#    (the LLM invokes these directly from its tool list — no peaks-loop envelope)
-#    browser_navigate --args '{"url":"<url>"}'
-#    → URL (after allow-list check), launches headed browser
-#
+#    (the LLM invokes these directly — no peaks-loop envelope)
+#    browser_navigate --args '{"url":"<url>"}' → URL (after allow-list), launches headed browser
 #    LOGIN GATE: after browser_navigate, check for login/CAPTCHA/SSO/MFA redirect.
-#    If detected → visible browser is open; WAIT for user to complete login and
-#    explicitly confirm ("登录好了" or equivalent). Do NOT
-#    infer login from DOM. If user does not confirm → pause and ask.
-#
-#    After confirmation: browser_take_screenshot (filename), browser_snapshot (a11y tree),
+#    If detected → WAIT for user to complete login and explicitly confirm ("登录好了"
+#    or equivalent). Do NOT infer login from DOM. If user does not confirm → pause and ask.
+#    After confirmation: browser_take_screenshot, browser_snapshot (a11y tree),
 #    browser_console_messages (errors), browser_network_requests (failures), browser_close.
 # The skill body NEVER bakes in the Playwright MCP prefix; the LLM's runtime resolves the name.
 
 # 5. write design-draft artifact to .peaks/_runtime/<session-id>/ui/design-draft.md
 
 # 5.5 DESIGN-DRAFT CONFIRMATION GATE (MANDATORY):
-#      After writing the design-draft, present a summary to the user:
-#        - style direction and rationale
-#        - key design dials (variance, motion, density, palette)
-#        - component tree
-#        - anti-template items rejected
-#      Ask user to confirm before handing off to RD.
-#      In full-auto mode: if the design-draft passes the anti-template checklist
-#      and browser validation shows no regressions, auto-confirm.
-#      If browser validation was blocked (no Playwright MCP), always ask user
-#      to explicitly confirm the design-draft before proceeding.
+#      After writing the design-draft, present a summary (style direction, key design
+#      dials, component tree, anti-template items rejected) and ask user to confirm
+#      before handing off to RD. In full-auto mode: if the design-draft passes the
+#      anti-template checklist and browser validation shows no regressions, auto-confirm.
+#      If browser validation was blocked (no Playwright MCP), always ask user to
+#      explicitly confirm the design-draft before proceeding.
 
 # 6. record visual direction, rejected generic patterns, regression seeds in the request artifact
 
@@ -192,16 +182,13 @@ You cannot declare a phase complete from memory. Each gate below is a `ls` comma
 **Peaks-Loop Gate A — After design-draft write:**
 ```bash
 ls .peaks/_runtime/<sessionId>/ui/design-draft.md
-# Expected output: .peaks/_runtime/<sessionId>/ui/design-draft.md
-# "No such file" → STOP, write the design-draft first. Do not proceed to handoff.
+# Expected: .peaks/_runtime/<sessionId>/ui/design-draft.md
+# No such file → STOP, write the design-draft first. Do not proceed to handoff.
 
-# Peaks-Loop Gate A also requires an ASCII wireframe section with at least one fenced block.
+# Gate A also requires an ASCII wireframe section with at least one fenced block.
 grep -c "^## Layout (ASCII wireframe)" .peaks/_runtime/<sessionId>/ui/design-draft.md
-# Expected: >= 1. Zero → BLOCKED. The mandatory ASCII wireframe section is missing.
 grep -c '^```' .peaks/_runtime/<sessionId>/ui/design-draft.md
-# Expected: >= 2 (one or more fenced code blocks for ASCII wireframes).
-# Zero → BLOCKED. Prose-only layout description is not acceptable; add ASCII wireframes
-# for the main page and every meaningful modal/drawer/state.
+# Both >= 1. Zero in either → BLOCKED. Prose-only layout is not acceptable.
 ```
 
 **Peaks-Loop Gate B — Before handoff to RD:**
@@ -281,27 +268,21 @@ Before writing design-draft.md, verify:
 
 In full-auto frontend design with NO prototype (verified above), default to the curated taste path instead of generic component generation. External skills are optional enhancements, not prerequisites.
 
-**If a prototype exists, skip this section.** The prototype IS the design direction. Use the prototype fidelity gate checklist above instead.
+**If a prototype exists, skip this section.** The prototype IS the design direction.
 
 **Self-contained design process (always available):**
 
 1. choose a specific style direction: editorial, bento, Swiss, luxury, retro-futurist, glass, or product-specific system UI. Pick one that fits the product's tone — do not default to "clean minimal."
-2. define design dials with concrete values:
-   - variance: conservative (subtle radius/shadows) | moderate (mixed depths) | bold (asymmetric, overlapping)
-   - motion: minimal (opacity-only) | medium (transform+opacity) | rich (staggered, spring, scroll-triggered)
-   - density: sparse (generous whitespace) | comfortable (standard) | dense (data-heavy)
-   - typography: one display/heading + one body font from system or project stack
-   - palette: 5 tokens (primary, surface, text-primary, text-secondary, accent) in oklch()/hsl() with concrete values
-3. reject anti-patterns: centered stock heroes, default card grids, unmodified library defaults, AI purple-blue gradients, generic three-card feature rows, safe gray-on-white
-4. require 6 states per surface: loading (skeleton), empty (illustration+CTA), error (message+retry), hover, focus, active
-5. browser-check with Playwright MCP, wait for user confirmation after any login challenge, iterate until UI looks intentional
+2. define design dials: variance (conservative | moderate | bold) / motion (minimal | medium | rich) / density (sparse | comfortable | dense) / typography (one display + one body) / palette (5 tokens in oklch/hsl).
+3. reject anti-patterns: centered stock heroes, default card grids, unmodified library defaults, AI purple-blue gradients, generic three-card feature rows, safe gray-on-white.
+4. require 6 states per surface: loading, empty, error, hover, focus, active.
+5. browser-check with Playwright MCP, wait for user confirmation after any login challenge, iterate.
 
 **When external design skills ARE available** (confirm via `peaks capabilities --source access-repo --json` first, reference only):
-
 - `awesome-design-md`: layout composition, rhythm, atmosphere
 - `taste-skill` / `design-taste-frontend`: anti-template, typography, color, density, motion critique
 
-Full-auto Peaks-Loop UI output must include a short taste report: visual direction, references used, rejected generic patterns, browser observations, remaining design risks, and the next visual iteration if the page is not yet good enough.
+Full-auto output must include a short taste report: visual direction, references used, rejected generic patterns, browser observations, remaining design risks, and the next visual iteration if the page is not yet good enough.
 
 ## Mandatory design-draft output
 
@@ -360,6 +341,15 @@ UI sub-agents follow the same G7 metadata-only + G8.6 share protocol. UI artifac
 
 ### G8.6 — UI sub-agent prompt template
 
+**Superpowers chain refusal (L1 worktree governance — locked 2026-07-29):** you MUST NOT follow the superpowers chain for worktree decisions: `superpowers:brainstorming` → `superpowers:writing-plans` → `superpowers:subagent-driven-development` → `superpowers:using-git-worktrees`. The chain ends with `git worktree add` (superpowers:using-git-worktrees SKILL.md line 96) and bypasses peaks-loop's L2 hook gate and L3 IDE `permissions.deny`. Even when L3 denies the terminal Skill, the chain has already taught you to use raw `git worktree add`, so L3 is not sufficient.
+
+For worktree operations, use ONLY:
+
+- `peaks worktree spawn --rid <rid> --ttl <duration> --purpose <text>` (after rid-L2-extended ships)
+- until then: `peaks worktree auth grant --rid <id> --reason <text> --ttl <5m>`
+
+The superpowers skills remain available as REFERENCE material for brainstorming / planning techniques, but MUST NOT be used as a workflow. peaks-ui's own UI artifacts (`.peaks/_runtime/<sessionId>/ui/<artifact>.md`) are authoritative. Full design: `skills/peaks-code/references/worktree-governance.md`.
+
 ```
 You are sub-agent role ui, batch <batchId>.
 
@@ -373,3 +363,19 @@ PROTOCOL (mandatory):
 
 Same as RD/QA. Use `--use-headroom` proactively.
 
+
+## L2 surface reference (post rid-l2-extended)
+
+For slices that touch the L2 surface, the canonical CLIs are:
+- `peaks worktree {spawn,renew,list,gc,lease-status,release}` — lease lifecycle (Part 1-2)
+- `peaks sub-agent dispatch --isolation worktree|container` — auto-spawns a lease (Part 2.C + Part 8 contract)
+- `peaks container {spawn,release}` — L4 container runtime (Part 12, docker)
+- `peaks lease-metrics [--rate] [--all-sessions]` — per-kind counts + leak rate (Part 4-5)
+- `peaks lease-stats` — project-wide summary (Part 6)
+- `peaks cron {init,list,run}` + `peaks cron-scheduler start` — periodic lease gc (Part 14-15)
+- `peaks audit red-lines --project .` — 119 catalog red-lines / 86 cli-backed enforcers / 51 discovered (Part 13)
+
+Verify the surface (no need to re-derive):
+1. `peaks audit red-lines --project .` reports `proseOnly: 0` for any shipped L2 surface.
+2. `peaks lease-metrics --rate` after a clean run reports `estimatedLeaked: 0`.
+3. `peaks worktree list` returns 0 active leases after a clean run.

package/skills/bee/peaks-ui/test-prompts.json

@@ -0,0 +1,12 @@
+[
+  {
+    "id": 1,
+    "prompt": "根据产品文档做前端页面迭代，要求全自动模式下设计不要模板化，要比普通 Tailwind/shadcn 默认页更好看。",
+    "expected": "Peaks UI 走 awesome-design-md + taste-skill/design-taste-frontend 的参考和品味链路，先定义风格方向、字体、色彩、动效、密度和交互状态，避免默认卡片栅格、居中 hero、AI 紫蓝渐变，并用浏览器可见检查迭代。"
+  },
+  {
+    "id": 2,
+    "prompt": "前端实现已经完成，但页面看起来像默认模板。",
+    "expected": "Peaks UI 产出 taste report，指出弱层级、模板感、交互状态缺失、响应式问题，并退回设计/RD 迭代后再 QA。"
+  }
+]

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.