peaks-loop 4.0.0-beta.7 → 4.0.0-beta.8

package/skills/bee/peaks-rd/references/rd-runbook.md

@@ -29,11 +29,11 @@ peaks codegraph context --project <repo> "<task>"
 peaks codegraph affected --project <repo> <changed-files...> --json
 
 # 4.1 read project-scan from Code's pre-RD scan — BLOCKING if missing
-# **STOP if .peaks/_runtime/<sessionId>/rd/project-scan.md does not exist.**
+# **STOP if .peaks/project-scan/project-scan.md does not exist.**
 # **Do not write any code, do not plan any implementation, do not pass go.**
 # **Create the project-scan first, then proceed.**
 # NOTE: 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
+# 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.
 # Required sections in project-scan:
 #   - build tool and framework

package/skills/bee/peaks-rd/references/rd-transition-gates.md

@@ -19,8 +19,8 @@ You cannot declare a phase complete from memory. Each gate below is a `ls` or `g
 
 **Peaks-Loop Gate A — After project-scan read (before any implementation):**
 ```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, create the project-scan first. Do not write code.
 ```
 

package/skills/bee/peaks-rd/references/writing-handoff-frontmatter.md

@@ -33,7 +33,7 @@ nextActions:
   - "peaks-qa reads this handoff and runs the regression matrix"
   - "If Gate C passes, transition to txt handoff"
 gateEvidence:
-  projectScan: .peaks/_runtime/<sessionId>/rd/project-scan.md
+  projectScan: .peaks/project-scan/project-scan.md
   prdHandoff: .peaks/_runtime/<sessionId>/prd/handoff.md
   codeReview: .peaks/_runtime/<sessionId>/rd/code-review.md
   securityReview: .peaks/_runtime/<sessionId>/rd/security-review.md

package/skills/bee/peaks-ui/SKILL.md

@@ -138,7 +138,7 @@ peaks request show <request-id> --role prd --project <repo> --json   # read link
 # browser-launch substitute (it cannot launch a browser of its own).
 
 # 3. read project-scan for component library and CSS framework context
-#    check .peaks/_runtime/<session-id>/rd/project-scan.md (blocking if missing for existing projects)
+#    check .peaks/project-scan/project-scan.md (blocking if missing for existing projects)
 #    NOTE: project-scan.md is a session-scoped singleton — check before regenerating. Reuse if complete.
 
 # 4. PROTOTYPE FIDELITY CHECK (MANDATORY before any design work):
@@ -319,7 +319,7 @@ Every UI invocation touching user-visible behavior MUST produce a design-draft a
 8. **Anti-template checklist** — which generic patterns were rejected.
 
 **Component library awareness rules:**
-- Read `.peaks/_runtime/<session-id>/rd/project-scan.md` before proposing UI changes.
+- Read `.peaks/project-scan/project-scan.md` before proposing UI changes.
 - antd → `theme.token`, `className`/`styles` APIs; no TailwindCSS utilities on antd components.
 - MUI → `sx` prop, `styled()`, `theme`; no TailwindCSS utilities on MUI components.
 - shadcn/ui → TailwindCSS utility classes + existing shadcn variants (expected pattern).

package/skills/peaks-code/SKILL.md

@@ -68,7 +68,7 @@ After autonomous work (RD, QA, security, perf), invoke peaks-final-review for 4-
 
 ### 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** (not advisory): Code MUST call `peaks session auto-compact --execute --project <repo>` autonomously. Pass `--enforce-job-mode` to force the MANDATORY semantics in single-rid mode too (`job-shape.json` auto-enables it). **≥ 0.95** red line: next Bash/Task call fires `peaks session auto-compact-hook` (PreToolUse), in-band spawning `claude --compact`. **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).
+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)
 
@@ -84,17 +84,11 @@ Run `peaks workspace init` + `peaks skill presence:set peaks-code` BEFORE any an
 
 ### 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 it FIRST and surface `Next: slice #N of M (<currentSlice>)`. `peaks job progress --job-id <jid> [--allow-missing]` is the canonical reader; the same JSON is surfaced by `peaks code gate-step-08` on every Bash call.
-
-**v2.11.0 D7 override:** if user just `/compact`ed, run `peaks code post-compact-detect --project <repo> --json` FIRST; `shouldAutoResume: true` skips AskUserQuestion (D7.b). Log to `.peaks/_runtime/<sessionId>/txt/auto-decisions.md`.
-
-→ see `references/resume-detection.md`.
+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`. Persist to `.peaks/preferences.json`. → `references/step-0-55-1x-detection.md`.
+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)
 
@@ -108,12 +102,7 @@ The CLI is a **recorder + gate** for job-shape (the LLM judges). LLM calls `peak
 
 **v3.1.2 mechanical gates** (recorder-only was bypassed twice):
 
-- **PreToolUse hook** — `peaks workspace init` installs the `Bash` matcher `peaks code gate-step-08 --project .`. Exits 0 when `job-shape.json` exists (also emits `Next: slice #N+1 of M` from `progress.json`); exits 2 BLOCKED when missing AND prompt matches a fail-closed backup regex; otherwise 0 (allow).
-- **Size-fear ban** — `peaks code emit-handoff` refuses a final handoff while `remaining > 0` under Job mode.
-- **Forced auto-compact** — `peaks code context-now --enforce-job-mode` (auto-enabled on `isJob=true`) returns `auto-compact-now` at ≥ 0.85; **In Job mode ≥ 0.85 is MANDATORY auto-compact** (not advisory).
-- **On-disk slice progress** — `peaks job checkpoint --state done` writes `progress.json`; `peaks job progress --job-id <jid> [--allow-missing]` is the canonical reader.
-
-Full mechanics (judgement criteria, hook table, backup-regex rationale, hook wiring) at `references/step-0-8-gate.md`.
+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 收尾
 
@@ -121,11 +110,11 @@ After commit: `peaks job checkpoint --slice-id <rid> --state done --commit-sha $
 
 ### 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 with TXT handoff.
+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 on-demand via `peaks job rotate-now`. Sequence: cycle-summary → checkpoint rotate-marker → `peaks session rotate` → next turn resumes via `peaks session resume --job-id <jid>`.
+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
 
@@ -147,9 +136,7 @@ Run `peaks project memories --project <repo> --json` to read decisions / convent
 
 ### 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 <sid> "<title>" --json`. Skip if a title is already set. → `references/skill-presence-and-title.md` (same file as Step 2).
-
-> **CLI reality check (D-002 sediment, 2026-07-09):** The session id is a **positional argument**, not a `--session-id` flag. Correct invocation is `peaks session title 2026-07-08-session-17918f "add-zcode-adapter — peaks-loop 第 9 IDE 接入" --json`. Passing `--session-id` will be rejected with `error: unknown option '--session-id'`.
+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)
 
@@ -157,16 +144,16 @@ When peaks-code dispatches a sub-agent (peaks-rd, peaks-qa, peaks-ui, peaks-txt,
 
 ## Boundaries
 
-Peaks-Loop Code may: identify scenarios, recommend profiles, coordinate role skills through artifacts, coordinate project memory extraction, request user confirmation at risk/commit boundaries. Peaks-Loop Code must NOT silently install hooks / create agents / enable MCP / modify Claude settings / create GitHub repos / bypass role-skill artifacts. → `references/boundaries.md`.
+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`.
 
 ## CLI Drift Index (sediment 2026-07-09)
 
-> **Reading guide:** This document was last verified against CLI surface in **peaks-loop 4.0.0-beta.6**. The CLI has drifted in 4 places since this SKILL.md was last fully aligned. Each drift below is annotated **inline at the relevant step** with a `> CLI reality check` blockquote. When you hit a `error: unknown option ...` error, **read the inline reality check first** before guessing.
+> **Reading guide:** Verified against peaks-loop 4.0.0-beta.6. Each drift below is annotated inline at the relevant step with a `> CLI reality check`. On `error: unknown option ...`, **read the inline reality check first** before guessing.
 
 | Drift ID | Step | Symptom | Fix | Inline location |
 |---|---|---|---|---|
 | **D-001** | 0.8 | `peaks code detect-job --is-job ...` rejected with `error: unknown option '--is-job'` | Use `peaks job init --job-id <jid> --slice-list <list> --main-loop-strategy <single\|rotating>` | §Step 0.8 first paragraph |
-| **D-002** | 2.5 | `peaks session title --session-id <sid> ...` rejected with `error: unknown option '--session-id'` | sid is positional: `peaks session title <sid> "<title>" --json` | §Step 2.5 |
+| **D-002** | 2.5 | `peaks session title --session-id <sid> ...` rejected with `error: unknown option '--session-id'` (this is the bare `<sid>` anti-pattern) | sid is positional: `peaks session title <sessionId> "<title>" --json` | §Step 2.5 |
 | **D-003** | 0.8 | `JOB_SHAPE_NOT_DECIDED` exception expected but never thrown | Current behavior is `peaks job status` reports `done: 0` passively — treat as recoverable miss, not hard error | §Step 0.8 third paragraph |
 | **D-010** | 11c | `peaks memory extract` returns `extractedCount: 0` despite `<!-- peaks-memory:start -->` existing | Block requires YAML frontmatter (`title:` + `kind:` + `---`) + closing `<!-- peaks-memory:end -->`. Bare `peaks-memory:start` is parsed silently but produces no writes | §Step 11c + 11d |
 
@@ -182,7 +169,9 @@ Step 0 creates the workspace; all intermediate artifacts land under `.peaks/_run
 
 ## Peaks-Loop Pre-RD project scan checklist (MANDATORY)
 
-Before handing off to `peaks-rd`, scan the project and record findings to `.peaks/_runtime/<sessionId>/rd/project-scan.md`. → `references/project-scan-checklist.md`.
+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`). Slice 2026-07-15-project-scan-bootstrap (G1 + G2): `peaks workspace init` and `peaks project context` both bootstrap this file automatically; only re-run the manual flow when the scan output is genuinely out of date. → `references/project-scan-checklist.md`.
+
+> **Slice 2026-07-15-project-scan-bootstrap G4b / AC9:** after `peaks workspace init`, the consumer project's `.peaks/project-scan/` directory carries 5 files: `project-scan.md` (generated by the scan logic) + `business-knowledge.md` + `security-template.md` + `perf-template.md` + `audit-output-schema.md` (the 4 audit/business templates bundled at `src/services/workspace/templates/project-scan/*.md`, copied on init; idempotent — existing files preserved unless `--force-project-scan-templates`). RD / UI / TXT / QA read from this tree; nothing else.
 
 ## Peaks-Loop Frontend-only development mode
 
@@ -190,15 +179,13 @@ When the project has no live backend (no swagger.json, no API server), Code must
 
 ## Peaks-Loop Request type classification + Workflow order + Transition verification gates
 
-The contract for the 6-type classification table, the 11-step workflow order, and the 7 transition verification gates (A through G with their `ls` / `grep` shell snippets) lives in `references/workflow-gates-and-types.md`. The peaks-code narrative references those gate numbers (Gate A through Gate G) — keep both files in lockstep when adding or renaming a gate.
+The 6-type table + 11-step order + 7 transition gates (A-G) live in `references/workflow-gates-and-types.md`. peaks-code narrative references Gate A-G — keep both files in lockstep.
 
 ## Peaks-Loop Default sub-agent fan-out (≥ 2 leaves/topological level → `--from-dag`)
 
 > **Slice 5:** when the slice DAG has ≥ 2 leaves at one topological level, dispatch via `peaks sub-agent dispatch --from-dag <dag-file>` (wall-time ≈ max, not sum).
 
-Write DAG → `.peaks/_runtime/<sessionId>/sc/slice-dag.json`, run `peaks sub-agent dispatch --from-dag <dag-file> --batch-id <id>` once; orchestrator emits N parallel `buildToolCall` (`dispatchCount === N`).
-
-> **2026-06-28 校准:** 主路径 = 唯一蜂群;config/docs/chore 跳过不打断。详见 `.peaks/memory/peaks-loop-24h-ai-programmer-positioning.md`。
+Write DAG → `.peaks/_runtime/<sessionId>/sc/slice-dag.json`, run `peaks sub-agent dispatch --from-dag <dag-file> --batch-id <id>` once; orchestrator emits N parallel `buildToolCall` (`dispatchCount === N`). 主路径 = 唯一蜂群;config/docs/chore 跳过不打断。详见 `.peaks/memory/peaks-loop-24h-ai-programmer-positioning.md`。
 
 ### Hard constraint: fan-out is mandatory (slice 2026-06-24-audit-5th-p2)
 
@@ -242,25 +229,7 @@ After final validation, refresh project-local standards via `peaks standards ini
 
 ## Peaks-Loop Step 11: Memory sediment (BLOCKING on workflow complete)
 
-> **Hard rule.** Code MUST NOT declare a workflow complete until Step 11 has produced ≥ 1 file in `.peaks/memory/` (the durable, LLM-authored memory store) OR the user has explicitly approved a no-sediment outcome via AskUserQuestion. Applies to **all modes** including `assisted` and `strict` — `assisted` previously skipped Step 10 because there was no `[CONFIRM]` gate; Step 11 fixes that.
-
-### Substeps (BLOCKING)
-
-**11a — Gate A (txt/ inventory):** `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):** `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** (the only CLI that writes `.peaks/memory/`): `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`. Full format reference: see any successful extract output (e.g. `.peaks/_runtime/2026-07-08-session-17918f/txt/handoff-003-add-zcode-adapter.md`).
-
-**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. Full bash + flow at `references/runbook.md` §Step 11.
-
-**Why this step 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`.
+> **Hard 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. Canonical CLI: `peaks memory extract --project <repo> --artifact .peaks/_runtime/<sessionId>/txt/handoff.md --apply --json` (the artifact-scoped extract; the batch-scoped sibling `peaks project memories:extract` is for non-handoff flows only). Substeps 11a/11b/11c/11d (Gate A/B/C), D-010 fix root cause check → `references/step-11-memory-sediment.md` + `references/runbook.md` §Step 11.
 
 ## Peaks-Loop External references and lifecycle
 
@@ -274,9 +243,9 @@ After final validation, refresh project-local standards via `peaks standards ini
 
 Main LLM reducer sees metadata-only view (~200 chars/sub-agent); on-demand `Read` for full content. Threshold table: 50% soft warn, 75% `CONTEXT_NEAR_LIMIT`, 80% hard reject (CLI + hook double-guard). → `references/context-governance.md`.
 
-## Sub-agent cross-batch signal — G8.4 share / shared-read / await (slice 2026-06-23-audit-3rd)
+## Sub-agent cross-batch signal — G8.4 share / shared-read / await
 
-Three CLI primitives let sibling sub-agents coordinate: `peaks sub-agent share / shared-read / await` (last-write-wins, ≤ 1KB warn / ≥ 64KB reject). Channel file gitignored under `.peaks/_sub_agents/<sessionId>/shared/`.
+Three CLI primitives: `peaks sub-agent share / shared-read / await` (last-write-wins, ≤ 1KB warn / ≥ 64KB reject). Channel gitignored under `.peaks/_sub_agents/<sessionId>/shared/`.
 
 ## References
 

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/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

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

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

@@ -184,7 +184,7 @@ A skill cannot itself trigger sub-agents — the Skill tool runs in the main loo
    - `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.
 

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

@@ -29,7 +29,7 @@ When Peaks-Loop Code coordinates development in a code repository, keep this ord
 
 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:
@@ -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/dist/src/cli/cli-helpers.d.ts

@@ -1,43 +0,0 @@
-import { Command } from 'commander';
-import { getErrorMessage, ok, redactSensitiveErrorMessage, type ResultEnvelope } from '../shared/result.js';
-import type { ArtifactProvider, GuidedArtifactSetup } from '../services/artifacts/artifact-service.js';
-import type { ConfigLayer } from '../services/config/config-service.js';
-import type { MiniMaxProviderSmokeResult } from '../services/providers/minimax-provider-service.js';
-import type { MiniMaxWorkerResult } from '../services/providers/minimax-worker-service.js';
-import type { RecommendationWorkflow } from '../services/recommendations/recommendation-service.js';
-export type ProgramIO = {
-    stdout: (text: string) => void;
-    stderr: (text: string) => void;
-};
-export declare function printResult<T>(io: ProgramIO, result: ResultEnvelope<T>, asJson?: boolean): void;
-export declare function addJsonOption(command: Command): Command;
-export declare function failUnsupportedNonDryRun(io: ProgramIO, command: string, asJson?: boolean): void;
-/** CLI shim helper: render a `{ ok: boolean, error?, data? }` envelope
- *  and set `process.exitCode = 1` on failure.
- *
- *  Library functions MUST return envelopes like `{ ok, error?, data? }`
- *  and MUST NOT mutate `process.exitCode` themselves. The shim (the
- *  Commander `.action()` callback in `register*Commands`) owns the
- *  process-exit side-effect so the library can be re-used from non-CLI
- *  contexts (vitest, programmatic dispatch, plugin loading).
- *
- *  Output format mirrors the existing `registerSedimentCommands` shim:
- *  a JSON envelope on stdout (one line, parseable), nothing else.
- */
-export interface CliEnvelope {
-    ok: boolean;
-    error?: string;
-    data?: unknown;
-}
-export declare function printCliEnvelope(io: ProgramIO, r: CliEnvelope): void;
-export declare function isRecommendationWorkflow(value: string): value is RecommendationWorkflow;
-export declare function isArtifactProvider(value: string): value is ArtifactProvider;
-export declare function isArtifactSetupStep(value: string): value is GuidedArtifactSetup['step'];
-export declare function isArtifactRepoSegment(value: string): boolean;
-export declare function isMiniMaxHttpsUrl(value: string): boolean;
-export declare function parseConfigLayer(value: string | undefined): ConfigLayer | undefined | null;
-export declare function printInvalidConfigLayer(io: ProgramIO, command: string, asJson?: boolean): void;
-export declare function multipleOption(value: string, previous: string[]): string[];
-export declare function summarizeMiniMaxSmokeResult(result: MiniMaxProviderSmokeResult): MiniMaxProviderSmokeResult;
-export declare function summarizeMiniMaxWorkerResult(result: MiniMaxWorkerResult): MiniMaxWorkerResult;
-export { getErrorMessage, ok, redactSensitiveErrorMessage };

package/dist/src/cli/cli-helpers.js

@@ -1,86 +0,0 @@
-import { fail, getErrorMessage, ok, redactSensitiveErrorMessage } from '../shared/result.js';
-const MINIMAX_API_HOST = 'api.minimaxi.com';
-export function printResult(io, result, asJson = false) {
-    if (asJson) {
-        io.stdout(JSON.stringify(result, null, 2));
-        return;
-    }
-    if (!result.ok) {
-        io.stderr(`${result.code}: ${result.message}`);
-        for (const action of result.nextActions) {
-            io.stderr(`- ${action}`);
-        }
-        return;
-    }
-    io.stdout(JSON.stringify(result.data, null, 2));
-    for (const warning of result.warnings) {
-        io.stderr(`warning: ${warning}`);
-    }
-    for (const action of result.nextActions) {
-        io.stdout(`next: ${action}`);
-    }
-}
-export function addJsonOption(command) {
-    return command.option('--json', 'print machine-readable JSON envelope');
-}
-export function failUnsupportedNonDryRun(io, command, asJson) {
-    printResult(io, fail(command, 'UNSUPPORTED_NON_DRY_RUN', 'Only dry-run planning is supported', {}, ['Rerun with --dry-run or omit --no-dry-run']), asJson);
-    process.exitCode = 1;
-}
-export function printCliEnvelope(io, r) {
-    if (r.ok) {
-        io.stdout(JSON.stringify({ ok: true, data: r.data ?? null }));
-        return;
-    }
-    io.stdout(JSON.stringify({ ok: false, error: r.error }));
-    process.exitCode = 1;
-}
-export function isRecommendationWorkflow(value) {
-    return value === 'code-refactor' || value === 'product-refactor' || value === 'frontend-design';
-}
-export function isArtifactProvider(value) {
-    return value === 'github' || value === 'gitlab';
-}
-export function isArtifactSetupStep(value) {
-    return value === 'detect' || value === 'configure' || value === 'validate' || value === 'complete';
-}
-export function isArtifactRepoSegment(value) {
-    return /^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(value) && !value.includes('..') && !value.endsWith('.');
-}
-export function isMiniMaxHttpsUrl(value) {
-    try {
-        const url = new URL(value);
-        return url.protocol === 'https:' && url.hostname === MINIMAX_API_HOST && url.username.length === 0 && url.password.length === 0 && url.search.length === 0 && url.hash.length === 0;
-    }
-    catch {
-        return false;
-    }
-}
-export function parseConfigLayer(value) {
-    if (value === undefined) {
-        return undefined;
-    }
-    return value === 'user' || value === 'project' ? value : null;
-}
-export function printInvalidConfigLayer(io, command, asJson) {
-    printResult(io, fail(command, 'INVALID_CONFIG_LAYER', 'Config layer must be user or project', {}, ['Use --layer user or --layer project']), asJson);
-    process.exitCode = 1;
-}
-export function multipleOption(value, previous) {
-    return [...(previous || []), value];
-}
-export function summarizeMiniMaxSmokeResult(result) {
-    return { ...result, responseText: null, summary: null };
-}
-export function summarizeMiniMaxWorkerResult(result) {
-    const provider = summarizeMiniMaxSmokeResult(result.provider);
-    return {
-        ...result,
-        provider,
-        reviewHandoff: {
-            model: result.reviewHandoff.model,
-            prompt: '[redacted]'
-        }
-    };
-}
-export { getErrorMessage, ok, redactSensitiveErrorMessage };

package/dist/src/cli/commands/adapter-commands-s2a.d.ts

@@ -1,34 +0,0 @@
-/**
- * `peaks adapter *` — vendor adapter registry CLI surface.
- *
- * Slice S2-a of RD-2 (2026-07-08 session). Two subcommands:
- *
- *   list     — list registered user adapters (persisted at
- *              `.peaks/runtime/adapters.json`).
- *   register — register a new adapter. Vendor verb strings live in
- *              the binary the user picks, NOT in peaks-loop source.
- *
- * This file coexists with the older `adapter-commands.ts` (slice
- * 2026-07-04-cli-15a) which exposes `peaks skill adapter <verb>` —
- * a different surface for skill materialization (resolveScratchDir /
- * materialize / publish). The two surfaces do NOT collide because
- * one is `peaks skill adapter` and the other is `peaks adapter`.
- */
-import type { Command } from 'commander';
-import { type ProgramIO } from '../cli-helpers.js';
-export interface AdapterListOptions {
-    json?: boolean;
-    project?: string;
-}
-export interface AdapterRegisterOptions {
-    json?: boolean;
-    id?: string;
-    /** Display name override (defaults to the id). */
-    name?: string;
-    binary?: string;
-    /** Repeated --arg values. */
-    arg?: string[];
-    force?: boolean;
-    project?: string;
-}
-export declare function registerAdapterS2ACommands(program: Command, io: ProgramIO): void;

package/dist/src/cli/commands/adapter-commands-s2a.js

@@ -1,92 +0,0 @@
-import { existsSync } from 'node:fs';
-import { addJsonOption, printResult } from '../cli-helpers.js';
-import { fail, ok, getErrorMessage } from '../../shared/result.js';
-import { AdapterRegistry } from '../../services/adapter/adapter-registry.js';
-import { registryFileFor } from './runtime-commands.js';
-function resolveProjectRoot(explicit) {
-    if (explicit !== undefined && explicit.length > 0)
-        return explicit;
-    return process.cwd();
-}
-export function registerAdapterS2ACommands(program, io) {
-    const adapter = program
-        .command('adapter')
-        .description('Vendor adapter registry (user-registered, persisted to .peaks/runtime/adapters.json)');
-    // -----------------------------------------------------------------
-    // 1. peaks adapter list [--json] [--project <root>]
-    // -----------------------------------------------------------------
-    addJsonOption(adapter
-        .command('list')
-        .description('List user-registered vendor adapters')
-        .option('--project <path>', 'project root (defaults to cwd)')).action((options) => {
-        try {
-            const projectRoot = resolveProjectRoot(options.project);
-            const file = registryFileFor(projectRoot);
-            const reg = new AdapterRegistry();
-            if (existsSync(file))
-                reg.load(file);
-            const records = reg.list();
-            printResult(io, ok('adapter.list', { projectRoot, file, records, count: records.length }, [], [
-                records.length === 0
-                    ? 'No adapters registered yet. Run `peaks adapter register --id <vendor> --binary <cmd>` to add one.'
-                    : `Run \`peaks runtime compact --via <id>\` to invoke a registered adapter.`
-            ]), options.json);
-        }
-        catch (error) {
-            printResult(io, fail('adapter.list', 'ADAPTER_LIST_FAILED', getErrorMessage(error), {}, []), options.json);
-            process.exitCode = 1;
-        }
-    });
-    // -----------------------------------------------------------------
-    // 2. peaks adapter register --id <id> --binary <cmd> [--arg <a>]... [--force]
-    // -----------------------------------------------------------------
-    addJsonOption(adapter
-        .command('register')
-        .description('Register a new vendor adapter; persists to .peaks/runtime/adapters.json')
-        .requiredOption('--id <id>', 'vendor adapter id (lowercase, e.g. my-cli)')
-        .option('--name <name>', 'human-readable display name (defaults to <id>)')
-        .requiredOption('--binary <cmd>', 'binary name to invoke for compact (e.g. my-cli)')
-        .option('--arg <value>', 'extra arg appended before --force (repeatable)', (value, previous = []) => [...previous, value])
-        .option('--force', 'overwrite an existing adapter with the same id')
-        .option('--project <path>', 'project root (defaults to cwd)')).action((options) => {
-        try {
-            const projectRoot = resolveProjectRoot(options.project);
-            const file = registryFileFor(projectRoot);
-            const reg = new AdapterRegistry();
-            if (existsSync(file))
-                reg.load(file);
-            const id = options.id ?? '';
-            const record = options.arg !== undefined
-                ? { id, displayName: options.name ?? id, binary: options.binary ?? '', args: options.arg }
-                : { id, displayName: options.name ?? id, binary: options.binary ?? '' };
-            let result;
-            try {
-                result = reg.register(record, { force: options.force === true });
-            }
-            catch (validationError) {
-                printResult(io, fail('adapter.register', 'INVALID_ADAPTER_RECORD', getErrorMessage(validationError), { id }, [
-                    'Use --id with /^[a-z0-9][a-z0-9._-]*$/, --binary as a binary name (no path separators).'
-                ]), options.json);
-                process.exitCode = 1;
-                return;
-            }
-            reg.persist(file);
-            const warnings = [];
-            if (!result.created && options.force !== true) {
-                warnings.push(`adapter "${id}" already registered; pass --force to overwrite`);
-            }
-            printResult(io, ok('adapter.register', {
-                projectRoot,
-                file,
-                adapter: result.record,
-                created: result.created
-            }, warnings, [
-                `Run \`peaks runtime compact --via ${id}\` to invoke it.`
-            ]), options.json);
-        }
-        catch (error) {
-            printResult(io, fail('adapter.register', 'ADAPTER_REGISTER_FAILED', getErrorMessage(error), {}, []), options.json);
-            process.exitCode = 1;
-        }
-    });
-}