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

package/examples/video-demo/README.md

@@ -1,40 +1,101 @@
-# peaks-loop video demo
+# peaks-loop video demo (v5)
 
-Remotion-based 30-second brand walk-through for peaks-loop 4.0. Mirrors `README.md`.
+Remotion-based ~27-second brand walk-through for peaks-loop 4.x. Mirrors the multi-domain + slash-command narrative of the top-level README.
 
 ## Composition
 
 - Two compositions, one per locale:
-  - `peaks-loop-demo`     — 30 seconds @ 30fps (900 frames), 1920×1080 — Chinese primary.
-  - `peaks-loop-demo-en`  — same frame budget, English primary.
-- Scene timeline (frozen in `src/Root.tsx`):
-  - 0–90    — **TitleScene** (`peaks-loop`, no ·, no emoji)
-  - 90–240  — **PhilosophyScene** — 5 hero philosophy items, bilingual
-  - 240–540 — **DemoScene × 3** — `写长任务代码` / `修 bug 当天发` / `接一个长跑的需求`
-  - 540–780 — **SedimentScene** — 3-beat `NL → MANIFEST → BEE`
-  - 780–900 — **ClosingScene** — `npm i -g peaks-loop` + repo-name vs skill-name arc + 5,439 tests stats
+  - `peaks-loop-demo`     — Chinese primary
+  - `peaks-loop-demo-en`  — English primary
+- Same frame budget for both; dimensions 1920×1080 @ 30fps.
+- Scene timeline (frozen in `src/Root.tsx`, v5 narrative):
+
+  | # | Scene | Slug | Frames |
+  | --- | --- | --- | --- |
+  | 1 | `IntroScene` | intro | 80 |
+  | 2 | `RecordingScene` | install | 100 |
+  | 3 | `RecordingScene` | first-slash | 100 |
+  | 4 | `RecordingScene` | domains | 100 |
+  | 5 | `RecordingScene` | sediment | 100 |
+  | 6 | `CreditScene` | credit | 130 |
+  | 7 | `ClosingScene` | closing | 110 |
+
+  Plus 12-frame overlap transitions between every scene.
 
 ## Visual style
 
-- Background: `#0f172a` (slate-900) via `bg-brand-bg`
-- Primary text: `#f8fafc` (slate-50) via `text-brand-fg`
-- Accent: `#6366f1` (indigo-500) via `text-brand-accent`
-- Stable badge: `#22c55e` (green-500)
-- Mono font for kickers / install chip / chat bubbles; sans font for headlines
+- Background: `#0f172a` (slate-900) via `bg-brand-bg` + `BrandBackground` (drifting indigo halo + diagonal sweep line + bottom green glow).
+- Accent: `#6366f1` (indigo-500) · Stable: `#22c55e` (green-500) · Warn: `#f59e0b` (amber-500).
+- Typography: `font-mono` for kickers, captions, IDE/terminal HUD; `font-sans` for headlines.
+- Three caption styles (`CaptionOverlay`):
+  - **subtitle** — black semi-transparent bar at the bottom.
+  - **callout** — indigo gradient emphasis box, slides in from the left.
+  - **annotation** — amber speech-bubble, drops in from the top-right.
 
-## Public preview files (tracked)
+## Scene components
 
-The READMEs embed `<video>` tags that point at:
+```
+src/scenes/
+├── IntroScene.tsx       — hero title + tagline (kicker / brand / tagline)
+├── RecordingScene.tsx   — the workhorse: 4 instances, each plays an HUD + captions + cursor
+├── HudWindow.tsx        — stylised terminal/IDE panel that types out lines one at a time
+├── CaptionOverlay.tsx   — 3-style caption layer (subtitle / callout / annotation)
+├── CursorHighlight.tsx  — macOS-style cursor with smooth waypoint interpolation + click ripple
+├── BrandBackground.tsx  — shared brand background (halo + sweep + bottom glow)
+├── CreditScene.tsx      — tribute + recommended stack
+└── ClosingScene.tsx     — install chip + 5,439 tests stats
+```
+
+## Copy registry
 
-- `preview/peaks-loop-demo.mp4`    (zh, 4.9 MB)
-- `preview/peaks-loop-demo-en.mp4` (en, 5.0 MB)
+All on-screen text lives in `src/copy.ts`. Both locales are strict: no hardcoded
+CN/EN inline in scene components. The `recordings[]` array holds 4 scene slugs
+(install / first-slash / domains / sediment), each with its own captions,
+cursor choreography, and HUD payload.
 
-These are produced by the render command below and committed to git so a clone (and the GitHub rendering) sees the same path. The shell snippet under **Render** keeps `preview/` in sync after a fresh build.
+## v5 recording pipeline (Playwright + Remotion)
 
-## Render
+The `RecordingScene` slots are designed to host **real recorded footage**
+when you have a Chromium-equipped machine. The HUD window is the stand-in
+for that footage until the recording pass runs.
+
+### 1. Install the recording side
 
 ```bash
 cd examples/video-demo
+pnpm add -D playwright
+pnpm exec playwright install chromium
+```
+
+### 2. Author a scenario JSON
+
+Write `recordings/<slug>.json` per scene using the
+`web-demo-video_skills` schema (`goto` / `click` / `fill` / `wait` / `screenshot`).
+For our 4 slugs, the natural targets are:
+
+| slug | URL / action |
+| --- | --- |
+| `install` | terminal typing `npm i -g peaks-loop` |
+| `first-slash` | Claude Code chat with `/peaks-code ...` |
+| `domains` | same chat, scrolling through the 5 `/peaks-*` slash commands |
+| `sediment` | same chat, completing a run + asking to sediment |
+
+### 3. Record per scene
+
+```bash
+pnpm exec tsx scripts/record-scenes.ts
+# outputs recordings/<slug>.webm  +  recordings/<slug>.cursor.json
+```
+
+### 4. Swap the HUD for the recorded clip
+
+In `src/scenes/RecordingScene.tsx`, replace the `<HudWindow>` block with a
+`<Video src={...}>` from the matching `recordings/<slug>.webm`. Drop the
+`HudWindow` import when no scene needs it any more.
+
+### 5. Render
+
+```bash
 pnpm install
 npx remotion render peaks-loop-demo out/peaks-loop-demo.mp4
 npx remotion render peaks-loop-demo-en out/peaks-loop-demo-en.mp4
@@ -44,10 +105,10 @@ cp out/peaks-loop-demo.mp4    preview/peaks-loop-demo.mp4
 cp out/peaks-loop-demo-en.mp4 preview/peaks-loop-demo-en.mp4
 ```
 
-Fallback (no Chromium available):
+Fallback (no Chromium available — renders the HUD stand-in only):
 
 ```bash
-npx remotion still peaks-loop-demo out/still.png --frame=120
+npx remotion still peaks-loop-demo out/still.png --frame=400
 ```
 
 ## Preview during dev
@@ -55,3 +116,27 @@ npx remotion still peaks-loop-demo out/still.png --frame=120
 ```bash
 npx remotion studio   # http://localhost:3000
 ```
+
+## Why this layout
+
+The 4 recording slugs follow the **black-box mental model** the README now
+uses: install → first slash command → tour the 5 domains → sediment. Each
+scene is **self-contained** (own HUD payload, captions, cursor ticks),
+so you can rearrange them, drop one, or A/B test a new one without
+touching the others. The 12-frame overlap transitions cross-fade between
+scenes so the result feels like one continuous take rather than a slide
+deck.
+
+## Adding a new scene
+
+1. Add a new entry to `recordings` in `src/copy.ts` (both `zh` and `en`):
+   - `slug` (kebab-case, used for the corner chip + recording filename)
+   - `captions` (array of `{ text, style }` triples)
+   - `cursor` (array of waypoints; empty = no cursor overlay)
+   - `hud` (terminal / ide, with the lines you want typed out)
+2. Add an extra frame budget to `src/Root.tsx` if you want a longer hold.
+3. Typecheck: `pnpm exec tsc --noEmit`.
+4. Re-render.
+
+If you have a recording, drop a `<Video>` into `RecordingScene.tsx` and
+point it at the new `recordings/<slug>.webm`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "peaks-loop",
-  "version": "4.0.0-beta.7",
+  "version": "4.0.0-beta.9",
   "description": "Loop Engineering CLI — workflow primitive / loop guards / evaluators / slice orchestration",
   "author": "SquabbyZ",
   "license": "MIT",
@@ -22,10 +22,12 @@
   },
   "files": [
     "bin/peaks.js",
-    "dist/src/cli/index.js",
-    "dist/src/**/*.js",
-    "dist/src/**/*.d.ts",
+    "dist/cli/index.js",
+    "dist/**/*.js",
+    "dist/**/*.d.ts",
+    "dist/**/*.md",
     "scripts/clean-dist.mjs",
+    "scripts/copy-templates.mjs",
     "scripts/sync-version.mjs",
     "scripts/install-skills.mjs",
     "scripts/watch.mjs",
@@ -46,7 +48,7 @@
     "examples/video-demo/out/en-closing-960.png"
   ],
   "scripts": {
-    "build": "node ./scripts/sync-version.mjs && node ./scripts/clean-dist.mjs && tsc -p tsconfig.json",
+    "build": "node ./scripts/sync-version.mjs && node ./scripts/clean-dist.mjs && tsc -p tsconfig.build.json && node ./scripts/copy-templates.mjs",
     "prepack": "npm run build",
     "prepublishOnly": "node scripts/prepublish-build.mjs",
     "prepublish": "node ./scripts/sync-version.mjs",
@@ -55,7 +57,18 @@
     "dev": "tsx src/cli/index.ts",
     "dev:watch": "node ./scripts/watch.mjs",
     "pretest": "node ./scripts/sync-version.mjs",
-    "test": "node ./scripts/lint/silent-warning-detector.mjs && vitest run",
+    "test": "vitest run tests/unit/cli-program.core.test.ts tests/unit/cli-program.stateful.test.ts tests/unit/cli-program.workflow.test.ts tests/unit/cli-program.workflow-cli.test.ts tests/unit/cli-program.workspace.test.ts tests/unit/cli",
+    "test:full": "vitest run",
+    "test:fast": "vitest run --maxWorkers=8 -t \"^((?!@slow|@integration|@replay).)*$\" tests/unit",
+    "test:dev": "vitest run tests/unit",
+    "test:dev:cli": "vitest run tests/unit/cli-program.core.test.ts tests/unit/cli-program.stateful.test.ts tests/unit/cli-program.workflow.test.ts tests/unit/cli-program.workflow-cli.test.ts tests/unit/cli-program.workspace.test.ts tests/unit/cli",
+    "test:unit": "vitest run tests/unit",
+    "test:integration": "vitest run tests/integration",
+    "test:cli": "vitest run tests/unit/cli-program.core.test.ts tests/unit/cli-program.stateful.test.ts tests/unit/cli-program.workflow.test.ts tests/unit/cli-program.workflow-cli.test.ts tests/unit/cli-program.workspace.test.ts tests/unit/cli",
+    "test:workflow": "vitest run tests/unit/cli-program.workflow.test.ts tests/unit/cli-program.workflow-cli.test.ts tests/unit/workflow-autonomous-resume-validation.test.ts tests/unit/workflow-autonomous-service.test.ts tests/unit/workflow-router-service.test.ts tests/unit/skill-browser-workflow.test.ts tests/unit/services/workflow",
+    "test:audit:silent-warning": "node ./scripts/lint/silent-warning-detector.mjs",
+    "test:ci": "node ./scripts/sync-version.mjs && node ./scripts/lint/silent-warning-detector.mjs && vitest run --coverage",
+    "test:changed": "node scripts/test-changed.mjs",
     "lint:silent-warning": "node ./scripts/lint/silent-warning-detector.mjs",
     "test:race": "vitest run --no-file-parallelism tests/unit/g8-shared-channel.test.ts tests/unit/dispatch-record-writer.test.ts tests/unit/services/retrospective/heartbeat.test.ts tests/unit/cli/commands/share-commands.test.ts",
     "test:replay": "node scripts/fixture-capture-setup.mjs && vitest run tests/unit/replay tests/unit/fixture",
@@ -99,13 +112,14 @@
     "@jridgewell/trace-mapping": "^0.3.31",
     "@stryker-mutator/core": "^8.7.1",
     "@stryker-mutator/typescript-checker": "^8.7.1",
-    "@stryker-mutator/vitest-runner": "^8.7.1",
+    "@stryker-mutator/vitest-runner": "^9.6.1",
     "@types/better-sqlite3": "^7.6.13",
     "@types/node": "^22.10.2",
-    "@vitest/coverage-v8": "^2.1.8",
+    "@vitest/coverage-v8": "^4.1.10",
     "tsx": "^4.19.2",
     "typescript": "^5.7.2",
-    "vitest": "^2.1.8",
+    "vite": "^6.0.0",
+    "vitest": "^4.1.0",
     "zod-to-json-schema": "^3.25.2"
   }
 }

package/scripts/copy-templates.mjs

@@ -0,0 +1,64 @@
+#!/usr/bin/env node
+/**
+ * copy-templates.mjs — copy bundled non-JS template assets into dist/
+ * after `tsc` runs. Required by slice 2026-07-15-project-scan-bootstrap
+ * (PRD G4b / R1 / QA BLOCKER): `tsc` only emits .js / .d.ts, so the
+ * audit/business markdown templates at
+ * `src/services/workspace/templates/project-scan/*.md` are absent
+ * from `dist/`. Downstream `npm install peaks-loop` consumers would
+ * therefore only get the dynamically-generated `project-scan.md` and
+ * the 4 audit/business templates would silently be missing.
+ *
+ * Idempotent: safe to run multiple times. Run after `tsc` in `build`.
+ */
+import { copyFileSync, mkdirSync, readdirSync, statSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const packageRoot = resolve(dirname(fileURLToPath(import.meta.url)), '..');
+
+/**
+ * @param {string} srcDir absolute source directory
+ * @param {string} destDir absolute destination directory (created if absent)
+ * @param {readonly string[]} extensions file extensions to copy (lowercase, with leading dot)
+ */
+function copyTree(srcDir, destDir, extensions) {
+  if (!statSync(srcDir, { throwIfNoEntry: false })) return;
+  mkdirSync(destDir, { recursive: true });
+  for (const entry of readdirSync(srcDir, { withFileTypes: true })) {
+    const srcPath = join(srcDir, entry.name);
+    const destPath = join(destDir, entry.name);
+    if (entry.isDirectory()) {
+      copyTree(srcPath, destPath, extensions);
+      continue;
+    }
+    if (!entry.isFile()) continue;
+    const ext = entry.name.toLowerCase().slice(entry.name.lastIndexOf('.'));
+    if (!extensions.includes(ext)) continue;
+    copyFileSync(srcPath, destPath);
+  }
+}
+
+const targets = [
+  {
+    src: join(packageRoot, 'src/services/workspace/templates/project-scan'),
+    dest: join(packageRoot, 'dist/services/workspace/templates/project-scan'),
+    extensions: ['.md']
+  }
+];
+
+let totalCopied = 0;
+for (const { src, dest, extensions } of targets) {
+  const before = statSync(dest, { throwIfNoEntry: false })
+    ? readdirSync(dest).length
+    : 0;
+  copyTree(src, dest, extensions);
+  const after = readdirSync(dest).length;
+  const added = after - before;
+  totalCopied += added;
+  process.stdout.write(
+    `copy-templates: ${src.replace(packageRoot + '/', '')} -> ${dest.replace(packageRoot + '/', '')} (+${added} files)\n`
+  );
+}
+
+process.stdout.write(`copy-templates: done (${totalCopied} files copied)\n`);

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

@@ -185,7 +185,7 @@ Peaks-Loop PRD/RD/QA gates remain authoritative: OpenSpec structures the durable
 
 ## Mock data placement rules (BLOCKING — framework-aware)
 
-When the project-scan in `.peaks/_runtime/<sessionId>/rd/project-scan.md` identifies a frontend framework, mock data MUST follow the framework's built-in mock mechanism. **Never write mock data inline in component files.**
+When the project-scan in `.peaks/project-scan/project-scan.md` (project-level, git-tracked; slice 2026-07-15-project-scan-bootstrap) identifies a frontend framework, mock data MUST follow the framework's built-in mock mechanism. **Never write mock data inline in component files.**
 
 → see `references/mock-data-placement.md` for the framework-to-mock-directory mapping + hard rules + verification gate.
 

package/skills/bee/peaks-rd/references/library-version-awareness.md

@@ -2,12 +2,12 @@
 
 > Body of `## Library version awareness (3rd-party breaking-change gate)`. After `peaks scan libraries` lands the dependency list under `## Library versions` in `rd/project-scan.md`, RD MUST cross-check the slice's diff against `schemas/library-breaking-changes.data.json` before writing any 3rd-party API call. Concretely:
 
-1. **Read the project's `## Library versions` section** in `.peaks/_runtime/<sessionId>/rd/project-scan.md`. Identify the `name` + `major` of every dependency the slice imports from.
+1. **Read the project's `## Library versions` section** in `.peaks/project-scan/project-scan.md`. Identify the `name` + `major` of every dependency the slice imports from.
 2. **Open `schemas/library-breaking-changes.data.json`** (LLM reads via the `Read` tool). For each library where the installed `major` matches a `toMajor` in the table, load the corresponding `breakingChanges[]` list.
 3. **For each `import` statement in the slice's diff** (e.g. `import { Drawer } from 'antd'`), check whether the imported symbol or its prop signature matches any `breakingChanges[].api` entry for the library's installed major.
 4. **On a hit**:
    - **Warn the LLM in the slice's handoff**: in `.peaks/_runtime/<sessionId>/rd/requests/<rid>.md` under `## Implementation evidence`, append a one-line note per hit: `- [lib-version] <library> <installed version> imports <api>; breaking-change rule says use <replacement> instead.`
-   - **Persist a `lesson` memory** at the END of `.peaks/_runtime/<sessionId>/rd/project-scan.md` (or the tech-doc, or the handoff — any of these is read by future RD runs):
+   - **Persist a `lesson` memory** at the END of `.peaks/project-scan/project-scan.md` (or the tech-doc, or the handoff — any of these is read by future RD runs):
      ```
      <!-- peaks-memory:start -->
      title: <library> <installed major> requires <api> → <replacement>

package/skills/bee/peaks-rd/references/mock-data-placement.md

@@ -2,7 +2,7 @@
 
 > Body of `## Mock data placement rules` + `### Framework-to-mock-directory mapping` + `### Hard rules` + `### Verification gate`. **BLOCKING — framework-aware.**
 
-When the project-scan in `.peaks/_runtime/<sessionId>/rd/project-scan.md` identifies a frontend framework, mock data MUST follow the framework's built-in mock mechanism. **Never write mock data inline in component files.**
+When the project-scan in `.peaks/project-scan/project-scan.md` identifies a frontend framework, mock data MUST follow the framework's built-in mock mechanism. **Never write mock data inline in component files.**
 
 ## Framework-to-mock-directory mapping
 

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.