peaks-loop 4.0.0-beta → 4.0.0-beta.11

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "peaks-loop",
-  "version": "4.0.0-beta",
+  "version": "4.0.0-beta.11",
   "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",
@@ -39,10 +41,14 @@
     "README.md",
     "README-en.md",
     "CHANGELOG.md",
-    "LICENSE"
+    "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"
   ],
   "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",
@@ -51,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",
@@ -95,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/scripts/install-skills.mjs

@@ -172,21 +172,15 @@ function readPackageVersion(packageRoot = resolvePackageRoot()) {
 }
 
 function createConfigDefaults(packageRoot) {
-  return {
+return {
     version: readPackageVersion(packageRoot),
     currentWorkspace: null,
   workspaces: [],
   language: 'en',
-  model: 'sonnet',
   economyMode: true,
   swarmMode: true,
   tokens: {},
-  providers: {
-    minimax: {
-      model: 'minimax-2.7'
-    }
-  },
-    proxy: {}
+  proxy: {}
   };
 }
 
@@ -381,7 +375,7 @@ function resolveProjectRoot(options) {
  * overrides `PEAKS_CLAUDE_SKILLS_DIR` / `PEAKS_CLAUDE_OUTPUT_STYLES_DIR`
  * continue to work, and the legacy default is preserved.
  */
-const IDE_DETECTION_DIRS = [
+export const IDE_DETECTION_DIRS = [
   { id: 'claude-code', dir: '.claude' },
   { id: 'trae', dir: '.trae' },
   { id: 'trae-cn', dir: '.trae-cn' },
@@ -389,6 +383,7 @@ const IDE_DETECTION_DIRS = [
   { id: 'cursor', dir: '.cursor' },
   { id: 'qoder', dir: '.qoder' },
   { id: 'tongyi-lingma', dir: '.tongyi-lingma' },
+  { id: 'zcode', dir: '.zcode' },
 ];
 
 /**
@@ -404,7 +399,7 @@ const IDE_DETECTION_DIRS = [
  * directory was never populated. 2.0 fixes this by giving
  * all 8 platforms canonical install paths.
  */
-const IDE_SKILL_INSTALL_PROFILES = {
+export const IDE_SKILL_INSTALL_PROFILES = {
   'claude-code': {
     skillsDir: join(homedir(), '.claude', 'skills'),
     outputStylesDir: join(homedir(), '.claude', 'output-styles'),
@@ -469,6 +464,14 @@ const IDE_SKILL_INSTALL_PROFILES = {
     envVar: 'PEAKS_OPENCLAW_SKILLS_DIR',
     outputStylesEnvVar: 'PEAKS_OPENCLAW_OUTPUT_STYLES_DIR',
   },
+  'zcode': {
+    skillsDir: join(homedir(), '.zcode', 'skills'),
+    outputStylesDir: join(homedir(), '.zcode', 'output-styles'),
+    agentsDir: join(homedir(), '.zcode', 'agents'),
+    envVar: 'PEAKS_ZCODE_SKILLS_DIR',
+    outputStylesEnvVar: 'PEAKS_ZCODE_OUTPUT_STYLES_DIR',
+    agentsEnvVar: 'PEAKS_ZCODE_AGENTS_DIR',
+  },
 };
 
 function detectInstalledIdeId(projectRoot) {

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+

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

@@ -56,7 +56,7 @@ The canonical scope dir for this request is provided as `envelope.data.scopeDir`
 
 ## Sub-agent dispatch (when launched by peaks-code swarm)
 
-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: Session id, Skill presence, Workspace initialization, Mode selection, Statusline install. The sub-agent must NOT call `peaks request init` (Solo already initialised the slot), and must write `.peaks/_runtime/<sessionId>/qa/test-cases/<rid>.md` with test cases that link to PRD acceptance items. Return only a compact JSON envelope.
+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: Session id, Skill presence, Workspace initialization, Mode selection, Statusline install. The sub-agent must NOT call `peaks request init` (Code already initialised the slot), and must write `.peaks/_runtime/<sessionId>/qa/test-cases/<rid>.md` with test cases that link to PRD acceptance items. Return only a compact JSON envelope.
 
 > **v2.15.0+ 校准:** 每个 slice 完成,user 必介入做**业务审阅**(4-5 项业务/产品清单:业务流程 / 需求覆盖 / 边界 case / UI 装配 / 能合入下版吗),**不是技术审阅**。业务审过 → 进 final;业务不通过 → 返工。详见 `.peaks/memory/peaks-loop-slice-review-and-qa-perspective.md`。
 

package/skills/bee/peaks-qa/references/artifact-per-request.md

@@ -9,12 +9,12 @@ The three files for any QA invocation land under the active session's `qa/` work
 | # | File | Path | Reader | Content |
 |---|------|------|--------|---------|
 | 1 | Test cases | `.peaks/_runtime/<session-id>/qa/test-cases/<request-id>.md` | RD (before impl), QA | Generated test scenarios with status |
-| 2 | Test report | `.peaks/_runtime/<session-id>/qa/test-reports/<request-id>.md` | QA, SC, Solo | Summary, coverage%, security, perf, risks |
-| 3 | Request artifact | `.peaks/_runtime/<session-id>/qa/requests/<request-id>.md` | Solo, RD↔QA loop | Verdict, boundary check, links to #1 and #2 |
+| 2 | Test report | `.peaks/_runtime/<session-id>/qa/test-reports/<request-id>.md` | QA, SC, Code | Summary, coverage%, security, perf, risks |
+| 3 | Request artifact | `.peaks/_runtime/<session-id>/qa/requests/<request-id>.md` | Code, RD↔QA loop | Verdict, boundary check, links to #1 and #2 |
 
 ## Required content
 
-The request artifact is the **verdict carrier** — it must include: QA verdict (`pass` / `return-to-rd` / `blocked`), the red-line audit outcome, links to the test-cases and test-report, the boundary check (acceptance items covered, gaps), and any cross-skill handoff notes for Solo. The test cases file enumerates every scenario with status; the test report summarises execution and links the security / performance / regression companion files.
+The request artifact is the **verdict carrier** — it must include: QA verdict (`pass` / `return-to-rd` / `blocked`), the red-line audit outcome, links to the test-cases and test-report, the boundary check (acceptance items covered, gaps), and any cross-skill handoff notes for Code. The test cases file enumerates every scenario with status; the test report summarises execution and links the security / performance / regression companion files.
 
 ## Rules
 

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

@@ -3,14 +3,14 @@
 > 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:
 
 - **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 Solo 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** — Solo has already run `peaks workspace init` before fan-out. Do not re-run it.
-- **Mode selection** — Solo has already chosen the mode.
-- **Statusline install** — already done by Solo at session startup.
+- **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.
+- **Mode selection** — Code has already chosen the mode.
+- **Statusline install** — already done by Code at session startup.
 
 What the sub-agent **MUST** still do:
 
-0. **Do NOT call `peaks request init`** — Solo has already initialised the request artefact slot in the main loop before fan-out. The sub-agent reads it via `peaks request show <rid> --role qa --project <repo> --json` if it needs to.
+0. **Do NOT call `peaks request init`** — Code has already initialised the request artefact slot in the main loop before fan-out. The sub-agent reads it via `peaks request show <rid> --role qa --project <repo> --json` if it needs to.
 2. `peaks request show <rid> --role prd --project <repo> --json` (and `--role rd`, `--role ui` if UI is in the swarm plan).
 3. Standards preflight (dry-run only).
 4. Write `.peaks/_runtime/<sessionId>/qa/test-cases/<rid>.md` with test cases that link to PRD acceptance items.
@@ -30,7 +30,7 @@ What the sub-agent **MUST** still do:
 **Hard prohibitions** (sub-agent context):
 
 - Do NOT call `Skill(skill="...")`.
-- Do NOT call `peaks skill presence:set` — Solo owns the active-skill file.
+- Do NOT call `peaks skill presence:set` — Code owns the active-skill file.
 - Do NOT run the actual test suite, do NOT execute security/perf tools, do NOT open a browser — those are the **QA validation** phase, not the Swarm planning phase.
 - Do NOT commit, push, install hooks, or apply settings.json mutations.
 - Do NOT ask the user interactive questions. If you need clarification, return `{"status":"blocked","blockedReason":"<text>"}`.

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

@@ -136,30 +136,7 @@ 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):** 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`.
-
-> **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`。
-
-> **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`.
-
-### Hard Karpathy-Gate (Slice 5/6)
-
-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 content extracted to **`references/parallel-review-fanout.md`** (3-way fan-out dispatch contract, when-to-fan-out rules, dispatch template, prereq gates). Read that file before issuing any 3-way fan-out.
 
 ## Refactor hard gates
 
@@ -185,7 +162,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-fanout-contracts.md

@@ -73,7 +73,7 @@ end of implementation, RD fires 3 sub-agents in parallel via
   conversation context. They MUST NOT mutate parent settings
   (`peaks skill presence:set`, hooks install, `.claude/settings.json`).
 - Sub-agents MUST NOT call `peaks workflow verify-pipeline` — that is
-  Solo's responsibility.
+  Code's responsibility.
 - Sub-agents MUST NOT modify the request artifact body — they only
   write their respective review artifact.
 - Sub-agents MUST NOT install or persist external material (no

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

@@ -28,12 +28,12 @@ peaks understand show   --project <repo> --json                # when UA artifac
 peaks codegraph context --project <repo> "<task>"
 peaks codegraph affected --project <repo> <changed-files...> --json
 
-# 4.1 read project-scan from Solo's pre-RD scan — BLOCKING if missing
-# **STOP if .peaks/_runtime/<sessionId>/rd/project-scan.md does not exist.**
+# 4.1 read project-scan from Code's pre-RD scan — BLOCKING if missing
+# **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-sub-agent-dispatch.md

@@ -37,21 +37,21 @@
 > design — if either changes, update the other.
 
 - **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-rd`. The sub-agent must not overwrite `.peaks/.active-skill.json`; the main Solo loop owns that file. If you need to mark your own state, write a marker file at `.peaks/_runtime/<sessionId>/system/sub-agent-rd.json` and only that.
-- **Workspace initialization** — Solo has already run `peaks workspace init` before fan-out. Do not re-run it.
-- **Mode selection** — Solo has already chosen the mode. Read it from the prompt arguments (or from `.peaks/.active-skill.json` if you can, but do not write it).
-- **Statusline install** — already done by Solo at session startup; do not re-run.
+- **Skill presence (MANDATORY first action)** — do NOT call `peaks skill presence:set peaks-rd`. 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-rd.json` and only that.
+- **Workspace initialization** — Code has already run `peaks workspace init` before fan-out. Do not re-run it.
+- **Mode selection** — Code has already chosen the mode. Read it from the prompt arguments (or from `.peaks/.active-skill.json` if you can, but do not write it).
+- **Statusline install** — already done by Code at session startup; do not re-run.
 
 What the sub-agent **MUST** still do, from this skill's contract:
 
-0. **Do NOT call `peaks request init`** — Solo has already initialised the request artefact slot in the main loop before fan-out (the runbook has the exact `peaks request init --role rd --id <rid> --project <repo> --apply --type <type> --json` call). The sub-agent reads the slot via `peaks request show <rid> --role rd --project <repo> --json` if it needs to. Note: `peaks request init` is **dry-run by default**. Pass `--apply` to actually create the artifact.
+0. **Do NOT call `peaks request init`** — Code has already initialised the request artefact slot in the main loop before fan-out (the runbook has the exact `peaks request init --role rd --id <rid> --project <repo> --apply --type <type> --json` call). The sub-agent reads the slot via `peaks request show <rid> --role rd --project <repo> --json` if it needs to. Note: `peaks request init` is **dry-run by default**. Pass `--apply` to actually create the artifact.
 2. `peaks request show <rid> --role prd --project <repo> --json` (and `--role ui` if UI is in the swarm plan).
-3. Standards preflight (dry-run only; Solo owns the apply step).
-4. Project-scan read; create `rd/project-scan.md` only if Solo flagged it missing in the dispatch prompt.
+3. Standards preflight (dry-run only; Code owns the apply step).
+4. Project-scan read; create `rd/project-scan.md` only if Code flagged it missing in the dispatch prompt.
 5. Write the planning artefact: `rd/requests/<rid>.md` (feature/refactor, per the `artifact-per-request.md` contract) or `rd/bug-analysis.md` (bugfix). If `--type` is `config|docs|chore`, **no planning artefact is required** — return immediately with `{"role":"rd-planning","status":"skipped","reason":"type=<type>"}`.
 
    > **v2.11.0 change (Group A):** `rd/tech-doc.md` is removed. The per-slice planning record is the per-request artefact at `rd/requests/<rid>.md`; the slice's source-of-truth architecture is the immutable peaks-prd handoff at `prd/handoff.md` (verify handoff hash = `<dispatched value>` before reading).
-6. Return only a compact JSON envelope — Solo will run the convergence gate (`ls` checks):
+6. Return only a compact JSON envelope — Code will run the convergence gate (`ls` checks):
 
 ```json
 {
@@ -67,12 +67,12 @@ What the sub-agent **MUST** still do, from this skill's contract:
 **Hard prohibitions** (sub-agent context, in addition to general red lines):
 
 - Do NOT call `Skill(skill="...")` from inside the sub-agent — that defeats the fan-out.
-- Do NOT call `peaks skill presence:set` — Solo owns the active-skill file.
+- Do NOT call `peaks skill presence:set` — Code owns the active-skill file.
 - Do NOT commit, push, install hooks, or apply settings.json mutations.
-- Do NOT ask the user interactive questions. If you need clarification, return `{"status":"blocked","blockedReason":"<text>"}` and let Solo handle the user message.
+- Do NOT ask the user interactive questions. If you need clarification, return `{"status":"blocked","blockedReason":"<text>"}` and let Code handle the user message.
 - Do NOT modify code (the Swarm phase is planning only; code edits happen in the RD implementation phase, which is a separate sub-agent or inline run after Gate B).
 
-After returning, Solo 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.
+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.
 
 ## Test Tool Detection (mandatory)
 

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.
 ```
 
@@ -104,7 +104,7 @@ peaks scan request-type-sanity --project <repo> --type <type> --json
 peaks request repair-status <rid> --project <repo> --session-id <session-id> --json
 # Expected: atCap=false. exit 0.
 # atCap=true → BLOCKED. Three repair cycles already attempted; emit a blocked TXT
-# handoff via Solo rather than entering a fourth cycle.
+# handoff via Code rather than entering a fourth cycle.
 ```
 
 **Peaks-Loop Gate B8 — Diff stays inside the declared red-line scope:**

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

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

@@ -61,7 +61,7 @@ Every SC invocation must write a change-control record at `.peaks/_runtime/<sess
 - validation result (`peaks sc validate` output);
 - boundary record (`peaks sc boundary` output).
 
-Solo reads this record before declaring the workflow complete.
+Code reads this record before declaring the workflow complete.
 
 ## Refactor role
 

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

@@ -1,5 +1,6 @@
 ---
 name: peaks-security-audit
+visibility: internal
 description: Independent security audit skill. Reads the immutable peaks-prd handoff + the project-level security-template.md, performs an OWASP Top-10 + 8-dimension threat model audit, and writes a structured envelope to `.peaks/_runtime/<sessionId>/audit/security-<rid>.md`. Decoupled from peaks-rd 5-way fan-out per slice v2.12.0 (Group A, Tier 2). Use when the slice introduces authn/authz, secrets, input validation, path/filesystem trust, SQL/NoSQL injection, XSS/content injection, dependency supply chain, or external API surface changes.
 metadata:
   appliesTo: peaks-loop v2.12.0+

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

@@ -21,7 +21,7 @@ Before any analysis or tool call, immediately run:
 peaks skill presence:set peaks-txt --project <repo> --mode <mode> --gate startup
 ```
 
-**When invoked as a sub-agent (peaks-code swarm):** do NOT call `peaks skill presence:set` (Solo owns the active-skill marker) and do NOT spawn your own session. Use the parent's sid — read `.peaks/_runtime/session.json` or pass `--session-id <parent-sid>` to any session-creating CLI. The new `peaks session info --active` reads the canonical binding for you.
+**When invoked as a sub-agent (peaks-code swarm):** do NOT call `peaks skill presence:set` (Code owns the active-skill marker) and do NOT spawn your own session. Use the parent's sid — read `.peaks/_runtime/session.json` or pass `--session-id <parent-sid>` to any session-creating CLI. The new `peaks session info --active` reads the canonical binding for you.
 
 On the first presence:set in a project, ensure the out-of-band status bar is installed so the user can see at a glance that Peaks is orchestrating — it renders the active skill in Claude Code's terminal status line, independent of model output:
 
@@ -68,7 +68,7 @@ When used alone or when a workflow needs portable artifacts that must survive se
 
 ```markdown
 ## Handoff: <request-id>
-- **Mode:** solo | assisted | swarm | strict
+- **Mode:** code | assisted | swarm | strict
 - **Status:** complete | blocked | return-to-rd
 - **Artifacts:**
   - PRD: .peaks/_runtime/<sessionId>/prd/requests/<rid>.md
@@ -114,7 +114,7 @@ Each entry should include:
 - lesson or rule;
 - why it exists;
 - affected skills;
-- how future PRD/RD/UI/QA/SC/Solo workflows should apply it;
+- how future PRD/RD/UI/QA/SC/Code workflows should apply it;
 - whether it is stable enough for `.peaks/memory` extraction.
 
 ## Project memory guidance

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

@@ -37,14 +37,14 @@ UI inherits `peaks-qa`'s hard-block contract: `AskUserQuestion` with three optio
 When this skill is launched as a sub-agent via `peaks sub-agent dispatch <role>` from `peaks-code`, these sections are **suspended** for the sub-agent run:
 
 - **Session id** — use parent's sid (`.peaks/_runtime/session.json` or `--session-id <parent-sid>`). Do NOT spawn your own session; `peaks session info --active` reads the canonical binding.
-- **Skill presence** — do NOT call `peaks skill presence:set peaks-ui`; Solo owns `.peaks/.active-skill.json`. Marker file at `.peaks/_runtime/<session-id>/system/sub-agent-ui.json` only.
-- **Workspace initialization** — Solo ran `peaks workspace init` before fan-out; do not re-run.
-- **Mode selection** — Solo chose the mode.
-- **Statusline install** — done by Solo at startup.
+- **Skill presence** — do NOT call `peaks skill presence:set peaks-ui`; Code owns `.peaks/.active-skill.json`. Marker file at `.peaks/_runtime/<session-id>/system/sub-agent-ui.json` only.
+- **Workspace initialization** — Code ran `peaks workspace init` before fan-out; do not re-run.
+- **Mode selection** — Code chose the mode.
+- **Statusline install** — done by Code at startup.
 
 What the sub-agent **MUST** still do:
 
-1. **Do NOT call `peaks request init`** — Solo already initialised the slot. Read via `peaks request show <rid> --role ui --project <repo> --json` if needed.
+1. **Do NOT call `peaks request init`** — Code already initialised the slot. Read via `peaks request show <rid> --role ui --project <repo> --json` if needed.
 2. Read PRD scope via `peaks request show <rid> --role prd --project <repo> --json`.
 3. Read `rd/project-scan.md` for component library / CSS framework / design-system context.
 4. Run the prototype fidelity check (Figma / PRD visuals / headed browser).
@@ -65,13 +65,13 @@ What the sub-agent **MUST** still do:
 **Hard prohibitions** (sub-agent context):
 
 - Do NOT call `Skill(skill="...")`.
-- Do NOT call `peaks skill presence:set` — Solo owns active-skill.
+- Do NOT call `peaks skill presence:set` — Code owns active-skill.
 - Do NOT modify application code. UI is design-direction only.
-- Do NOT install MCP servers. If Playwright MCP is missing and headed browser is required, return `{"status":"blocked","blockedReason":"playwright-mcp-unavailable"}` for Solo escalation. (peaks-loop no longer manages MCP install — user runs `claude mcp add playwright -- npx @playwright/mcp@latest` in Claude Code.)
+- Do NOT install MCP servers. If Playwright MCP is missing and headed browser is required, return `{"status":"blocked","blockedReason":"playwright-mcp-unavailable"}` for Code escalation. (peaks-loop no longer manages MCP install — user runs `claude mcp add playwright -- npx @playwright/mcp@latest` in Claude Code.)
 - Do NOT commit, push, install hooks, or apply settings.json mutations.
 - Do NOT ask user questions; return `{"status":"blocked","blockedReason":"<text>"}` if blocked.
 
-If the request does not affect user-visible behavior (no frontend keyword hit, `frontendOnly=false`), the swarm plan should not include UI at all — Solo will not launch this sub-agent. But if it does launch you and you determine the work is non-visual, return `{"status":"skipped","reason":"non-frontend-request"}` so Solo can record the misfire.
+If the request does not affect user-visible behavior (no frontend keyword hit, `frontendOnly=false`), the swarm plan should not include UI at all — Code will not launch this sub-agent. But if it does launch you and you determine the work is non-visual, return `{"status":"skipped","reason":"non-frontend-request"}` so Code can record the misfire.
 
 ## Skill presence (MANDATORY first action — main-loop context only)
 
@@ -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).