peaks-loop 4.0.0-beta → 4.0.0-beta.10

package/skills/peaks-issue-fix-orchestrator/SKILL.md

@@ -0,0 +1,307 @@
+---
+name: peaks-issue-fix-orchestrator
+description: End-to-end orchestrator that surveys open issues in a target repo, classifies them by difficulty, mines reference merged-PRs, fixes each issue with real commits (with Repository + AI-modified declaration), writes normalized PR description files, and emits a one-line submit script. Use when the user wants to drive a "fix N open issues and prepare PRs" run on an upstream repo (any language; primarily Python + TypeScript). Reuses Loop Engineering primitives: 4-layer asset model, Darwin ratchet, karpathy-engineered red lines, Human-NL-Choice-Only. Triggers on `/peaks-issue-fix-orchestrator`, "fix 30 issues", "dogfood on <repo>", "open-issue sweep on <repo>".
+---
+
+# peaks-issue-fix-orchestrator
+
+peaks-issue-fix-orchestrator is the **user-facing skill** that turns a natural-language "dogfood on this repo, fix 30 open issues" request into a reproducible batch fix run. The LLM orchestrates the survey, classification, reference-PR mining, per-batch fix+commit, per-branch relocation, normalized PR body authoring, and submit-script emission. The user only describes a target and picks among a few multi-choice options.
+
+## Loop Engineering role
+
+peaks-issue-fix-orchestrator is a **non-crystallizing orchestrator**. It does **NOT** create `loop_release` / `bee_release` / `crystallization_event` rows in the local SkillHub. Its durable artifact is the git history + the PR body files written inside the **target repo** (the upstream the user wants to fix). A user may optionally run `peaks asset crystallize` AFTER a successful dogfood to capture the orchestrator's workflow as a Loop Engineering asset — but that is a separate, post-run step owned by `peaks-maker`, not this skill.
+
+This non-crystallizing shape is deliberate: the value of a dogfood run lives in the target repo's commits + PRs, not in peaks-loop's own asset pool. Crystallizing the orchestrator itself would conflate "I shipped 28 PRs upstream" with "I want this run to become a reusable skill" — two different user intents, kept on two different timelines.
+
+Reference: the karpathy-engineered red lines that govern every Loop-Engineering-participating peaks-* skill live at `.peaks/standards/loop-engineering-guidelines.md`. peaks-issue-fix-orchestrator honors `RL-1` (Human-NL-Choice-Only), `RL-2` (security-critical-path ban), `RL-3` (AI-modified declaration), and `RL-8` (peaks-code domain boundary — this skill is a code-domain orchestrator).
+
+---
+
+## When to use
+
+Concrete triggers:
+
+- The user says `/peaks-issue-fix-orchestrator` or `peaks issue-fix-orchestrator`.
+- "Dogfood on `<owner>/<repo>`" or "open-issue sweep on `<owner>/<repo>`".
+- "Fix 30 (or N) open issues" / "prepare PRs for the top open issues" / "ship PRs against upstream".
+- A team wants to drive a `simple + medium + hard` difficulty-banded issue sweep on a Python or TypeScript upstream (e.g. NousResearch/hermes-agent, FastAPI, anything in the `good-first-issue`-friendly band).
+
+## When NOT to use
+
+The rubric-banned surfaces — this skill MUST refuse these targets:
+
+- **OAuth / auth / secrets / token / credential-pool** paths (e.g. `tools/mcp_oauth.py`, `agent/auth/*`, anything that mutates a `.env` / keyring / token cache).
+- **Agent-loop critical paths**: `agent/conversation_loop.py`, `agent/tool_guardrails.py`, `agent/error_classifier.py` retry-loop interaction.
+- **Model router / inference-classifier** surfaces that gate the retry loop.
+- **Prompt-cache** surfaces (cache key invalidation logic, cache TTL, OTel propagation that touches the cache).
+- **Multi-subsystem refactors** that touch >3 modules or introduce a new public API surface.
+- **macOS-only / Windows-only** candidates — replaced with cross-platform alternatives before commit (RL-7).
+- Anything that requires a **touch to a security-critical hot path** (auth, secrets, prompt cache, agent loop, model router, tool dispatcher).
+
+If the only available candidates fall in these surfaces, the skill surfaces the skip list with reasons and asks the user to expand the issue source list — it does not bypass the rubric.
+
+---
+
+## Inputs (NL or choice only — RL-1)
+
+The skill accepts exactly **four** trigger forms. Every form resolves via `AskUserQuestion` multi-choice or free-form NL; the user never types a CLI verb or hand-authors JSON.
+
+1. **`user_explicit count`** — "fix 30 issues". The user names the integer. LLM picks the first N after classification.
+2. **`difficulty bucket sizes`** — "10 simple + 10 medium + 10 hard". The user picks bucket sizes via multi-choice (`[10/10/10]`, `[5/10/15]`, `[15/5/10]`, `[20/10/0]`).
+3. **`scope-bounded count`** — "fix every OpenRouter-credential bug" or "fix every memory-provider bug". LLM filters survey to the user's NL filter, then takes all matching candidates.
+4. **`survey-only`** — "just survey, no commits". LLM produces only `01-issue-survey.md` + the rubric skip list; no commits, no PRs.
+
+The user also provides: (a) the upstream `<owner>/<repo>` (NL — "hermes-agent", "FastAPI", etc.); (b) the working directory on disk (LLM derives from `peaks workspace init`); (c) optional `max-diff-lines` cap (default 30).
+
+---
+
+## Default runbook
+
+The 6-step procedure the LLM must follow on every run.
+
+### 1. Anchor + skill marker
+
+```bash
+peaks workspace init --project <repo>
+peaks skill presence:set peaks-issue-fix-orchestrator
+```
+
+### 2. Survey
+
+Three pages of `GET /repos/<owner>/<repo>/issues?state=open&per_page=100` via the public REST API (no auth required). Save the raw JSON to `<plan>/raw/page-1.json`, `raw/page-2.json`, `raw/page-3.json`, plus a per-issue summary table at `<plan>/01-issue-survey.md` Section A.
+
+### 3. Classify
+
+Bucket candidates into 10 simple + 10 medium + 10 hard by the rubric (file scope, blast radius, surface area). Replace any platform-only candidate (macOS-only / Windows-only) with the next available cross-platform alternative — document the swap in `01-issue-survey.md` Section E. List 5+ explicitly-skipped issues with reasons in `01-issue-survey.md` Section D.
+
+### 4. Mine reference PRs
+
+Search the upstream for closed/merged PRs similar to each candidate via `GET /search/issues?q=is:pr+is:merged+<topic>`. Capture per candidate: PR# + title + file paths touched + a 1-line "mimic strategy". Save to `<plan>/02-reference-pr-summary.md`. Cache the raw responses in `raw/ref-pr-<issue>.json` so re-runs do not re-hit the rate limit.
+
+### 5. Fix + commit (per-batch)
+
+Dispatch to sub-agents in three batches: **simple**, **medium**, **hard**. Each sub-agent returns a list of commit SHAs + per-issue file paths. Each commit body MUST include:
+
+```text
+fix(<scope>): <short title> (#<NNNNN>)
+
+Repository: https://github.com/<owner>/<repo>
+AI-modified: yes
+Modifying tool: peaks-loop / peaks-issue-fix-orchestrator
+Session: <ISO date>
+Reference PR(s): <PR list>
+
+<1-2 paragraph body>
+
+Closes #<NNNNN>
+```
+
+- **Author identity** = local gitconfig `user.name` / `user.email`. Must NOT be overridden to an AI name.
+- **No** `Co-Authored-By: Claude / Anthropic / MiniMax` trailer — CLAUDE.md red rule.
+- Tests: if the touched area has a test, run it before commit; if not, add one. Capture test output in the per-issue PR body.
+
+### 6. Relocate commits to per-issue branches
+
+For each committed fix, cut a per-issue branch from the upstream HEAD and cherry-pick the commit. Example (substitute the real upstream HEAD for `2c0820c9f`):
+
+```bash
+git checkout -b fix/<NNNNN>-<slug> 2c0820c9f
+git cherry-pick <sha>
+git checkout main
+```
+
+Then reset `main` to upstream HEAD (do NOT push `--force`). `git log <upstream-HEAD>..main` must be empty at end of run (RL-8).
+
+---
+
+## PR body format
+
+Each PR description file follows the normalized 11-section shape:
+
+```markdown
+# fix(<scope>): <short title> (#<NNNNN>)
+
+## Summary
+<1-paragraph description of the issue and the user-visible fix>
+
+## Root cause / Scope
+<1-paragraph: file(s) + class/function + the path through the bug>
+
+## Fix
+<1-paragraph: the change, with code-block snippet if short>
+
+## Tests
+<test file paths + a 1-line description of what each test asserts>
+
+## Reference
+<the merged PR(s) we mimicked + a 1-line "why this is a good mimic">
+
+**Repository:** https://github.com/<owner>/<repo>
+**AI-modified:** yes
+**Branch:** fix/<NNNNN>-<slug>
+**Issue:** Closes #<NNNNN>
+
+```bash
+gh pr create --repo <owner>/<repo> \
+  --base main \
+  --head <user>:<branch> \
+  --title "fix(<scope>): <short title> (#<NNNNN>)" \
+  --body-file <plan>/prs/<NNNNN>.md
+```
+```
+
+Output path: `<repo>/.peaks/_runtime/<sessionId>/peaks-issue-fix-orchestrator/prs/<NNNNN>.md`. One file per issue.
+
+---
+
+## Submit script
+
+A one-line shell script iterates the N `(issue, branch)` pairs and runs `gh pr create` for each. Pre-flight guards:
+
+- `git log --oneline -1 main` must equal the upstream HEAD (refuses to push dirty main).
+- `gh auth status` must succeed.
+
+Write to `<repo>/.peaks/_runtime/<sessionId>/peaks-issue-fix-orchestrator/push-all-prs.sh` with a `#!/usr/bin/env bash` shebang, `set -euo pipefail`, and a per-PR call:
+
+```bash
+gh pr create --repo <owner>/<repo> \
+  --base main \
+  --head <user>:<branch> \
+  --title "fix(<scope>): <short title> (#<NNNNN>)" \
+  --body-file "<plan>/prs/<NNNNN>.md"
+```
+
+Append each PR URL to `<repo>/.peaks/_runtime/<sessionId>/peaks-issue-fix-orchestrator/push-all-prs.log`.
+
+---
+
+## Red lines (karpathy 4-section form)
+
+Each red line is written in the karpathy 4-section form (Failure modes / Rewrite / Self-check / Out-of-scope). The skill refuses to advance past any red line violation.
+
+### RL-1 — Human-NL-Choice-Only
+
+**Failure modes.** User is asked to hand-fill JSON or type a CLI verb; user pushed into schema decisions; user accepts opaque recommendations by default.
+
+**Rewrite.** Every user input is either an `AskUserQuestion` multi-choice pick or free-form NL. The LLM runs the CLI. Forbidden: `peaks issue-fix-orchestrator survey`, `peaks issue-fix-orchestrator submit`, `peaks issue-fix-orchestrator fix`.
+
+**Self-check.** Did any step require the user to type a verb? Is every choice expressible in NL? Does every recommendation include an evidence brief? Does the skill still gate every CLI invocation through the LLM?
+
+**Out-of-scope.** Machine-driven CI flows; emergency security gates (LLM + red lines take over; user is informed in NL).
+
+### RL-2 — No commit on a security-critical path
+
+**Failure modes.** A "fix" touches OAuth, secrets, auth, agent loop, model router, tool dispatcher, prompt cache. The rubric-ban list leaks into the run.
+
+**Rewrite.** Survey-banned list is explicit in `01-issue-survey.md` Section D. Forbidden file paths: `tools/mcp_oauth.py`, `agent/auth/*`, `agent/conversation_loop.py`, `agent/tool_guardrails.py`, `agent/error_classifier.py`, `*/prompt_cache*`, `*/token_cache*`.
+
+**Self-check.** Does the candidate's file-path list intersect the banned set? Does the fix mutate any auth/secret/credential-pool keyring? Does the change touch a retry-loop classifier?
+
+**Out-of-scope.** Documentation-only changes to those files (they are banned entirely, doc or not).
+
+### RL-3 — AI-modified declaration
+
+**Failure modes.** Commit silently authored by an LLM with no marker; `Co-Authored-By: <AI name>` trailer sneaks in; future readers cannot tell which commits are AI-modified.
+
+**Rewrite.** Every commit body contains literal lines `Repository: …`, `AI-modified: yes`, `Modifying tool: peaks-loop / peaks-issue-fix-orchestrator`, `Session: <ISO date>`. Forbidden trailers: `Co-Authored-By: Claude`, `Co-Authored-By: Anthropic`, `Co-Authored-By: MiniMax`.
+
+**Self-check.** Does `git show -s <sha> | grep -E 'Repository:|AI-modified:'` return both lines? Is the trailer set empty of AI names?
+
+**Out-of-scope.** Squash merges that preserve only the merged message — the LLM re-applies the body when relocating.
+
+### RL-4 — Reference PR required
+
+**Failure modes.** A fix is invented from whole cloth with no analogue in the upstream history; the fix lands a new pattern that has not survived upstream review.
+
+**Rewrite.** Each candidate has 1-2 reference PRs documented in `02-reference-pr-summary.md` with a 1-line "mimic strategy". The fix follows the reference's pattern, not a novel design.
+
+**Self-check.** Is there a reference PR# listed in `02-reference-pr-summary.md` for this candidate? Does the diff mirror the reference's approach (file, class, helper)? Is the reference PR actually merged (not just closed)?
+
+**Out-of-scope.** Brand-new features with no analogue upstream — those are out of scope for this skill.
+
+### RL-5 — Test before commit
+
+**Failure modes.** A fix lands without a regression test; a fix breaks an existing test; the touched area has a test suite and the LLM never ran it.
+
+**Rewrite.** If the touched area has a test, run it before commit. If not, add one. Captured test output is pasted in the per-issue PR body under `## Tests`.
+
+**Self-check.** Did the test command exit 0? Did the new test fail without the fix (proves the test catches the bug)? Is the test file path listed in the PR body?
+
+**Out-of-scope.** Pure-documentation fixes with no behavior change (RL-5 is satisfied vacuously).
+
+### RL-6 — One commit per issue
+
+**Failure modes.** Fixup commits, squashed histories, multi-issue commits, ambiguous 1:1 mapping between issue → branch → commit → PR.
+
+**Rewrite.** The submit script maps 1:1 issue → branch → commit → PR. Each branch has exactly 1 commit on top of the upstream HEAD. No `--amend`, no `git reset --soft` + re-commit cycles, no squash.
+
+**Self-check.** Does `git log <upstream-HEAD>..<branch>` show exactly 1 commit? Does the commit body mention exactly 1 issue number in `Closes #<N>`?
+
+**Out-of-scope.** Multi-issue umbrella PRs — those go through `peaks-rd`, not this skill.
+
+### RL-7 — Cross-platform candidates only
+
+**Failure modes.** A macOS-only or Windows-only candidate slips through; the fix is platform-locked and useless to other users.
+
+**Rewrite.** Platform-only candidates (`macos-only`, `windows-only`, `pulseaudio-bridge`, `terminal.app-*`, `wsl-*`) are replaced with cross-platform alternatives before commit. The replacement is explicit in `01-issue-survey.md` Section E.
+
+**Self-check.** Does the candidate's `os` label intersect the platform-only set? If yes, is there a replacement listed in Section E? Does the replacement touch zero platform-specific subsystems?
+
+**Out-of-scope.** Genuinely platform-bound issues that have no cross-platform analogue — those are deferred, not fixed.
+
+### RL-8 — `main` is never polluted
+
+**Failure modes.** Fix commits land on `main`; an accidental `git push origin main` pollutes upstream; the user's fork diverges from the upstream HEAD.
+
+**Rewrite.** All dogfood work lands on per-issue branches cut from the upstream HEAD. `main` is reset to upstream HEAD at end of run. `git log <upstream-HEAD>..main` is always empty.
+
+**Self-check.** Is `main` at the upstream HEAD SHA? Is the per-issue branch's only parent the upstream HEAD? Did the script ever `git push origin main`?
+
+**Out-of-scope.** Squash-merge back into `main` on the user's local fork — that is the user's choice, not this skill's.
+
+---
+
+## Boundaries
+
+What this skill MUST NOT do:
+
+- **Push without explicit user confirmation** — the submit script is written but not run by default.
+- **Force-push** (`git push --force`, `git push --force-with-lease`) to any branch.
+- **Edit upstream history** (no interactive rebase, no `git filter-branch`, no commit signing on someone else's behalf).
+- **Write to security-critical paths** (OAuth, secrets, agent loop, model router, prompt cache — see RL-2).
+- **Change the user identity** in git (no `git config user.name "Claude"`, no `git -c user.email=...` override).
+- **Add `Co-Authored-By: <AI>` trailers** — CLAUDE.md red rule.
+- **Hand-author JSON or SKILL.md on the user's behalf** when the user is just describing a target.
+- **Create a `loop_release` / `bee_release` / `crystallization_event`** in peaks-loop's own SkillHub (this is a non-crystallizing orchestrator; see "Loop Engineering role").
+
+---
+
+## Audit (reproducibility)
+
+The 5-line verification block the user can run after a dogfood session:
+
+```bash
+git -C <repo> log --oneline -1 main                                  # must be upstream HEAD
+git -C <repo> log --oneline <upstream-HEAD>..main                    # must be empty
+git -C <repo> branch --list | grep -c '^  fix/'                      # must equal N
+ls <repo>/.peaks/_runtime/<sessionId>/peaks-issue-fix-orchestrator/prs | wc -l   # must equal N
+git -C <repo> show -s fix/<branch> | grep -E 'Repository:|AI-modified:'   # every commit must have both
+```
+
+If any line returns an unexpected value, the run has been mutated externally; the per-issue PR body files + the `00-FINAL-AUDIT.md` are the source of truth.
+
+---
+
+## First-class outputs
+
+The skill produces the following files for the user to verify:
+
+- `<repo>/.peaks/_runtime/<sessionId>/peaks-issue-fix-orchestrator/01-issue-survey.md` — survey + classification + skip list + replacement table.
+- `<repo>/.peaks/_runtime/<sessionId>/peaks-issue-fix-orchestrator/02-reference-pr-summary.md` — per-candidate reference PRs + mimic strategy.
+- `<repo>/.peaks/_runtime/<sessionId>/peaks-issue-fix-orchestrator/03-replacement-candidates.md` — macOS-only / Windows-only swap log.
+- `<repo>/.peaks/_runtime/<sessionId>/peaks-issue-fix-orchestrator/00-FINAL-AUDIT.md` — final audit (per-issue, per-concern).
+- `<repo>/.peaks/_runtime/<sessionId>/peaks-issue-fix-orchestrator/prs/<NNNNN>.md` — N normalized PR description files (one per issue).
+- `<repo>/.peaks/_runtime/<sessionId>/peaks-issue-fix-orchestrator/push-all-prs.sh` — the one-line submit script (NOT run by default).
+- `<repo>/.peaks/_runtime/<sessionId>/peaks-issue-fix-orchestrator/raw/page-{1,2,3}.json` — cached GitHub API responses.
+- `<repo>/.peaks/_runtime/<sessionId>/peaks-issue-fix-orchestrator/raw/ref-pr-<issue>.json` — cached reference PR responses.
+- N `fix/<NNNNN>-<slug>` branches on the user's local fork, each with exactly 1 commit on top of the upstream HEAD.

package/skills/peaks-resume/SKILL.md

@@ -3,9 +3,9 @@ name: peaks-resume
 description: Universal resume primitive for any in-flight Peaks-Loop workflow (orchestrator-agnostic). Detects the current session's deepest completed gate and surfaces a resume option via AskUserQuestion. Use when ANY bee (peaks-code, future peaks-research, future peaks-content, …) needs to recover from /compact or session interruption. Triggers on "/peaks-resume", "continue the unfinished work", "继续完成", "把刚才没做完的收尾". (Replaces peaks-resume as a top-level primitive.)
 ---
 
-# Peaks-Loop Solo Resume (wrapper)
+# Peaks-Loop Code Resume (wrapper)
 
-Peaks-Loop Solo Resume is a thin wrapper that handles the **most common high-frequency request shape**: "I was in the middle of something, continue it." It detects the current session's deepest completed gate, surfaces a resume option, then yields to the main `peaks-code` skill (which runs the actual workflow from the matching gate onwards).
+Peaks-Loop Code Resume is a thin wrapper that handles the **most common high-frequency request shape**: "I was in the middle of something, continue it." It detects the current session's deepest completed gate, surfaces a resume option, then yields to the main `peaks-code` skill (which runs the actual workflow from the matching gate onwards).
 
 **This is a transparent wrapper.** The user does not stay in this skill — once the resume option is confirmed, control hands off to `peaks-code`. The wrapper exists only to (a) detect the in-flight slice without the LLM re-reading 3-5 artifact files, and (b) surface the resume option as a `AskUserQuestion` before the main loop skips ahead.
 

package/skills/peaks-slice-decompose/SKILL.md

@@ -108,4 +108,64 @@ This skill does NOT modify source code. It documents the v2 envelope produced by
 |---|---|
 | `references/v2-schema.md` | Field-by-field table for `DecompositionResultV2`, `PassResult`, `SliceV2`, `CrossPassEdge.arbitratedBy`, `LlmArbitration`. |
 | `references/granularity-decision.md` | Decision tree for the 4 `--granularity` modes; `shouldSubdivide()` thresholds + tie-break semantics. |
-| `references/cross-pass-edge-interpretation.md` | The 4 edge kinds and how `peaks-rd` should use them for dispatch ordering; `LlmArbitration` trace reader. |
+| `references/cross-pass-edge-interpretation.md` | The 4 edge kinds and how `peaks-rd` should use them for dispatch ordering; `LlmArbitration` trace reader. |
+
+---
+
+## SC template hard rules (sediment 2026-07-09)
+
+These rules are added in response to **D-009a + D-009c** discovered while running RID 003-add-zcode-adapter. They prevent the same class of mistake from re-occurring in future SC drafts.
+
+### Rule 1 — Pre-flight: detect ESM vs CJS before writing export syntax (D-009c)
+
+Before specifying `--caller-id` / export guard syntax in any SC task, run:
+
+```bash
+head -3 package.json | grep '"type"'
+```
+
+- `"type": "module"` → ESM. Use `export const FOO = ...` for any constant that tests need to import. **Do NOT** write `if (typeof module !== 'undefined' && module.exports) { module.exports = { FOO }; }` — that pattern is CJS-only.
+- No `"type"` field (or `"type": "commonjs"`) → CJS. Use the `module.exports` guard.
+
+Why: RID-003 SC §3.5 originally specified the CJS guard for `scripts/install-skills.mjs`. The script is actually ESM (`"type": "module"`). The RD agent had to backtrack and the SC lost 5 minutes of spec clarity.
+
+### Rule 2 — Whitelist fixture sync is NOT collateral (D-009a)
+
+When a slice adds a new entry to a **whitelist fixture** (e.g. `tests/unit/ide/ide-registry.test.ts` asserting `expect(adapters).toHaveLength(7)` after adding the 8th adapter), that fixture sync is a **primary task**, not a "by the way" footnote.
+
+Mandatory structure for any slice that adds to a known set:
+
+```markdown
+### Tasks
+
+| Task | File | Change |
+|---|---|---|
+| T-1 | `src/services/ide/ide-types.ts` | Add `'zcode'` to IdeId |
+| T-2 | `src/services/ide/ide-registry.ts` | Register ZCODE_ADAPTER |
+| T-3 | `tests/unit/ide/ide-registry.test.ts` | Update whitelist: 7 → 8 adapters, add 'zcode' |
+| T-4 | `tests/unit/install-skills-script.test.ts` | Update whitelist: 5 → 6 platforms, add 'zcode' |
+```
+
+If you find a whitelist fixture during execution but didn't pre-list it as a task, treat it as a **NEW TASK** and run the SC ↔ QA repair loop, not as "necessary collateral". Pre-listing prevents surprises at Gate 1.
+
+### Rule 3 — Adapter interface optional fields (D-009b reciprocal)
+
+When extending `IdeAdapter` (or any plugin-interface in `src/services/**/ide/`), prefer **optional fields** over required fields so existing implementations don't need stub updates:
+
+```ts
+// ✅ Optional — back-compat safe
+interface IdeAdapter {
+  readonly detectCurrentModel?: () => Promise<string | undefined>;
+}
+
+// ❌ Required — every existing adapter must add a stub
+interface IdeAdapter {
+  readonly detectCurrentModel: () => Promise<string | undefined>;
+}
+```
+
+If a field MUST be required, document in the SC why each existing implementation must be updated inline, and pre-list those updates as primary tasks (Rule 2 pattern).
+
+---
+
+**Sediment source:** `.peaks/_runtime/2026-07-08-session-17918f/qa/003-add-zcode-adapter/{slice-A-completion,slice-B-completion}.md` D-009a/b/c sections. Master lesson: `.peaks/memory/peaks-code-runbook-4-0-0-beta-6-skill-md-cli-d-001-d-002-d-003-d-010.md`.

package/skills/peaks-solo/SKILL.md

@@ -0,0 +1,197 @@
+---
+name: peaks-solo
+description: |
+  Dispatcher (分诊员) for the Peaks-Loop skill family. Use when the user describes a task in natural language and does NOT know which peaks-* skill fits. peaks-solo reads the live skill pool via `peaks skill search`, dispatches to a matching leaf (peaks-code / peaks-content / peaks-doctor / peaks-issue-fix-orchestrator / etc.) or falls back to self-planned execution (deep-search / WebSearch / Bash / Edit markdown) if no leaf matches, and then asks the user whether to sediment the result.
+
+  Triggers: 自然语言描述诉求且无明确 peaks-* skill 选择 / "帮我处理这个" / "我不知道该用哪个" / "随便都行".
+
+  NOT for: code-specific work (use /peaks-code) / content-specific work (use /peaks-content) / project health check (use /peaks-doctor) / issue sweep (use /peaks-issue-fix-orchestrator) / SOP authoring (use /peaks-sop).
+metadata:
+  type: dispatcher
+  domain: triage
+  visibility: public
+  supersedes: peaks-solo (eradicated 2026-07-05, revived 2026-07-08)
+  red_lines: [RL-1, RL-8, HC-7, HC-8, HC-9, HC-10, HC-11]
+---
+
+# peaks-solo — Dispatcher (分诊员)
+
+> peaks-solo 是 Peaks-Loop 的 dispatcher,不是 orchestrator。读取技能池 → 分诊 → 转交 leaf 或自规划 → 回头问沉淀。**不持有 implementation surface**。
+
+---
+
+## 1. 角色定义 (dispatcher ≠ orchestrator)
+
+**peaks-solo 是一条 dispatcher skill**,跟 `peaks-code` 这种 orchestrator 平行存在,但更薄一层:
+
+| 角色 | 工作 | 是否持有 implementation surface |
+|---|---|---|
+| **dispatcher** (peaks-solo,本 skill) | 看用户 NL → 查 skill 池 → 转交 / 自规划 → 问沉淀 | **不持有**(只调度,不实现) |
+| **orchestrator** (peaks-code / peaks-content / peaks-doctor) | 看用户 NL → 走 11 步 runbook → 直接调 prd/rd/qa/ui/sc/txt 蜂群 → 沉淀 | **持有**(通过子蜂群间接持有) |
+
+**核心区分(HC-11 锁死):** peaks-solo 能看、能查、能转交、能跑通用工具(deep-search / WebSearch / Bash / Edit markdown)、能提议沉淀;**不能**写代码、**不能**写 PRD、**不能**跑 vitest、**不能**改 Loop Engineering 资产(那是用户主权)。
+
+**与 peaks-* leaf 的关系:** peaks-solo 是新加的第三条入口,不替代任何 leaf。3.x / 4.x 老用户继续 `/peaks-code` / `/peaks-content` / `/peaks-doctor` 等,**老入口 0 改动**(HC-10)。
+
+---
+
+## 2. 触发条件
+
+peaks-solo 由 LLM 在三种匹配类之一触发,**不依赖**任何固定的 slash 命令前缀:
+
+### 2.1 Source-trace 触发
+
+LLM 自身启动循环(如 Claude Code 启动新会话、resume 检测、auto-decide 路径)时,**没有**其它 skill 已被 dispatch,且用户描述诉求 → 走 peaks-solo 分诊。
+
+### 2.2 Trigger-phrase 触发(主路径)
+
+用户自然语言描述诉求 + 满足下列任一短语:
+
+- 自然语言描述诉求且无明确 peaks-* skill 选择(主触发)
+- "帮我处理这个" / "帮我看看"
+- "我不知道该用哪个"
+- "随便都行" / "你帮我决定"
+- "我有个事需要处理" / "我想做点东西"
+
+**反向:** 用户已明确指定 `/peaks-code` / `/peaks-content` / `/peaks-doctor` 等具体 skill → 不进 peaks-solo,直接 dispatch 到该 leaf(HC-10 老入口保留)。
+
+### 2.3 LLM-judge 触发
+
+用户 NL 表述是开放性、跨域、或者 LLM 无法判定属于哪个 peaks-* 域时(例如"帮我看下 GitHub trending top 10"),LLM 自己判断"这事没有专属 leaf",走 peaks-solo 兜底。
+
+---
+
+## 3. Triage 决策流
+
+peaks-solo 的 triage 流严格按以下伪代码执行:
+
+```
+1. user NL → peaks-solo 触发
+2. peaks-solo 跑 peaks skill search --query "<NL>" → 拿到 candidates []
+3. if candidates.length == 0:
+     → 走自规划兜底(§4)
+4. if candidates.length == 1:
+     → 直接 Skill tool 调起该 skill(转交,无感)
+5. if candidates.length >= 2:
+     → 走 AskUserQuestion 多选("NL 描述匹配到 N 个 peaks-* skill,请选一个:")
+     → 用户选 → Skill tool 调起
+     → 用户选 "(e) 都不对" → 自规划兜底(§4)
+6. leaf 跑完 → leaf 内部自己处理 sediment(不重复问;HC-9)
+7. 自规划跑完 → 走 §5 沉淀提议
+```
+
+### 3.1 多候选 AskUserQuestion 模板(HC-9 锁死)
+
+```
+question: "这个诉求匹配到以下 peaks-* skill,请选一个:"
+options:
+  - (a) <name + 一句话功能 + 适用场景>
+  - (b) <name + 一句话功能 + 适用场景>
+  - ...
+  - (e) 都不对,我自己跑
+multiSelect: false
+```
+
+**关键约束:** 必须是 AskUserQuestion,**不**允许让用户自由文本输入 skill 名(HC-9 Human-NL-Choice-Only)。
+
+### 3.2 用户主动说"我自己来" / "不用分诊"
+
+LLM **bail out**(返回控制权给用户,不调任何 leaf,不进自规划兜底)。
+
+### 3.3 关键词 → leaf skill 快速映射
+
+完整 ≥ 10 行关键词表见 `references/triage-decision-table.md`。下面只列最常见的 5 类:
+
+| keyword | → leaf skill |
+|---|---|
+| code / 改 bug / 全流程 / 端到端 | `/peaks-code` |
+| 文档 / article / 内容 / 写稿 | `/peaks-content` |
+| 健康 / 体检 / audit 报告 | `/peaks-doctor` |
+| issue / 批量修 / sweep | `/peaks-issue-fix-orchestrator` |
+| SOP / 流程 / 工作流 | `/peaks-sop` |
+
+---
+
+## 4. 自规划兜底
+
+当 `peaks skill search` 返回 0 个候选,或用户选"(e) 都不对",LLM 走自规划:用通用工具(deep-search / WebSearch / Bash / Edit markdown)完成用户诉求。
+
+### 4.1 允许工具清单
+
+| 工具 | 适用场景 | 限制 |
+|---|---|---|
+| `deep-search` skill | 信息查询 / 研究类(若已装) | 不主动 install |
+| `WebSearch` / `WebFetch` | 实时性高的查询(超过训练数据) | 内置工具 |
+| `Bash` | 数值计算 / 系统命令 / git 操作 | **不写 src/** 业务代码(那是 peaks-code 域) |
+| `Edit` / `Write` | 改 markdown / 改 yaml / 改 `.peaks/memory/` 文件 | **不改 src/** 业务代码;**不改 `skills/peaks-{code,content,doctor,...}/`** 任何 leaf skill 文件 |
+| `peaks memory extract` | 跑完提议沉淀 | 走现成 CLI,不重写 |
+
+完整 allowed + blocked 清单见 `references/fallback-tool-inventory.md`。
+
+### 4.2 自规划成功后的下一步
+
+自规划跑完 **必须** 走 §5 沉淀提议(HC-9 Human-NL-Choice-Only);不允许静默丢弃结果。
+
+---
+
+## 5. 沉淀提议
+
+自规划兜底跑完(leaf 转交跑完则由 leaf 内部 Step 11 处理,不重复问)→ peaks-solo 用 AskUserQuestion 提议沉淀。
+
+### 5.1 AskUserQuestion 模板(HC-9 锁死)
+
+```
+question: "本次结果是否沉淀?"
+options:
+  - (a) 沉淀为普通 lesson / convention → peaks memory extract --apply
+  - (b) 沉淀为 Loop Engineering 资产 → peaks asset crystallize
+  - (c) 改 scope 再沉淀(LLM 继续追问)
+  - (d) 不沉淀(单次性,丢弃)
+multiSelect: false
+```
+
+**默认推荐 = (a)**(普通 lesson / convention),LLM 必须给一段 NL 解释为什么推荐 (a) 或 (b),**不**允许默认推荐 (d)。
+
+完整 4-option 模板 + 触发条件矩阵见 `references/sediment-prompt-template.md`。
+
+### 5.2 触发条件矩阵
+
+| peaks-solo 跑完类型 | 是否问 | trigger |
+|---|---|---|
+| 转交 leaf 跑完 | **不问** | (leaf 内部 Step 11 处理) |
+| 自规划兜底跑完 | **默认问** | `success_default_prompt` |
+| 用户主动说"沉淀这个" | **立即问** | `user_explicit` |
+| LLM 识别 ≥ 2 个 reuse signals | **附带 4-section brief 问** | `llm_suggested` |
+
+---
+
+## 6. Out of scope (HC-11 锁死)
+
+peaks-solo 是 dispatcher,**不**是 orchestrator,**不**是 implementer。下面四类操作**禁止**直接在 peaks-solo 内部执行:
+
+- **no code** — 不写 / 不改 / 不重构 `src/**` 业务代码,也不调 peaks-rd / peaks-qa / peaks-ui / peaks-sc 子蜂群(那是 peaks-code 的 implementation surface)。遇到 code-domain 需求必须转交 `/peaks-code` 或建议用户自己跑。
+- **no PRD** — 不写产品需求文档(那是 peaks-code → peaks-prd 的范围)。peaks-solo 自己不持有 PRD 的生成 surface。
+- **no vitest** — 不跑测试,也不写 `tests/**` 业务测试。遇到测试需求必须转交 `/peaks-test` 或 `/peaks-code`。
+- **no Loop Engineering Asset mutation** — 不调 `peaks asset crystallize` 改 Loop Engineering 资产,也不写 `.peaks/standards/` / `.peaks/memory/` 之外的 peaks-loop 内部资产(那是用户主权,peak-* 技能层没有改动权)。
+
+**唯一例外:** 沉淀提议模板里 **选项 (b)** 提到 `peaks asset crystallize` 是给用户看的,不是 peaks-solo 自动执行;真正执行由用户在 AskUserQuestion 选中后由 LLM 代跑该 CLI。
+
+### 6.1 边角 case
+
+| case | 处理 |
+|---|---|
+| 用户中途换需求 | 重新跑 §3 triage,不复用旧 candidates |
+| 兜底工具失败(如 WebSearch 不可用) | 转下一种 allowed 工具;3 次失败后 AskUserQuestion 问用户是否要继续 |
+| 沉淀被拒后(用户选 d) | 不重复问,直接关闭本 skill session |
+| 用户在 AskUserQuestion 中输入自由文本(理论上不该发生) | 把它当作 NL 描述,重新跑 §3 triage |
+
+---
+
+## 相关引用
+
+- `references/triage-decision-table.md` — 关键词 → leaf skill 完整映射表(≥ 10 行)
+- `references/fallback-tool-inventory.md` — 自规划允许 + 禁止工具清单
+- `references/sediment-prompt-template.md` — 4-option AskUserQuestion 沉淀模板
+- spec: `docs/superpowers/specs/2026-07-08-peaks-solo-dispatcher-design.md` §3.1, §3.3, §3.4, §3.5
+- plan: `docs/superpowers/plans/2026-07-08-peaks-solo-dispatcher/s1-peaks-solo-skill.md`
+- decision memo: `.peaks/memory/user-decision-2026-07-08-revive-peaks-solo-as-dispatcher.md`

package/skills/peaks-solo/references/fallback-tool-inventory.md

@@ -0,0 +1,46 @@
+# peaks-solo — Fallback Tool Inventory (自规划兜底工具清单)
+
+> 当 `peaks skill search` 返回 0 候选,或用户在 AskUserQuestion 选"(e) 都不对",peaks-solo 走自规划兜底。本表规定自规划下 LLM **允许**与**禁止**调用的工具。
+> **核心边界(HC-11 锁死):** peaks-solo 不写业务代码、不写 PRD、不跑 vitest、不改 Loop Engineering 资产。下面 blocked 列表是 HC-11 的可执行形式。
+
+## Allowed tools (允许)
+
+| 工具 | 适用场景 | 限制 |
+|---|---|---|
+| `deep-search` skill | 信息查询 / 研究类 / 多跳事实核查 | 若 LLM CLI 平台装了 deep-search 自动出现;peaks-solo **不主动 install**;若未装,降级到 WebSearch |
+| `WebSearch` | 实时性高的查询(超过训练数据)/ trending / top N | 内置工具,无需 install |
+| `WebFetch` | 已知 URL 的内容抓取(单页,无 JS 渲染) | 内置工具;不爬取含登录 / 反爬的页面 |
+| `Bash` | 数值计算 / 系统命令 / git 操作 / `ls` / `cat` / `rg` / `grep` | 仅**只读命令**;不写 src/** 业务代码;不 rm;不 git push --force;不 chmod 777;不 curl \| sh |
+| `Edit` / `Write` | 改 markdown / 改 yaml / 改 `.peaks/memory/<user>/*.md` / 改临时文件 | **只允许**改:`*.md` / `*.yaml` / `*.yml` / `.peaks/memory/`;**不允许**改:`src/**` 业务代码 / `skills/peaks-{code,content,doctor,sop,status,test,resume,ide,final-review,slice-decompose,issue-fix-orchestrator,perf-audit,security-audit,audit}/**` 任何 leaf skill |
+| `peaks memory extract` | 跑完提议沉淀(选项 a) | 走现成 CLI,不重写;不创建新 CLI |
+| `AskUserQuestion` | 多候选分诊 / 沉淀提议 / 兜底方案选择 | HC-9 锁死;**不**引入自由文本输入 |
+
+## Blocked tools / operations (禁止)
+
+下表是**显式禁止**——LLM 在自规划兜底中**不能**调这些工具或跑这些操作。违反即违反 HC-11。
+
+| blocked 操作 | 原因 | 替代方案 |
+|---|---|---|
+| `rm -rf <path>` | 不可逆破坏性操作 | 改用 `mv <path> <path>.bak` 或只读 `ls` |
+| `git push --force` / `git push -f` | 改写历史,影响其他协作者 | 用 `git push --force-with-lease`(若必须)或拒绝 push 让用户自己来 |
+| `Edit src/**` / `Write src/**` 业务代码 | HC-11: no code;peaks-code 域 | 转交 `/peaks-code` |
+| `Edit skills/peaks-{code,content,doctor,sop,status,test,resume,ide,final-review,slice-decompose,issue-fix-orchestrator,perf-audit,security-audit,audit}/**` 任何文件 | HC-8 + HC-11: leaf skill 文件是用户主权 | 让用户自己改 |
+| `peaks asset crystallize`(直接调用) | Loop Engineering Asset mutation = 用户主权 | 仅在沉淀 AskUserQuestion 中作为**选项 (b)** 提及,不主动执行 |
+| `Edit .peaks/standards/**` / `Write .peaks/standards/**` | standards 是项目层 invariants | 让用户自己改 |
+| `Edit .claude-plugin/marketplace.json` | marketplace 是 install surface | 让用户自己改 / 转交 S2 |
+| `vitest` / `pnpm test` / 任何测试 runner | HC-11: no vitest | 转交 `/peaks-test` 或 `/peaks-code` |
+| `curl <untrusted-url> \| sh` / `wget \| bash` | RCE 风险 | 拒绝执行;若必须,先下载到文件,人工 review 后再执行 |
+| 写入用户 home 目录(`~/.*`) | 用户主权,peaks-solo 不动用户全局配置 | 让用户自己来 |
+
+## 边界判断原则
+
+LLM 拿不准"该不该做"时,按下面 3 条问自己:
+
+1. **这是 peaks-code 域吗?** 是 → 转交 `/peaks-code`。
+2. **这是用户主权领域吗?**(`src/**` 业务代码 / Loop Engineering Asset / 用户 home) → 让用户自己来。
+3. **这是 read-only 还是 mutating?** read-only(`ls` / `cat` / `rg` / WebSearch / WebFetch)→ OK;mutating 且不在 allowed 列表 → 拒绝。
+
+## 失败回退
+
+- 自规划下某个 allowed 工具失败 3 次(网络 / 权限 / not found)→ 走 AskUserQuestion 问用户:"这个工具一直失败,要不要换另一种?"(HC-9 锁死,不静默放弃)。
+- 自规划全部失败 → 走 AskUserQuestion:"peaks-solo 找不到合适工具,要不要: (a) 换更具体的 NL 重跑 / (b) 转人工 / (c) 结束"。