peaks-loop 4.0.0-beta.9 → 4.0.1

package/package.json

@@ -1,11 +1,10 @@
 {
   "name": "peaks-loop",
-  "version": "4.0.0-beta.9",
+  "version": "4.0.1",
   "description": "Loop Engineering CLI — workflow primitive / loop guards / evaluators / slice orchestration",
   "author": "SquabbyZ",
   "license": "MIT",
   "type": "module",
-  "packageManager": "pnpm@10.11.0",
   "publishConfig": {
     "access": "public"
   },
@@ -26,6 +25,7 @@
     "dist/**/*.js",
     "dist/**/*.d.ts",
     "dist/**/*.md",
+    "dist/**/*.sql",
     "scripts/clean-dist.mjs",
     "scripts/copy-templates.mjs",
     "scripts/sync-version.mjs",
@@ -41,56 +41,11 @@
     "README.md",
     "README-en.md",
     "CHANGELOG.md",
-    "LICENSE",
-    "examples/video-demo/preview/peaks-loop-demo.mp4",
-    "examples/video-demo/preview/peaks-loop-demo-en.mp4",
-    "examples/video-demo/out/zh-closing-960.png",
-    "examples/video-demo/out/en-closing-960.png"
+    "LICENSE"
   ],
-  "scripts": {
-    "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",
-    "postinstall": "node ./scripts/install-skills.mjs",
-    "predev": "node ./scripts/sync-version.mjs",
-    "dev": "tsx src/cli/index.ts",
-    "dev:watch": "node ./scripts/watch.mjs",
-    "pretest": "node ./scripts/sync-version.mjs",
-    "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",
-    "fixture:capture-setup": "node scripts/fixture-capture-setup.mjs",
-    "test:coverage": "vitest run --coverage",
-    "test:coverage:workflow": "vitest run --coverage --coverage.include='src/services/workflow/plan-*.ts' tests/unit/services/workflow/",
-    "pretest:coverage": "node ./scripts/pretest-coverage.mjs",
-    "schema:generate": "node scripts/generate-context-schema.mjs",
-    "typecheck": "tsc -p tsconfig.json --noEmit && vitest run --coverage --coverage.include='src/services/workflow/plan-*.ts' tests/unit/services/workflow/",
-    "mut:run": "peaks mut run --project . --out mut-report.json",
-    "mut:scan": "peaks mut asserts --in mut-report.json",
-    "audit:prose-ratio": "peaks audit prose-ratio --project .",
-    "dogfood:sediment": "bash scripts/dogfood-sediment-cycle.sh"
-  },
   "engines": {
     "node": ">=20.0.0"
   },
-  "pnpm": {
-    "onlyBuiltDependencies": [
-      "better-sqlite3"
-    ]
-  },
   "dependencies": {
     "@colbymchenry/codegraph": "0.7.10",
     "better-sqlite3": "^12.11.1",
@@ -98,7 +53,10 @@
     "fzf": "^0.5.2",
     "headroom-ai": "0.22.4",
     "yaml": "^2.9.0",
-    "zod": "^3.25.76"
+    "zod": "^3.25.76",
+    "peaks-loop-mut": "0.1.3",
+    "peaks-loop-shared": "0.0.29",
+    "peaks-loop-shared-channel": "0.0.8"
   },
   "peerDependencies": {
     "@alibaba-group/open-code-review": "1.3.1"
@@ -109,17 +67,55 @@
     }
   },
   "devDependencies": {
+    "@changesets/cli": "2.31.1",
     "@jridgewell/trace-mapping": "^0.3.31",
     "@stryker-mutator/core": "^8.7.1",
     "@stryker-mutator/typescript-checker": "^8.7.1",
     "@stryker-mutator/vitest-runner": "^9.6.1",
     "@types/better-sqlite3": "^7.6.13",
     "@types/node": "^22.10.2",
+    "@vitest/coverage-istanbul": "^4.1.10",
     "@vitest/coverage-v8": "^4.1.10",
+    "c8": "^10.1.3",
     "tsx": "^4.19.2",
     "typescript": "^5.7.2",
     "vite": "^6.0.0",
-    "vitest": "^4.1.0",
+    "vitest": "^4.1.10",
     "zod-to-json-schema": "^3.25.2"
+  },
+  "scripts": {
+    "build": "node ./scripts/sync-version.mjs && node ./scripts/clean-dist.mjs && pnpm -r --filter \"./packages/*\" run build && tsc -p tsconfig.build.json && node ./scripts/copy-templates.mjs && node ./scripts/check-build-integrity.mjs",
+    "prepublish": "node ./scripts/sync-version.mjs",
+    "postinstall": "node ./scripts/install-skills.mjs",
+    "predev": "node ./scripts/sync-version.mjs",
+    "dev": "tsx src/cli/index.ts",
+    "dev:watch": "node ./scripts/watch.mjs",
+    "pretest": "node ./scripts/sync-version.mjs && pnpm --filter peaks-loop-shared build && node ./scripts/check-build-integrity.mjs",
+    "test": "vitest run",
+    "test:full": "pnpm -r --include-workspace-root --workspace-concurrency=2 run test",
+    "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",
+    "test:unit": "vitest run tests/unit",
+    "test:integration": "vitest run tests/integration",
+    "test:cli": "vitest run tests/unit",
+    "test:workflow": "vitest run tests/unit",
+    "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 packages/peaks-loop-shared-channel/tests/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",
+    "fixture:capture-setup": "node scripts/fixture-capture-setup.mjs",
+    "test:coverage": "node ./scripts/coverage-c8.mjs",
+    "test:coverage:c8": "node ./scripts/coverage-c8.mjs",
+    "test:coverage:vitest": "vitest run --coverage",
+    "test:coverage:workflow": "vitest run --coverage --coverage.include='src/services/workflow/plan-*.ts' tests/unit/services/workflow/",
+    "schema:generate": "node scripts/generate-context-schema.mjs",
+    "typecheck": "tsc -p tsconfig.json --noEmit && vitest run --coverage --coverage.include='src/services/workflow/plan-*.ts' tests/unit/services/workflow/",
+    "mut:run": "peaks mut run --project . --out mut-report.json",
+    "mut:scan": "peaks mut asserts --in mut-report.json",
+    "audit:prose-ratio": "peaks audit prose-ratio --project .",
+    "dogfood:sediment": "bash scripts/dogfood-sediment-cycle.sh"
   }
-}
+}

package/scripts/clean-dist.mjs

@@ -1,8 +1,38 @@
 #!/usr/bin/env node
-import { rmSync } from 'node:fs';
+import { readdirSync, rmSync } from 'node:fs';
 import { join, resolve } from 'node:path';
 import { dirname } from 'node:path';
 import { fileURLToPath } from 'node:url';
 
 const packageRoot = resolve(dirname(fileURLToPath(import.meta.url)), '..');
+
+// Slice 2026-07-30 — extend clean-dist to also wipe every
+// packages/*/dist. Rationale: tsc's incremental-build cache
+// compares files by mtime + size, and a stale dist that
+// survived from a previous build can cause tsc to skip the
+// emission of newly-added src/*.ts (Bug-04 lineage — see
+// tests/unit/scripts/sync-version-invalidation.test.ts for
+// the regression pin on version.ts specifically).
+//
+// The wider wipe is safe because:
+//   - watch.mjs only watches src/, schemas/, skills/ — it
+//     never reads packages/*/dist during dev iteration
+//   - sync-version.mjs's later unlink step on
+//     packages/peaks-loop-shared/dist/version.* is now a
+//     narrower no-op safety net, not the load-bearing invalidator
+//
+// We deliberately use { recursive: true, force: true } for
+// every dist — missing dirs are tolerated so a fresh clone
+// without prior builds does not crash.
+
 rmSync(join(packageRoot, 'dist'), { recursive: true, force: true });
+
+const packagesRoot = join(packageRoot, 'packages');
+for (const entry of readdirSync(packagesRoot, { withFileTypes: true })) {
+  if (!entry.isDirectory()) continue;
+  rmSync(join(packagesRoot, entry.name, 'dist'), {
+    recursive: true,
+    force: true,
+  });
+}
+

package/scripts/copy-templates.mjs

@@ -9,6 +9,15 @@
  * therefore only get the dynamically-generated `project-scan.md` and
  * the 4 audit/business templates would silently be missing.
  *
+ * D-019 (2026-07-16): also copy the SkillHub SQLite migrations
+ * (`src/services/skillhub/migrations/*.sql`) into dist/. Without this,
+ * the published `peaks-loop` tarball ships an empty
+ * `dist/services/skillhub/migrations/` and `openStateDb()` opens a
+ * schema-less database, breaking any `peaks skill sediment <verb>`
+ * on a fresh consumer install. Vitest tests still pass because they
+ * use tsx + the source tree directly, but downstream npm consumers
+ * see `no such table: bee_release` on the very first command.
+ *
  * Idempotent: safe to run multiple times. Run after `tsc` in `build`.
  */
 import { copyFileSync, mkdirSync, readdirSync, statSync } from 'node:fs';
@@ -44,6 +53,13 @@ const targets = [
     src: join(packageRoot, 'src/services/workspace/templates/project-scan'),
     dest: join(packageRoot, 'dist/services/workspace/templates/project-scan'),
     extensions: ['.md']
+  },
+  {
+    // D-019: SkillHub SQLite migrations must reach the published tarball
+    // so `openStateDb()` can apply the schema on first run.
+    src: join(packageRoot, 'src/services/skillhub/migrations'),
+    dest: join(packageRoot, 'dist/services/skillhub/migrations'),
+    extensions: ['.sql']
   }
 ];
 

package/scripts/sync-version.mjs

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { readFileSync, writeFileSync } from 'node:fs';
+import { existsSync, readFileSync, unlinkSync, writeFileSync } from 'node:fs';
 import { resolve } from 'node:path';
 
 const packageJson = JSON.parse(readFileSync(resolve('package.json'), 'utf8'));
@@ -9,4 +9,55 @@ if (typeof version !== 'string' || version.length === 0) {
   throw new Error('package.json version must be a non-empty string');
 }
 
-writeFileSync(resolve('src/shared/version.ts'), `export const CLI_VERSION = ${JSON.stringify(version)};\n`);
+// Slice 3a — version.ts lives in the peaks-loop-shared workspace package.
+// The shared package is `private: true` and is consumed via workspace:*,
+// so its own package.json `version` field is irrelevant for downstream
+// consumers; we always emit the main peaks-loop version.
+writeFileSync(
+  resolve('packages/peaks-loop-shared/src/version.ts'),
+  `export const CLI_VERSION = ${JSON.stringify(version)};\n`,
+);
+
+// 2026-07-23 follow-up (peaks-publish-stale fix, AC6): the shared
+// bump used to live here, gated on `PEAKS_AUTO_BUMP_SHARED === '1'`.
+// That gate was the Layer 2 root cause: publish.yml set the env on
+// the CI Build step, but local dev runs (and any path that didn't
+// re-export the env) produced stale shared tarballs. The bump now
+// lives in `scripts/bump-version.mjs` (which always runs when root
+// version changes) and `bump-version.mjs` is the single owner of
+// the shared/package.json#version bump.
+//
+// This script keeps a fallback shared bump when explicitly invoked
+// from another path with `PEAKS_AUTO_BUMP_SHARED === '1'` — that
+// preserves the contract for any out-of-band build invocation that
+// still sets the env var. The bump-version.mjs path is primary and
+// always-on; the gate here is just a back-stop.
+
+// 2026-07-22 follow-up (Bug-04 root-cause fix): the previous version of
+// this script wrote `version.ts` only, then handed off to `tsc`. Tsc's
+// incremental-build cache compares `version.ts` only by mtime + size —
+// and the freshly-written version.ts has the SAME size as before, so tsc
+// reported "no changes" and skipped emitting `dist/version.js`. The
+// pre-existing `dist/version.js` (from a prior build with an OLD CLI_VERSION)
+// was then re-packed by `release-pack.mjs` into the npm tarball, causing
+// downstream `peaks -v` to print the wrong version.
+//
+// Fix: invalidate the shared `dist/version.js` (and its .d.ts / .map) so a
+// subsequent `tsc -p tsconfig.json` on the shared subpackage has to regen it.
+// This is idempotent: if no dist yet exists, noop; if it exists, unlink.
+for (const ext of ['js', 'd.ts', 'd.ts.map']) {
+  const sharedDist = resolve('packages/peaks-loop-shared/dist/version.' + ext);
+  if (existsSync(sharedDist)) {
+    unlinkSync(sharedDist);
+  }
+}
+
+// Slice 2026-07-30 — the targeted unlink above is now a
+// regression-test pin for Bug-04; the load-bearing dist
+// invalidation moved up to `clean-dist.mjs`, which wipes every
+// packages/*/dist wholesale before any subpackage build runs.
+// This narrow unlink stays because it is unit-tested by
+// tests/unit/scripts/sync-version-invalidation.test.ts and
+// catching the Bug-04 lineage on its own is cheap insurance
+// against future pipeline reorderings.
+

package/skills/bee/peaks-perf-audit/SKILL.md

@@ -1,5 +1,6 @@
 ---
 name: peaks-perf-audit
+visibility: internal
 description: Independent performance audit skill. Reads the immutable peaks-prd handoff + the project-level perf-template.md, performs a 6-dimension perf audit, and writes a structured envelope to `.peaks/_runtime/<sessionId>/audit/perf-<rid>.md`. Decoupled from peaks-rd 5-way fan-out per slice v2.12.0 (Group A, Tier 3). Use when the slice introduces CPU-bound hot loops, I/O throughput changes, memory allocation patterns, concurrency model changes, bundle size deltas, or cold-start costs.
 metadata:
   appliesTo: peaks-loop v2.12.0+
@@ -164,3 +165,19 @@ required fixes deduped by `(file, line, hint)`).
   template, or the diff under audit. It only writes a new audit artifact.
 - **#4 Goal-Driven Execution** — every audit output references a
   verifiable handoff goal via the `handoffHash` field.
+
+## L2 surface reference (post rid-l2-extended)
+
+For slices that touch the L2 surface, the canonical CLIs are:
+- `peaks worktree {spawn,renew,list,gc,lease-status,release}` — lease lifecycle (Part 1-2)
+- `peaks sub-agent dispatch --isolation worktree|container` — auto-spawns a lease (Part 2.C + Part 8 contract)
+- `peaks container {spawn,release}` — L4 container runtime (Part 12, docker)
+- `peaks lease-metrics [--rate] [--all-sessions]` — per-kind counts + leak rate (Part 4-5)
+- `peaks lease-stats` — project-wide summary (Part 6)
+- `peaks cron {init,list,run}` + `peaks cron-scheduler start` — periodic lease gc (Part 14-15)
+- `peaks audit red-lines --project .` — 119 catalog red-lines / 86+ cli-backed enforcers / 0 prose-only (Part 13)
+
+Verify the surface (no need to re-derive):
+1. `peaks audit red-lines --project .` reports `proseOnly: 0` for any shipped L2 surface.
+2. `peaks lease-metrics --rate` after a clean run reports `estimatedLeaked: 0`.
+3. `peaks worktree list` returns 0 active leases after a clean run.

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

@@ -323,3 +323,19 @@ Use `peaks capabilities --source mcp-server --json` before recommending product
 Do not implement code, run tests, install hooks, or modify runtime configuration. Use Peaks-Loop CLI reports and downstream artifacts instead.
 
 Reference: `references/workflow.md`.
+
+## L2 surface reference (post rid-l2-extended)
+
+For slices that touch the L2 surface, the canonical CLIs are:
+- `peaks worktree {spawn,renew,list,gc,lease-status,release}` — lease lifecycle (Part 1-2)
+- `peaks sub-agent dispatch --isolation worktree|container` — auto-spawns a lease (Part 2.C + Part 8 contract)
+- `peaks container {spawn,release}` — L4 container runtime (Part 12, docker)
+- `peaks lease-metrics [--rate] [--all-sessions]` — per-kind counts + leak rate (Part 4-5)
+- `peaks lease-stats` — project-wide summary (Part 6)
+- `peaks cron {init,list,run}` + `peaks cron-scheduler start` — periodic lease gc (Part 14-15)
+- `peaks audit red-lines --project .` — 119 catalog red-lines / 86 cli-backed enforcers / 51 discovered (Part 13)
+
+Verify the surface (no need to re-derive):
+1. `peaks audit red-lines --project .` reports `proseOnly: 0` for any shipped L2 surface.
+2. `peaks lease-metrics --rate` after a clean run reports `estimatedLeaked: 0`.
+3. `peaks worktree list` returns 0 active leases after a clean run.

package/skills/bee/peaks-prd/test-prompts.json

@@ -0,0 +1,12 @@
+[
+  {
+    "id": 1,
+    "prompt": "Feishu 文档 https://example.feishu.cn/wiki/PRODUCT_DOC_ID 是产品文档，需要登录。目标是 /Users/yuanyuan/Desktop/work/platform-rag-web 前端项目，请从文档提取可以交给 RD 实现、QA 复测的前端改动点。",
+    "expected": "先校验文档 URL 使用 https 且属于批准的 Feishu/Lark tenant 域名，再使用 headed gstack/browse/dist/browse 打开有头浏览器访问，遇到登录时等待用户完成并回复确认后再继续；登录后只提取产品实现逻辑、页面/路由/组件/状态/API contract/mock 假设/验收标准/联调问题，输出 .peaks/_runtime/<session-id>/prd/ 下的脱敏实现型 PRD handoff；不得保留登录 URL、cookie、headers、tokens、storage state、browser traces、raw browser/network state 或 PII/SSO/MFA 截图/日志。"
+  },
+  {
+    "id": 2,
+    "prompt": "产品文档业务背景很多，但用户明确只要落实到前端开发和 QA 验收，不要长篇业务叙述。当前没有 swagger.json，需要先 mock。",
+    "expected": "压缩业务背景，只输出待联调态 frontend delta、mock/API contract、后续 swagger 替换清单、QA 浏览器验收路径和阻塞问题。"
+  }
+]

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

@@ -243,4 +243,19 @@ Index of every `references/` file in this skill. Read on demand.
 | `references/regression-gates.md` | Regression gates (preserved). |
 | `references/requirement-boundary-recheck.md` | 5-step requirement boundary recheck. |
 | `references/test-case-generation.md` | Test case categories + format + acceptance linkage. |
-| `references/test-report-output.md` | Test report minimum 8 sections. |
+| `references/test-report-output.md` | Test report minimum 8 sections. |
+## L2 surface reference (post rid-l2-extended)
+
+For QA slices that verify lease / dispatch / observability behavior, the L2 ecosystem (shipped 2026-07-29) provides these read-mostly surfaces:
+
+- `peaks lease-metrics [--rate] [--all-sessions]` — per-kind event counts (spawn/renew/release/gc/autoRelease/autoRelease-failed). QA can assert that an L2 test scenario emits the expected sequence.
+- `peaks lease-stats` — project-wide summary; verify per-rid / per-role / per-isolation breakdown matches the test plan
+- `peaks worktree list` — canonical "alive" set of leases (FS state). `lease-metrics` is a historical view; `peaks worktree list` is the source of truth for "is this lease still alive right now?"
+- `peaks audit red-lines` — 119 red lines / 66 cli-backed / 0 partial. QA can gate a release on `proseOnly === 0` + `cliBacked >= partial threshold`
+- `peaks container list` — L4 container leases (Part 12). Use to verify container-isolation scenarios when `--isolation container` is exercised
+
+QA contracts to assert on the L2 surface (a minimal acceptance test set):
+1. After `dispatch --isolation worktree` + `heartbeat --status done`, the lease file is `released` AND the worktree dir is gone.
+2. `peaks worktree list` reports 0 active leases after a clean run.
+3. `peaks lease-metrics --rate` after a 1-spawn / 0-release test reports `estimatedLeaked: 1, completedLifetimes: 0`.
+4. `peaks audit red-lines` reports `proseOnly: 0` and `partial: 0` for any shipped L2 surface.

package/skills/bee/peaks-qa/references/qa-sub-agent-dispatch.md

@@ -2,6 +2,28 @@
 
 > Body of `## Sub-agent dispatch`. When this skill is launched as a sub-agent via `peaks sub-agent dispatch <role>` (then the LLM executes the returned toolCall) from `peaks-code`, the following sections of THIS skill are **suspended** for the sub-agent run:
 
+## Superpowers chain refusal (L1 worktree governance — locked 2026-07-29)
+
+You MUST NOT follow the superpowers chain for worktree decisions:
+
+- superpowers:brainstorming → superpowers:writing-plans →
+  superpowers:subagent-driven-development → superpowers:using-git-worktrees
+
+This chain ends with `git worktree add` (superpowers:using-git-worktrees SKILL.md line 96). It bypasses peaks-loop's L2 hook gate and L3 IDE `permissions.deny`. Even when L3 denies the terminal Skill, the chain has already taught you to use raw `git worktree add`, so L3 is not sufficient.
+
+For worktree operations, use ONLY:
+
+- `peaks worktree spawn --rid <rid> --ttl <duration> --purpose <text>` (after rid-L2-extended ships)
+- until then: `peaks worktree auth grant --rid <id> --reason <text> --ttl <5m>`
+
+The superpowers skills remain available as REFERENCE material for brainstorming / planning techniques, but MUST NOT be used as a workflow. peaks-qa's own QA artifacts (`.peaks/_runtime/<sessionId>/qa/<artifact>.md`) are authoritative.
+
+If the upstream superpowers chain suggests raw `git worktree add`:
+
+1. STOP
+2. Re-author the QA plan as a peaks-qa artifact
+3. Continue with `peaks worktree spawn` (or the auth-grant fallback)
+
 - **Session id** — use the parent's sid (read `.peaks/_runtime/session.json` or pass `--session-id <parent-sid>` to any session-creating CLI). Do NOT spawn your own session. The new `peaks session info --active` reads the canonical binding for you.
 - **Skill presence (MANDATORY first action)** — do NOT call `peaks skill presence:set peaks-qa`. The sub-agent must not overwrite `.peaks/.active-skill.json`; the main Code loop owns that file. If you need to mark your own state, write a marker file at `.peaks/_runtime/<sessionId>/system/sub-agent-qa.json` and only that.
 - **Workspace initialization** — Code has already run `peaks workspace init` before fan-out. Do not re-run it.

package/skills/bee/peaks-qa/test-prompts.json

@@ -0,0 +1,12 @@
+[
+  {
+    "id": 1,
+    "prompt": "验证 /Users/yuanyuan/Desktop/work/platform-rag-web 的前端需求实现。后端 swagger.json 不存在，当前实现使用 mock/API contract。",
+    "expected": "QA 运行相关测试/API 或 mock contract 验证，启动前端应用，用 headed gstack/browse/dist/browse 有头浏览器做强制 E2E，遇到登录时等待用户完成并回复确认后再继续，记录脱敏 route/actions、脱敏 console/network 失败、脱敏截图或观察；不得保留登录 URL、cookie、headers、tokens、storage state、browser traces、PII/SSO/MFA 材料；生成 .peaks/_runtime/<session-id>/qa/validation-report.md，并包含安全和性能检查结果。"
+  },
+  {
+    "id": 2,
+    "prompt": "浏览器 E2E 中如果页面白屏、console 报错、网络 mock 失败、UI 有明显回归怎么办？",
+    "expected": "QA 必须带证据退回 RD 修复，不能通过 QA；修复后重新浏览器验证。"
+  }
+]

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

@@ -136,30 +136,20 @@ If any gate fails, return to development for fixes or hand off as blocked. Do no
 
 ## Parallel review fan-out (v2.12.0 3-way fanout — code-reviewer + qa-test-cases-writer + karpathy-reviewer)
 
-The THREE review activities run in parallel via `peaks sub-agent dispatch <role>`, not sequentially. Sub-agents: `code-reviewer`, `qa-test-cases-writer` (writes `qa/test-cases/<rid>.md`), `karpathy-reviewer` (the **hard Karpathy-Gate**). This is the v2.12.0 3-way fanout. Feature / refactor / bugfix: all three. Config / docs / chore: no fan-out — no `karpathy-reviewer` dispatched. OCR augmentation (B3): `peaksConfig.ocr.llm` → `peaks code-review run-ocr --json` → merge into `code-review.md`; → `references/ocr-integration.md`.
+**v2.12.0 collapse (Group A — Tier 1+2+3):** the previous 5-way fan-out (slice 004 4-way + slice 5/6 `karpathy-reviewer` addition) totalled **5 sub-agents**. The `security-reviewer` and `perf-baseline-reviewer` slots moved out of the RD 3-way fan-out into two new standalone audit skills:
 
-> **v2.12.0 collapse (Group A):** the 5-way fan-out moved `security-reviewer` + `perf-baseline-reviewer` into standalone audit skills (`peaks-security-audit` + `peaks-perf-audit`). → `references/v2-12-fanout-collapse.md`.
+- `peaks-security-audit` — CLI: `peaks security-audit run`. Writes `audit/security.md` (under `.peaks/_runtime/<sessionId>/audit/security.md`). Required RD-side prereq `AUDIT_SECURITY`.
+- `peaks-perf-audit` — CLI: `peaks perf-audit run`. Writes `audit/perf.md` (under `.peaks/_runtime/<sessionId>/audit/perf.md`). Required RD-side prereq `AUDIT_PERF`.
 
-> **v2.15.0+:** 技术决策 AI 据 prd 业务场景块自决,user 不参与;存量项目无 UT,改 A 前跑 `peaks impact scan`(G13);fork 场景 tech-doc 列上游基线+业务 patch 集(G11)。详见 `.peaks/memory/peaks-loop-user-role-and-tech-decision.md`。
+Both audit skills consume the immutable peaks-prd handoff (`prd/handoff.md`) and the project-scoped audit templates under `.peaks/project-scan/{security-template, perf-template, audit-output-schema}.md`. The handoff presence is enforced by the `AUDIT_REQUIRES_HANDOFF` prereq. The 1-minor-release back-compat window (v2.12.0) keeps the old `rd/security-review.md` and `rd/perf-baseline.md` paths readable via `mustContainAny` — see `references/rd-fanout-contracts.md` §"Deprecated reviewer back-compat".
 
-> **Slice 2026-06-24-efficiency-4p-bundle / G4 (P1.3) — karpathy-skip policy authoritative.** Decision table at `src/services/rd/reviewer-dispatch-policy.ts` (`shouldDispatchKarpathy`, `reviewerListFor`). Pinned by `tests/unit/rd/karpathy-skip-on-config-docs-chore.test.ts`.
+**Current 3-way fan-out** (always runs for feature / refactor / bugfix; no fan-out for config / docs / chore):
 
-### Hard Karpathy-Gate (Slice 5/6)
+1. `code-reviewer` — writes `rd/code-review.md` (Gate B3).
+2. `qa-test-cases-writer` — writes `qa/test-cases/<rid>.md` (Gate C2).
+3. `karpathy-reviewer` — writes `rd/karpathy-review.md` (the **hard Karpathy-Gate**, KARPATHY_REVIEW prereq).
 
-The `karpathy-reviewer` sub-agent is a **hard gate** for `rd:qa-handoff`. Per `andrej-karpathy-skills:karpathy-guidelines` §1 Think Before Coding ("state your assumptions") + §3 Surgical Changes ("touch only what the user asked"), `peaks request transition --state qa-handoff` is BLOCKED by the CLI gate until `.peaks/_runtime/<sessionId>/rd/karpathy-review.md` exists with the `## Karpathy-Gate` header and at least one of the 4 guideline section markers. The file is enforced by the `KARPATHY_REVIEW` prerequisite in `src/services/artifacts/artifact-prerequisites.ts` (added in Slice 5). The escape hatch is `peaks request transition --allow-incomplete --confirm` (assisted mode). The companion `peaks scan karpathy` CLI is a structural scanner for the same file (`src/services/scan/karpathy-service.ts`); the semantic review is the sub-agent's job.
-
-### Peaks-Loop Gate C — type-specific RD evidence
-
-The CLI gate at `rd:qa-handoff` is the authoritative check. Missing any required file → DO NOT attempt the qa-handoff transition; CLI will reject with `PREREQUISITES_MISSING`.
-
-| Request type | Required RD evidence |
-|---|---|
-| feature / refactor | `audit/security.md` + `audit/perf.md` + `rd/code-review.md` + `rd/karpathy-review.md` + `qa/test-cases/<rid>.md` + `prd/handoff.md` |
-| bugfix | `audit/security.md` + `audit/perf.md` (perf-shaped only) + `rd/code-review.md` + `rd/karpathy-review.md` + `qa/test-cases/<rid>.md` + `prd/handoff.md` |
-| config | `audit/security.md` |
-| docs / chore | (no extra evidence required) |
-
-→ see `references/rd-fanout-contracts.md` for the **3** sub-agents' contracts + hard prohibitions + aggregation + degradation. Pre-v2.12.0 `rd/{security-review,perf-baseline}.md` paths remain readable for the 1-minor-release back-compat window.
+Full dispatch contract (when-to-fan-out rules, dispatch template, prereq gates) lives in **`references/parallel-review-fanout.md`**. Read that file before issuing any 3-way fan-out.
 
 ## Refactor hard gates
 
@@ -229,6 +219,12 @@ Do not bypass the parallel review fan-out when the slice has a code-review / qa-
 
 **Security / perf audit boundary (v2.12.0):** security and perf audit run as standalone audit skills (`peaks-security-audit`, `peaks-perf-audit`) whose outputs land at `audit/security.md` / `audit/perf.md`. RD does **not** dispatch `security-reviewer` or `perf-baseline-reviewer` sub-agents. See `references/rd-fanout-contracts.md` §"Deprecated reviewer back-compat".
 
+## Karpathy cost self-review (slice 2026-07-30-karpathy-cost-self-review)
+
+The `karpathy-reviewer` sub-agent now reports its own runtime cost in the JSON envelope at `rd/karpathy-review.md` (fields `evaluationCost` + `costRatio`; see `agents/karpathy-reviewer.md` §4). The **orchestrator-side** command `peaks job karpathy-cost-check --review-file <path>` reads that envelope and decides whether to downgrade a `'block'` gateAction to `'warn'` when `costRatio > 10`. **24h-mode is the override** — the check is entirely skipped when `peaks session 24h-mode state` reports `24H_ACTIVE`.
+
+The main RD loop MUST call `peaks job karpathy-cost-check` after every `peaks request transition --state qa-handoff` and before the next-slice work begins. If the decision kind is `downgraded`, the LLM MUST honor the downgraded `warn` and proceed to the next slice; the `'block'` was an artifact of the reviewer's own cost, not the slice's quality. If the decision kind is `reported` (costRatio > 50, gate not `'block'`), the LLM MAY continue; the sediment will be appended by `peaks memory extract` at handoff time. The full design lives in `.peaks/memory/2026-07-30-karpathy-evaluation-cost-self-review-design.md` (sediment locked 2026-07-30).
+
 ## Sub-agent context governance (G7 + G7.7 + G8 + G9 — slice #010)
 
 RD sub-agent prompt template MUST include the G7 path convention + G8.6 share protocol. Detailed protocol: `skills/peaks-code/references/context-governance.md` + `skills/peaks-code/references/headroom-integration.md`.
@@ -283,4 +279,17 @@ Index of every `references/` file in this skill. Read on demand.
 | `references/rd-transition-gates.md` | Per-gate A-A3-B-B9 contract. |
 | `references/refactor-workflow.md` | Refactor hard gates + required artifacts. |
 | `references/skill-presence-and-title.md` | RD skill presence (main loop only). |
-| `references/v2-12-fanout-collapse.md` | v2.12.0 fan-out collapse. |
+| `references/v2-12-fanout-collapse.md` | v2.12.0 fan-out collapse. |
+## L2 surface reference (post rid-l2-extended)
+
+For RD slices that touch the lease / dispatch / observability stack, the canonical L2 surface is the L2 ecosystem shipped 2026-07-29 (commits `33aad895` through `075321af`). The high-leverage CLIs RD slices will encounter:
+
+- `peaks worktree spawn / renew / list / gc / lease-status / release` — lease lifecycle (source of truth for L2 hook gate)
+- `peaks sub-agent dispatch --isolation worktree|container` — auto-spawns a lease; `PEAKS_WORKTREE_LEASE_ID` env var is the gate's lookup key
+- `peaks container spawn / release` — L4 container runtime (Part 12); pairs with `--isolation container` on dispatch
+- `peaks lease-metrics [--rate] [--all-sessions]` — per-kind event counts + leak-rate + lifetime stats
+- `peaks lease-stats` — project-wide summary (per-rid / per-role / per-isolation breakdown)
+- `peaks cron init / list / run` — scheduled tasks (lease-gc-daily built-in); `peaks cron-scheduler start` for daemon mode
+- `peaks audit red-lines` — 119 catalog red-lines; 66 cli-backed enforcers (sweep 003) + 53 catalog
+
+The pre-existing SKILL.md reference set (this section is additive — not a replacement) covers the LLM-flow contracts. The CLIs above are operator / dashboard surfaces.

package/skills/bee/peaks-rd/references/rd-sub-agent-dispatch.md

@@ -2,6 +2,28 @@
 
 > Body of `## Sub-agent dispatch`. When this skill is launched as a sub-agent via `peaks sub-agent dispatch <role>` (then the LLM executes the returned toolCall) from `peaks-code`, the following sections of THIS skill are **suspended** for the sub-agent run:
 
+## Superpowers chain refusal (L1 worktree governance — locked 2026-07-29)
+
+You MUST NOT follow the superpowers chain for worktree decisions:
+
+- superpowers:brainstorming → superpowers:writing-plans →
+  superpowers:subagent-driven-development → superpowers:using-git-worktrees
+
+This chain ends with `git worktree add` (superpowers:using-git-worktrees SKILL.md line 96). It bypasses peaks-loop's L2 hook gate and L3 IDE `permissions.deny`. Even when L3 denies the terminal Skill, the chain has already taught you to use raw `git worktree add`, so L3 is not sufficient.
+
+For worktree operations, use ONLY:
+
+- `peaks worktree spawn --rid <rid> --ttl <duration> --purpose <text>` (after rid-L2-extended ships)
+- until then: `peaks worktree auth grant --rid <id> --reason <text> --ttl <5m>`
+
+The superpowers skills remain available as REFERENCE material for brainstorming / planning techniques, but MUST NOT be used as a workflow. peaks-rd's own PRD/RD artifacts (`.peaks/_runtime/<sessionId>/rd/requests/<rid>.md`) are authoritative.
+
+If the upstream superpowers chain suggests raw `git worktree add`:
+
+1. STOP
+2. Re-author the plan as a peaks-rd artifact
+3. Continue with `peaks worktree spawn` (or the auth-grant fallback)
+
 ## Default `--from-dag` is mandatory (slice 2026-06-24-efficiency-4p-bundle / G2 / P0.3)
 
 > **Hard constraint**: when the swarm plan DAG has ≥ 2 leaves at the
@@ -74,6 +96,23 @@ What the sub-agent **MUST** still do, from this skill's contract:
 
 After returning, Code re-checks Gate B (`ls .peaks/_runtime/<sessionId>/rd/requests/<rid>.md` etc.) and proceeds to RD implementation, which is a different sub-agent or inline run.
 
+## G11.5 visibility contract (mandatory, slice 2026-07-28-sub-agent-visibility)
+
+Any RD/QA/SC sub-agent dispatched by `peaks sub-agent dispatch --from-dag` (or by the single-shot `dispatch <role> --prompt ...` path) MUST register an artifact path via `--write-artifact <path>` BEFORE spawning, and the orchestrator MUST surface a 1-line `⏳ Spawning sub-agent via Task tool: <description>` prose to the user BEFORE each `Agent` tool call.
+
+**Hard rules (text-locked, no skip):**
+
+1. **Artifact registration is mandatory for non-trivial RD/QA/SC sub-agents.** The dispatch CLI now exposes two new envelope fields — `artifactsPublicPaths: string[]` and `orchestratorVisibleHint: string` — that the orchestrator reads back to the user. The RD/QA/SC sub-agent MUST register the artifact path it intends to write via `--write-artifact <absolute-path>` so the envelope surfaces the path to the user before the agent actually starts. Skipping `--write-artifact` is a visibility regression: the user cannot tell what file the sub-agent will create.
+2. **Orchestrator surfaces the prose BEFORE spawning.** For every `Agent` tool call that materializes a `peaks sub-agent dispatch` envelope, the orchestrator MUST emit one visible line of prose to the user of the form `⏳ Spawning sub-agent via Task tool: <description>` where `<description>` is ≥ 6 chars and includes the rid. The line lives in the orchestrator's reply text, not in the tool result.
+3. **Fan-out keeps the line singular.** When the envelope returns `dispatchCount > 1` (i.e. `--from-dag` with N ≥ 2 leaves), the orchestrator emits the prose once for the whole batch, not N times. Per-leaf prose defeats the wall-time benefit of fan-out.
+4. **No auto-commit disclaimer survives this contract.** The same prompt template that today forbids `git commit / git push / install hooks / apply settings.json mutations` (slice 2026-06-28 incident) is unchanged. G11.5 layers ABOVE that — visibility first, hard prohibitions second.
+
+**Where the orchestrator reads the values from**: `data.orchestratorVisibleHint` (one line, copy verbatim) and `data.artifactsPublicPaths` (the public list of artifact paths the sub-agent will own). The CLI fills these in; the orchestrator just transcribes.
+
+**Regression guard**: `tests/unit/dispatch/dispatch-fanout-mandatory.test.ts` parses `rd-sub-agent-dispatch.md` and asserts the G11.5 heading is present. Do not delete the heading without updating the guard.
+
+---
+
 ## Test Tool Detection (mandatory)
 
 The dispatch CLI (`peaks sub-agent dispatch`) automatically prepends a Test Tool Detection block to every sub-agent prompt — telling the sub-agent to read `package.json#scripts.test` first and use the project-local runner (`./node_modules/.bin/<runner>` or `pnpm test -- <file>`). NEVER use `npx <runner>`. This rule is machine-injected, not a prompt ritual — every sub-agent gets it including rd/qa/ui/txt/sc.

package/skills/bee/peaks-rd/test-prompts.json

@@ -0,0 +1,12 @@
+[
+  {
+    "id": 1,
+    "prompt": "根据 peaks-prd 产出的前端待联调 delta，在 /Users/yuanyuan/Desktop/work/platform-rag-web 中实现 UI/交互/API mock。项目没有后端 swagger.json，需要先用 mock/API contract 开发。",
+    "expected": "RD 先做 standards init/update dry-run 和项目扫描；非平凡变更检查 OpenSpec；按最小 slice 实现；新增/变更代码有单测或合理 focused coverage；前端/UI slice 自测必须用 headed gstack/browse/dist/browse 有头浏览器端到端验证并记录脱敏 route/actions、脱敏 console/network 观察和验收结果；完成 code review、安全 review、post-check dry-run 后才交给 QA；所有进入 .peaks/_runtime/<session-id>/rd/ 的浏览器证据必须脱敏，不得保留登录 URL、cookie、headers、tokens、storage state、browser traces、raw browser/network state 或 PII/SSO/MFA 截图/日志。"
+  },
+  {
+    "id": 2,
+    "prompt": "目标项目是存量前端项目，整体 UT 覆盖率可能不达标，但本次只要求新增和改动部分覆盖。",
+    "expected": "不能因历史低覆盖直接失败；必须要求新增/改动代码的 focused test/coverage 证据，缺失则阻塞 RD completion。"
+  }
+]

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

@@ -1,5 +1,6 @@
 ---
 name: peaks-reviewer
+visibility: internal
 description: Third-party independent code-review skill for Peaks. Use as a parallel reviewer to karpathy-reviewer when a workflow needs an out-of-band (non-RD-model) review pass to mitigate single-LLM self-dogfood blind spots. Emits a schema-validated ReviewerEnvelope (no free-form LLM JSON). v2.14.0 G4.
 ---
 
@@ -74,3 +75,19 @@ Missing section: reviewer is skipped (transition still passes; envelope records
 ## Sub-agent dispatch (when launched by peaks-code swarm)
 
 When this skill runs as a sub-agent dispatched by peaks-code, the sub-agent receives the parent session id and change-id via envelope. It MUST write its output to `.peaks/_runtime/<sessionId>/rd/third-party-review.json` + `.md` and return a compact JSON envelope.
+
+## L2 surface reference (post rid-l2-extended)
+
+For slices that touch the L2 surface, the canonical CLIs are:
+- `peaks worktree {spawn,renew,list,gc,lease-status,release}` — lease lifecycle (Part 1-2)
+- `peaks sub-agent dispatch --isolation worktree|container` — auto-spawns a lease (Part 2.C + Part 8 contract)
+- `peaks container {spawn,release}` — L4 container runtime (Part 12, docker)
+- `peaks lease-metrics [--rate] [--all-sessions]` — per-kind counts + leak rate (Part 4-5)
+- `peaks lease-stats` — project-wide summary (Part 6)
+- `peaks cron {init,list,run}` + `peaks cron-scheduler start` — periodic lease gc (Part 14-15)
+- `peaks audit red-lines --project .` — 119 catalog red-lines / 86+ cli-backed enforcers / 0 prose-only (Part 13)
+
+Verify the surface (no need to re-derive):
+1. `peaks audit red-lines --project .` reports `proseOnly: 0` for any shipped L2 surface.
+2. `peaks lease-metrics --rate` after a clean run reports `estimatedLeaked: 0`.
+3. `peaks worktree list` returns 0 active leases after a clean run.

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

@@ -170,3 +170,19 @@ git log --oneline -5
 Do not implement code or test logic. Do not create GitHub repositories directly from the skill body. Use the Peaks-Loop CLI artifact commands.
 
 Reference: `references/artifact-retention.md`.
+
+## L2 surface reference (post rid-l2-extended)
+
+For slices that touch the L2 surface, the canonical CLIs are:
+- `peaks worktree {spawn,renew,list,gc,lease-status,release}` — lease lifecycle (Part 1-2)
+- `peaks sub-agent dispatch --isolation worktree|container` — auto-spawns a lease (Part 2.C + Part 8 contract)
+- `peaks container {spawn,release}` — L4 container runtime (Part 12, docker)
+- `peaks lease-metrics [--rate] [--all-sessions]` — per-kind counts + leak rate (Part 4-5)
+- `peaks lease-stats` — project-wide summary (Part 6)
+- `peaks cron {init,list,run}` + `peaks cron-scheduler start` — periodic lease gc (Part 14-15)
+- `peaks audit red-lines --project .` — 119 catalog red-lines / 86 cli-backed enforcers / 51 discovered (Part 13)
+
+Verify the surface (no need to re-derive):
+1. `peaks audit red-lines --project .` reports `proseOnly: 0` for any shipped L2 surface.
+2. `peaks lease-metrics --rate` after a clean run reports `estimatedLeaked: 0`.
+3. `peaks worktree list` returns 0 active leases after a clean run.