peaks-loop 3.1.2 → 4.0.0-beta.10

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

@@ -0,0 +1,247 @@
+# Peaks-Loop Default Runbook (orchestrator, full-auto profile)
+
+> **Maintenance**: The numbered workflow list in `skills/peaks-code/SKILL.md` (steps 0-11) is the canonical phase sequence. This runbook is the executable CLI transcription. When updating, keep both in lockstep — a change to one must be reflected in the other.
+>
+> **Why this is a reference, not inline**: the runbook is a stable, copy-pasteable shell (~150 lines of bash) that does not change between skill runs. Inlining it bloats the orchestrator skill body past the 800-line cap (per `common/coding-style.md`). Extracting it here keeps SKILL.md focused on flow / decisions / contracts, while the runbook stays as the canonical place for the CLI sequence.
+>
+> **How peaks-loop tooling reads this file**:
+> - `peaks skill runbook peaks-code` (CLI) reads the `## Default runbook` section in either SKILL.md or `references/runbook.md` (whichever has the bash code).
+> - The test in `tests/unit/skill-default-runbook.test.ts` looks for `## Default runbook` in SKILL.md first, then falls back to `references/runbook.md` here.
+
+## Default runbook — CLI sequence
+
+The end-to-end CLI sequence for the `full-auto` profile. `assisted` and `strict` profiles pause at `[CONFIRM]` markers below. `full-auto` and `swarm` auto-proceed through all gates. See Transition Gates for artifact verification at each stage.
+
+Canonical single-shot sub-agent dispatch (the `--prompt` flag is required):
+
+```bash
+peaks sub-agent dispatch <role> --prompt "<body>" --request-id <rid> --batch-id <uuid> --json
+```
+
+```bash
+# 0. Peaks-Loop Snapshot + 0.5 Peaks-Loop Workspace + 0.6 Peaks-Loop Project scan + 0.7 Peaks-Loop Existing-system extraction
+peaks doctor --json
+peaks project dashboard --project <repo> --json
+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/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
+# → copy tokens, sources, conventions, inconsistencies into .peaks/_runtime/<session-id>/system/existing-system.md (Peaks-Loop Gate A.5)
+
+# 1. Peaks-Loop Standards preflight + apply
+#    Run dry-run first to inspect deltas, then APPLY. In full-auto and swarm modes,
+#    --apply is the default — Standards files (CLAUDE.md, .claude/rules/**) live INSIDE
+#    the target project and are required for downstream skill preflight, so producing
+#    them is part of completing the workflow. Assisted/Strict modes pause for [CONFIRM]
+#    between dry-run and apply.
+peaks standards init   --project <repo> --dry-run --json
+# or: peaks standards update --project <repo> --dry-run --json
+peaks standards init   --project <repo> --apply --json
+# or: peaks standards update --project <repo> --apply --json
+# After apply, verify the files actually exist on disk (see Peaks-Loop Gate G).
+
+# 2. Peaks-Loop PRD (Assisted/Strict: [CONFIRM] before confirmed-by-user)
+# Classify the request type from the PRD: feature | bugfix | refactor | docs | config | chore
+# This drives RD/QA gate strictness — see "Mandatory RD QA repair loop" for the matrix.
+peaks request init --role prd --id <rid> --project <repo> --apply --type <type> --json
+# Cross-verify the chosen --type against the current git diff (only meaningful if RD has started writing code;
+# safe to run early too, just expect "no changes" rationale until code lands).
+peaks scan request-type-sanity --project <repo> --type <type> --json
+# → consistent=false → re-classify before continuing. consistent=true → proceed.
+# Lint the PRD artifact before transitioning out of draft.
+peaks request lint <rid> --role prd --project <repo> --json
+# → ok=false → fill in <placeholders>, then re-run.
+peaks request transition <rid> --role prd --state confirmed-by-user --project <repo> --json
+peaks request transition <rid> --role prd --state handed-off --project <repo> --json
+
+# 3. Peaks-Loop Default sub-agent fan-out (slice 5 contract)
+#    Code computes the swarm plan from --type + frontendOnly + frontend-keyword scan,
+#    writes it to .peaks/_runtime/<sid>/sc/swarm-plan.json, then writes the slice
+#    DAG to .peaks/_runtime/<sid>/sc/slice-dag.json and launches ONE
+#    `peaks sub-agent dispatch --from-dag <dag-file>` call. The CLI's
+#    envelope.dispatchCount is N (not 1) when the DAG has >= 2 leaves at the
+#    same topological level — that is the canonical "fan-out" signal. The
+#    orchestrator emits N parallel `buildToolCall` descriptors in ONE response;
+#    the LLM-side runner executes them concurrently.
+#    See "Peaks-Loop Default sub-agent fan-out" above for the default rule and
+#    exceptions; the gate logic is single-sourced in references/swarm-dispatch-contract.md.
+#    Hard rule: do NOT call Skill(skill="peaks-rd" | "peaks-qa" | "peaks-ui") from
+#    the Swarm phase — that's the v1.x anti-pattern. And do NOT issue N sequential
+#    `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: 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);
+#     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:
+# peaks request init --role ui --id <rid> --project <repo> --apply --type <type> --json
+# peaks request init --role rd --id <rid> --project <repo> --apply --type <type> --json
+# peaks request init --role qa --id <rid> --project <repo> --apply --type <type> --json
+# 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. 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
+#     same-level leaves; 1 otherwise). Each prompt embeds the role's body
+#     minus Step 0 / presence, plus the runtime args (rid / sid / mode /
+#     type / paths). The orchestrator's Promise.all drives the N leaves
+#     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, 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
+# bugfix             → ls .peaks/_runtime/<sid>/rd/bug-analysis.md
+ls .peaks/_runtime/<sid>/qa/test-cases/<rid>.md                # QA test-cases (skipped for docs|chore)
+# ui (only when in plan):
+ls .peaks/_runtime/<sid>/ui/design-draft.md 2>&1               # non-blocking (Gate B info)
+# Apply the degradation rules in the main SKILL.md if any artefact is missing.
+# → Peaks-Loop Gate B convergence check. Assisted/Strict: [CONFIRM]
+
+# 4. Peaks-Loop RD planning artifact (the file required by the prerequisite gate)
+#    feature / refactor → write .peaks/_runtime/<id>/rd/tech-doc.md
+#    bugfix             → write .peaks/_runtime/<id>/rd/bug-analysis.md
+#    config             → no planning artifact required at this state
+#    docs / chore       → no planning artifact required
+peaks request transition <rid> --role rd --state implemented --project <repo> --json
+
+# 5. Peaks-Loop Code review + security review BEFORE qa-handoff transition.
+#    Produce the evidence files the CLI gate enforces:
+#      - .peaks/_runtime/<id>/rd/code-review.md     (CRITICAL/HIGH findings + fixes; required for feature/bugfix/refactor)
+#      - .peaks/_runtime/<id>/rd/security-review.md (required for feature/bugfix/refactor/config)
+#    Then transition. If --type is docs/chore the gate is empty and the transition is unguarded.
+peaks request transition <rid> --role rd --state qa-handoff --project <repo> --json
+
+# 6. Peaks-Loop QA validation (AUTO-PROCEED from RD in full-auto)
+#    Before each QA transition, produce the evidence files the CLI gate enforces:
+#      Before qa:running        → .peaks/_runtime/<id>/qa/test-cases/<rid>.md
+peaks request transition <rid> --role qa --state running --project <repo> --json
+#      Before qa:verdict-issued → .peaks/_runtime/<id>/qa/test-reports/<rid>.md
+#                                 + .peaks/_runtime/<id>/qa/security-findings.md
+#                                 + .peaks/_runtime/<id>/qa/performance-findings.md (feature/refactor only)
+peaks request transition <rid> --role qa --state verdict-issued --project <repo> --json
+# → Peaks-Loop Gate D check. Assisted/Strict: [CONFIRM]
+
+# 7. Peaks-Loop RD↔QA repair loop — if verdict is return-to-rd, re-run 4 through 6 until QA passes or blocked TXT.
+#    Before invoking peaks-rd again, check the cycle count so you don't blow past the cap silently:
+peaks request repair-status <rid> --project <repo> --json
+# → atCap=true → STOP and emit a blocked TXT handoff. Do NOT enter another cycle.
+# → remaining > 0 → safe to continue. The next transition's --reason must include "QA return-to-rd cycle N: ..."
+#                   so this command keeps counting accurately.
+# After RD finishes the repair, re-check that the diff is still consistent with the declared --type:
+peaks scan request-type-sanity --project <repo> --type <type> --json
+# → consistent=false → RD scope-creeped during repair; review before re-handoff.
+
+# 8. Peaks-Loop SC phase
+peaks sc impact --change-id <cid> --module <module> --file <path> --json
+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 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)
+#     peaks-txt writes the handoff capsule to .peaks/_runtime/<id>/txt/handoff.md. Inside the
+#     capsule body, peaks-txt embeds <!-- peaks-memory:start --> blocks for every
+#     stable project fact surfaced this session. Applies to ALL modes including
+#     `assisted` (audit 2026-07-03 found `assisted` previously skipped this step).
+#
+# 10a. Skill-side scan (do this BEFORE the AskUserQuestion below):
+#      grep -n "peaks-memory:start" .peaks/_runtime/<id>/txt/handoff.md
+#      Record the count. This is the skill doing the work, not a CLI command —
+#      we deliberately do not ship a `peaks memory scan` because the LLM is
+#      the only consumer and the LLM has grep.
+
+# 10b. AskUserQuestion (only if 10a returned count >= 1):
+#      "The TXT handoff has N peaks-memory:start blocks. Persist to .peaks/memory/?
+#       (a) Apply all — `peaks memory extract --project <repo>
+#                            --artifact .peaks/_runtime/<id>/txt/handoff.md --apply --json`
+#       (b) Apply selectively — re-edit handoff.md first, then re-apply
+#       (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 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
+#      --apply is REQUIRED to write .peaks/memory/; without it the command only
+#      previews. The extract regenerates index.json in the same call.
+
+# 11. Peaks-Loop Final snapshot
+peaks project dashboard --project <repo> --json
+peaks skill doctor --json
+```
+
+Repair loop details: see `## Mandatory RD QA repair loop` in SKILL.md for the full 5-step procedure and the 3-cycle cap. Append transition notes via `--reason` rather than rewriting artifacts during repair cycles.
+
+```bash
+
+# Peaks-Loop Default runbook — Job path (excerpt; full flow in references/job-loop.md)
+
+# 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 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 code detect-job \
+  --is-job true \
+  --rationale "35 parallel app/ subdirs + 'until all done' + '不用考虑费用'" \
+  --suggested-job-id app-ut-batch \
+  --suggested-strategy rotating \
+  --confidence high
+
+# Step 0.81-init: if Job-shaped, init BEFORE Step 1.
+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')
+  # LLM-derived slice list (not CLI-derived).
+  peaks job init --job-id "$JID" --slice-list "<LLM_DERIVED>" --main-loop-strategy "$STRATEGY" --rotate-every 3 --json
+fi
+
+# After Step 7 (RD+QA commit) lands AND Step 0.8 fired (state.json exists):
+peaks job checkpoint --slice-id <rid> --state done --commit-sha $(git rev-parse HEAD)
+# v3.1.2: `peaks job checkpoint --state done` ALSO writes
+# .peaks/_runtime/<sid>/job/<jid>/progress.json. Read it on resume:
+peaks job progress --job-id <jid> --json
+peaks job status --job-id <jid> --json
+peaks job subagent-cleanup --job-id <jid> --batch-id <bid> --force   # Step 0.87 gate
+# Loop control:
+#   remaining > 0  → return to Step 1 (next slice)
+#   remaining == 0 → Step 8/9/10/11 (original tail)
+#   blocked (strict) → peaks job block + STOP
+# Rotating-mode: every rotateEvery slices → Step 0.86 (peaks session rotate + resume)
+
+# 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 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.
+# 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 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 code detect-job` first.
+peaks code gate-step-08 --project <repo> --json
+```

package/skills/peaks-code/references/skill-presence-and-title.md

@@ -0,0 +1,31 @@
+# Step 2 + 2.5 — Skill presence and session title
+
+> Combined body for `### Peaks-Loop Step 2: Re-set skill presence with the chosen mode` and `### Peaks-Loop Step 2.5: Set session title`.
+
+## Step 2 — Re-set skill presence
+
+Step 0 already set presence with no mode. Now that the mode is known (user selected or explicitly named), re-run presence:set so the header/status line shows the profile:
+
+```bash
+peaks skill presence:set peaks-code --project <repo> --mode <mode-value> --gate startup
+```
+
+On the first presence:set in a project, ensure the out-of-band status bar is installed so the user can see at a glance that Peaks is orchestrating — it renders the active skill in Claude Code's terminal status line, independent of model output:
+
+```bash
+peaks statusline install --project <repo>   # idempotent; skips if already installed
+```
+
+Then display the compact status header: `Peaks-Loop Skill: peaks-code | Peaks-Loop Gate: startup | Next: <one short action>`. Display this header on EVERY turn while the skill is active.
+
+Update with `peaks skill presence:set peaks-code --project <repo> --mode <mode> --gate <gate>` when gates change. The presence file persists across the full workflow lifecycle — do NOT clear it at workflow end.
+
+## Step 2.5 — Set session title
+
+Extract a short (8-20 Chinese characters, or 4-10 English words) descriptive title from the user's first request. The title should capture the core task — e.g. "修复登录页OAuth回调异常", "添加暗色模式开关", "搭建项目基础架构". Then run:
+
+```bash
+peaks session title $(peaks session info --active --project "$(git rev-parse --show-toplevel)" --json | python3 -c "import sys,json; print(json.load(sys.stdin)['data']['sessionId'])") "<title>"
+```
+
+If the session directory already has a title (check via `peaks session list --json`), skip this step — the title is already set.

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

@@ -0,0 +1,23 @@
+# Project standards preflight
+
+> Body of `## Peaks-Loop Project standards preflight`. Before orchestrating an end-to-end code repository workflow, gather the project standards preflight status from RD and QA by calling the Peaks-Loop CLI:
+
+- `peaks standards init --project <path> --dry-run`
+- `peaks standards update --project <path> --dry-run`
+
+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/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.
+
+Do not hand-write standards file mutations inside the skill.
+
+For project-analysis requests such as "分析项目" / "分析下这个项目", Step 0 still applies: the workspace is initialized and `peaks-code` presence is set before any analysis output. These requests run the lightweight analysis branch (project scan + standards dry-run) rather than the full RD/QA pipeline, but they never skip workspace anchoring or exit the workflow. The handoff must include an explicit **Standards increment** section. Report the current `CLAUDE.md` and `.claude/rules/**` status from the dry-run output as incremental deltas, not just a generic preflight note:
+
+- whether `CLAUDE.md` is missing, existing, planned, skipped, appended, or review-only;
+- which `.claude/rules/**` files are planned, existing, skipped, appended, or review-only;
+- whether writes were applied or intentionally left as dry-run because authorization or scope was absent;
+- the exact next action if standards should be applied later.
+
+If the dry-run output lacks enough detail to explain those deltas, say that the standards increment is unknown and keep standards application blocked until another `peaks standards init/update --dry-run` provides evidence.

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

@@ -0,0 +1,83 @@
+# Step 0.55 — 1.x → 2.0 detection reference
+
+> Body of `### Peaks-Loop Step 0.55`. Slice: 2026-06-12-code-step-0-55-1x-detection.
+
+## Why this step exists
+
+The peaks-loop 1.x → 2.0 closeout ships:
+
+1. A postinstall that auto-detects 1.x state and dispatches the upgrade (slice 1, commit `b6e34e6`).
+2. A standards-migrate path that thins `.claude/rules/**/*.md` and scaffolds `.peaks/standards/` (slice 2, commit `33dd392`).
+3. **THIS STEP** — a peaks-code startup sequence probe that detects 1.x state when the user invokes `/peaks-code` directly in a 1.x consumer project, and prompts the user to upgrade.
+
+The 1.x user experience is: "I just typed /peaks-code. Why is it not working in 2.0 mode?" Step 0.55 catches this case and surfaces an `AskUserQuestion` with a one-click upgrade.
+
+## Detection algorithm
+
+```bash
+# 1. Read-only probe via the umbrella CLI
+peaks upgrade --detect-1x --project <root> --json
+```
+
+The CLI returns:
+```json
+{
+  "ok": true,
+  "command": "upgrade.detect-1x",
+  "data": {
+    "isOneX": true,
+    "signals": [
+      "<path> has schema_version 1.0.0, expected '2.0.0'",
+      "..."
+    ],
+    "projectRoot": "/path/to/project",
+    "configPath": null
+  },
+  "warnings": [],
+  "nextActions": [
+    "Detected 1.x state. peaks-code Step 0.55 should present an AskUserQuestion to invoke `peaks upgrade --to 2.0 --auto --project /path/to/project`."
+  ]
+}
+```
+
+The detection logic mirrors `scripts/install-skills.mjs:detect1xProjectState` (canonical implementation) — it walks up to find `.peaks/_runtime/`, then sniffs:
+
+1. `~/.peaks/config.json` for `version: 1.x`
+2. `<projectRoot>/.claude/rules/common/dev-preference.md` for "peaks progress"
+3. `<projectRoot>/.peaks/preferences.json` for missing or non-`2.0.0` `schema_version`
+
+The TS mirror in `src/services/upgrade/1x-detector-service.ts` is the canonical entrypoint for the skill; the postinstall `.mjs` version is the canonical entrypoint for the npm-install flow. The two implementations MUST stay in parity (a parity test is in the slice's test suite).
+
+## AskUserQuestion (only when `isOneX: true`)
+
+| Option | What it does |
+|---|---|
+| Run `peaks upgrade --to 2.0 --auto --project <root>` (Recommended) | Invokes the umbrella. The user sees the 6 sub-step results in the terminal. After the upgrade, re-run peaks-code with the standing 2.0 layout. Persist `autoUpgradePrompt: opt-in` to `.peaks/preferences.json`. |
+| Skip for this session | Continue with the standing 1.x layout. Persist `autoUpgradePrompt: skip-this-session` to `.peaks/preferences.json`. The next time the user invokes peaks-code in this project, the question re-asks. |
+| Never ask again for this project | Persist `autoUpgradePrompt: skip-forever` to `.peaks/preferences.json`. Step 0.55 becomes a no-op for this project from now on. The user can re-enable later by removing the `autoUpgradePrompt` key from preferences.json. |
+
+## Persistence contract
+
+The decision is persisted via `peaks preferences set --project <root> --key autoUpgradePrompt --value <opt-in|skip-this-session|skip-forever> --apply`. Subsequent Step 0.55 invocations read the value first:
+
+- If `opt-in` (and Step 0.55 is the first invocation in the session), the user has already opted in; auto-run the umbrella without re-asking.
+- If `skip-this-session`, the user already said no this session; skip without re-asking (but re-ask next session).
+- If `skip-forever`, the user said no permanently; skip without re-asking.
+- If the key is absent, present the AskUserQuestion.
+
+## What is NOT in this step
+
+- The auto-upgrade execution itself: the umbrella is invoked via the AskUserQuestion's recommended option. The umbrella's behavior (6 sub-commands + write-upgrade-record) is documented in the umbrella's own help text.
+- The postinstall auto-dispatch: that's `scripts/install-skills.mjs:autoUpgrade1xProjectIfPresent`, which fires fire-and-forget on `npm i -g peaks-loop@2.0`. Step 0.55 is the user-invoked path.
+- Re-authoring the 1.x detector heuristics: the implementation is a 1:1 mirror of the canonical `.mjs` version. Drift is prevented by the parity test.
+
+## How this integrates with the rest of the workflow
+
+- 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

@@ -0,0 +1,60 @@
+# 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 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 code detect-job`, and downstream steps refuse to proceed until the decision file exists.
+
+### LLM judgement criteria (read once, then call the recorder)
+
+- N parallel targets (`app/components/*`, `app/modules/*`, `for each subdir`, "以目录为维度", "把剩下的也跑了").
+- Completion phrase implying batch continuation (`until all done`, "继续执行下个 slice", "全部添加完", "all of them").
+- Cost / length disavowal (`不用考虑费用`, "don't worry about cost", "一直跑").
+- Explicit slice count (`25 slices`, "切分成 N 段", "拆成 N 块").
+
+### Action sequence
+
+1. LLM reads the user prompt and applies judgement → `isJob: boolean + rationale + suggestedJobId + suggestedStrategy + confidence`.
+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 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 code gate-step-08`
+
+`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 code detect-job` before retrying |
+| `job-shape.json` missing AND no regex match | 0 (allow) | allow, no Job trigger |
+
+### 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 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 code gate-step-08` also surfaces it on every Bash call so the LLM cannot "wake up cold".
+
+## Backup regex rationale
+
+The fail-closed backup regex (mentioned above) exists so the gate has defense in depth: even if the recorder's downstream enforcement is bypassed, the hook catches obvious Job-shaped prompts. The regex is intentionally narrow — it MUST miss benign prompts and MUST hit obvious batches — so the LLM-side judgement remains primary.
+
+## Hook wiring
+
+`peaks workspace init` writes both matchers (Bash + Write|Edit|MultiEdit) atomically; if either fails the whole init fails. `peaks workspace init --remove-hooks` reverses both. The Bash matcher is required for Step 0.8; the Write|Edit|MultiEdit matcher pre-existed (Step 0 [Fact-Forcing Gate]).

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