peaks-loop 4.0.0-beta.9 → 4.0.1

package/skills/peaks-code/references/peaks-worktree-l2-enforcers.md

@@ -0,0 +1,208 @@
+# peaks worktree L2 enforcers — reference
+
+> **Slice 2026-07-29-rid-prose-only-sweep Part 33.** Companion to
+> the L2 ecosystem shipped across 28 commits. The peaks
+> `peaks audit red-lines --project .` command reports 119
+> catalog red-lines, of which **86+ are cli-backed enforcers**
+> (the rest are discovered prose-only lines still being
+> sweeped). This document is the operator-side reference for
+> the L2 surface.
+
+## What is the L2 surface?
+
+The **L2 surface** is the worktree / dispatch / observability
+stack peaks-loop owns. Sub-agents touching any of the L2
+verbs (`peaks worktree *`, `peaks container *`,
+`peaks sub-agent dispatch --isolation <mode>`, `peaks lease-*`,
+`peaks cron*`, `peaks audit red-lines`) need to read this
+document to know which enforcers will run against them.
+
+## Why this document exists
+
+LLM-side runners (skills/peaks-code, peaks-rd, peaks-qa, etc.)
+read the prose-only catalog as guidance but historically
+under-estimated how strict the cli-backed enforcers are.
+Documenting the enforcer surface upfront prevents
+"discovered late in a cycle" surprises.
+
+## Enforcers by source
+
+### peaks-worktree authority (L2 grant + lease)
+
+- **`withSuperpowersSkillDenylist`** (src/services/skills/hooks-settings-service.ts)
+  Installs `UseSkill(superpowers:using-git-worktrees)` into
+  `permissions.deny`. Triggered by `peaks hooks install`.
+- **`withoutSuperpowersSkillDenylist`** — symmetric uninstall.
+- **`withTriggeredDenyList`** (Part 27 / 29) — appends
+  `Edit(deny-trigger:<phrase>)` when the existing settings
+  has superpowers / git-worktree / podman-run entries. LLM
+  must run `peaks hooks uninstall` to remove.
+- **`decideFromAuthorization`** (src/services/hooks/worktree-authorization-gate.ts)
+  Decides allow / deny for a worktree-mutating tool call
+  based on `peaks worktree auth grant` file contents.
+- **`decideFromLease`** (Part 2.B) — falls back to the lease
+  file when no grant is on file. Activated by
+  `PEAKS_WORKTREE_LEASE_ID` env var.
+- **`decideFromContainerLease`** (Part 19) — analogous to
+  `decideFromLease` for the L4 container surface.
+  Activated by `PEAKS_CONTAINER_LEASE_ID` env var.
+
+### L2 section structure (P2-a lint)
+
+- **`rl-section-hard-contracts-001`** (lint-style.ts) — peaks-*
+  bee SKILL.md must declare `## Hard contracts` section.
+- **`rl-section-mandatory-artifact-001`** — must declare
+  `## Mandatory per-request artifact` section.
+- **`rl-section-default-runbook-001`** — must declare
+  `## Default runbook` section.
+- **`rl-section-gate-index-001`** — must declare
+  `## RD gate index` / `## QA gate index` section.
+- **`rl-section-naming-axiom-001`** — single-scope-axis
+  naming convention.
+
+### L2 frontmatter (P2-a lint)
+
+- **`rl-frontmatter-skills-md-001`** — name / description
+  frontmatter on every SKILL.md.
+- **`rl-frontmatter-references-load-strategy-001`** —
+  loadStrategy field on references/*.md.
+- **`rl-frontmatter-applicable-task-levels-001`** —
+  applicableTaskLevels field on references/*.md.
+
+### L2 output style (P2-a lint)
+
+- **`rl-output-style-status-header-001`** — every peaks-*
+  response carries a `peaks-loop skill: | peaks-loop gate: |
+  peaks-loop next:` status header.
+- **`rl-output-style-no-fluff-001`** — no greeting / persona
+  fluff in SKILL.md.
+- **`rl-output-style-no-closing-prompt-001`** — no "Should I
+  continue?" closing prompt.
+
+### L2 reference integrity (P2-a lint)
+
+- **`rl-ref-path-resolves-001`** — every `references/*.md`
+  link in a SKILL.md resolves to a real file.
+- **`rl-ref-no-broken-mkdir-001`** — no `mkdir -p
+  nonexistent/dir` in references code blocks.
+- **`rl-ref-no-pwd-symlink-jumps-001`** — no pwd that
+  jumps symlinks.
+- **`rl-ref-no-relative-archive-paths-001`** — no relative
+  archive paths in references.
+
+### L2 OpenSpec
+
+- **`rl-openspec-proposal-has-ac-bullets-001`** — OpenSpec
+  proposal must have acceptance criteria bullets.
+- **`rl-openspec-proposal-has-spec-changes-001`** — OpenSpec
+  proposal must have spec changes.
+
+### L2 CLI back
+
+- **`rl-cli-back-mandatory-text-001`** — every CLI command's
+  `--help` text matches the canonical `mandatory` keyword.
+- **`rl-cli-back-no-orphan-blocking-001`** — every blocking
+  red line has a corresponding enforcer.
+- **`rl-cli-back-no-orphan-must-not-001`** — every MUST-NOT
+  red line has a corresponding enforcer.
+- **`rl-cli-back-prose-only-threshold-001`** — the
+  prose-only ratio stays ≤ 5% (per §10.2 L2 acceptance).
+- **`rl-cli-back-prose-only-ratio-001`** — secondary
+  threshold (7% per slice 2026-07-28).
+
+### L2 catalog governance
+
+- **`rl-catalog-total-le-45-001`** — the catalog size must
+  grow to ≥ 45 (P2-a target).
+- **`rl-catalog-prose-only-ratio-001`** — secondary 7%
+  threshold (post-reform).
+
+### L2 peaks-* bee runtime contracts (sweep 1-8)
+
+- **`rl-skill-presence-mandatory-001`** (sweep 003) —
+  peaks-* bee SKILL.md must declare the "Skill presence
+  (MANDATORY first action)" section.
+- **`rl-prd-source-snapshot-placement-001`** (sweep 004) —
+  peaks-prd SKILL.md must declare the source-snapshot
+  placement guidance + Prohibited paths.
+- **`rl-prd-artifact-handoff-001`** (sweep 004) — peaks-prd
+  SKILL.md must declare the artifact handoff contract
+  (Preserved behavior + step 5.5 + Transition verification
+  gates).
+- **`rl-rd-handoff-contract-001`** (sweep 005) — peaks-rd
+  SKILL.md must declare the QA-handoff BLOCKING contract
+  (tech-doc + perf-baseline).
+- **`rl-rd-coverage-discipline-001`** (sweep 005) —
+  peaks-rd SKILL.md must declare the coverage discipline
+  (100% target + no-padding rule).
+- **`rl-qa-gateguard-preflight-001`** (sweep 006) — peaks-qa
+  SKILL.md must declare the gateguard pre-flight BLOCKING
+  section.
+- **`rl-qa-runtime-contract-001`** (sweep 006) — peaks-qa
+  SKILL.md must declare the runtime contract (transition
+  gates + Playwright MCP fallback + OpenSpec integration).
+- **`rl-peaks-ui-superpowers-chain-001`** (sweep 007) —
+  peaks-ui SKILL.md must declare the superpowers chain
+  refusal + reference-material contract.
+- **`rl-peaks-ui-involvement-001`** (sweep 007) — peaks-ui
+  SKILL.md must declare the UI-involvement identification
+  block.
+- **`rl-peaks-txt-upstream-001`** (sweep 007) — peaks-txt
+  SKILL.md must declare the upstream-inspection +
+  memory-block contract.
+- **`rl-peaks-perf-audit-scope-001`** (sweep 007) —
+  peaks-perf-audit SKILL.md must declare the non-perf
+  MUST NOT invoke clause.
+- **`rl-peaks-rd-runtime-contract-001`** (sweep 008) —
+  peaks-rd SKILL.md must declare the runtime contract
+  (OpenSpec usage + Frontend project generation).
+- **`rl-peaks-ui-transition-gates-001`** (sweep 008) —
+  peaks-ui SKILL.md must declare the Transition verification
+  gates section.
+- **`rl-peaks-sc-transition-gates-001`** (sweep 008) —
+  peaks-sc SKILL.md must declare the Transition verification
+  gates section.
+- **`rl-peaks-txt-runtime-contract-001`** (sweep 008) —
+  peaks-txt SKILL.md must declare the runtime contract
+  (Transition verification gates + Memory block embedding
+  rule).
+
+## How to run
+
+```sh
+# Default — list every catalog red line.
+peaks audit red-lines --project .
+
+# Just the cli-backed ones (the L2 surface).
+peaks audit red-lines --project . --json | jq '.audit[] | select(.backing == "cli-backed")'
+```
+
+## How to read the report
+
+Each entry has:
+
+- `id` — the catalog id (e.g. `rl-skill-presence-mandatory-001`).
+- `rule` — the human-readable description of the contract.
+- `source.file` — the file the marker was found in.
+- `source.line` — the line number (1-indexed).
+- `source.marker` — MANDATORY / BLOCKING / MUST NOT / RED LINE.
+- `backing` — `cli-backed` (an enforcer file exists) or
+  `prose-only` (no enforcer; the line is documented in
+  skills/ and audited by humans).
+
+A red line that is `prose-only` is **not enforced** by
+peaks. The audit report's `proseOnly` count is the backlog
+that has not been closed yet.
+
+## Related memory
+
+- [[2026-07-29-worktree-l2-extended-part1]] — lease foundation
+- [[2026-07-29-worktree-l2-extended-part2]] — renew/list/gc/status + hook
+- [[2026-07-29-worktree-l2-extended-part3]] — auto-release
+- [[2026-07-29-worktree-l2-extended-part4]] — observability + v3
+- [[2026-07-29-worktree-l2-extended-part5]] — leak rate + cross-session
+- [[2026-07-29-worktree-l2-extended-part6-9]] — final sediment
+- [[2026-07-29-worktree-l1-dispatch-block]] — L1 dispatch hardening
+- [[2026-07-29-worktree-skills-md-shipped]] — SKILL.md npm contract
+- [[2026-07-29-worktree-layer3-deny]] — L3 superpowers deny
+- [[2026-07-27-worktree-user-auth-hard-gate]] — L2 grant token

package/skills/peaks-code/references/periodic-checkpoint.md

@@ -72,10 +72,10 @@ This step is strictly IDE-agnostic. The LLM calls the peaks CLI; no IDE-specific
 
 ## Companion surface — auto-compact (zero-pause)
 
-When the runner crosses the v2.13.0 auto-compact thresholds (0.85 pre-compact / 0.95 red-line), `peaks session checkpoint` is NOT enough on its own — the LLM must also fire `peaks code auto-compact --execute` (or wait for the in-band PreToolUse hook at ratio ≥ 0.95 to compact the runner itself). See:
+When the runner crosses the v2.13.0 auto-compact thresholds (0.85 pre-compact / 0.95 red-line), `peaks session checkpoint` is NOT enough on its own — the LLM must also fire `peaks compact auto --execute` (or wait for the in-band PreToolUse hook at ratio ≥ 0.95 to compact the runner itself). See:
 
-- `peaks code auto-compact --execute` — orchestrator that writes the convergence plan + dispatches the compact pathway
-- `peaks session auto-compact-hook` — the PreToolUse hook entrypoint fired by `.claude/settings.local.json` (slice 2026-07-02-auto-compact-zero-pause)
+- `peaks compact auto --execute` — orchestrator that writes the convergence plan + dispatches the compact pathway
+- `peaks compact auto` — the PreToolUse hook entrypoint fired by `.claude/settings.local.json` (slice 2026-07-02-auto-compact-zero-pause)
 - `.peaks/memory/2026-06-27-auto-compact-design.md` — zero-human-intervention design rationale
 
-The two surfaces compose: `peaks session checkpoint` persists the context state, `peaks code auto-compact` collapses the runner's window. The LLM fires both in the 0.85–0.95 zone; the hook fires alone at ≥ 0.95.
+The two surfaces compose: `peaks session checkpoint` persists the context state, `peaks compact auto` collapses the runner's window. The LLM fires both in the 0.85–0.95 zone; the hook fires alone at ≥ 0.95.

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

@@ -45,6 +45,18 @@ peaks standards init   --project <repo> --apply --json
 # or: peaks standards update --project <repo> --apply --json
 # After apply, verify the files actually exist on disk (see Peaks-Loop Gate G).
 
+# ── Step 1.x — `peaks --help` 路由速查(4.x 收敛后:73→9 字节恒等) ─────────
+#
+#   peaks --help
+#     ├─ doctor / code / skill / session / workflow   (5 super-command)
+#     ├─ make / learn / sop / sub-agent               (4 ops)
+#     └─ (其他 60+ top-level subcommand)
+#
+# 全 73 个原命令收敛到 9 个 super-command 后,surface 字节恒等;
+# 4 ops 路由分别管:动态造 skill / 沉淀学习 / SOP 注册 / sub-agent 派发。
+# 若 LLM 看到 peaks-code runbook 里出现老命令(>9 之外的 raw 名字),
+# 先 `peaks --help` 校验当前 surface,再决定改 runbook 还是改命令。
+
 # 2. Peaks-Loop PRD (Assisted/Strict: [CONFIRM] before confirmed-by-user)
 # Classify the request type from the PRD: feature | bugfix | refactor | docs | config | chore
 # This drives RD/QA gate strictness — see "Mandatory RD QA repair loop" for the matrix.
@@ -59,6 +71,25 @@ peaks request lint <rid> --role prd --project <repo> --json
 peaks request transition <rid> --role prd --state confirmed-by-user --project <repo> --json
 peaks request transition <rid> --role prd --state handed-off --project <repo> --json
 
+# 2.7. Peaks-Loop Superpowers bridge (effective 2026-07-24, slice 2026-07-24-peaks-code-bridge-002-rootcause)
+# Why: peaks-code must coexist with the superpowers skill family without being overridden by it.
+# When the user (or the IDE skill picker) suggests invoking superpowers:brainstorming /
+# superpowers:writing-plans, the LLM MUST:
+#   1. Run the superpowers skill as REFERENCE ONLY — read the brainstorm / plan output.
+#   2. Re-author the borrowed plan as a peaks-rd PRD artefact via:
+#        peaks sub-agent dispatch prd --prompt "<brainstorm-seed>" --request-id <rid> --batch-id <uuid> --json
+#   3. Continue peaks-code from Step 3 (sub-agent fan-out). Do NOT dispatch
+#      superpowers:executing-plans or superpowers:subagent-driven-development; peaks-rd / peaks-qa
+#      own plan execution.
+# Verify junction integrity before any LLM edit to a user-global skill path:
+#   fsutil reparsepoint query "$HOME/.claude/skills/peaks-code"   # Windows
+#   readlink -f "$HOME/.claude/skills/peaks-code"                 # POSIX
+# → not a junction (or not a symlink) → STOP and re-route via peaks skill sync after junction rebuild.
+# Forbidden: hand-authoring hook scripts at ~/.claude/skills/peaks-code/hooks/*. Hook source MUST
+# come from src/services/hooks/*.sh in the peaks-loop repo, distributed by `peaks hooks install`.
+# Mandatory closure: every peaks-code request MUST finish `peaks request transition` through
+# `spec-locked → implemented → qa-handoff → handed-off` plus `peaks memory extract`.
+
 # 3. Peaks-Loop Default sub-agent fan-out (slice 5 contract)
 #    Code computes the swarm plan from --type + frontendOnly + frontend-keyword scan,
 #    writes it to .peaks/_runtime/<sid>/sc/swarm-plan.json, then writes the slice
@@ -184,6 +215,28 @@ peaks project dashboard --project <repo> --json
 peaks skill doctor --json
 ```
 
+## 24h mode — bridge surface (rid-020b)
+
+```bash
+# Inspect the current 24h-mode state snapshot (rid-020a backbone)
+peaks session 24h-mode state --json
+
+# Code-run with the 24h flag (T3/T4 auto-engage; otherwise brainstorming reference-only bridge)
+peaks code run <change-id> --24h --tier T3 --project <repo> --json
+peaks code run <change-id> --24h --tier T2 --project <repo> --json   # non-T3/T4 → Bucket B (reference-only)
+peaks code run <change-id> --24h --trigger T4 --project <repo> --json # T4 also auto-engages 24H_ACTIVE
+
+# Read-only 24h long-run indicator dashboard (5 indicator classes + boundary cases)
+peaks dashboard long-run --since 24h --project <repo> --json
+peaks dashboard long-run --since 8h  --project <repo> --json
+peaks dashboard long-run --since 30m --project <repo> --json
+peaks dashboard long-run --since 72h --project <repo> --json   # capped at 24h
+
+# Manual state transition (Bucket C — user-confirm path)
+peaks session 24h-mode transition --state 24H_ACTIVE --reason "T1 keyword match" --project <repo> --json
+peaks session 24h-mode transition --state HANDOFF --exit-condition user_abort --project <repo> --json
+```
+
 Repair loop details: see `## Mandatory RD QA repair loop` in SKILL.md for the full 5-step procedure and the 3-cycle cap. Append transition notes via `--reason` rather than rewriting artifacts during repair cycles.
 
 ```bash
@@ -236,7 +289,7 @@ peaks code emit-handoff --project <repo> --job-id <jid> --json
 # job-shape.json says isJob=true, ≥0.85 is MANDATORY auto-compact.
 # Code MUST call this without confirmation under Job mode.
 peaks code context-now --project <repo> --enforce-job-mode --json
-peaks session auto-compact --execute --project <repo> --json
+peaks compact auto --execute --project <repo> --json
 
 # v3.1.2 PreToolUse gate (installed by `peaks workspace init`):
 # every Bash tool call runs `peaks code gate-step-08` automatically.
@@ -244,4 +297,13 @@ peaks session auto-compact --execute --project <repo> --json
 # progress.json exists). Exit 2 = BLOCKED; LLM must call
 # `peaks code detect-job` first.
 peaks code gate-step-08 --project <repo> --json
+
+# rid-020a: 24h mode state machine. The CLI is the muscle; peaks-code
+# is the LLM that drives it. Sub-actions: state, transition, attempts,
+# reset. Persists to .peaks/_runtime/<sessionId>/24h-state.json. The
+# full SKILL.md chapter and rid-020b code-run sub-command ship next.
+peaks session 24h-mode state --project <repo> --session-id <sessionId> --json
+peaks session 24h-mode transition --state 24H_ACTIVE --project <repo> --session-id <sessionId> --json
+peaks session 24h-mode attempts --project <repo> --session-id <sessionId> --json
+peaks session 24h-mode reset --project <repo> --session-id <sessionId> --json
 ```

package/skills/peaks-code/references/startup-sequence.md

@@ -0,0 +1,110 @@
+---
+name: peaks-code-startup-sequence
+description: peaks-code startup sequence Steps 0 / 0.5-0.87 / 1 / 2 / 2.3 / 2.5 / N / N+1 / N+2 — extracted from SKILL.md 2026-07-16 to keep SKILL.md under 25,000-byte cap
+---
+
+# Peaks-Loop Startup sequence (MANDATORY — execute in order)
+
+> **Extracted from SKILL.md on 2026-07-16.** This file is the
+> authoritative reference; SKILL.md points here with a 1-line pointer.
+> Do not edit `SKILL.md` for content changes — edit this file instead.
+
+### 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)
+
+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 compact auto --execute`). Pass `--enforce-job-mode` for single-rid. **≥ 0.95** red line: next Bash/Task fires `peaks compact auto`. **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).
+
+### Peaks-Loop Step 0: Anchor the workflow (MANDATORY FIRST ACTIONS — no bail-out)
+
+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.
+
+→ see `references/anchoring-and-session-info.md` for the full Step 0 contract + session-conflict resolution.
+
+#### Step 0 bypass — Claude Code [Fact-Forcing Gate] (slice 2.0.1-bug3)
+
+`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.
+
+→ see `references/anchoring-and-session-info.md` for the full bypass contract, recovery flow, and anti-bail-out rule.
+
+### Peaks-Loop Step 0.7: Detect unfinished work and offer resume (BLOCKING on first invocation per session)
+
+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`.
+
+### 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)
+
+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`.
+
+### Peaks-Loop Step 0.8 — Job 启动 (BLOCKING on LLM judgement — v3.1.1 patch + v3.1.2 mechanical gates)
+
+> **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`.
+
+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.
+
+**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.
+
+> **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.
+
+→ see `references/job-loop.md` for state machine, visibility, rotation cadence, cross-day recovery, 9 red lines.
+
+### Peaks-Loop Step 1: Mode selection
+
+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`.
+
+### Peaks-Loop Step 2: Re-set skill presence with the chosen mode
+
+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`.
+
+### Peaks-Loop Step 2.3: Load project memory (durable, LLM-authored memories)
+
+Run `peaks project memories --project <repo> --json` to read decisions / conventions / modules / rules / lessons from `.peaks/memory`. → `references/project-memory-loading.md`.
+
+### Peaks-Loop Step 2.5: Set session title
+
+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`).
+
+## Sub-agent session sharing (MANDATORY — one conversation = one sid)
+
+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).
+
+## Boundaries
+
+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`.

package/skills/peaks-code/references/step-0-8-gate.md

@@ -45,7 +45,7 @@ Refuses to emit a final handoff while `remaining > 0` under Job mode. Pass `--fo
 
 ### 3. Forced auto-compact — `--enforce-job-mode`
 
-`peaks code context-now --enforce-job-mode` (auto-enabled when `job-shape.json` says `isJob=true`) returns `action: 'auto-compact-now'` at ≥ 0.85; Code MUST call `peaks session auto-compact --execute` without confirmation.
+`peaks code context-now --enforce-job-mode` (auto-enabled when `job-shape.json` says `isJob=true`) returns `action: 'auto-compact-now'` at ≥ 0.85; Code MUST call `peaks compact auto --execute` without confirmation.
 
 ### 4. On-disk slice progress — `progress.json`
 

package/skills/peaks-code/references/sub-agent-dispatch.md

@@ -85,7 +85,10 @@ peaks sub-agent dispatch <role> --prompt <text> [--request-id <rid>] [--session-
       "artifactBytes": 0,
       "totalBytes": 4321
     },
-    "artifactMetas": []
+    "artifactMetas": [],
+    "orchestratorVisibleHint": "⏳ Spawning sub-agent via Task tool: rd for rid=002-2026-06-07, batch-id=… (ETA ~45s)",
+    "artifactsPublicPaths": [],
+    "expectedCompletionSeconds": 45
   },
   "warnings": [],
   "nextActions": [
@@ -248,6 +251,94 @@ once the poller has read them.
 - AC-25..AC-32: G5 resource lifecycle (RL-1 batch counter, dispatch record schema, reducer dispose, slice archive, cancel dispose)
 - AC-33..AC-37: G6 heartbeat CLI, schema, poller, status line, E2E
 
+## G11.5 — visibility contract (slice 2026-07-28-sub-agent-visibility)
+
+The dispatch CLI is a `dry-run` primitive — it never spawns the Task
+tool itself. The LLM orchestrator (peaks-code / peaks-rd / peaks-qa)
+executes the returned `data.toolCall` via the IDE's `Task` agent. The
+harness does not always render the spawned agent's progress in the
+user's terminal, so the user frequently sees "peaks dispatched" but
+no Task UI feedback. This rule closes that gap with three
+machine-readable + one prose obligation.
+
+**Envelope additions (single dispatch and `--from-dag`):**
+
+- `data.orchestratorVisibleHint: string` — a single-line prose string
+  the orchestrator MUST echo verbatim in the user-facing turn
+  (i.e. in the orchestrator's response, NOT just the tool call).
+  Format: `⏳ Spawning sub-agent via Task tool: <role> for rid=<rid>, batch-id=<batchId> (ETA ~<seconds>s)`.
+- `data.artifactsPublicPaths: readonly string[]` — public artifact
+  paths the sub-agent will own. Empty when `--write-artifact` is not
+  passed; otherwise contains the single user-supplied path. The
+  orchestrator surfaces this list before fan-out so the user can see
+  what files will appear on disk.
+- `data.expectedCompletionSeconds: number` — ETA budget. Single
+  dispatch defaults to 45s; `--from-dag` defaults to 60s. Use as a
+  hint, not a hard deadline (the heartbeat poller at §G6 still owns
+  the 5-min stale threshold).
+
+**Orchestrator obligations (text-locked, no skip):**
+
+1. Before every `Agent` tool call that materializes a `data.toolCall`
+   returned by `peaks sub-agent dispatch`, the orchestrator MUST emit
+   one line of prose to the user containing
+   `⏳ Spawning sub-agent via Task tool: <description>`. `<description>`
+   MUST be ≥ 6 chars and MUST include the rid. (`description` is the
+   short label rendered by the IDE; the prose line is the user-visible
+   counter-part.) The line is rendered in the assistant's reply text,
+   not in the tool result block.
+2. When the CLI returns a fan-out envelope (`dispatchCount > 1`),
+   the orchestrator MUST emit the prose line once for the whole fan-out
+   (not once per leaf) and then issue all `Agent` tool calls in the
+   same turn. Repeating the line N times defeats the point of fan-out.
+3. If the orchestrator cannot satisfy (1) (e.g. an inline tool call
+   failed and the orchestrator wants to retry), it MUST explain the
+   retry in the next user-visible message — silent retry is a
+   visibility regression.
+
+**Why the prose, not just the envelope field**: the
+`orchestratorVisibleHint` field is machine-readable, but a terminal
+user reads prose. The LLM MUST transcribe the hint into the visible
+reply. The two surfaces are not redundant — the field is for
+downstream tooling, the prose is for the human. Same payload,
+different readers.
+
+**Regression guard**: `tests/unit/dispatch/dispatch-fanout-mandatory.test.ts`
+parses the same SKILL.md text and asserts the G11.5 paragraph is
+present; do not delete the heading without also updating the guard.
+
+---
+
+## D21 — LLM-side completion signal (mandatory)
+
+`peaks sub-agent dispatch` writes the record in `queued` state. The
+dispatcher has no other way to learn that the spawned Task tool
+actually returned. **The LLM runner MUST call `peaks sub-agent finalize`
+once per dispatched Task, in the post-completion branch** (after the
+Task tool's `tool_result` has been received). Without it, the record
+stays `queued, no-execution` forever.
+
+```sh
+# After each Task tool returns:
+peaks sub-agent finalize --request-id <rid> --outcome done
+
+# On Task failure:
+peaks sub-agent finalize --request-id <rid> --outcome failed --error "<msg>"
+
+# Crash-recovery sweep (only if the runner was interrupted and many
+# records are stuck in queued):
+peaks sub-agent finalize --all-stale --outcome done
+```
+
+`finalize` calls `markCompleted` (in dispatch-record-writer.ts), which
+transitions the record to the chosen status and unregisters the path
+from `active-dispatches.json`. The next runner does not see a stale
+ghost.
+
+This was added in slice 2026-07-17-D21 after 13 stale records were
+observed in the peaks-loop repo (`active-dispatches.json` would have
+grown unboundedly without this fix).
+
 ## How to apply
 
 When writing a SKILL.md that fans out sub-agents: