peaks-loop 4.0.0-beta.2 → 4.0.0-beta.20

package/skills/peaks-content/SKILL.md

@@ -0,0 +1,272 @@
+---
+name: peaks-content
+description: Non-code orchestrator for content workflows (draft / edit / publish / archive). Use when a user wants to drive an end-to-end content-production loop (blog post, newsletter, marketing copy, social thread, doc page) where the LLM must coordinate draft / edit / tone / publish / archive stages with explicit gates between them, and where the user only wants to speak natural language and pick options. NOT for free-form chatting; NOT for code review. Reuses the peaks-loop Loop Engineering primitives (Loop Engineering Asset, Bee Asset, Workflow Trace, Evolution Evaluation) but does NOT import peaks-code internals. Triggers on `/peaks-content`, "peaks content", "content workflow", "publish this to <channel>", "edit the draft", "archive the previous version".
+---
+
+# peaks-content
+
+`peaks-content` is the **content-domain** orchestrator for peaks-loop. It drives an end-to-end content-production loop — draft, edit, publish, archive — through LLM-mediated sub-agents (the "bees") so a non-technical user can produce a polished, channel-ready piece of writing by speaking natural language and picking from multi-choice options. The user never types a CLI verb; the user never hand-authors markdown or JSON; the LLM runs every structured operation on the user's behalf.
+
+This is a **content-domain** orchestrator. It is NOT code (peaks-code does that), NOT research (a future `peaks-research` skill does that), NOT data, NOT medical, and NOT legal. It does NOT import peaks-code internals — it reuses the same Loop Engineering primitives (Loop Engineering Asset, Bee Asset, Workflow Trace, Evolution Evaluation) defined in the shared guideline file at `.peaks/standards/loop-engineering-guidelines.md`.
+
+## Loop Engineering role
+
+`peaks-content` is a **non-crystallizing orchestrator** for the content domain. The skill drives LLM-mediated sub-agents (the "bees" — see "Sub-agents (the bees)") that perform the actual draft / edit / publish work. The skill does NOT crystallize `loop_release` / `bee_release` / `crystallization_event` rows by itself. A user may optionally invoke `peaks asset crystallize` AFTER a run to persist the 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 mirrors the M6 `peaks-maker` pattern: the durable artifact of a content run is the published piece + the archive history, not a peaks-loop SkillHub release. Crystallizing the orchestrator itself would conflate "I shipped a blog post" 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-content` honors `RL-0` (karpathy × darwin co-equal), `RL-1` (Human-NL-Choice-Only), `RL-2` (no durable change pre-run), `RL-8` (peaks-code domain boundary), and `RL-9` (desktop + share go through the peaks CLI).
+
+## When to use
+
+Concrete triggers:
+
+- The user says `/peaks-content` or "peaks content" or "content workflow".
+- "Draft a blog post about `<topic>`" / "write a post on `<topic>`".
+- "Edit the draft" / "tighten the tone" / "check the claims" / "shorten this".
+- "Publish to `<channel>`" / "post this to Medium" / "send the newsletter" / "schedule the thread".
+- "Archive the previous version" / "supersede the old post".
+- "Take this topic from draft to publish" (full-pipeline run).
+- "What stage is `<draft>` in?" (inspect-pipeline-state run).
+- "Save this draft → edit → publish loop as a Loop Engineering asset" (crystallization request — routed to `peaks asset crystallize`).
+
+## When NOT to use
+
+The rubric-banned surfaces — `peaks-content` MUST refuse these targets:
+
+- **Medical advice** — anything that contains (or appears to contain) clinical recommendations, dosage, diagnosis, or treatment. The skill refuses and routes the user to a different peaks-* skill with stricter medical gates.
+- **Legal advice** — anything that contains statutory interpretation, contract review, or jurisdictional guidance. The skill refuses and routes the user to a legal-domain peaks-* skill.
+- **Financial advice** — anything that contains investment guidance, tax planning, or securities recommendations. The skill refuses and routes the user to a finance-domain peaks-* skill.
+- **User-generated content moderation** — bulk review, flagging, takedown, or appeal handling for user-submitted content is a different policy with different gates; the user must use a moderation-specific peaks-* skill.
+- **Personal data extraction** — drafts that ingest emails, phone numbers, addresses, government IDs, or other PII into the piece. The skill refuses to ingest PII (see RL-2).
+- **Code-coupled content** — drafts that require the LLM to write or modify source code (e.g. "show me the API response in this post") are routed to peaks-code for the code part; the content part stays here, but only after the code piece is stable.
+- **Hand-authored markdown / JSON** — anything that requires the user to type markdown structure or fill a JSON file. The LLM authors the markdown; the user describes the intent in NL.
+
+If the only available candidate falls in a banned surface, the skill surfaces the skip list with reasons and asks the user to expand the topic source — it does not bypass the rubric.
+
+## Domain boundary (RL-8 echo)
+
+`peaks-content` is **content-domain only**. It does NOT do code, research, data, medical, or legal. Cross-domain work goes to:
+
+- `peaks-code` for code.
+- `peaks-research` (future) for research.
+- `peaks-product` (future) for product artifacts.
+- A medical-domain peaks-* skill for medical content.
+- A legal-domain peaks-* skill for legal content.
+
+Each of these is a separate orchestrator skill, NOT a subclass of `peaks-content` and NOT a subclass of `peaks-code`. Each must import `.peaks/standards/loop-engineering-guidelines.md` and pass `peaks skill lint --category loop-engineering-readiness`.
+
+## 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. **A. Run a stage on a piece** — "draft a post about `<topic>`" / "edit the draft" / "publish to `<channel>`" / "archive `<old-version>`". The user names the stage; the LLM finds the piece in `.peaks/content/drafts/` and runs only that stage.
+2. **B. Run a full pipeline** — "take this topic from draft to publish". The skill proposes the 4-stage chain (draft → edit → publish → archive) and asks for one confirm pick.
+3. **C. Inspect pipeline state** — "what stage is `<draft>` in?" The skill reads the frontmatter and returns a one-screen status.
+4. **D. Crystallize the workflow** — "save this draft → edit → publish loop as a Loop Engineering asset". The skill routes to `peaks asset crystallize` after a successful run; the crystallization prompt itself is owned by `peaks-maker`, not this skill.
+
+The user also provides: (a) the topic or piece slug (NL — "hermes-agent launch post", "Q3 newsletter", "developer-tool thread"); (b) the target channel (NL — "blog", "Medium", "Twitter thread", "email newsletter", "internal doc"); (c) the tone (NL — "casual", "editorial", "technical"); (d) the length target (NL — "500 words", "a long-form post"); (e) the publish deadline (ISO or NL — "next Friday" → the LLM derives an ISO date).
+
+## Default runbook
+
+The 6-step procedure the LLM must follow on every run. The LLM runs the CLI on the user's behalf — the user only describes and picks.
+
+### 1. Anchor + skill marker
+
+```bash
+peaks workspace init --project .
+peaks skill presence:set peaks-content --gate startup
+```
+
+### 2. NL interview (one question at a time)
+
+The LLM asks ONE question at a time (the "test user does not know the system" scenario). The interview collects: the piece slug (or the LLM looks it up in `.peaks/content/drafts/`), the target channel, the tone, the length target, and the publish deadline. The user never sees a JSON form or a CLI prompt — every input is a multi-choice pick or free-form NL.
+
+### 3. Draft stage — `bee-content-draft`
+
+The LLM dispatches to the draft bee. The draft is a plain markdown file at `.peaks/content/drafts/<slug>.md`. The frontmatter captures the 4-section brief (see "PR / artifact format"). The body is the actual content.
+
+### 4. Edit stage — `bee-content-edit`
+
+A separate edit bee runs. The 4-section gate fires between draft and edit:
+
+- **Tone gate** — the edit bee confirms the piece matches the user-confirmed tone.
+- **Factual-claims gate** — the edit bee flags any claim that lacks a citation. Drafts with unflagged claims cannot advance to publish (RL-3).
+- **Length gate** — the edit bee confirms the piece is within the user-confirmed length target.
+- **No-PII gate** — the edit bee scans for emails, phone numbers, addresses, government IDs. If any are present, the bee refuses to advance and tells the user which lines to remove (RL-2).
+
+### 5. Publish stage — `bee-content-publish` (GATED on user pick)
+
+A separate publish bee runs. The gate fires between edit and publish: the user (Human-NL-Choice-Only) confirms the **final draft + target channel** via `AskUserQuestion`. The skill MUST ask the user to pick the final channel + final tone + final length before any external write. Only after the user's pick is captured does the publish bee run.
+
+**Hard rule (RL-1 enforcement):** the skill MUST refuse to write to any external channel (Twitter / Medium / email / Discord / etc.) without an explicit user pick. The user is the only actor who can authorize an external write. The LLM may prepare the payload (markdown, tags, schedule), but the actual outbound call is gated on the user's choice.
+
+### 6. Archive stage — `bee-content-archive`
+
+The previous version of the piece (if any) is moved to `.peaks/content/archive/<channel>/<slug>-<version>.md`. A `crystallization_event` is recorded for the full run only if the user picked option D in the inputs (and even then, the crystallization itself is owned by `peaks-maker` via `peaks asset crystallize`).
+
+## Sub-agents (the bees)
+
+The skill orchestrates four bees. Each bee is a sub-agent dispatch; the skill is the orchestrator that schedules them. Each bee has its own prompt + context; none of them touch the user's content directly without the orchestrator passing them the artifact path.
+
+- `bee-content-draft` — generates the first draft from a brief. Consumes: topic + tone + length + audience. Produces: `.peaks/content/drafts/<slug>.md` with frontmatter + body.
+- `bee-content-edit` — runs tone / factual / length / PII checks. Consumes: the draft path + the frontmatter brief. Produces: an edit report (line-level findings) + an advance/blocked verdict.
+- `bee-content-publish` — formats + posts to the channel (gated on user pick). Consumes: the final-draft path + the user-confirmed channel. Produces: the outbound payload + the publish receipt.
+- `bee-content-archive` — moves the previous version to the archive dir. Consumes: the current-version path + the new-version path. Produces: the archived copy + a manifest update.
+
+## PR / artifact format
+
+The markdown file header used in `.peaks/content/drafts/<slug>.md`:
+
+```markdown
+---
+title: <piece title>
+channel: <target channel>
+status: draft | edit | publish | archive
+version: <semver>
+created_at: <ISO>
+updated_at: <ISO>
+author_intent_raw: <the user's original NL request>
+tone: <user-confirmed tone>
+length_target: <user-confirmed length>
+publish_deadline: <ISO or null>
+crystallization_event: <id or null>
+---
+```
+
+The 4-section brief is stored as the frontmatter; the body is the actual content. This mirrors M4/M5 evidence-brief conventions. The `crystallization_event` field is null unless the user picked option D in the inputs and a crystallization event was recorded by `peaks-maker`.
+
+## Red lines (karpathy 4-section form)
+
+Each red line below 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 (echo; the publish gate)
+
+**Failure modes.** User is asked to hand-fill JSON or type a CLI verb; user pushed into schema decisions; user accepts opaque publish recommendations by default; the publish bee writes to an external channel without an explicit user pick.
+
+**Rewrite.** Every user input is either an `AskUserQuestion` multi-choice pick or free-form NL. The LLM runs the CLI. The publish bee is gated on an explicit `AskUserQuestion` confirm of channel + tone + length; the LLM may prepare the payload, but the outbound call only fires after the pick.
+
+**Self-check.** Did any step require the user to type a verb? Is the publish bee blocked until the user picks the channel? Does every recommendation include an evidence brief? Does the new 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 personal data (PII) in any draft
+
+**Failure modes.** A draft contains an email, phone number, postal address, or government ID; the edit bee advances the piece anyway; the piece publishes with PII and the user's privacy is exposed.
+
+**Rewrite.** The edit bee MUST scan the draft for emails, phone numbers, addresses, and government IDs. If any are present, the bee refuses to advance and the user must explicitly remove them before the next gate. Forbidden patterns: `\b\S+@\S+\.\S+\b`, `\b\d{3}[-.\s]?\d{3}[-.\s]?\d{4}\b`, any 9-digit numeric run, any line containing "SSN" / "passport" / "driver's license".
+
+**Self-check.** Does the edit bee's report include a PII scan section? Are any of the forbidden patterns matched in the draft? If matched, did the bee refuse to advance?
+
+**Out-of-scope.** Public-figure bylines (the user explicitly opted in to a public byline at draft time), branded content that names the user's company (not personal data).
+
+## RL-3 — No fabricated citations / facts
+
+**Failure modes.** A draft makes a claim ("X% of users prefer Y") with no citation; the edit bee advances the piece anyway; the piece publishes with unverified claims and the user's credibility is exposed.
+
+**Rewrite.** The edit bee MUST flag any claim that lacks a citation. Drafts with unflagged claims cannot advance to publish. A "claim" is any sentence containing a number, a percentage, a date, a named study, or a comparative ("X is faster than Y"). A "citation" is a URL, a paper title, or a user-supplied source pointer.
+
+**Self-check.** Does the edit bee's report include a claims-without-citations list? Is the list empty? If non-empty, did the bee refuse to advance?
+
+**Out-of-scope.** Subjective opinions ("I think X"), user-supplied anecdotes ("in my experience"), or branded opinions ("we believe X") — these are not factual claims.
+
+## RL-4 — One piece = one decision
+
+**Failure modes.** The LLM batch-publishes multiple pieces in one user pick; the user did not see each piece's final draft; an embarrassing piece slips through with the good ones.
+
+**Rewrite.** Each piece gets its own confirm pick. The publish bee is invoked once per piece. The user sees the final draft of THIS piece only and confirms THIS piece's channel + tone + length. No "publish all 5 of these" UI affordance is offered.
+
+**Self-check.** Did the user see a confirm pick for THIS piece? Did the publish bee run for THIS piece only? Is the count of pieces the user confirmed equal to the count of pieces the publish bee ran for?
+
+**Out-of-scope.** A user-explicit "publish the whole batch" — the skill surfaces the list, asks the user to confirm each one, and refuses to bulk-publish.
+
+## RL-5 — Tone + length + channel are user-confirmed before publish
+
+**Failure modes.** The LLM infers tone / length / channel from the brief alone; the user did not confirm; the piece publishes with the wrong shape.
+
+**Rewrite.** The publish bee refuses to run without these three fields set in the frontmatter. The user-confirmed values come from the `tone`, `length_target`, and `channel` fields of `.peaks/content/drafts/<slug>.md`. If any of the three is null or empty, the publish bee returns `BLOCKED_NEEDS_USER_CONFIRM`.
+
+**Self-check.** Are all three frontmatter fields non-null at publish time? Did the user confirm each of the three in the publish-gate pick? If any field changed during edit, did the user re-confirm?
+
+**Out-of-scope.** Auto-correction at edit time — the edit bee may propose a tone tweak, but the user must re-confirm before the publish bee runs.
+
+## RL-6 — Drafts are immutable once published
+
+**Failure modes.** A live edit modifies a published piece without archiving the previous version; the user loses the audit trail; the piece's history is untraceable.
+
+**Rewrite.** Once a piece is published, the only path to update it is the archive step. A "live edit" without archive is forbidden. The archive step moves the previous version to `.peaks/content/archive/<channel>/<slug>-<version>.md` before the new version is written.
+
+**Self-check.** Is the previous version present in the archive dir? Does the new version have a semver greater than the archived one? Did the archive step run BEFORE the new write?
+
+**Out-of-scope.** Typo fixes — those go through the same archive step (typo fixes are version bumps, not silent edits).
+
+## RL-7 — No medical / legal / financial advice
+
+**Failure modes.** The LLM drafts a piece that contains medical dosage, legal interpretation, or investment guidance; the user ships it; the user is exposed to liability.
+
+**Rewrite.** The skill MUST refuse to draft any piece that contains (or appears to contain) advice in those domains. The trigger phrases are checked at draft time: any sentence containing "should take", "is safe to", "prescribe", "diagnose", "statute", "case law", "investment recommendation", or similar domain markers → the skill refuses and routes the user to the appropriate peaks-* skill.
+
+**Self-check.** Does the draft contain any of the forbidden trigger phrases? If yes, did the skill refuse to advance? Did the skill surface the skip list with reasons?
+
+**Out-of-scope.** General-audience health explainers ("how sleep works"), legal news summaries ("the EU passed a law"), financial education ("how index funds work") — these are not advice in the actionable sense.
+
+## RL-8 — Cross-domain work is a different skill
+
+**Failure modes.** The skill smuggles code-writing into a blog post; the user gets a code-coupled draft that the LLM cannot reliably produce; the content piece relies on broken code.
+
+**Rewrite.** If the user asks for a content piece that requires code (e.g. "show me the API response in this post"), the skill routes the code part to `peaks-code`; the content part stays here, but only after the code piece is stable and reviewed. The skill never writes or modifies source code.
+
+**Self-check.** Does the draft reference code that the LLM authored? If yes, did that code go through `peaks-code` first? Is the code piece reviewed and stable?
+
+**Out-of-scope.** Documentation pages that link to existing code snippets in the user's repo (read-only references, no code authoring).
+
+## RL-9 — Crystallization is opt-in
+
+**Failure modes.** The skill auto-crystallizes a run, polluting the user's SkillHub with one-off content runs; the user did not opt in; the asset pool fills with low-signal content loops.
+
+**Rewrite.** The skill does NOT auto-crystallize. The user must pick option D in the inputs to crystallize a run as a Loop Engineering asset. Even then, the crystallization itself is owned by `peaks-maker` via `peaks asset crystallize`; the skill only records the run in the frontmatter `crystallization_event` field.
+
+**Self-check.** Is the `crystallization_event` field null unless the user picked option D? Did the skill refuse to call `peaks asset crystallize` without the user pick?
+
+**Out-of-scope.** Replay of a previously crystallized content run — the replay is a new run, not a new crystallization; the frontmatter `crystallization_event` field points to the existing asset, not a new one.
+
+## Boundaries
+
+What this skill MUST NOT do:
+
+- **Publish to any external channel without an explicit user pick** (RL-1 / RL-5).
+- **Touch the user's repo** (write to source code) — `peaks-code` does that.
+- **Hand-author markdown / JSON on the user's behalf** when the user is just describing intent.
+- **Ingest personal data** into the draft (RL-2).
+- **Run a publish** without the user-confirmed tone / length / channel (RL-5).
+- **Live-edit a published piece** without archiving the previous version (RL-6).
+- **Draft medical / legal / financial advice** (RL-7).
+- **Smuggle code-writing into a content piece** (RL-8).
+- **Auto-crystallize a run** without the user's option D pick (RL-9).
+- **Batch-publish multiple pieces in one user pick** (RL-4).
+
+## Audit (reproducibility)
+
+The 5-line verification block the user can run after a content run:
+
+```bash
+cat .peaks/content/drafts/<slug>.md            # piece exists, frontmatter is complete
+git status .peaks/content/                    # archive step committed
+cat .peaks/content/archive/<channel>/<slug>-<version>.md 2>/dev/null   # previous version archived
+.peaks/standards/loop-engineering-guidelines.md -c "RL-1|RL-5|RL-7"   # ensure RLs are referenced
+.peaks/_runtime/<sessionId>/crystallization-event.json 2>/dev/null   # crystallization event if user picked D
+```
+
+If any line returns an unexpected value, the run has been mutated externally; the per-piece frontmatter + the archive history are the source of truth.
+
+## First-class outputs
+
+The skill produces the following files for the user to verify:
+
+- `.peaks/content/drafts/<slug>.md` — the working draft (frontmatter + body).
+- `.peaks/content/drafts/<slug>.edit-report.md` — the edit bee's report (tone / factual / length / PII findings).
+- `.peaks/content/archive/<channel>/<slug>-<version>.md` — the previous version (after archive step).
+- `.peaks/content/published/<channel>/<slug>-<version>.md` — a copy of the published piece (for audit; the real publish lives on the channel).
+- `.peaks/_runtime/<sessionId>/peaks-content/run-summary.md` — the LLM's run summary (stage sequence, gate verdicts, user picks).
+- `.peaks/_runtime/<sessionId>/peaks-content/publish-receipt.json` — the publish bee's receipt (channel, post URL, timestamp).
+- `.peaks/_runtime/<sessionId>/crystallization-event.json` — the crystallization event (only if the user picked option D).

package/skills/peaks-doctor/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: peaks-doctor
 description: Orchestrate peaks-loop's L3 doctor (peaks audit + peaks doctor + peaks openspec from-doctor) for project health. Use when the user asks for a project health check, doctor report, audit, or wants to convert doctor findings into OpenSpec change records. Coordinates the L2 audit framework + the L3.2 doctor + the L3.3 from-doctor proposal generator. Triggers on `/peaks-doctor`, "peaks doctor", "项目健康", "doctor report", "health check", "check the project", "audit my repo".
-internal: true
+visibility: internal
 ---
 ---
 

package/skills/peaks-ide/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: peaks-ide
 description: Orchestrate peaks-loop's IDE-aware behavior (hooks + statusline + handle) for a user's specific IDE. Detects the current state (which IDE the user is on, what peaks has already installed), plans the install / switch / status / uninstall actions, and invokes the existing peaks CLI primitives. Triggers on `/peaks-ide`, "set up peaks for my IDE", "switch peaks to Trae", "what did peaks install", "uninstall peaks hooks". Sits between the user and `peaks hooks install` / `peaks statusline install` / `peaks hook handle` — those are the CLI primitives; this skill is the user-facing surface.
-internal: true
+visibility: internal
 ---
 ---
 

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.