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

package/skills/peaks-code/references/swarm-dispatch-contract.md

@@ -1,6 +1,6 @@
 # Swarm dispatch contract
 
-> Reference for `peaks-code` Swarm phase and the role sub-agents (`peaks-ui` / `peaks-rd` planning / `peaks-qa` test-cases). Defines the **mechanism** of fan-out: how Solo launches sub-agents, what the sub-agent prompt must contain, what the sub-agent must return, and how Solo reduces the result.
+> Reference for `peaks-code` Swarm phase and the role sub-agents (`peaks-ui` / `peaks-rd` planning / `peaks-qa` test-cases). Defines the **mechanism** of fan-out: how Code launches sub-agents, what the sub-agent prompt must contain, what the sub-agent must return, and how Code reduces the result.
 
 ## Peaks-Loop Swarm parallel phase (sub-agent fan-out, default)
 
@@ -18,7 +18,7 @@
 > `references/fanout-mandatory.md`).
 
 The Swarm phase is the **default** for any DAG with ≥ 2 leaves at
-the same topological level. Solo derives the fan-out set from the
+the same topological level. Code derives the fan-out set from the
 DAG topology — not from a default of "always launch three", and
 not from a strict conditional check. The swarm gate (PRD state +
 request type + frontend touch), mode-driven fan-out shape, and
@@ -28,7 +28,7 @@ degradation rules live in the references file.
 
 The previous "Swarm" used `Skill(skill="peaks-rd")` calls. That is **single-stack and blocking** — there is no concurrency. Three sequential `Skill` calls run in order on the same main loop, not in parallel. The "parallel Agent calls" wording in the old SKILL.md was a v1.x illusion.
 
-This contract (slice #009) replaces the IDE-private sub-agent literal with the IDE-agnostic primitive `peaks sub-agent dispatch <role>`. The CLI returns a JSON `data.toolCall` descriptor; the LLM executes that tool in its own environment. SKILL.md is now free of IDE-private tool names and the same prompt works on every registered IDE. Real concurrent fan-out is achieved by Solo launching N dispatch calls in a single message and the platform scheduling the returned toolCalls concurrently.
+This contract (slice #009) replaces the IDE-private sub-agent literal with the IDE-agnostic primitive `peaks sub-agent dispatch <role>`. The CLI returns a JSON `data.toolCall` descriptor; the LLM executes that tool in its own environment. SKILL.md is now free of IDE-private tool names and the same prompt works on every registered IDE. Real concurrent fan-out is achieved by Code launching N dispatch calls in a single message and the platform scheduling the returned toolCalls concurrently.
 
 ```
 You are a sub-agent invoked by peaks-code. You are NOT the main Claude session.
@@ -43,7 +43,7 @@ Return a compact JSON envelope — do not write prose.
 - Do NOT ask the user interactive questions. If you need clarification, return
   {"status":"blocked","blockedReason":"<text>"} and let the main loop handle it.
 
-## Runtime arguments (provided by Solo)
+## Runtime arguments (provided by Code)
 - project: <repo>            (git repo root, NOT a sub-package)
 - session-id: <sid>          (from .peaks/.active-skill.json or .peaks/.session.json)
 - request-id: <rid>          (PRD id)
@@ -52,7 +52,7 @@ Return a compact JSON envelope — do not write prose.
 - project-scan-path: <path>  (read this for component library / CSS / build tool)
 - existing-system-path: <path>  (legacy projects only)
 - frontendOnly: <bool>       (from project-scan)
-- frontendKeywordHit: <bool> (Solo's PRD scan result)
+- frontendKeywordHit: <bool> (Code's PRD scan result)
 ```
 
 ### 3.2 peaks-ui sub-agent prompt
@@ -82,7 +82,7 @@ Steps:
    }
 
 If you determine the request is non-visual (no UI surface, no design impact),
-return {"status":"skipped","reason":"non-frontend-request"} so Solo can record
+return {"status":"skipped","reason":"non-frontend-request"} so Code can record
 the misfire in sc/swarm-plan.json.
 ```
 
@@ -97,7 +97,7 @@ Steps:
 1. peaks request init --role rd --id <rid> --project <repo> --apply --type <type> --json
 2. peaks request show <rid> --role prd --project <repo> --json
 3. peaks request show <rid> --role ui  --project <repo> --json  (if ui in plan)
-4. Read <project-scan-path>. If absent and Solo did not pre-create it, create it
+4. Read <project-scan-path>. If absent and Code did not pre-create it, create it
    by running `peaks scan archetype --project <repo> --json` and copying the JSON
    into rd/project-scan.md.
 5. Read <existing-system-path> if archetype is legacy-*.
@@ -144,9 +144,9 @@ If --type is docs|chore, return {"status":"skipped","reason":"type=<type>"} —
 no acceptance surface to plan tests for.
 ```
 
-## 4. Reducer (Solo side)
+## 4. Reducer (Code side)
 
-After all sub-agent dispatch calls return and the LLM has invoked the toolCalls, Solo:
+After all sub-agent dispatch calls return and the LLM has invoked the toolCalls, Code:
 
 1. Restores presence ONCE (not per-agent):
    ```
@@ -158,9 +158,9 @@ After all sub-agent dispatch calls return and the LLM has invoked the toolCalls,
 
 ## 5. Presence restoration (single-shot)
 
-Sub-agents are explicitly forbidden from calling `peaks skill presence:set`. That means `.peaks/.active-skill.json` does not move during the fan-out. Solo sets it to `gate=swarm-fan-out` before fan-out and to `gate=swarm-converged` once after all Tasks return. The status header (the `Peaks-Loop Skill: peaks-code | Peaks-Loop Gate: <gate>` line) therefore reads consistently across the fan-out window.
+Sub-agents are explicitly forbidden from calling `peaks skill presence:set`. That means `.peaks/.active-skill.json` does not move during the fan-out. Code sets it to `gate=swarm-fan-out` before fan-out and to `gate=swarm-converged` once after all Tasks return. The status header (the `Peaks-Loop Skill: peaks-code | Peaks-Loop Gate: <gate>` line) therefore reads consistently across the fan-out window.
 
-If a sub-agent is misbehaving and writes to `.peaks/.active-skill.json` anyway, the next Solo presence-set (after fan-out) overwrites it — the bug self-heals on the next gate advance, but the swarm-phase display may be off. The hard prohibition is there to prevent this; Solo should still treat the file as a single-writer resource.
+If a sub-agent is misbehaving and writes to `.peaks/.active-skill.json` anyway, the next Code presence-set (after fan-out) overwrites it — the bug self-heals on the next gate advance, but the swarm-phase display may be off. The hard prohibition is there to prevent this; Code should still treat the file as a single-writer resource.
 
 ## 6. Why not a `peaks-swarm` skill?
 
@@ -177,18 +177,18 @@ A skill cannot itself trigger sub-agents — the Skill tool runs in the main loo
 
 ### Swarm gate (decide BEFORE fan-out)
 
-> Body of `### Swarm gate`. Before launching any sub-agent, Solo must compute the **swarm plan** from three signals:
+> Body of `### Swarm gate`. Before launching any sub-agent, Code must compute the **swarm plan** from three signals:
 
 1. **PRD state** — `prd/requests/<rid>.md` must be in state `confirmed-by-user` or `handed-off`. If not, STOP. The Swarm is downstream of PRD, not a substitute for it.
 2. **Request type** (`--type` from `peaks request init`):
    - `feature` / `refactor` / `bugfix` → RD(planning) and QA(test-cases) are always in the swarm
    - `config` / `docs` / `chore` → no swarm. RD/QA artefacts are not required by Gates B/C/D for these types. Skip the Swarm phase entirely and proceed to step 4 (RD implementation) with only the PRD in hand.
 3. **Frontend touch** — does the request affect user-visible behavior? This is decided by:
-   - Reading `.peaks/_runtime/<sessionId>/rd/project-scan.md` `## Project mode` for `frontendOnly` (project-shape signal)
+   - Reading `.peaks/project-scan/project-scan.md` `## Project mode` for `frontendOnly` (project-shape signal)
    - **AND** scanning the PRD body for frontend keywords: 页面 / 组件 / 表单 / 弹窗 / 表格 / 样式 / 布局 / 交互 / UI / UX / page / component / form / modal / table / styling / layout / interaction
    - UI joins the swarm when (a) is `true` OR (b) matches. Both signals required `false` to skip UI.
 
-Solo records the swarm plan in `.peaks/_runtime/<sessionId>/sc/swarm-plan.json` so SC and TXT can audit what was launched:
+Code records the swarm plan in `.peaks/_runtime/<sessionId>/sc/swarm-plan.json` so SC and TXT can audit what was launched:
 
 ```json
 {
@@ -200,26 +200,26 @@ Solo records the swarm plan in `.peaks/_runtime/<sessionId>/sc/swarm-plan.json`
 }
 ```
 
-Sub-agent presence in this list = Solo launched a Task for it. Absence = the role was skipped with documented reason.
+Sub-agent presence in this list = Code launched a Task for it. Absence = the role was skipped with documented reason.
 
 ### Mode-driven fan-out shape
 
 > Body of `### Mode-driven fan-out shape`.
 
-| Mode | How the swarm plan is decided | What Solo does |
+| Mode | How the swarm plan is decided | What Code does |
 |---|---|---|
 | `full-auto` | Compute plan from signals above, no question to user | Auto-launch all sub-agents in the plan in parallel |
 | `swarm` | Same as `full-auto` | Same as `full-auto` (this profile name is historical — behavior is identical) |
 | `assisted` | `AskUserQuestion` with three options: (a) Full — UI + RD(planning) + QA(test-cases); (b) Backend-only — RD(planning) + QA(test-cases); (c) Sequential — run RD first, then QA, skip UI | Use the user's choice as the plan |
 | `strict` | Same as `assisted` (the question is informational; strict still enforces confirmation gates later) | Same as `assisted` |
 
-In all modes, **the plan must be written to `sc/swarm-plan.json` before any Task call.** Solo updates `.peaks/.active-skill.json` to `gate=swarm-fan-out` at this point.
+In all modes, **the plan must be written to `sc/swarm-plan.json` before any Task call.** Code updates `.peaks/.active-skill.json` to `gate=swarm-fan-out` at this point.
 
 ### Degradation when swarm roles fail or are absent
 
 > Body of `### Degradation when swarm roles fail or are absent`.
 
-| Condition | Solo action | TXT handoff note |
+| Condition | Code action | TXT handoff note |
 |---|---|---|
 | UI sub-agent returns blocked/error | RD continues with PRD visual descriptions | `ui-design-missing` |
 | RD planning sub-agent returns blocked/error | RD continues with PRD-derived planning | `tech-doc-missing` |

package/skills/peaks-code/references/workflow-gates-and-types.md

@@ -1,6 +1,6 @@
 # Peaks-Loop Workflow Order + Request Type Classification + Transition Verification Gates
 
-> **Maintenance**: This reference holds the canonical contract for (a) how Solo sequences the 11 workflow steps, (b) which `--type` to pass to `peaks request init` for which slice shape, and (c) the executable `ls` / `grep` gate commands that physically block progression. SKILL.md keeps the narrative ("what peaks-code does"); this file keeps the contract.
+> **Maintenance**: This reference holds the canonical contract for (a) how Code sequences the 11 workflow steps, (b) which `--type` to pass to `peaks request init` for which slice shape, and (c) the executable `ls` / `grep` gate commands that physically block progression. SKILL.md keeps the narrative ("what peaks-code does"); this file keeps the contract.
 >
 > **Why extracted from SKILL.md**: this content is 165 lines of mostly-tabular + bash-block contract — reference data, not orchestration prose. Inlining it bloats SKILL.md past the 800-line cap (per `common/coding-style.md`). The numbers, gate command shapes, and type-classification rules change rarely; the SKILL.md prose around them (orchestration flow, repair-loop intent, swarm fan-out shape) changes more often.
 >
@@ -25,11 +25,11 @@ Before initializing any role artifact, classify the request into exactly one of
 
 For ambiguous cases (e.g. "improve login flow"), ask the user to clarify before initializing. The cost of one `AskUserQuestion` round is much lower than running the wrong gate matrix for the whole workflow.
 
-When Peaks-Loop Solo coordinates development in a code repository, keep this order explicit:
+When Peaks-Loop Code coordinates development in a code repository, keep this order explicit:
 
 0. **Peaks-Loop Snapshot** — `peaks doctor` + `peaks project dashboard` to capture baseline state before anything else;
 0.5. **Peaks-Loop Workspace initialization** — `.peaks/_runtime/<session-id>/` created, directory structure verified;
-0.6. **Peaks-Loop Project scan** — archetype, component library, CSS framework, build tool, state management, routing, data fetching, legacy signals detected and recorded to `.peaks/_runtime/<session-id>/rd/project-scan.md`;
+0.6. **Peaks-Loop Project scan** — archetype, component library, CSS framework, build tool, state management, routing, data fetching, legacy signals detected and recorded to `.peaks/project-scan/project-scan.md`;
 0.7. **Peaks-Loop Existing-system extraction** (MANDATORY when archetype ∈ {legacy-frontend, legacy-fullstack, frontend-monorepo}; SKIP for greenfield) — extract visual tokens and code conventions from the live codebase to `.peaks/_runtime/<session-id>/system/existing-system.md`. The path lives under `system/` (not `ui/`) because the file also records non-UI conventions (service-layer signatures, hooks, naming) that backend-only or legacy-fullstack work consumes. See `references/existing-system-extraction.md`. UI design-draft and RD implementation MUST treat the extracted tokens and conventions as hard constraints;
 1. **Peaks-Loop Standards preflight** — `peaks standards init/update --dry-run`, must reference concrete project-scan findings (never emit generic templates);
 2. **Peaks-Loop PRD phase** — capture request as canonical artifact, extract scope and acceptance criteria:
@@ -44,7 +44,7 @@ When Peaks-Loop Solo coordinates development in a code repository, keep this ord
 6. **Peaks-Loop QA validation** (auto-proceed from RD in full-auto) — execute test cases + API checks + Playwright MCP headed browser E2E for frontend + security/perf checks + test report;
 7. **Peaks-Loop RD↔QA repair loop** — if QA verdict is `return-to-rd`, loop back to step 4 (RD implementation) and re-run through QA; max 3 repair cycles, then emit blocked TXT regardless;
 8. **Peaks-Loop SC phase** — change-control evidence: impact, retention, validate, boundary;
-9. **Peaks-Loop OpenSpec archive** — exit gate: validate → archive only after QA verdict=pass (when `openspec/` exists);
+9. **Peaks-Loop Workspace reconcile** — slate cleanup;
 10. **Peaks-Loop TXT handoff capsule** — mode, validated decisions, artifact paths, standards deltas, open questions, next action;
 11. **Peaks-Loop Final snapshot** — `peaks project dashboard` + `peaks skill doctor` to confirm the workflow closed cleanly.
 
@@ -54,8 +54,8 @@ You cannot declare a phase complete from memory. Each gate below is a `ls` comma
 
 **Peaks-Loop Gate A — After workspace init + project scan:**
 ```bash
-ls .peaks/_runtime/<sessionId>/rd/project-scan.md
-# Expected output: .peaks/_runtime/<sessionId>/rd/project-scan.md
+ls .peaks/project-scan/project-scan.md
+# Expected output: .peaks/project-scan/project-scan.md
 # "No such file" → STOP, run project scan first
 # File present but missing `## Archetype` or `## Project mode` sections → INCOMPLETE, rerun scan
 # File present and complete → reuse (project-scan is a session-scoped singleton)

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

@@ -1,17 +1,17 @@
-# Peaks Solo Workflow
+# Peaks Code Workflow
 
-Peaks Solo is a facade over role skills. It keeps the workflow moving without absorbing role-specific responsibility.
+Peaks Code is a facade over role skills. It keeps the workflow moving without absorbing role-specific responsibility.
 
 ## Modes
 
-- Solo: default, single controller with soft gates.
+- Code: default, single controller with soft gates.
 - Assisted: role skills contribute artifacts without broad swarm execution.
 - Swarm: multiple subagents work in parallel when the CLI-managed profile is enabled.
 - Strict: hook/profile guarded mode for high-risk work.
 
 ## Required code workflow evidence
 
-A code workflow is not complete until Solo has linked or summarized:
+A code workflow is not complete until Code has linked or summarized:
 
 1. standards preflight;
 2. PRD/RD scope and OpenSpec artifacts when required;
@@ -31,7 +31,7 @@ For legacy repositories with pre-existing low UT coverage, do not require histor
 
 ## RD QA loop
 
-Every RD implementation or repair slice must be followed by QA validation. If QA does not fully pass, Solo routes the report back to RD, then repeats RD repair and QA validation until QA is all green or the workflow is blocked. In full-auto mode, Claude Code's `goal` command may be used to keep the controller objective explicit while Peaks artifacts remain authoritative.
+Every RD implementation or repair slice must be followed by QA validation. If QA does not fully pass, Code routes the report back to RD, then repeats RD repair and QA validation until QA is all green or the workflow is blocked. In full-auto mode, Claude Code's `goal` command may be used to keep the controller objective explicit while Peaks artifacts remain authoritative.
 
 ## Capability discovery
 

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).