peaks-loop 4.0.0-beta → 4.0.0-beta.11

package/skills/peaks-code/references/micro-cycle.md

@@ -171,20 +171,20 @@ verdict=return-to-rd → RD 修 (new slice 内部走 micro-cycle)
 >
 > When PRD lands, classify the request type before running `peaks request init` for every role — pass `--type <type>` so the artifact records it and downstream transitions enforce the right gates. Misclassifying a feature as `docs` to skip gates is a workflow violation. If a transition fails with `code: PREREQUISITES_MISSING`, the response lists every missing path — produce them, then re-transition. For one-off exceptions, the escape hatch `--allow-incomplete --reason "<text>"` records the bypass in the artifact transition note.
 
-After `peaks-rd` finishes any implementation, repair, or code-output slice, Peaks-Loop Solo MUST automatically route the result to `peaks-qa` without waiting for user confirmation. This is not optional in full-auto mode. Solo must not declare the workflow complete, emit a TXT handoff, or stop at RD completion.
+After `peaks-rd` finishes any implementation, repair, or code-output slice, Peaks-Loop Code MUST automatically route the result to `peaks-qa` without waiting for user confirmation. This is not optional in full-auto mode. Code must not declare the workflow complete, emit a TXT handoff, or stop at RD completion.
 
-**How Solo invokes another role (mechanism, not metaphor):**
+**How Code invokes another role (mechanism, not metaphor):**
 
-Solo is itself a skill running in the current session. There are **two distinct mechanisms** in this skill, and they MUST NOT be confused:
+Code is itself a skill running in the current session. There are **two distinct mechanisms** in this skill, and they MUST NOT be confused:
 
 1. **Swarm fan-out (planning side, after PRD confirmed)** — uses `peaks sub-agent dispatch <role>` to launch real concurrent sub-agents. The CLI returns a per-IDE tool-call descriptor that the LLM executes in its environment. See "Peaks-Loop Swarm parallel phase" above for the full contract. Sub-agents do NOT call Skill(...) back into the role; they execute the role's instructions inline from the prompt.
-2. **Sequential handoff (execution side, RD↔QA repair loop)** — Solo is the only loop, and after RD or QA finishes (whether as a sub-agent or directly), Solo drives the next step from the orchestrator seat. Do NOT use the `Skill` tool to "reactivate" peaks-rd or peaks-qa in the main loop; doing so is the v1.x anti-pattern that masqueraded as "calling the role" but actually just re-prompted the same session. From v1.3 onward, the main loop drives roles via the CLI gate (`peaks request transition`) and reads back artefacts (`peaks request show ... --json`); the actual RD/QA work is either done inline by Solo (when Solo has just been re-invoked by the user) or by a Task sub-agent (in swarm mode).
+2. **Sequential handoff (execution side, RD↔QA repair loop)** — Code is the only loop, and after RD or QA finishes (whether as a sub-agent or directly), Code drives the next step from the orchestrator seat. Do NOT use the `Skill` tool to "reactivate" peaks-rd or peaks-qa in the main loop; doing so is the v1.x anti-pattern that masqueraded as "calling the role" but actually just re-prompted the same session. From v1.3 onward, the main loop drives roles via the CLI gate (`peaks request transition`) and reads back artefacts (`peaks request show ... --json`); the actual RD/QA work is either done inline by Code (when Code has just been re-invoked by the user) or by a Task sub-agent (in swarm mode).
 
-After RD completes (whether inline or sub-agent), Solo does not stop — it must advance to QA. There is no "RD done, ask the user" state in full-auto mode. The only valid stops are: (a) QA verdict=pass, (b) repair cap hit, (c) explicit user cancel.
+After RD completes (whether inline or sub-agent), Code does not stop — it must advance to QA. There is no "RD done, ask the user" state in full-auto mode. The only valid stops are: (a) QA verdict=pass, (b) repair cap hit, (c) explicit user cancel.
 
-**RD's internal reviews are already parallelized.** When RD finishes implementation, it issues a 3-way sub-agent fan-out (code-review + security-review + perf-baseline, see `skills/peaks-rd/SKILL.md` "Parallel review fan-out") and waits for all to return before transitioning to `qa-handoff`. Solo does NOT need to track three separate RD-side sub-runs; the RD role owns the fan-out lifecycle end-to-end. Solo's presence restoration after the swarm converges is the only coordination point.
+**RD's internal reviews are already parallelized.** When RD finishes implementation, it issues a 3-way sub-agent fan-out (code-review + security-review + perf-baseline, see `skills/peaks-rd/SKILL.md` "Parallel review fan-out") and waits for all to return before transitioning to `qa-handoff`. Code does NOT need to track three separate RD-side sub-runs; the RD role owns the fan-out lifecycle end-to-end. Code's presence restoration after the swarm converges is the only coordination point.
 
-**Presence restoration after RD/QA work returns (MANDATORY):** In v1.x, role skills called `peaks skill presence:set <role>` internally and stomped on `.peaks/.active-skill.json`. From v1.3 onward, sub-agents in the Swarm path are forbidden from calling `peaks skill presence:set` (see "Sub-agent dispatch" in each role's SKILL.md), so the main loop's presence file is preserved across the fan-out window by construction. The one place Solo still has to actively restore presence is **once after the fan-out returns** (gate=swarm-converged) and again **after each RD↔QA repair iteration** (gate=repair-cycle-<N>). Use the same command from Step 2 with the current mode and the gate that has just advanced:
+**Presence restoration after RD/QA work returns (MANDATORY):** In v1.x, role skills called `peaks skill presence:set <role>` internally and stomped on `.peaks/.active-skill.json`. From v1.3 onward, sub-agents in the Swarm path are forbidden from calling `peaks skill presence:set` (see "Sub-agent dispatch" in each role's SKILL.md), so the main loop's presence file is preserved across the fan-out window by construction. The one place Code still has to actively restore presence is **once after the fan-out returns** (gate=swarm-converged) and again **after each RD↔QA repair iteration** (gate=repair-cycle-<N>). Use the same command from Step 2 with the current mode and the gate that has just advanced:
 
 ```bash
 peaks skill presence:set peaks-code --project <repo> --mode <mode> --gate <current-gate>
@@ -192,13 +192,13 @@ peaks skill presence:set peaks-code --project <repo> --mode <mode> --gate <curre
 
 This keeps the CLAUDE.md status header accurate (`Peaks-Loop Skill: peaks-code`) instead of showing a stale role name. Use the current mode and gate values; the gate may have advanced since startup. Skipping this step causes the header to display the last-known gate permanently.
 
-**Full-auto auto-proceed rule**: In the `full-auto` profile, when RD transitions to `qa-handoff`, Solo immediately drives QA — by launching a `peaks sub-agent dispatch qa` sub-agent carrying the `peaks-qa` body (swarm path), then executing the returned toolCall, or by running QA inline in the main loop (assisted/strict path). Do not pause, do not ask the user, do not summarize RD results as if they were final. The only valid reason to skip QA is when `--type` is `docs` or `chore` (no acceptance surface).
+**Full-auto auto-proceed rule**: In the `full-auto` profile, when RD transitions to `qa-handoff`, Code immediately drives QA — by launching a `peaks sub-agent dispatch qa` sub-agent carrying the `peaks-qa` body (swarm path), then executing the returned toolCall, or by running QA inline in the main loop (assisted/strict path). Do not pause, do not ask the user, do not summarize RD results as if they were final. The only valid reason to skip QA is when `--type` is `docs` or `chore` (no acceptance surface).
 
 A QA report with any failing, blocked, missing, or unverified acceptance item is not a pass.
 
-**How Solo routes QA findings back to RD (mechanism, not metaphor):**
+**How Code routes QA findings back to RD (mechanism, not metaphor):**
 
-When `peaks-qa` returns `verdict=return-to-rd`, Solo does NOT manually rewrite RD artifacts. Instead it follows this exact sequence:
+When `peaks-qa` returns `verdict=return-to-rd`, Code does NOT manually rewrite RD artifacts. Instead it follows this exact sequence:
 
 1. Read the QA verdict and findings via `peaks request show <rid> --role qa --project <repo> --json`. The findings live in the QA artifact body (failing acceptance items, evidence paths, severity).
 2. Transition the RD artifact back from `qa-handoff` to a working state and record the QA verdict in the transition note:
@@ -209,13 +209,13 @@ When `peaks-qa` returns `verdict=return-to-rd`, Solo does NOT manually rewrite R
    ```
    `spec-locked` is the canonical "needs more RD work" state. The reason is mandatory in repair cycles so the artifact history shows the loop.
 3. Re-launch `peaks-rd` work. Two paths, mode-driven:
-   - **Swarm / full-auto**: launch a fresh `peaks sub-agent dispatch rd` sub-agent (then execute the returned toolCall) with the same `peaks-rd` body used in the Swarm phase, plus the QA findings path so it can read the failure list. Solo restores presence after the sub-agent returns.
-   - **Assisted / strict / inline-fallback**: Solo executes the RD repair steps directly in the main loop, since there is no concurrent fan-out to coordinate.
+   - **Swarm / full-auto**: launch a fresh `peaks sub-agent dispatch rd` sub-agent (then execute the returned toolCall) with the same `peaks-rd` body used in the Swarm phase, plus the QA findings path so it can read the failure list. Code restores presence after the sub-agent returns.
+   - **Assisted / strict / inline-fallback**: Code executes the RD repair steps directly in the main loop, since there is no concurrent fan-out to coordinate.
    In both paths, pass the QA findings path so the repair sees what failed.
 4. peaks-rd fixes the reported issues only (red-line scope: do not modify unrelated surfaces), regenerates code-review and security-review evidence if changes touched reviewed surfaces, then transitions `rd → implemented → qa-handoff` again.
-5. Solo re-runs QA (sub-agent Task in swarm/full-auto, inline in assisted/strict) with the same `<request-id>`. QA re-runs gates against the new diff.
+5. Code re-runs QA (sub-agent Task in swarm/full-auto, inline in assisted/strict) with the same `<request-id>`. QA re-runs gates against the new diff.
 6. Repeat steps 1-5 until QA returns `verdict=pass`, or the cap below fires.
-   **After each repair iteration** (after peaks-rd and peaks-qa both return), Solo MUST restore presence:
+   **After each repair iteration** (after peaks-rd and peaks-qa both return), Code MUST restore presence:
    ```bash
    peaks skill presence:set peaks-code --project <repo> --mode <mode> --gate repair-cycle-<N>
    ```

package/skills/peaks-code/references/mode-selection-with-stale-presence.md

@@ -62,14 +62,14 @@ peaks skill presence --check-stale --project <path> --json
 
 Returns the same `stale` / `reason` / `currentOuterSessionId` / `recordedOuterSessionId` fields attached to the standard presence envelope. Default `false` (back-compat).
 
-## Pause integration via `peaks solo should-pause`
+## Pause integration via `peaks code should-pause`
 
-`peaks solo should-pause --step step-1-mode-select --mode <mode>` now consults `presence:check-stale` automatically. When stale:
+`peaks code should-pause --step step-1-mode-select --mode <mode>` now consults `presence:check-stale` automatically. When stale:
 
 ```json
 {
   "ok": true,
-  "command": "solo.should-pause",
+  "command": "code.should-pause",
   "data": {
     "shouldPause": true,
     "reason": "stale-presence — re-ask Step 1 (recorded outer session id does not match current)",
@@ -79,7 +79,7 @@ Returns the same `stale` / `reason` / `currentOuterSessionId` / `recordedOuterSe
 }
 ```
 
-The hard-pause on `step-1-mode-select` is preserved for ALL modes (defect #1 fix from slice 2026-06-28-solo-mode-bypass-fix). Stale-presence is an additional reason — even when the user names a profile explicitly, peaks-code can still surface the staleness for visibility.
+The hard-pause on `step-1-mode-select` is preserved for ALL modes (defect #1 fix from slice 2026-06-28-code-mode-bypass-fix). Stale-presence is an additional reason — even when the user names a profile explicitly, peaks-code can still surface the staleness for visibility.
 
 ## Auto-clear on session rotation
 
@@ -108,7 +108,7 @@ peaks workspace init --project . --json
 peaks skill presence:check-stale --project . --json
 # → { stale: true, reason: "no-presence", presence: null }
 
-peaks solo should-pause --step step-1-mode-select --mode full-auto --json
+peaks code should-pause --step step-1-mode-select --mode full-auto --json
 # → { shouldPause: true, reason: "step=step-1-mode-select is a mode/context-selection step → always pause" }
 
 # 3. User picks a profile (or repeats "full-auto"). Then:

package/skills/peaks-code/references/mode-selection.md

@@ -1,13 +1,13 @@
 # Step 1 — Mode selection
 
-> Body of `### Peaks-Loop Step 1`. After Step 0 has anchored the workspace and presence, when the user invokes Peaks-Loop Solo without explicitly naming an execution profile, use `AskUserQuestion` to pick the profile. Present the recommended full-auto path as the first/default option with a practical description for each:
+> Body of `### Peaks-Loop Step 1`. After Step 0 has anchored the workspace and presence, when the user invokes Peaks-Loop Code without explicitly naming an execution profile, use `AskUserQuestion` to pick the profile. Present the recommended full-auto path as the first/default option with a practical description for each:
 
 1. **Full auto (Recommended)** — Peaks-Loop handles planning, role coordination, validation, and compact handoff end-to-end while preserving required confirmation gates for risky or shared-state actions.
 2. **Assisted** — Peaks-Loop proposes plans, artifacts, and checks, then pauses for user decisions at major workflow boundaries.
 3. **Swarm** — Peaks-Loop maximizes safe parallel role/worker execution for larger RD or QA workloads while keeping reducer validation and artifact boundaries explicit.
 4. **Strict** — Peaks-Loop uses the most conservative gates: explicit confirmations, strict slice specs, coverage evidence, QA acceptance, and commit boundaries before continuing.
 
-Map the user's selection to the `--mode` flag value (used by `peaks skill presence:set`; `presence:set --mode` accepts any string, so the name matches the user-facing label rather than overloading "solo" which is also the skill name):
+Map the user's selection to the `--mode` flag value (used by `peaks skill presence:set`; `presence:set --mode` accepts any string, so the name matches the user-facing label rather than overloading "code" which is also the skill name):
 
 | User selects | `--mode` value |
 |---|---|
@@ -16,6 +16,6 @@ Map the user's selection to the `--mode` flag value (used by `peaks skill presen
 | Swarm | `swarm` |
 | Strict | `strict` |
 
-> Note: `peaks workflow route --mode solo|team` is a **different** CLI dimension (solo developer vs team flow) and is unrelated to the profile choice here. Do not conflate them.
+> Note: `peaks workflow route --mode code|team` is a **different** CLI dimension (code developer vs team flow) and is unrelated to the profile choice here. Do not conflate them.
 
 If the user already names a profile in their invocation (e.g. `/peaks-code --full-auto`, "用全自动模式"), skip this question and use the named profile directly.

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

@@ -27,7 +27,7 @@ checkpoint as often as it wants.
 > does **not** expose a `--periodic-every <n>` override flag — the
 > cadence is owned by the skill, not the CLI. Any patch that relaxes
 > this must update both files in lockstep or fail the
-> `tests/unit/solo/checkpoint-periodic-frequency.test.ts` guard.
+> `tests/unit/code/checkpoint-periodic-frequency.test.ts` guard.
 
 ## Checkpoint CLI contract
 
@@ -72,10 +72,10 @@ This step is strictly IDE-agnostic. The LLM calls the peaks CLI; no IDE-specific
 
 ## Companion surface — auto-compact (zero-pause)
 
-When the runner crosses the v2.13.0 auto-compact thresholds (0.85 pre-compact / 0.95 red-line), `peaks session checkpoint` is NOT enough on its own — the LLM must also fire `peaks solo auto-compact --execute` (or wait for the in-band PreToolUse hook at ratio ≥ 0.95 to compact the runner itself). See:
+When the runner crosses the v2.13.0 auto-compact thresholds (0.85 pre-compact / 0.95 red-line), `peaks session checkpoint` is NOT enough on its own — the LLM must also fire `peaks code auto-compact --execute` (or wait for the in-band PreToolUse hook at ratio ≥ 0.95 to compact the runner itself). See:
 
-- `peaks solo auto-compact --execute` — orchestrator that writes the convergence plan + dispatches the compact pathway
+- `peaks code auto-compact --execute` — orchestrator that writes the convergence plan + dispatches the compact pathway
 - `peaks session auto-compact-hook` — the PreToolUse hook entrypoint fired by `.claude/settings.local.json` (slice 2026-07-02-auto-compact-zero-pause)
 - `.peaks/memory/2026-06-27-auto-compact-design.md` — zero-human-intervention design rationale
 
-The two surfaces compose: `peaks session checkpoint` persists the context state, `peaks solo auto-compact` collapses the runner's window. The LLM fires both in the 0.85–0.95 zone; the hook fires alone at ≥ 0.95.
+The two surfaces compose: `peaks session checkpoint` persists the context state, `peaks code auto-compact` collapses the runner's window. The LLM fires both in the 0.85–0.95 zone; the hook fires alone at ≥ 0.95.

package/skills/peaks-code/references/project-scan-checklist.md

@@ -2,7 +2,9 @@
 
 > Extracted from `skills/peaks-code/SKILL.md` on 2026-06-09 (slice 019 — slim skill files to references) to keep SKILL.md under the 800-line cap from `common/coding-style.md`. The content below is the verbatim Pre-RD project scan checklist that was previously inline; nothing was paraphrased, just relocated.
 
-Before handing off to `peaks-rd`, scan the project and record findings to `.peaks/_runtime/<sessionId>/rd/project-scan.md`. RD and UI roles read this before starting work. **project-scan.md is a session-scoped singleton** — check if it already exists before regenerating (e.g. via `ls .peaks/_runtime/<sessionId>/rd/project-scan.md`). If it exists and is complete (has `## Archetype` and `## Project mode` sections), reuse it. Only regenerate if missing or incomplete.
+Before handing off to `peaks-rd`, scan the project and record findings to `.peaks/project-scan/project-scan.md` (project-level, git-tracked; sibling of `.peaks/PROJECT.md`). RD and UI roles read this before starting work. **project-scan.md is a project-scoped singleton** — check if it already exists before regenerating (e.g. via `ls .peaks/project-scan/project-scan.md`). If it exists and is complete (has `## Archetype` and `## Project mode` sections), reuse it. Only regenerate if missing or incomplete.
+
+> **Slice 2026-07-15-project-scan-bootstrap (G1 + G2 + G4b):** `peaks workspace init` and `peaks project context` now both bootstrap `.peaks/project-scan/project-scan.md` automatically. On a brand-new 0-1 project (no `package.json` or no source files) the file is seeded with `archetype: unknown` + `(empty)` placeholder rows. On an existing project it is filled from `peaks scan archetype` + `peaks scan libraries` output. Idempotent — re-running `workspace init` does NOT overwrite the existing file unless `--force` is passed.
 
 ### 0. Project archetype detection (MANDATORY — run FIRST, deterministic CLI)
 

package/skills/peaks-code/references/quality-gate-cheatsheet.md

@@ -7,7 +7,7 @@
 | `peaks request lint <rid> --role <role> --project <path>` | Scan artifact body for unfilled `<placeholder>`, bare `- ...` bullets, TBD/TODO markers | Before every transition out of `draft` / before role handoff | Any `error`-severity finding (unfilled placeholder, bare-dot bullet) |
 | `peaks request repair-status <rid> --project <path>` | Count RD↔QA repair cycles from `--reason` transition notes ("QA cycle N: ...") | Before every RD repair iteration in step 7 | Cycle count reached the 3-cycle cap |
 | `peaks scan request-type-sanity --project <path> --type <type>` | Cross-verify declared `--type` against the actual `git diff` file mix (catches "feature mis-declared as docs" workflow violations) | After PRD type lock-in AND after each RD repair iteration | Declared type disagrees with the file mix |
-| `peaks scan libraries --project <path>` | Enumerate every dependency + devDependency + peerDependency + optionalDependency with parsed major version; output goes to `## Library versions` in `rd/project-scan.md`. Read-only. | At Solo step 0.6 (alongside `peaks scan archetype`) | Always exits 0 (warnings in JSON envelope; never blocks) |
+| `peaks scan libraries --project <path>` | Enumerate every dependency + devDependency + peerDependency + optionalDependency with parsed major version; output goes to `## Library versions` in `rd/project-scan.md`. Read-only. | At Code step 0.6 (alongside `peaks scan archetype`) | Always exits 0 (warnings in JSON envelope; never blocks) |
 | `peaks slice check [--rid <rid>] [--project <path>]` | 4-stage slice 边界 check (typecheck + unit-tests + review-fanout + gate-verify-pipeline). Aggregate pass/fail; non-zero exit if any stage fails. See "Slice 边界 check" below for usage rules (boundary only, never inside a micro-cycle). | At slice 边界（post-micro-cycle, pre-peaks-qa）| Any stage fails |
 
 Together with `peaks request transition` (which already CLI-enforces per-type artifact prerequisites), these five commands form the runtime quality net. SKILL.md prose is descriptive; the CLI is what physically blocks bad workflows.

package/skills/peaks-code/references/refactor-mode.md

@@ -1,4 +1,4 @@
-# Peaks Solo Refactor Mode
+# Peaks Code Refactor Mode
 
 `peaks-code refactor` is the primary MVP path.
 

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

@@ -26,8 +26,8 @@ peaks skill runbook peaks-code --json
 peaks workspace init --project <repo> --json
 peaks workspace reconcile --project <repo> --json
 peaks scan archetype --project <repo> --json
-# → copy archetype, frontendOnly, signals into .peaks/_runtime/<session-id>/rd/project-scan.md (Peaks-Loop Gate A)
-# → copy libraries[] into .peaks/_runtime/<session-id>/rd/project-scan.md under `## Library versions`
+# → copy archetype, frontendOnly, signals into .peaks/project-scan/project-scan.md (Peaks-Loop Gate A; project-level, git-tracked — slice 2026-07-15-project-scan-bootstrap G1)
+# → copy libraries[] into .peaks/project-scan/project-scan.md under `## Library versions`
 peaks scan libraries --project <repo> --json
 # → if archetype != greenfield AND archetype != unknown:
 peaks scan existing-system --project <repo> --json
@@ -60,7 +60,7 @@ peaks request transition <rid> --role prd --state confirmed-by-user --project <r
 peaks request transition <rid> --role prd --state handed-off --project <repo> --json
 
 # 3. Peaks-Loop Default sub-agent fan-out (slice 5 contract)
-#    Solo computes the swarm plan from --type + frontendOnly + frontend-keyword scan,
+#    Code computes the swarm plan from --type + frontendOnly + frontend-keyword scan,
 #    writes it to .peaks/_runtime/<sid>/sc/swarm-plan.json, then writes the slice
 #    DAG to .peaks/_runtime/<sid>/sc/slice-dag.json and launches ONE
 #    `peaks sub-agent dispatch --from-dag <dag-file>` call. The CLI's
@@ -75,10 +75,10 @@ peaks request transition <rid> --role prd --state handed-off --project <repo> --
 #    `peaks sub-agent dispatch <role>` calls in N separate messages when a fan-out
 #    shape exists — `--from-dag` is the only path that exercises the orchestrator.
 #
-# 3a. Pre-fan-out: Solo initialises every role's request artefact slot in the main
+# 3a. Pre-fan-out: Code initialises every role's request artefact slot in the main
 #     loop so sub-agents find a stable rid <-> artefact binding. Each role's
 #     sub-agent may also call peaks request init itself (idempotent on the same rid);
-#     Solo's call here is the source of truth. Only init roles that are in the
+#     Code's call here is the source of truth. Only init roles that are in the
 #     swarm plan — roles not in the plan do not get a slot yet.
 peaks skill presence:set peaks-code --project <repo> --mode <mode> --gate swarm-fan-out
 # for each role in swarm-plan.subAgents:
@@ -88,7 +88,7 @@ peaks skill presence:set peaks-code --project <repo> --mode <mode> --gate swarm-
 # e.g. if plan = [ui, rd, qa]: run init for ui, rd, qa.
 # If plan = [rd, qa]: run for rd, qa only.
 # If plan = [] (config|docs|chore skip): no inits here, jump to step 4 directly.
-# 3b. Solo writes the slice DAG to a JSON file then issues ONE
+# 3b. Code writes the slice DAG to a JSON file then issues ONE
 #     `peaks sub-agent dispatch --from-dag <dag-file> --batch-id <id>` call.
 #     The CLI envelope returns N parallel buildToolCall descriptors
 #     (dispatchCount = len(swarm-plan.subAgents) when the DAG has >= 2
@@ -98,7 +98,7 @@ peaks skill presence:set peaks-code --project <repo> --mode <mode> --gate swarm-
 #     concurrently, so wall-time approximates max(per-leaf time), not sum.
 peaks sc build-dag --change-id <cid> --project <repo> --json > .peaks/_runtime/<sid>/sc/slice-dag.json
 peaks sub-agent dispatch --from-dag .peaks/_runtime/<sid>/sc/slice-dag.json --batch-id <id> --project <repo> --json
-# 3c. After fan-out, Solo restores presence once and runs Gate B (ls checks):
+# 3c. After fan-out, Code restores presence once and runs Gate B (ls checks):
 peaks skill presence:set peaks-code --project <repo> --mode <mode> --gate swarm-converged
 ls .peaks/_runtime/<sid>/prd/requests/<rid>.md                # PRD artefact must exist (Gate B hard)
 # feature / refactor → ls .peaks/_runtime/<sid>/rd/tech-doc.md
@@ -149,9 +149,7 @@ peaks sc retention --slice-id <rid> --prd <prd> --rd <rd> --qa <qa> --json
 peaks sc validate --slice-id <rid> --json
 peaks sc boundary --slice-id <rid> --artifact <artifact> --code <file> --json
 
-# 9. Peaks-Loop OpenSpec archive (exit gate; only after QA pass, when openspec/ exists)
-peaks openspec validate <cid> --project <repo> --json
-peaks openspec archive <cid> --project <repo> --apply --json
+# 9. Peaks-Loop Workspace reconcile (slate cleanup)
 peaks workspace reconcile --project <repo> --apply --older-than 7
 
 # 10. Peaks-Loop TXT handoff — invoke peaks-txt which embeds memory markers (BLOCKING)
@@ -174,7 +172,7 @@ peaks workspace reconcile --project <repo> --apply --older-than 7
 #       (c) Skip for now — blocks stay in the handoff only, no .peaks/memory/ write"
 #      If 10a returned 0 AND the session surfaced a stable project fact
 #      (decision / convention / approved refactor), STOP — peaks-txt must go
-#      back and embed at least one block before Solo can advance.
+#      back and embed at least one block before Code can advance.
 
 # 10c. After the user picks (a) or (b), run:
 peaks memory extract --project <repo> --artifact .peaks/_runtime/<id>/txt/handoff.md --apply --json
@@ -195,13 +193,13 @@ Repair loop details: see `## Mandatory RD QA repair loop` in SKILL.md for the fu
 # Step 0.8 (BLOCKING): LLM judges Job-shape, CLI records it.
 # This is a RECORDER, not a detector. The LLM supplies --is-job + --rationale;
 # the CLI writes .peaks/_runtime/<sid>/job-shape.json. Downstream steps call
-# `peaks solo read-job-shape` to enforce the decision exists.
+# `peaks code read-job-shape` to enforce the decision exists.
 
 # (The LLM does the semantic judgement, e.g.:)
 #   "The user named N=35 parallel app/ subdirs, said 'continue until all done',
 #    and disavowed cost. isJob=true, rationale=..., suggestedJobId=app-ut-batch,
 #    suggestedStrategy=rotating, confidence=high."
-peaks solo detect-job \
+peaks code detect-job \
   --is-job true \
   --rationale "35 parallel app/ subdirs + 'until all done' + '不用考虑费用'" \
   --suggested-job-id app-ut-batch \
@@ -209,7 +207,7 @@ peaks solo detect-job \
   --confidence high
 
 # Step 0.81-init: if Job-shaped, init BEFORE Step 1.
-DECISION=$(peaks solo read-job-shape --json)
+DECISION=$(peaks code read-job-shape --json)
 if [ "$(echo "$DECISION" | jq -r '.data.decision.isJob')" = "true" ]; then
   JID=$(echo "$DECISION" | jq -r '.data.decision.suggestedJobId')
   STRATEGY=$(echo "$DECISION" | jq -r '.data.decision.suggestedStrategy')
@@ -232,18 +230,18 @@ peaks job subagent-cleanup --job-id <jid> --batch-id <bid> --force   # Step 0.87
 
 # v3.1.2 size-fear ban: refuse to emit a final handoff while remaining > 0.
 # The LLM cannot bypass this; --force-under-job requires explicit user approval.
-peaks solo emit-handoff --project <repo> --job-id <jid> --json
+peaks code emit-handoff --project <repo> --job-id <jid> --json
 
 # v3.1.2 forced auto-compact: when --enforce-job-mode is set OR
 # job-shape.json says isJob=true, ≥0.85 is MANDATORY auto-compact.
-# Solo MUST call this without confirmation under Job mode.
-peaks solo context-now --project <repo> --enforce-job-mode --json
+# Code MUST call this without confirmation under Job mode.
+peaks code context-now --project <repo> --enforce-job-mode --json
 peaks session auto-compact --execute --project <repo> --json
 
 # v3.1.2 PreToolUse gate (installed by `peaks workspace init`):
-# every Bash tool call runs `peaks solo gate-step-08` automatically.
+# every Bash tool call runs `peaks code gate-step-08` automatically.
 # Exit 0 = allow (with optional Next: slice #N+1 of M line when
 # progress.json exists). Exit 2 = BLOCKED; LLM must call
-# `peaks solo detect-job` first.
-peaks solo gate-step-08 --project <repo> --json
+# `peaks code detect-job` first.
+peaks code gate-step-08 --project <repo> --json
 ```

package/skills/peaks-code/references/standards-preflight.md

@@ -7,7 +7,7 @@
 
 Use `standards init` for first-time creation and `standards update` for existing `CLAUDE.md` append/review behavior. In `full-auto` and `swarm` profiles, `--apply` runs automatically after `--dry-run` succeeds — these files live inside the target project, are required for downstream skill preflight, and producing them is part of finishing the workflow (Peaks-Loop Gate G enforces this). `assisted` and `strict` profiles pause for explicit user confirmation between dry-run and apply.
 
-**CRITICAL — Standards must reflect the project scan.** When generating or updating `CLAUDE.md`, the content must reference concrete findings from `.peaks/_runtime/<sessionId>/rd/project-scan.md`: the detected component library (e.g. "This project uses antd 5.x"), CSS solution (e.g. "Uses Less via Umi"), build tool, state management, and routing. Never emit a generic template that says "read .claude/rules/..." without naming the actual project stack. If the project-scan has not been run yet, run it before standards init/update.
+**CRITICAL — Standards must reflect the project scan.** When generating or updating `CLAUDE.md`, the content must reference concrete findings from `.peaks/project-scan/project-scan.md`: the detected component library (e.g. "This project uses antd 5.x"), CSS solution (e.g. "Uses Less via Umi"), build tool, state management, and routing. Never emit a generic template that says "read .claude/rules/..." without naming the actual project stack. If the project-scan has not been run yet, run it before standards init/update.
 
 **Legacy projects additionally** — when archetype ∈ {legacy-frontend, legacy-fullstack, frontend-monorepo}, the `CLAUDE.md` Conventions section MUST extract concrete naming, directory, service-layer, and hooks conventions from `.peaks/_runtime/<sessionId>/system/existing-system.md` and record them as hard constraints for new code. It must also list the `## Legacy constraints` from `project-scan.md` (class components, moment, enzyme, etc.) and instruct that new code in the same module preserves those patterns unless PRD explicitly authorizes modernization. A `CLAUDE.md` for a legacy project that contains only generic rule pointers without naming the actual conventions is a blocking violation — regenerate it.
 

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

@@ -0,0 +1,110 @@
+---
+name: peaks-code-startup-sequence
+description: peaks-code startup sequence Steps 0 / 0.5-0.87 / 1 / 2 / 2.3 / 2.5 / N / N+1 / N+2 — extracted from SKILL.md 2026-07-16 to keep SKILL.md under 25,000-byte cap
+---
+
+# Peaks-Loop Startup sequence (MANDATORY — execute in order)
+
+> **Extracted from SKILL.md on 2026-07-16.** This file is the
+> authoritative reference; SKILL.md points here with a 1-line pointer.
+> Do not edit `SKILL.md` for content changes — edit this file instead.
+
+### Peaks-Loop Slice 011 — workspace consolidate + session checkpoint/resume
+
+`peaks workspace consolidate` is the slice-011 umbrella primitive. `peaks session checkpoint` (context-overflow defense) and `peaks session resume` surface as Step 0.75 + Step N. See `references/cross-date-session-check.md`.
+
+### Peaks-Loop Step 0.75: Resume from checkpoint (BLOCKING on same-day re-invocation)
+
+When a NEW conversation opens on a session whose `lastActivity` is from today AND `.peaks/_runtime/<sessionId>/checkpoints/` has `*.json`, surface via `peaks session info --active --json` + `peaks session resume --from <path> --project <repo>`. Prompt via `AskUserQuestion` (resume / fresh); if "resume", prepend the block. Step 0.75 is no-op on precondition fail. See `references/checkpoint-resume.md`.
+
+### Peaks-Loop Step N: Periodic checkpoint (auto-fire, no user action)
+
+Proactive context-overflow defense. CLI: `peaks session checkpoint [--reason <r>] [...flags]`. Fire `--reason periodic` every 20 tool calls (G1 hard-coded), `--reason artifact-written` per PRD/RD/QA/TXT write. See `references/periodic-checkpoint.md` (otherwise `tests/unit/code/checkpoint-periodic-frequency.test.ts` fails).
+
+### Peaks-Loop Step 0.6: Audit + Goal (NEW)
+
+Invoke peaks-audit after need expressed; store approved goal at `.peaks/_runtime/<sessionId>/audit-goal/<rid>.json`. **All autonomous work requires approved goal.** → `references/audit-goal-gate.md`.
+
+### Peaks-Loop Step N+1: Final Review (NEW)
+
+After autonomous work (RD, QA, security, perf), invoke peaks-final-review for 4-dim evidence. All 4 pass → final delivery; else loop back. See `references/final-review-gate.md`.
+
+### Peaks-Loop Step N+2: Main-session context monitor (D6 + slice 2026-07-02)
+
+After every 4th tool call, probe via `peaks code context-now --project <repo> --json`. Thresholds: 50% / **0.85 pre-compact / 0.95 red-line** (v2.13.0). **In Job mode ≥ 0.85 is MANDATORY auto-compact** (`peaks session auto-compact --execute`). Pass `--enforce-job-mode` for single-rid. **≥ 0.95** red line: next Bash/Task fires `peaks session auto-compact-hook`. **Karpathy §4 exception**: compact red line keeps runner alive — zero-intervention wins; LLM MUST NOT ask user to run `/compact`. Honor `--in-flight-batch` (D6.e).
+
+### Peaks-Loop Step 0: Anchor the workflow (MANDATORY FIRST ACTIONS — no bail-out)
+
+Run `peaks workspace init` + `peaks skill presence:set peaks-code` BEFORE any analysis, role handoff, or mode-selection question. Even "分析下这个项目" / "看一下代码" / one-line questions anchor first.
+
+→ see `references/anchoring-and-session-info.md` for the full Step 0 contract + session-conflict resolution.
+
+#### Step 0 bypass — Claude Code [Fact-Forcing Gate] (slice 2.0.1-bug3)
+
+`peaks workspace init` materializes `.claude/settings.local.json` (a PreToolUse hook allow-list for `.peaks/**` paths and `peaks <subcommand>` Bash) so the [Fact-Forcing Gate] does not block Step 0. Pass `--no-claude-hooks` to opt out.
+
+→ see `references/anchoring-and-session-info.md` for the full bypass contract, recovery flow, and anti-bail-out rule.
+
+### Peaks-Loop Step 0.7: Detect unfinished work and offer resume (BLOCKING on first invocation per session)
+
+After Step 0, run the resume-detection probe; surface via `AskUserQuestion` if a slice is in flight. **v3.1.2 resume rule:** if `.peaks/_runtime/<sessionId>/job/<jid>/progress.json` exists, read FIRST and surface `Next: slice #N of M`. **v2.11.0 D7 override:** if user just `/compact`ed, run `peaks code post-compact-detect --project <repo> --json` FIRST; `shouldAutoResume: true` skips AskUserQuestion. → `references/resume-detection.md`.
+
+### Peaks-Loop Step 0.55: 1.x → 2.0 detection (BLOCKING on first invocation per session, when the project is not on a 2.0 layout)
+
+After Step 0.7 returns "fresh", run `peaks upgrade --detect-1x --project <root> --json`. If `isOneX: true`, surface `AskUserQuestion`. → `references/step-0-55-1x-detection.md`.
+
+### Peaks-Loop Step 0.8 — Job 启动 (BLOCKING on LLM judgement — v3.1.1 patch + v3.1.2 mechanical gates)
+
+> **CLI reality check (D-001 sediment, 2026-07-09):** The CLI surface has changed since this section was last verified. The actual command is **`peaks job init --job-id <jid> --slice-list <list> --main-loop-strategy <single|rotating> [--parallelism-hint <serial|llm-decides>] [--exit-policy <strict|best-effort>] [--project <repo>]`**. The legacy `peaks code detect-job --is-job/--suggested-job-id/--confidence` form described below is **no longer present** in 4.0.0-beta.6. If you find `--is-job` rejected, fall back to `peaks job init`.
+
+The CLI is a **recorder + gate** for job-shape (the LLM judges). LLM calls `peaks job init --job-id <jid> --slice-list <list> --main-loop-strategy <single|rotating>` (with `--caller-id <id>` and `--project <repo>` in non-Claude-Code environments), which writes `.peaks/_runtime/<sessionId>/job/<jid>/state.json` and emits a `[job-event] {kind: job-started, jobId, total, strategy}` line. Downstream steps call `peaks job status --job-id <jid>` to read state.
+
+**Hard rule (v3.1.1 red-line #10):** LLM MUST NOT skip the job-init call. If `peaks job status` reports `done: 0` and the slice work has begun, the LLM forgot to initialize — re-call `peaks job init` immediately.
+
+> **D-003 sediment (2026-07-09):** The historical `JOB_SHAPE_NOT_DECIDED` exception thrown by `read-job-shape` is no longer wired in 4.0.0-beta.6. The current CLI uses `peaks job status` which reports a passive `done: 0` instead of throwing. Both behaviors enforce the same intent (no work may begin before init) but the failure mode is a soft warning rather than a hard exception. LLM should treat `done: 0` after Step 0.8 as a recoverable miss, not an unrecoverable error.
+
+**v3.1.2 mechanical gates** (recorder-only was bypassed twice):
+
+PreToolUse hook on `peaks code gate-step-08`; size-fear ban on `peaks code emit-handoff`; forced auto-compact at ≥ 0.85 in Job mode; on-disk slice progress via `peaks job checkpoint` (canonical reader `peaks job progress --job-id <jid>`). Full mechanics (judgement criteria, hook table, backup-regex rationale, hook wiring) at `references/step-0-8-gate.md`.
+
+### Peaks-Loop Step 0.81 — per-slice 收尾
+
+After commit: `peaks job checkpoint --slice-id <rid> --state done --commit-sha $(git rev-parse HEAD)` → `peaks job status` → loop (remaining>0 → Step 1; ==0 → Step 8/9/10/11; blocked → Step 0.85).
+
+### Peaks-Loop Step 0.85 — slice 阻塞处理
+
+Trigger: `repair-status` atCap=true, context-now red-line ≥5min, or `subagent-cleanup` fails twice. Action: `peaks job block --slice-id <rid> --reason "<reason>"` then STOP.
+
+### Peaks-Loop Step 0.86 — main session rotation
+
+Active in rotating mode; fires every `rotateEvery` slices or via `peaks job rotate-now`. Sequence: cycle-summary → checkpoint rotate-marker → `peaks session rotate` → resume via `peaks session resume --job-id <jid>`.
+
+### Peaks-Loop Step 0.87 — sub-agent cleanup gate
+
+After every `peaks sub-agent dispatch --batch-id <id>` inside a Job, BEFORE next slice checkpoint: `peaks job subagent-cleanup --job-id <jid> --batch-id <id> --force`. Non-zero → block.
+
+→ see `references/job-loop.md` for state machine, visibility, rotation cadence, cross-day recovery, 9 red lines.
+
+### Peaks-Loop Step 1: Mode selection
+
+Use `AskUserQuestion` with `Full auto (Recommended)` first when user did not name a profile OR skill presence is stale (run `peaks skill presence:check-stale --project <path> --json` first; `stale: true` ⇒ re-ask). → `references/mode-selection.md`, `references/fast-mode.md`, `references/mode-selection-with-stale-presence.md`.
+
+### Peaks-Loop Step 2: Re-set skill presence with the chosen mode
+
+Re-run `peaks skill presence:set peaks-code --mode <mode-value> --gate startup`. Install statusline on first run (`peaks statusline install`). → `references/skill-presence-and-title.md`.
+
+### Peaks-Loop Step 2.3: Load project memory (durable, LLM-authored memories)
+
+Run `peaks project memories --project <repo> --json` to read decisions / conventions / modules / rules / lessons from `.peaks/memory`. → `references/project-memory-loading.md`.
+
+### Peaks-Loop Step 2.5: Set session title
+
+Extract a short title from the user's first request (8-20 Chinese chars or 4-10 English words). Run `peaks session title <sessionId> "<title>" --json`. Skip if a title is already set. → `references/skill-presence-and-title.md` (same file as Step 2). D-002: sid is positional, NOT `--session-id` flag (rejected with `error: unknown option`).
+
+## Sub-agent session sharing (MANDATORY — one conversation = one sid)
+
+When peaks-code dispatches a sub-agent (peaks-rd, peaks-qa, peaks-ui, peaks-txt, peaks-sc), the prompt MUST include the parent's sid. The sub-agent MUST NOT call `peaks workspace init` (would orphan the parent's binding).
+
+## Boundaries
+
+Peaks-Loop Code may identify scenarios, recommend profiles, coordinate role skills via artifacts, coordinate project memory extraction, request user confirmation at risk/commit boundaries. MUST NOT silently install hooks / create agents / enable MCP / modify Claude settings / create GitHub repos / bypass role-skill artifacts. → `references/boundaries.md`.

package/skills/peaks-code/references/step-0-55-1x-detection.md

@@ -1,6 +1,6 @@
 # Step 0.55 — 1.x → 2.0 detection reference
 
-> Body of `### Peaks-Loop Step 0.55`. Slice: 2026-06-12-solo-step-0-55-1x-detection.
+> Body of `### Peaks-Loop Step 0.55`. Slice: 2026-06-12-code-step-0-55-1x-detection.
 
 ## Why this step exists
 
@@ -73,10 +73,11 @@ The decision is persisted via `peaks preferences set --project <root> --key auto
 
 ## How this integrates with the rest of the workflow
 
-- Step 0.5 (OpenSpec opt-in) — runs first if `openspec/` is missing.
 - Step 0 (anchor) — runs always.
 - Step 0.7 (resume detection) — runs after Step 0.
 - **Step 0.55 (1.x detection) — runs after Step 0.7, only when the project is not on a 2.0 layout.**
 - Step 1 (mode selection) — runs after Step 0.55.
 
 The 1.x detection is intentionally placed AFTER Step 0.7 because the user might already have a 1.x-converted in-flight slice; the resume flow takes precedence over the upgrade prompt.
+
+> **Historical note (prior to 2026-07-08 RR slice):** an OpenSpec first-run opt-in step (Step 0.5) used to sit between Step 0 and Step 0.7. peaks-code is now decoupled from OpenSpec and does not surface that step; this reference still preserves the historical ordering for context.

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

@@ -1,10 +1,10 @@
-# Peaks-Loop Solo — Step 0.8 (v3.1.1 + v3.1.2) Gate Deep-Dive
+# Peaks-Loop Code — Step 0.8 (v3.1.1 + v3.1.2) Gate Deep-Dive
 
 > Read alongside `SKILL.md` Step 0.8. The SKILL.md header is the LOCKED CONTRACT; this file is the mechanics.
 
-## Recorder contract (`peaks solo detect-job`)
+## Recorder contract (`peaks code detect-job`)
 
-The CLI does NOT judge whether the request is Job-shaped — that is the LLM's job. Keyword regexes are wrong here (too brittle, miss natural-language variants, shift the LLM's semantic understanding into code). The CLI is a **recorder and gate**: the LLM makes the judgement, writes it via `peaks solo detect-job`, and downstream steps refuse to proceed until the decision file exists.
+The CLI does NOT judge whether the request is Job-shaped — that is the LLM's job. Keyword regexes are wrong here (too brittle, miss natural-language variants, shift the LLM's semantic understanding into code). The CLI is a **recorder and gate**: the LLM makes the judgement, writes it via `peaks code detect-job`, and downstream steps refuse to proceed until the decision file exists.
 
 ### LLM judgement criteria (read once, then call the recorder)
 
@@ -16,40 +16,40 @@ The CLI does NOT judge whether the request is Job-shaped — that is the LLM's j
 ### Action sequence
 
 1. LLM reads the user prompt and applies judgement → `isJob: boolean + rationale + suggestedJobId + suggestedStrategy + confidence`.
-2. LLM calls `peaks solo detect-job --is-job <bool> --rationale <text> --suggested-job-id <jid> --suggested-strategy <single|rotating> --confidence <high|medium|low> [--force]`.
+2. LLM calls `peaks code detect-job --is-job <bool> --rationale <text> --suggested-job-id <jid> --suggested-strategy <single|rotating> --confidence <high|medium|low> [--force]`.
 3. CLI records to `.peaks/_runtime/<sessionId>/job-shape.json`.
 4. If `isJob: true` → `peaks job init --job-id <jid> --slice-list <...> --main-loop-strategy <strategy> --rotate-every 3` (BEFORE Step 1).
 5. Downstream steps (Step 1, Step 0.81, etc.) call `read-job-shape` to refuse if missing.
 
 ### Hard rule (v3.1.1 red-line #10)
 
-LLM MUST NOT skip `peaks solo detect-job` even when the trigger is obvious from context. If the next step's `read-job-shape` throws `JOB_SHAPE_NOT_DECIDED`, Solo MUST record a decision before proceeding. Keyword-based "I already know it's a Job" is not a substitute.
+LLM MUST NOT skip `peaks code detect-job` even when the trigger is obvious from context. If the next step's `read-job-shape` throws `JOB_SHAPE_NOT_DECIDED`, Code MUST record a decision before proceeding. Keyword-based "I already know it's a Job" is not a substitute.
 
 ## v3.1.2 mechanical gates
 
 The recorder-only design was bypassed twice under load; the gate must be un-bypassable.
 
-### 1. PreToolUse hook — `peaks solo gate-step-08`
+### 1. PreToolUse hook — `peaks code gate-step-08`
 
-`peaks workspace init` installs the `Bash` matcher `peaks solo gate-step-08 --project .` in `.claude/settings.local.json` (alongside the existing Write|Edit|MultiEdit matcher). The hook runs before every Bash call:
+`peaks workspace init` installs the `Bash` matcher `peaks code gate-step-08 --project .` in `.claude/settings.local.json` (alongside the existing Write|Edit|MultiEdit matcher). The hook runs before every Bash call:
 
 | Condition | Exit | Behaviour |
 |---|---|---|
 | `job-shape.json` exists | 0 (allow) | allow + emit decision; if `progress.json` exists, add `Next: slice #N+1 of M (<currentSlice>)` |
-| `job-shape.json` missing AND prompt matches the fail-closed backup regex | 2 (BLOCKED) | LLM must call `peaks solo detect-job` before retrying |
+| `job-shape.json` missing AND prompt matches the fail-closed backup regex | 2 (BLOCKED) | LLM must call `peaks code detect-job` before retrying |
 | `job-shape.json` missing AND no regex match | 0 (allow) | allow, no Job trigger |
 
-### 2. Size-fear ban — `peaks solo emit-handoff`
+### 2. Size-fear ban — `peaks code emit-handoff`
 
 Refuses to emit a final handoff while `remaining > 0` under Job mode. Pass `--force-under-job` only with explicit user approval.
 
 ### 3. Forced auto-compact — `--enforce-job-mode`
 
-`peaks solo context-now --enforce-job-mode` (auto-enabled when `job-shape.json` says `isJob=true`) returns `action: 'auto-compact-now'` at ≥ 0.85; Solo MUST call `peaks session auto-compact --execute` without confirmation.
+`peaks code context-now --enforce-job-mode` (auto-enabled when `job-shape.json` says `isJob=true`) returns `action: 'auto-compact-now'` at ≥ 0.85; Code MUST call `peaks session auto-compact --execute` without confirmation.
 
 ### 4. On-disk slice progress — `progress.json`
 
-`peaks job checkpoint --state done` writes `progress.json`. `peaks job progress --job-id <jid> [--allow-missing]` is the canonical reader; `peaks solo gate-step-08` also surfaces it on every Bash call so the LLM cannot "wake up cold".
+`peaks job checkpoint --state done` writes `progress.json`. `peaks job progress --job-id <jid> [--allow-missing]` is the canonical reader; `peaks code gate-step-08` also surfaces it on every Bash call so the LLM cannot "wake up cold".
 
 ## Backup regex rationale
 

package/skills/peaks-code/references/step-11-memory-sediment.md

@@ -0,0 +1,56 @@
+# Peaks-Loop Step 11 — Memory sediment (substep details)
+
+Companion to `SKILL.md` §"Peaks-Loop Step 11". This file holds the substep-by-substep bash + flow + sediment history; the SKILL.md only carries the hard-rule one-liner and the link.
+
+## Blocking rule
+
+Code MUST NOT declare a workflow complete until Step 11 has produced ≥ 1 file in `.peaks/memory/` OR the user has explicitly approved a no-sediment outcome via AskUserQuestion. Applies to **all modes** including `assisted` and `strict`.
+
+## Substeps
+
+### 11a — Gate A (txt/ inventory)
+
+```bash
+find .peaks/_runtime/<sessionId>/txt/ -type f -name '*.md' | head
+```
+
+If **0 files** → STOP. Dispatch `peaks-txt` first to write `handoff.md`, then return to 11c.
+
+### 11b — Gate B (memory block embed scan)
+
+```bash
+grep -c 'peaks-memory:start' .peaks/_runtime/<sessionId>/txt/handoff.md || true
+```
+
+If **0 AND this session surfaced a stable project fact** (decision / convention / approved refactor / hard rule), STOP and tell peaks-txt to embed at least one `<!-- peaks-memory:start -->` block first.
+
+### 11c — Canonical extract
+
+```bash
+peaks memory extract --project <repo> --artifact .peaks/_runtime/<sessionId>/txt/handoff.md --apply --json
+```
+
+`--apply` is REQUIRED (without it the command only previews — no files land).
+
+> **CLI reality check (D-010 sediment, 2026-07-09):** The `<!-- peaks-memory:start -->` block must be followed immediately by a **YAML frontmatter** (`title: ...`, `kind: lesson | decision | convention`) and a `---` separator. Each block must close with `<!-- peaks-memory:end -->`. A bare `peaks-memory:start` without the YAML fields is parsed but produces no `plannedWrites` — the CLI silently returns `extractedCount: 0`.
+
+### 11d — Gate C (zero-write outcome)
+
+If `extractedCount === 0` after 11c, fire AskUserQuestion:
+
+> "本次 code 未沉淀任何 `.peaks/memory` 文件。可选: (a) 回去在 handoff.md 嵌入至少 1 个 `peaks-memory:start` block 后重试; (b) 显式接受 no-sediment 并记录为 lesson; (c) 取消完成。"
+
+> **D-010 fix root cause check:** When firing 11d, first inspect whether the block has the YAML frontmatter (`title:` + `kind:` + `---`). If the `<!-- peaks-memory:start -->` exists but no `title:` line follows, fix the block format and re-run 11c — don't ask the user yet. Default option = (a). Code MUST NOT silently accept (b) without user pick.
+
+## Why Step 11 exists
+
+Audit 2026-07-03 confirmed 2 consecutive sessions produced zero `.peaks/memory/` files despite completing RD + QA + handoff artifacts; `assisted` mode silently skipped runbook Step 10 (no STOP condition).
+
+## Why `peaks memory extract` (not `peaks project memories:extract`)
+
+The artifact-scoped extract is canonical; the batch-scoped sibling is for non-handoff flows. Always use `peaks memory extract --apply`.
+
+## Related
+
+- `references/runbook.md` §Step 11 — full bash + flow.
+- `references/project-memory-loading.md` — Step 2.3 memory loading (read-side).