peaks-loop 4.0.0-beta.8 → 4.0.1

package/dist/shared/stale-policy.d.ts

@@ -0,0 +1,67 @@
+/**
+ * stale-policy — pure helper for stale detection and filtering on memory
+ * and (future) retrospective entries.
+ *
+ * Slice 023 (R3) applies this to memory only (`peaks project memories:show`
+ * and the underlying `readMemoryIndex` load path). The retrospective index
+ * loader shares the same shape (`updatedAt: string`) and will be wired to
+ * the same helper in a future slice.
+ *
+ * Behavior:
+ *   - `isStale(updatedAt)` returns true when (now - updatedAt) >
+ *     thresholdDays * 86_400_000. Strict greater-than: a 30-day-old
+ *     entry is NOT stale.
+ *   - `applyStalePolicy(entries)` adds `stale: boolean` and
+ *     `ageDays: number` to every entry (computed at CLI load time, never
+ *     persisted to source `.md` files) and filters out entries where
+ *     `stale === true` unless `includeStale: true` is passed.
+ *   - Missing `updatedAt` is treated as fresh (`stale: false`,
+ *     `ageDays: 0`); we never throw, so older index.json entries that
+ *     lack the field stay loadable.
+ */
+export interface StalePolicyOptions {
+    /** Reference clock (ms since epoch). Defaults to Date.now(). Injected for testability. */
+    now?: number;
+    /** Threshold in days. Default 30. */
+    thresholdDays?: number;
+    /** When true, keep stale entries in the returned array (with `stale: true` set). Default false. */
+    includeStale?: boolean;
+}
+export interface StaleAnnotated<T> {
+    stale: boolean;
+    ageDays: number;
+}
+export type StaleAnnotatedEntry<T> = T & StaleAnnotated<T>;
+export interface StalePolicyResult<T> {
+    /** Filtered array, with stale entries removed (unless includeStale=true). */
+    entries: StaleAnnotatedEntry<T>[];
+    /** Count of entries dropped as stale. */
+    droppedCount: number;
+    /** Total count before filtering. */
+    totalCount: number;
+}
+export declare const DAY_MS = 86400000;
+export declare const DEFAULT_STALE_DAYS = 30;
+/**
+ * Returns true when the entry is older than `thresholdDays`. Strict
+ * greater-than: an entry exactly at the threshold is NOT stale.
+ *
+ * A missing or unparseable `updatedAt` is treated as fresh (false). This
+ * is the "defensive — older index.json entries may lack the field" rule
+ * from PRD R4.
+ */
+export declare function isStale(updatedAt: string | undefined | null, options?: StalePolicyOptions): boolean;
+/**
+ * Age in days between `updatedAt` and `now` (default Date.now()).
+ * Returns 0 for a missing / unparseable `updatedAt`.
+ */
+export declare function ageInDays(updatedAt: string | undefined | null, now?: number): number;
+/**
+ * Apply the stale policy to a list of entries. Each entry is augmented
+ * with `stale: boolean` and `ageDays: number` (immutably — a fresh
+ * object is returned per entry). Stale entries are dropped from
+ * `entries` unless `includeStale: true` is passed.
+ */
+export declare function applyStalePolicy<T extends {
+    updatedAt?: string | null;
+}>(entries: T[], options?: StalePolicyOptions): StalePolicyResult<T>;

package/dist/shared/stale-policy.js

@@ -0,0 +1,85 @@
+/**
+ * stale-policy — pure helper for stale detection and filtering on memory
+ * and (future) retrospective entries.
+ *
+ * Slice 023 (R3) applies this to memory only (`peaks project memories:show`
+ * and the underlying `readMemoryIndex` load path). The retrospective index
+ * loader shares the same shape (`updatedAt: string`) and will be wired to
+ * the same helper in a future slice.
+ *
+ * Behavior:
+ *   - `isStale(updatedAt)` returns true when (now - updatedAt) >
+ *     thresholdDays * 86_400_000. Strict greater-than: a 30-day-old
+ *     entry is NOT stale.
+ *   - `applyStalePolicy(entries)` adds `stale: boolean` and
+ *     `ageDays: number` to every entry (computed at CLI load time, never
+ *     persisted to source `.md` files) and filters out entries where
+ *     `stale === true` unless `includeStale: true` is passed.
+ *   - Missing `updatedAt` is treated as fresh (`stale: false`,
+ *     `ageDays: 0`); we never throw, so older index.json entries that
+ *     lack the field stay loadable.
+ */
+export const DAY_MS = 86_400_000;
+export const DEFAULT_STALE_DAYS = 30;
+/**
+ * Returns true when the entry is older than `thresholdDays`. Strict
+ * greater-than: an entry exactly at the threshold is NOT stale.
+ *
+ * A missing or unparseable `updatedAt` is treated as fresh (false). This
+ * is the "defensive — older index.json entries may lack the field" rule
+ * from PRD R4.
+ */
+export function isStale(updatedAt, options = {}) {
+    const parsed = parseUpdatedAt(updatedAt);
+    if (parsed === null)
+        return false;
+    const now = options.now ?? Date.now();
+    const thresholdDays = options.thresholdDays ?? DEFAULT_STALE_DAYS;
+    return now - parsed > thresholdDays * DAY_MS;
+}
+/**
+ * Age in days between `updatedAt` and `now` (default Date.now()).
+ * Returns 0 for a missing / unparseable `updatedAt`.
+ */
+export function ageInDays(updatedAt, now = Date.now()) {
+    const parsed = parseUpdatedAt(updatedAt);
+    if (parsed === null)
+        return 0;
+    return Math.max(0, Math.floor((now - parsed) / DAY_MS));
+}
+/**
+ * Apply the stale policy to a list of entries. Each entry is augmented
+ * with `stale: boolean` and `ageDays: number` (immutably — a fresh
+ * object is returned per entry). Stale entries are dropped from
+ * `entries` unless `includeStale: true` is passed.
+ */
+export function applyStalePolicy(entries, options = {}) {
+    const now = options.now ?? Date.now();
+    const thresholdDays = options.thresholdDays ?? DEFAULT_STALE_DAYS;
+    const includeStale = options.includeStale ?? false;
+    const annotated = entries.map((entry) => {
+        const parsed = parseUpdatedAt(entry.updatedAt ?? null);
+        if (parsed === null) {
+            return { ...entry, stale: false, ageDays: 0 };
+        }
+        const stale = now - parsed > thresholdDays * DAY_MS;
+        const ageDays = Math.max(0, Math.floor((now - parsed) / DAY_MS));
+        return { ...entry, stale, ageDays };
+    });
+    const filtered = includeStale
+        ? annotated
+        : annotated.filter((entry) => !entry.stale);
+    return {
+        entries: filtered,
+        droppedCount: annotated.length - filtered.length,
+        totalCount: annotated.length
+    };
+}
+function parseUpdatedAt(value) {
+    if (value === null || value === undefined || value === '')
+        return null;
+    const parsed = Date.parse(value);
+    if (Number.isNaN(parsed))
+        return null;
+    return parsed;
+}

package/dist/skills/peaks-maker/index.d.ts

@@ -0,0 +1,5 @@
+export declare const peaksMakerManifest: {
+    name: string;
+    description: string;
+    body: string;
+};

package/dist/skills/peaks-maker/index.js

@@ -0,0 +1,32 @@
+// src/skills/peaks-maker/index.ts
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { dirname, join } from "node:path";
+function parseFrontmatter(md) {
+    const m = md.match(/^---\n([\s\S]+?)\n---\n([\s\S]*)$/);
+    if (!m)
+        throw new Error("peaks-maker SKILL.md is missing YAML frontmatter");
+    const fm = {};
+    for (const line of m[1].split("\n")) {
+        const i = line.indexOf(":");
+        if (i > 0)
+            fm[line.slice(0, i).trim()] = line.slice(i + 1).trim();
+    }
+    // The non-null assertions below were unsafe: if `name:` or `description:`
+    // was absent from the frontmatter, `fm[name]` would be `undefined`, which
+    // violates the declared return type and silently leaks a malformed
+    // manifest to every consumer of `peaksMakerManifest`. Validate explicitly
+    // so a missing/empty key surfaces as a clear error at module-load time.
+    const name = fm.name;
+    const description = fm.description;
+    if (typeof name !== "string" || name.length === 0) {
+        throw new Error("peaks-maker SKILL.md is missing name or description in frontmatter");
+    }
+    if (typeof description !== "string" || description.length === 0) {
+        throw new Error("peaks-maker SKILL.md is missing name or description in frontmatter");
+    }
+    return { name, description, body: m[2] };
+}
+const here = dirname(fileURLToPath(import.meta.url));
+const md = readFileSync(join(here, "SKILL.md"), "utf-8");
+export const peaksMakerManifest = parseFrontmatter(md);

package/package.json

@@ -1,11 +1,10 @@
 {
   "name": "peaks-loop",
-  "version": "4.0.0-beta.8",
+  "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"
   },
@@ -22,9 +21,11 @@
   },
   "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",
+    "dist/**/*.sql",
     "scripts/clean-dist.mjs",
     "scripts/copy-templates.mjs",
     "scripts/sync-version.mjs",
@@ -40,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",
@@ -97,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"
@@ -108,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';
@@ -42,8 +51,15 @@ function copyTree(srcDir, destDir, extensions) {
 const targets = [
   {
     src: join(packageRoot, 'src/services/workspace/templates/project-scan'),
-    dest: join(packageRoot, 'dist/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；修复后重新浏览器验证。"
+  }
+]