peaks-loop 4.0.49 → 4.0.51

package/dist/services/workspace/workspace-service.js

@@ -363,6 +363,15 @@ export async function initWorkspace(options) {
                 .map((write) => write.relativePath)
         };
     }
+    const claudeSettings = await materializeClaudeSettingsLocal(options.projectRoot, options.noClaudeHooks === true);
+    // G4 (2026-09-15): record which release generated this project's config.
+    // Without it there is nothing on disk for a LATER release to compare
+    // against, so "your generated config is behind the installed peaks-loop"
+    // is not a decidable question — which is the whole of D1. Written on every
+    // init (including the no-op ones): the stamp answers "when did a release
+    // last regenerate this project", not "when did the bytes change". See
+    // `generated-artifacts-stamp.ts`.
+    writeGeneratedArtifactsStamp(options.projectRoot);
     return {
         sessionId: options.sessionId,
         sessionRoot,
@@ -370,7 +379,7 @@ export async function initWorkspace(options) {
         alreadyExisted,
         bound,
         previousSessionId,
-        claudeSettings: await materializeClaudeSettingsLocal(options.projectRoot, options.noClaudeHooks === true),
+        claudeSettings,
         standardsMissing,
         ...(standardsApplied !== undefined ? { standardsApplied } : {})
     };
@@ -385,6 +394,7 @@ export async function initWorkspace(options) {
 // are unchanged (verbatim move).
 import { materializeClaudeSettingsLocal } from './workspace-claude-settings-materializer.js';
 export { materializeClaudeSettingsLocal } from './workspace-claude-settings-materializer.js';
+import { writeGeneratedArtifactsStamp } from './generated-artifacts-stamp.js';
 /**
  * Slice C10 (2026-06-24-legacy-change-id-sibling): whole-dir shape check
  * for the legacy sibling `.peaks/_runtime/<sessionId>/`. Returns `true` ONLY when

package/dist/shared/fs-utils.d.ts

@@ -1,4 +1,30 @@
 import { type Platform } from './platform.js';
+/**
+ * Does this error mean "the path is legitimately absent or unreadable by us"?
+ *
+ * A `catch` is allowed to turn THAT class of failure into a fallback value.
+ * Every other error is a bug and must propagate. Without the distinction,
+ * "this catch only swallows IO errors" is a claim the code cannot keep:
+ *
+ *   catch (err) {
+ *     if (err instanceof ReferenceError) throw err;
+ *     if (err instanceof SyntaxError) throw err;
+ *     return null;   // ← swallows every TypeError, every ERR_INVALID_ARG_TYPE,
+ *                    //   every error a dependency throws, and calls it "IO"
+ *   }
+ *
+ * That exact shape sat on two priority sites (`post-compact-detector`,
+ * `step-08-gate`) with that exact comment. Rethrowing the two JS error
+ * classes it happened to name is not the same rule as swallowing one error
+ * class and rethrowing the rest — and it is the *inverted* one: the more
+ * unexpected the failure, the more certainly it was swallowed.
+ *
+ * The set is deliberately the "miss" codes only. `EISDIR` is included because
+ * reading a directory where a file was expected is indistinguishable from
+ * absent to every caller here, and excluding it would turn a pre-existing
+ * silent fallback into a new loud failure for no gain.
+ */
+export declare function isExpectedFsMiss(err: unknown): boolean;
 export declare function getDirectoryLinkType(targetPlatform?: Platform): 'junction' | 'dir';
 export declare function createDirectoryLinkSync(target: string, linkPath: string): void;
 export declare function readDirectoryLinkTarget(linkPath: string): string | null;

package/dist/shared/fs-utils.js

@@ -1,5 +1,40 @@
 import { symlinkSync as nodeSymlinkSync, readlinkSync } from 'node:fs';
 import { platform } from './platform.js';
+/**
+ * Does this error mean "the path is legitimately absent or unreadable by us"?
+ *
+ * A `catch` is allowed to turn THAT class of failure into a fallback value.
+ * Every other error is a bug and must propagate. Without the distinction,
+ * "this catch only swallows IO errors" is a claim the code cannot keep:
+ *
+ *   catch (err) {
+ *     if (err instanceof ReferenceError) throw err;
+ *     if (err instanceof SyntaxError) throw err;
+ *     return null;   // ← swallows every TypeError, every ERR_INVALID_ARG_TYPE,
+ *                    //   every error a dependency throws, and calls it "IO"
+ *   }
+ *
+ * That exact shape sat on two priority sites (`post-compact-detector`,
+ * `step-08-gate`) with that exact comment. Rethrowing the two JS error
+ * classes it happened to name is not the same rule as swallowing one error
+ * class and rethrowing the rest — and it is the *inverted* one: the more
+ * unexpected the failure, the more certainly it was swallowed.
+ *
+ * The set is deliberately the "miss" codes only. `EISDIR` is included because
+ * reading a directory where a file was expected is indistinguishable from
+ * absent to every caller here, and excluding it would turn a pre-existing
+ * silent fallback into a new loud failure for no gain.
+ */
+export function isExpectedFsMiss(err) {
+    const code = err?.code;
+    return (code === 'ENOENT' ||
+        code === 'ENOTDIR' ||
+        code === 'EISDIR' ||
+        code === 'EACCES' ||
+        code === 'EPERM' ||
+        code === 'ELOOP' ||
+        code === 'ENAMETOOLONG');
+}
 export function getDirectoryLinkType(targetPlatform = platform) {
     return targetPlatform === 'win32' ? 'junction' : 'dir';
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "peaks-loop",
-  "version": "4.0.49",
+  "version": "4.0.51",
   "description": "Loop Engineering CLI — workflow primitive / loop guards / evaluators / slice orchestration",
   "author": "SquabbyZ",
   "keywords": [
@@ -102,10 +102,10 @@
     "picomatch": "4.0.4",
     "yaml": "^2.9.0",
     "zod": "^4.4.3",
-    "peaks-loop-internal-runtime": "0.0.34",
-    "peaks-loop-mut": "0.1.47",
-    "peaks-loop-shared": "0.0.83",
-    "peaks-loop-shared-channel": "0.0.51"
+    "peaks-loop-internal-runtime": "0.0.36",
+    "peaks-loop-mut": "0.1.49",
+    "peaks-loop-shared": "0.0.85",
+    "peaks-loop-shared-channel": "0.0.53"
   },
   "devDependencies": {
     "@changesets/cli": "2.31.1",
@@ -141,6 +141,8 @@
     "test:dev": "vitest run tests/unit",
     "test:dev:cli": "vitest run tests/unit",
     "test:unit": "vitest run tests/unit",
+    "test:e2e": "vitest run --config vitest.config.e2e.ts",
+    "test:lint": "vitest run --config vitest.config.lint.ts",
     "test:integration": "vitest run --config vitest.config.integration.ts tests/integration",
     "test:capability-guard": "vitest run --config vitest.config.integration.ts tests/integration/capability-guard",
     "test:cli": "vitest run tests/unit",
@@ -149,8 +151,8 @@
     "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",
+    "test:race": "vitest run --no-file-parallelism packages/peaks-loop-shared-channel/tests/shared-channel.test.ts tests/unit/services/dispatch/dispatch-record-writer.test.ts",
+    "test:replay": "node scripts/fixture-capture-setup.mjs && vitest run tests/unit/services/dispatch/conflict-replay.test.ts tests/unit/services/dispatch/e2e-fixtures.test.ts",
     "fixture:capture-setup": "node scripts/fixture-capture-setup.mjs",
     "test:coverage": "node ./scripts/coverage-c8.mjs",
     "test:coverage:c8": "node ./scripts/coverage-c8.mjs",

package/scripts/copy-templates.mjs

@@ -60,18 +60,6 @@ const targets = [
     src: join(packageRoot, 'src/services/skillhub/migrations'),
     dest: join(packageRoot, 'dist/services/skillhub/migrations'),
     extensions: ['.sql']
-  },
-  {
-    // Slice c5-write-hook-exec-form: the Write|Edit|MultiEdit PreToolUse gate
-    // emitted by `peaks workspace init` is invoked as `node <path>`, and the
-    // path is resolved relative to this module — `dist/services/hooks/` in an
-    // installed consumer, `src/services/hooks/` under tsx. A plain `.js` asset
-    // (not a `.ts` compiled by tsc) is what lets ONE relative filename be valid
-    // in both trees. Without this copy the hook would be a broken path in every
-    // installed consumer while every test in this repo still passed.
-    src: join(packageRoot, 'src/services/hooks'),
-    dest: join(packageRoot, 'dist/services/hooks'),
-    extensions: ['.js']
   }
 ];
 

package/scripts/install-skills.mjs

@@ -256,10 +256,6 @@ function validateConfigPath(root, peaksRoot, configPath, label) {
   }
 }
 
-function validateProjectConfigPaths(projectRoot, peaksRoot, configPath) {
-  validateConfigPath(projectRoot, peaksRoot, configPath, 'Project');
-}
-
 function validateUserConfigPaths(userRoot, peaksRoot, configPath) {
   validateConfigPath(userRoot, peaksRoot, configPath, 'User');
 }
@@ -345,10 +341,6 @@ function writeFileAtomically(configPath, content, errorMessage, validateBeforeWr
   }
 }
 
-function writeProjectConfig(projectRoot, peaksRoot, configPath, content) {
-  writeFileAtomically(configPath, content, 'Project config path changed during write', () => validateProjectConfigPaths(projectRoot, peaksRoot, configPath));
-}
-
 function writeUserConfig(userRoot, peaksRoot, configPath, content) {
   writeFileAtomically(configPath, content, 'User config path changed during write', () => validateUserConfigPaths(userRoot, peaksRoot, configPath));
 }
@@ -374,6 +366,16 @@ function resolveProjectRoot(options) {
  * + emits a stderr warning. The dispatch is conservative: the env-var
  * overrides `PEAKS_CLAUDE_SKILLS_DIR` / `PEAKS_CLAUDE_OUTPUT_STYLES_DIR`
  * continue to work, and the legacy default is preserved.
+ *
+ * 2026-09-15 (D12 fix): `hermes` and `openclaw` have install profiles in
+ * `IDE_SKILL_INSTALL_PROFILES` but were absent from this table. A profile
+ * that no detector can ever return is reachable only through the
+ * every-platform fan-out — i.e. it is installed for users who do NOT have
+ * the tool and skipped for nobody. Both are listed here now, so detection
+ * and installation answer the same question with the same table.
+ *
+ * This table is ALSO the presence oracle for `isPlatformPresent` below: a
+ * directory here in the project root means the user has that tool.
  */
 export const IDE_DETECTION_DIRS = [
   { id: 'claude-code', dir: '.claude' },
@@ -384,23 +386,33 @@ export const IDE_DETECTION_DIRS = [
   { id: 'qoder', dir: '.qoder' },
   { id: 'tongyi-lingma', dir: '.tongyi-lingma' },
   { id: 'zcode', dir: '.zcode' },
+  { id: 'hermes', dir: '.hermes' },
+  { id: 'openclaw', dir: '.openclaw' },
 ];
 
 /**
  * Per-IDE skill install paths. Per peaks-loop tenet
  * "minimal-user-operation" (2026-06-11), the user should
  * never have to run a per-platform install command — the
- * `npm i -g peaks-loop` postinstall iterates ALL of these
- * and symlinks the peaks-* skill family to every platform
- * the user might be on.
+ * `npm i -g peaks-loop` postinstall iterates the platforms
+ * the user HAS and symlinks the peaks-* skill family into each
+ * (see `isPlatformPresent`; D9/2026-09-15 made "has" load-bearing).
  *
  * 1.x had only `claude-code` (the other 5 entries were
  * `null`); real Trae users reported the Trae skill
  * directory was never populated. 2.0 fixes this by giving
- * all 8 platforms canonical install paths.
+ * every platform a canonical install path.
  */
 export const IDE_SKILL_INSTALL_PROFILES = {
   'claude-code': {
+    // `alwaysPresent` — see `isPlatformPresent`. Declared HERE, in the
+    // vendor's own row, rather than as an `ideId === 'claude-code'` branch in
+    // the consumer: the guard at
+    // `tests/unit/runtime/vendor-neutral-identity-guard.test.ts` pins identity
+    // DECISIONS to the vendor declarations, and a comparison in the consumer
+    // is exactly the re-injection shape it exists to catch. A future vendor
+    // opts into the same policy by setting this field.
+    alwaysPresent: true,
     skillsDir: join(homedir(), '.claude', 'skills'),
     outputStylesDir: join(homedir(), '.claude', 'output-styles'),
     agentsDir: join(homedir(), '.claude', 'agents'),
@@ -489,6 +501,46 @@ function resolveIdeSkillInstallProfile(ideId) {
   return IDE_SKILL_INSTALL_PROFILES[ideId] ?? null;
 }
 
+/**
+ * Is this platform actually installed FOR? (D9 fix, 2026-09-15.)
+ *
+ * Before this gate, the postinstall ran `mkdirSync(targetRoot, {recursive:
+ * true})` for ALL 10 profiles unconditionally, so `npm i -g peaks-loop` created
+ * `~/.hermes`, `~/.openclaw`, `~/.qoder`, `~/.tongyi-lingma` and `~/.zcode` in
+ * the home of a user who has never installed those tools. The peaks-loop tenet
+ * is "the user never has to run a per-platform install command" — it is NOT
+ * "peaks-loop guesses which tools you have". Creating a directory for a tool
+ * the user does not own is the tenet misread, and it is visible on disk.
+ *
+ * Present means EITHER:
+ *   - the tool's marker directory exists in the project root (the same
+ *     directory `detectInstalledIdeId` consults above), OR
+ *   - the tool's own home directory (`~/.<tool>`, derived from its profile)
+ *     already exists on this machine.
+ *
+ * `claude-code` is unconditionally present: it is peaks-loop's primary runtime
+ * and the documented legacy install target, so a machine with no `~/.claude`
+ * yet still gets the trees the user is installing peaks-loop for. That fact is
+ * declared as `alwaysPresent: true` IN THE VENDOR'S OWN PROFILE ROW — not as an
+ * `ideId === 'claude-code'` branch here. This file sits outside the adapter
+ * layer, so an identity comparison in it is the re-injection shape
+ * `tests/unit/runtime/vendor-neutral-identity-guard.test.ts` pins; reading the
+ * vendor's declaration keeps the policy in one place and vendor-neutral.
+ *
+ * A named target bypasses this gate entirely — `options.targetRoot`,
+ * `options.ideId`, and the `PEAKS_<TOOL>_SKILLS_DIR` env vars are callers who
+ * have already said which platform they mean; guessing a second time there
+ * would break the 1.x back-compat contract that slice 2026-06-12 restored.
+ */
+function isPlatformPresent(ideId, profile, projectRoot) {
+  if (profile.alwaysPresent === true) return true;
+  const detection = IDE_DETECTION_DIRS.find((entry) => entry.id === ideId);
+  if (detection !== undefined && projectRoot !== null && existsSync(join(projectRoot, detection.dir))) {
+    return true;
+  }
+  return existsSync(dirname(profile.skillsDir));
+}
+
 function warnUnverifiedIde(ideId, projectRoot) {
   process.stderr.write(
     `peaks install-skills: IDE '${ideId}' has no skillInstall profile declared; ` +
@@ -540,29 +592,26 @@ export function installUserConfig(options = {}) {
   return writeMergedConfig(configPath, 'User', createConfigDefaults(options.packageRoot), (content) => writeUserConfig(userRoot, peaksRoot, configPath, content));
 }
 
-export function installProjectConfig(options = {}) {
-  if (process.env.PEAKS_SKIP_SKILL_INSTALL === '1' || process.env.PEAKS_SKIP_PROJECT_CONFIG_INSTALL === '1') {
-    return createConfigResult({ skipped: true });
-  }
-
-  const projectRoot = resolveProjectRoot(options);
-  if (!projectRoot) {
-    return createConfigResult({ skipped: true });
-  }
-
-  const peaksRoot = resolve(projectRoot, '.peaks');
-  const configPath = resolve(peaksRoot, 'config.json');
-  if (!isInsidePath(configPath, projectRoot)) {
-    throw new Error('Project config path must stay inside the project root');
-  }
-
-  if (!existsSync(peaksRoot)) {
-    mkdirSync(peaksRoot, { recursive: true });
-  }
-  validateProjectConfigPaths(projectRoot, peaksRoot, configPath);
-
-  return writeMergedConfig(configPath, 'Project', createConfigDefaults(options.packageRoot), (content) => writeProjectConfig(projectRoot, peaksRoot, configPath, content));
-}
+/*
+ * D11 (2026-09-15): `installProjectConfig` — plus its two private helpers
+ * `writeProjectConfig` and `validateProjectConfigPaths` — was DELETED here.
+ *
+ * It was dead: definition + `export`, and zero call sites in the whole repo
+ * (verified by a repo-wide grep for the identifier, excluding node_modules
+ * and dist). The `PEAKS_SKIP_PROJECT_CONFIG_INSTALL` env var existed only to
+ * disable it.
+ *
+ * Deleted rather than wired, because wiring it would be the bigger defect:
+ * `npm i -g peaks-loop` executed from inside a user's repo would write
+ * `<project>/.peaks/config.json` as a side effect of a GLOBAL install. The
+ * project-level config is owned by `peaks workspace init` and the config
+ * service at runtime; a postinstall reaching into the current working
+ * directory to create project state is the opposite of the "minimal user
+ * operation" tenet — an operation the user never asked for.
+ *
+ * The user-config sibling (`installUserConfig`, below) is live and is what
+ * the postinstall actually calls.
+ */
 
 export function installBundledSkills(options = {}) {
   const packageRoot = resolvePackageRoot(options);
@@ -684,6 +733,40 @@ export function installBundledSkills(options = {}) {
   return { installed, skipped };
 }
 
+/**
+ * DISPATCH STRATEGY — the three paths in this file, and why they differ
+ * (D10, written down 2026-09-15).
+ *
+ * This script installs three kinds of asset, and each one resolves its target
+ * by a different rule. That was undocumented and untested; it is now
+ * documented here and each rule is stated with its reason.
+ *
+ *   1. SKILLS  (`installBundledSkillsForAllPlatforms`)
+ *      Fan out to every platform the user HAS (`isPlatformPresent`).
+ *      Reason: a skill directory is per-tool; the same skill is legitimately
+ *      wanted in several tools at once, and peaks cannot know which tool the
+ *      user will open next. Fan-out is the tenet; presence is the licence.
+ *
+ *   2. AGENTS  (`installBundledAgentsForAllPlatforms`)
+ *      Fan out to present platforms, INTERSECTED with the profiles that
+ *      declare `agentsDir`. Reason: sub-agent loaders are not a universal
+ *      concept — only 6 of 10 profiles have one. The intersection is the fan
+ *      of (1) with a capability filter, not a third rule.
+ *
+ *   3. OUTPUT STYLES (`installBundledOutputStyles`, this function)
+ *      ONE target: the IDE detected in the project root, else the legacy
+ *      `~/.claude/output-styles`. Reason: an output style is not a
+ *      per-tool asset — it is registered as THE active style for the
+ *      session by writing a single `outputStyle` key into
+ *      `~/.claude/settings.json` (`installBundledOutputStyleDefault`). A
+ *      second copy in `~/.trae/output-styles` would be a file nothing reads
+ *      and a setting no one consults; fanning it out would be storing the
+ *      same answer in ten places and reading it from one.
+ *
+ * So: (1) and (2) share one predicate and differ only by capability; (3) is
+ * deliberately single-target, and this comment is the reason the brief asked
+ * for. If a future platform needs a different rule, state it here.
+ */
 export function installBundledOutputStyles(options = {}) {
   const packageRoot = resolvePackageRoot(options);
   const outputStylesRoot = join(packageRoot, 'output-styles');
@@ -1034,12 +1117,18 @@ export function installBundledAgents(options = {}) {
 }
 
 /**
- * Per-platform fan-out — iterate ALL 8 IdeIds and call
- * `installBundledAgents` for each platform that has an `agentsDir` profile
- * field. Only `claude-code` ships with `agentsDir` set today; the other 7
- * platforms return `installed: []` from their profile lookup. Future
- * platforms can add an `agentsDir` field to their `IDE_SKILL_INSTALL_PROFILES`
- * entry to opt in.
+ * Per-platform fan-out — iterate the platforms the user HAS and call
+ * `installBundledAgents` for each one that also declares an `agentsDir`
+ * profile field. 6 of the 10 profiles declare `agentsDir` today
+ * (claude-code, trae, trae-cn, codex, cursor, zcode); the other 4 have no
+ * sub-agent loader to write into and are skipped by construction. A future
+ * platform opts in by adding `agentsDir` to its
+ * `IDE_SKILL_INSTALL_PROFILES` entry.
+ *
+ * D9/D10 fix (2026-09-15): the platform set is filtered by
+ * `isPlatformPresent` (same predicate as the skills fan-out), so this no
+ * longer creates `~/.trae/agents`, `~/.codex/agents`, … for tools the user
+ * does not have.
  *
  * Per peaks-loop tenet "minimal-user-operation" (2026-06-11): the user
  * should never have to run a per-platform install command. Symlink /
@@ -1047,8 +1136,10 @@ export function installBundledAgents(options = {}) {
  * failure doesn't block the others.
  */
 export function installBundledAgentsForAllPlatforms(options = {}) {
+  const projectRoot = resolveProjectRoot(options);
   const platforms = Object.entries(IDE_SKILL_INSTALL_PROFILES)
-    .filter(([, profile]) => typeof profile.agentsDir === 'string');
+    .filter(([, profile]) => typeof profile.agentsDir === 'string')
+    .filter(([ideId, profile]) => isPlatformPresent(ideId, profile, projectRoot));
   const perPlatform = [];
   for (const [ideId, profile] of platforms) {
     try {
@@ -1091,29 +1182,37 @@ export function installBundledAgentsForAllPlatforms(options = {}) {
 }
 
 /**
- * Per-platform fan-out — iterate ALL 8 IdeIds and call
+ * Per-platform fan-out — iterate the platforms the user actually HAS and call
  * `installBundledSkills` for each. Per peaks-loop tenet
  * "minimal-user-operation" (2026-06-11): the user should
  * never have to run a per-platform install command. The
  * 1.x postinstall only handled the auto-detected single
  * IDE; 2.0 fixes this so the peaks-* skill family is
- * symlinked to every platform the user might be on.
+ * symlinked to every platform the user is on.
+ *
+ * D9/D10 fix (2026-09-15): the set is filtered by `isPlatformPresent`, not
+ * "all 10 profiles". See that helper for why, and see the DISPATCH STRATEGY
+ * note above `installBundledOutputStyles` for how this fan-out relates to the
+ * other two dispatch paths in this file.
  *
  * Returns an array of { ideId, skillsDir, installed, skipped }
  * per platform. Symlink failures are soft (logged to stderr,
  * never throw) so one platform's failure doesn't block the
- * other 7.
+ * others.
  */
 export function installBundledSkillsForAllPlatforms(options = {}) {
-  const platforms = Object.keys(IDE_SKILL_INSTALL_PROFILES);
+  const projectRoot = resolveProjectRoot(options);
+  const platforms = Object.keys(IDE_SKILL_INSTALL_PROFILES).filter((ideId) =>
+    isPlatformPresent(ideId, IDE_SKILL_INSTALL_PROFILES[ideId], projectRoot)
+  );
   const perPlatform = [];
   // Back-compat precedence (regression fix 2026-06-12,
   // slice 2026-06-12-postinstall-1x-detector-tdd):
-  // when iterating the 8 platforms, the claude-code install
+  // when iterating the present platforms, the claude-code install
   // must still honor the PEAKS_CLAUDE_SKILLS_DIR env var
-  // (the legacy back-compat surface from 1.x). The other 7
+  // (the legacy back-compat surface from 1.x). The other
   // platforms use their per-IDE profile paths unconditionally.
-  // Without this fix the 8-IDE fan-out regresses the
+  // Without this fix the fan-out regresses the
   // `peaks install-skills` env-var override contract that
   // user CI / 1.x → 2.0 migration scripts depend on.
   const claudeEnv = process.env.PEAKS_CLAUDE_SKILLS_DIR;
@@ -1298,10 +1397,12 @@ export async function autoUpgrade1xProjectIfPresent(options = {}) {
 if (process.argv[1] !== undefined && import.meta.url === pathToFileURL(resolve(process.argv[1])).href) {
   try {
     // 2.0 fix for the 1.x Trae bug (per real user feedback
-    // 2026-06-11): iterate ALL 8 platforms, not just the
-    // auto-detected one. Per the "minimal-user-operation"
-    // tenet, the user should never have to run a
-    // per-platform install command.
+    // 2026-06-11): iterate every platform the user HAS, not just the
+    // one auto-detected in the project root. Per the
+    // "minimal-user-operation" tenet, the user should never have to run a
+    // per-platform install command — S6 (2026-09-15) narrowed "every" from
+    // "all 10 profiles" to `isPlatformPresent`, because creating a home
+    // directory for a tool the user does not own is that tenet misread.
     const perPlatform = installBundledSkillsForAllPlatforms();
     let totalInstalled = 0;
     for (const p of perPlatform) {

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

@@ -184,8 +184,8 @@ required fixes deduped by `(file, line, hint)`).
 - Schema: `.peaks/project-scan/audit-output-schema.md`
 - Service: `src/services/audit-independent/perf-audit-service.ts`
 - CLI: `src/cli/commands/perf-audit-commands.ts`
-- Tests: `tests/unit/services/audit-independent/perf-audit-service.test.ts`
-- Companion: `skills/peaks-security-audit/SKILL.md` (symmetric structure)
+- Tests: none — the unit suite for the service was deleted in `f17aa377`.
+- Companion: `skills/bee/peaks-security-audit/SKILL.md` (symmetric structure)
 
 ## Karpathy alignment
 

package/skills/bee/peaks-perf-audit/references/audit-protocol.md

@@ -170,4 +170,4 @@ section is the source of new sediment rows; the format is:
 - Service: `src/services/audit-independent/perf-audit-service.ts`
 - Template: `.peaks/project-scan/perf-template.md`
 - Schema: `.peaks/project-scan/audit-output-schema.md`
-- Companion: `skills/peaks-security-audit/references/audit-protocol.md`
+- Companion: `skills/bee/peaks-security-audit/references/audit-protocol.md`

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

@@ -147,7 +147,7 @@ PRD 模板在原 7 段基础上,增加 4 个**质量前置必填块**(user 写,A
 3. **UI 装配意图**(页面模式 / 关键交互 / 信息密度;**不画 ASCII 视觉**,视觉由选定的开源组件库自动决定)
 4. **上游基线**(fork 场景必填:当前 fork 基于哪个 tag / 偏离度 / 业务 patch 集)
 
-**反伪选择原则:** user 不参与技术决策(库/框架/语言/性能/安全/架构),只写业务/产品意图。AI 据业务场景块选库选架构。详见 `.peaks/memory/peaks-loop-prd-template-design.md`。
+**反伪选择原则:** user 不参与技术决策(库/框架/语言/性能/安全/架构),只写业务/产品意图。AI 据业务场景块选库选架构。详见 `.peaks/memory/peaks-cli-prd-template-design.md`。
 
 ## Project-scan gate (v2.11.0 D3 — read before brainstorm)
 
@@ -264,7 +264,7 @@ Use gstack as a concrete workflow reference for the product-facing parts of `Thi
 
 ## Authenticated product document workflow
 
-When the source PRD is an authenticated web document such as Feishu/Lark, use the Playwright MCP headed-browser surface rather than unauthenticated fetch tools. Chrome DevTools MCP is a secondary surface that only connects to an already-running Chrome (`--remote-debugging-port=9222`); it does not launch a browser on its own. The canonical browser workflow lives in `peaks-code/references/browser-workflow.md`; the rules below are the PRD-specific application.
+When the source PRD is an authenticated web document such as Feishu/Lark, use the Playwright MCP headed-browser surface rather than unauthenticated fetch tools. Chrome DevTools MCP is a secondary surface that only connects to an already-running Chrome (`--remote-debugging-port=9222`); it does not launch a browser on its own. The canonical browser workflow lives in `../../peaks-code/references/browser-workflow.md`; the rules below are the PRD-specific application.
 
 1. Confirm Playwright MCP is installed: check the LLM tool list for any Playwright MCP entry in the LLM tool list. If absent, the user installs via `claude mcp add playwright -- npx @playwright/mcp@latest` (Claude Code) or the IDE-native install command. Do not hand-edit `.claude/settings.json`.
 2. Before navigation, verify the user-provided document URL uses `https:` and belongs to an approved Feishu/Lark tenant domain such as `*.feishu.cn`, `*.larksuite.com`, `*.larksuite.com.cn`, or a project-configured tenant. Reject `file:`, `data:`, `javascript:`, `http:`, localhost, loopback, link-local, private IP, and raw IP hosts unless the user explicitly approves a controlled local test target.
@@ -294,7 +294,7 @@ Summarize business context only when it changes implementation priority, scope,
 
 When the user explicitly says the target is a frontend project, transform the product document into frontend implementation inputs before RD starts:
 
-> **v2.15.0+ 校准:** UI 视觉 = 开源组件库装配(shadcn / Radix / antd / mui),不是原创设计。prd 不画 ASCII 视觉,只描述"页面模式 + 关键交互 + 信息密度"。AI 据此选组件库 + 装配。详见 `.peaks/memory/peaks-loop-prd-template-design.md`。
+> **v2.15.0+ 校准:** UI 视觉 = 开源组件库装配(shadcn / Radix / antd / mui),不是原创设计。prd 不画 ASCII 视觉,只描述"页面模式 + 关键交互 + 信息密度"。AI 据此选组件库 + 装配。详见 `.peaks/memory/peaks-cli-prd-template-design.md`。
 
 1. identify target pages, routes, components, forms, tables, modals, empty/loading/error states, permissions, data dependencies, edge cases, and affected user flows;
 2. separate frontend-only work from API/backend联调 assumptions;

package/skills/bee/peaks-prd/references/prd-for-multi-pass.md

@@ -46,4 +46,4 @@ Single-service feature → single-pass PRD. Do not force a Pass 2 layer if the w
 - Pass 2 ACs each name a file path under one of the Pass 1 services.
 - A `peaks slice audit-prd --rid <rid>` (when present) returns zero cross-cutting flags.
 
-See `../peaks-slice-decompose/SKILL.md` for the envelope contract and `../peaks-rd/references/reading-v2-slice-results.md` for the RD-side read.
+See `../../../peaks-slice-decompose/SKILL.md` for the envelope contract and `../../peaks-rd/references/reading-v2-slice-results.md` for the RD-side read.

package/skills/bee/peaks-prd/references/workflow.md

@@ -15,7 +15,7 @@ When the product source is an authenticated Feishu/Lark/wiki document:
 7. Do not persist login URLs, redirect URLs, cookies, request or response headers, session tokens, tokens, storage state, QR payloads, raw browser state, raw network logs, browser traces, or screenshots/logs containing PII or SSO/MFA material into artifacts; redact sensitive evidence before writing `.peaks` outputs.
 8. If access remains blocked, record only a redacted document identifier, a sanitized state category such as `login-required`, `mfa-required`, or `access-denied`, and the exact user action needed.
 
-Canonical browser workflow: `../../peaks-code/references/browser-workflow.md`.
+Canonical browser workflow: `../../../peaks-code/references/browser-workflow.md`.
 
 ## Implementation-oriented analysis
 

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

@@ -47,7 +47,7 @@ denied again after a long pause. That is the gate resetting, not you regressing.
 
 > **Read once at the top of this file; the rest of the skill is written against it.**
 
-The `.peaks/` workspace is partitioned by a **single scope axis** (session-id, at `.peaks/_runtime/<sessionId>/...`) with a nested **sub-agent axis** under `.peaks/_sub_agents/<sessionId>/...`. Use `<sessionId>` placeholders (NEVER bare `<sid>`). The peaks-loop change-id axis was removed in slice `2026-06-29-change-id-root-removal`; reviewable artifacts now live under `.peaks/_runtime/<sessionId>/<role>/...` only. OpenSpec's independent `openspec/changes/<change-id>/` vocabulary (L4) is preserved untouched. CLI mapping: session-id → `peaks session *`; sub-agent → `peaks sub-agent *`. Regression test `tests/unit/skills/skills-skill-md-naming.test.ts` enforces (a) zero bare `<sid>`, (b) every `.peaks/_runtime/<X>/` has an axis label, (c) this callout is present.
+The `.peaks/` workspace is partitioned by a **single scope axis** (session-id, at `.peaks/_runtime/<sessionId>/...`) with a nested **sub-agent axis** under `.peaks/_sub_agents/<sessionId>/...`. Use `<sessionId>` placeholders (NEVER bare `<sid>`). The peaks-loop change-id axis was removed in slice `2026-06-29-change-id-root-removal`; reviewable artifacts now live under `.peaks/_runtime/<sessionId>/<role>/...` only. OpenSpec's independent `openspec/changes/<change-id>/` vocabulary (L4) is preserved untouched. CLI mapping: session-id → `peaks session *`; sub-agent → `peaks sub-agent *`. Normative by documentation only — the guard that once asserted (a) zero bare `<sid>`, (b) an axis label on every runtime path, and (c) this callout's presence was deleted in `457b9a87`. Comply by convention.
 
 ## peaks-context auto-build (v3.0)
 
@@ -92,7 +92,7 @@ The canonical scope dir for this request is provided as `envelope.data.scopeDir`
 
 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`。
+> **v2.15.0+ 校准:** 每个 slice 完成,user 必介入做**业务审阅**(4-5 项业务/产品清单:业务流程 / 需求覆盖 / 边界 case / UI 装配 / 能合入下版吗),**不是技术审阅**。业务审过 → 进 final;业务不通过 → 返工。详见 `.peaks/memory/peaks-cli-slice-review-and-qa-perspective.md`。
 
 → see `references/qa-sub-agent-dispatch.md` for the full contract + hard prohibitions.
 
@@ -106,7 +106,7 @@ Project-level security + perf plans live at `.peaks/_runtime/<sessionId>/qa/secu
 
 When peaks-qa is the **main loop** (i.e. it is the active skill and is about to run its own sub-agent dispatch, rather than being a sub-agent itself), it fans out only the **business verification** sub-agent: `qa-business`. Security and performance review are **NOT** peaks-qa's responsibility in v2.11.0 — they are owned by peaks-rd's 4-way audit fan-out (code-review + security-review + perf-baseline + karpathy-review) and the rd-side evidence files (`audit/security-<rid>.md`, `audit/perf-<rid>.md`). peaks-qa reads those files by reference; it does NOT re-do them.
 
-> **v2.15.0+ 校准:** `qa-business` 只跑业务/产品视角的 6 项验收清单(业务流程 / 需求覆盖 / 边界 case / UI 装配 / 异常态语调 / 能上线吗),**不跑技术指标**(覆盖率 / 性能 / 安全)。技术指标由 RD 4-way fan-out 自决,QA 只读 `audit/security-<rid>.md` + `audit/perf-<rid>.md`。详见 `.peaks/memory/peaks-loop-slice-review-and-qa-perspective.md`。
+> **v2.15.0+ 校准:** `qa-business` 只跑业务/产品视角的 6 项验收清单(业务流程 / 需求覆盖 / 边界 case / UI 装配 / 异常态语调 / 能上线吗),**不跑技术指标**(覆盖率 / 性能 / 安全)。技术指标由 RD 4-way fan-out 自决,QA 只读 `audit/security-<rid>.md` + `audit/perf-<rid>.md`。详见 `.peaks/memory/peaks-cli-slice-review-and-qa-perspective.md`。
 
 If the PRD or project warrants it, subdivide `qa-business` further into roles like `qa-business-api` / `qa-business-frontend` / `qa-business-regression`. Subdivision must stay ≤ 2 levels deep (RL-4).
 
@@ -182,7 +182,7 @@ QA must generate test cases, not merely inspect existing ones. Every QA invocati
 
 **Pre-drafted test cases (slice 004 optimization):** when peaks-rd's 4-way parallel fan-out ran a `qa-test-cases-writer` sub-agent, the test plan is pre-drafted at `.peaks/_runtime/<sessionId>/qa/test-cases/<rid>.md` and shipped through the rd:qa-handoff gate. QA main loop is aware of this and treats the pre-drafted file as the canonical starting point. **Missing** the pre-drafted file (sub-agent failed, or the slice was a config/docs/chore that did not fan out) → QA drafts it inline as before, falling back to the standard generation flow.
 
-> **v2.15.0+ 校准:** 业务验证层(user 必审) = 4-5 项业务/产品清单。技术验证层(AI 自决) = 覆盖率 / P99 / 安全扫描 / 自动化。两层解耦:技术不过 → AI 内部重跑;业务不过 → user 反馈修。user **不看**技术指标。详见 `.peaks/memory/peaks-loop-slice-review-and-qa-perspective.md` G5。
+> **v2.15.0+ 校准:** 业务验证层(user 必审) = 4-5 项业务/产品清单。技术验证层(AI 自决) = 覆盖率 / P99 / 安全扫描 / 自动化。两层解耦:技术不过 → AI 内部重跑;业务不过 → user 反馈修。user **不看**技术指标。详见 `.peaks/memory/peaks-cli-slice-review-and-qa-perspective.md` G5。
 
 → see `references/test-case-generation.md` for the full format + acceptance-linkage contract.
 
@@ -198,7 +198,7 @@ QA cannot pass a change until the report contains evidence for every applicable
 
 If Playwright MCP is unavailable, the LLM checks its own tool list for the Playwright MCP server entry; if absent, the LLM tells the user the install command (`claude mcp add playwright -- npx @playwright/mcp@latest` for Claude Code) and marks the gate blocked with the missing capability. Screenshots, logs, manual steps, or other tools must not substitute for the mandatory frontend browser gate. Do not silently downgrade frontend validation to API-only testing.
 
-> **v2.15.0+ 校准:** 存量项目无 UT 兜底,QA 验证必须有"轻量回归"(G14):5-10 分钟跑 10 条关键路径(关键路径来源:prd 业务场景块 / 老板强调的流程 / 历史事故 / G13 影响面扫描),**不跑完整 E2E 1-2 小时**。上线后必须走"观察期"(G15):灰度 → 监控 → 反馈聚合 → 紧急修复 → 修复回灌关键路径(防下次再犯)。详见 `.peaks/memory/peaks-loop-fast-iteration-quality-loop.md`。
+> **v2.15.0+ 校准:** 存量项目无 UT 兜底,QA 验证必须有"轻量回归"(G14):5-10 分钟跑 10 条关键路径(关键路径来源:prd 业务场景块 / 老板强调的流程 / 历史事故 / G13 影响面扫描),**不跑完整 E2E 1-2 小时**。上线后必须走"观察期"(G15):灰度 → 监控 → 反馈聚合 → 紧急修复 → 修复回灌关键路径(防下次再犯)。详见 `.peaks/memory/peaks-cli-fast-iteration-quality-loop.md`。
 
 ## Local intermediate artifacts
 
@@ -258,7 +258,6 @@ Index of every `references/` file in this skill. Read on demand.
 | `references/artifact-per-request.md` | QA 3-file per-request artifact contract. |
 | `references/browser-validation-contracts.md` | Browser contracts (1) + (2) + AskUserQuestion. |
 | `references/codegraph-regression-focus.md` | Codegraph regression-surface evidence. |
-| `references/command-migration.md` | Legacy command migration map. |
 | `references/external-capability-guidance.md` | Playwright / Chrome DevTools / Agent Browser. |
 | `references/openspec-validation-gate.md` | OpenSpec validation + archive gate. |
 | `references/qa-compact-handoff.md` | QA compact handoff capsule. |
@@ -298,4 +297,4 @@ QA contracts to assert on the L2 surface (a minimal acceptance test set):
 
 ## Sub-role detached mode (Phase C, slice 2026-08-10)
 
-QA sub-roles (`qa-business`, `qa-perf`, `qa-security`, `qa-business-api`, `qa-business-frontend`, `qa-business-regression`) accept `--mode detached --vendor <vendor>` for parallel test-case execution. Detached mode spawns a real OS process via `peaks sub-agent dispatch --mode detached`, isolated from the orchestrator session. Use detached mode when the test-case writer's expected runtime exceeds 60s OR it processes ≥ 20 source files. The default remains `in-process` (backward compat; existing 106+ dispatch tests untouched). When `--mode detached` is used, the child QA agent receives the `<peaks-auto-compact>` marker (corrected 2026-09-13, rid `2026-09-13-defects-e`): it asks the child to persist durable state to `.peaks/_runtime/<sid>/detached/<rid>/compact/<n>.json` before its own harness compacts the session — the child cannot compact itself, and nothing is spliced back into its prompt. See `peaks-code/references/sub-agent-dispatch.md` §"Detached Mode" for the full contract.
+QA sub-roles (`qa-business`, `qa-perf`, `qa-security`, `qa-business-api`, `qa-business-frontend`, `qa-business-regression`) accept `--mode detached --vendor <vendor>` for parallel test-case execution. Detached mode spawns a real OS process via `peaks sub-agent dispatch --mode detached`, isolated from the orchestrator session. Use detached mode when the test-case writer's expected runtime exceeds 60s OR it processes ≥ 20 source files. The default remains `in-process` (backward compat; existing 106+ dispatch tests untouched). When `--mode detached` is used, the child QA agent receives the `<peaks-auto-compact>` marker (corrected 2026-09-13, rid `2026-09-13-defects-e`): it asks the child to persist durable state to `.peaks/_runtime/<sid>/detached/<rid>/compact/<n>.json` before its own harness compacts the session — the child cannot compact itself, and nothing is spliced back into its prompt. See `skills/peaks-code/references/sub-agent-dispatch.md` §"Detached Mode" for the full contract.

package/skills/bee/peaks-qa/references/external-capability-guidance.md

@@ -5,5 +5,5 @@
 - Playwright MCP is the required path for controlled headed browser and E2E validation (it launches a headed browser on demand). The LLM runtime exposes the Playwright tools under its own server-and-tool namespace (the Playwright MCP); QA invokes them by name from the LLM's tool list. (peaks-loop no longer auto-installs MCPs as of slice #016; the user runs `claude mcp add playwright -- npx @playwright/mcp@latest` themselves when the tool list is empty.)
 - Chrome DevTools MCP is an optional secondary surface for CDP inspection (console, network, performance) of an already-running Chrome started with `--remote-debugging-port=9222`; it does NOT launch a browser on its own. The LLM invokes Chrome DevTools MCP tools directly when present in the tool list.
 - Agent Browser can support browser walkthroughs, but never submit forms, purchase, delete, or mutate authenticated state without explicit confirmation.
-- Canonical browser workflow (URL allow-list, login handoff, sanitization rules, tool mapping): `peaks-code/references/browser-workflow.md`.
+- Canonical browser workflow (URL allow-list, login handoff, sanitization rules, tool mapping): `skills/peaks-code/references/browser-workflow.md`.
 - If Playwright MCP is not installed and the user does not authorize installation, mark frontend browser validation blocked; screenshots, logs, manual steps, or other tools must not substitute for the mandatory headed browser gate.