peaks-cli 1.4.2 → 2.0.1

package/scripts/install-skills.mjs

@@ -1,5 +1,6 @@
 #!/usr/bin/env node
 import { closeSync, constants, existsSync, fchmodSync, fstatSync, lstatSync, mkdirSync, openSync, readFileSync, readlinkSync, realpathSync, readdirSync, renameSync, symlinkSync, unlinkSync, writeFileSync } from 'node:fs';
+import { spawnSync } from 'node:child_process';
 import { createHash, randomUUID } from 'node:crypto';
 import { homedir } from 'node:os';
 import { basename, dirname, isAbsolute, join, relative, resolve } from 'node:path';
@@ -389,6 +390,19 @@ const IDE_DETECTION_DIRS = [
   { id: 'tongyi-lingma', dir: '.tongyi-lingma' },
 ];
 
+/**
+ * Per-IDE skill install paths. Per peaks-cli tenet
+ * "minimal-user-operation" (2026-06-11), the user should
+ * never have to run a per-platform install command — the
+ * `npm i -g peaks-cli` postinstall iterates ALL of these
+ * and symlinks the peaks-* skill family to every platform
+ * the user might be on.
+ *
+ * 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.
+ */
 const IDE_SKILL_INSTALL_PROFILES = {
   'claude-code': {
     skillsDir: join(homedir(), '.claude', 'skills'),
@@ -396,11 +410,48 @@ const IDE_SKILL_INSTALL_PROFILES = {
     envVar: 'PEAKS_CLAUDE_SKILLS_DIR',
     outputStylesEnvVar: 'PEAKS_CLAUDE_OUTPUT_STYLES_DIR',
   },
-  'trae': null,
-  'codex': null,
-  'cursor': null,
-  'qoder': null,
-  'tongyi-lingma': null,
+  'trae': {
+    skillsDir: join(homedir(), '.trae', 'skills'),
+    outputStylesDir: join(homedir(), '.trae', 'output-styles'),
+    envVar: 'PEAKS_TRAE_SKILLS_DIR',
+    outputStylesEnvVar: 'PEAKS_TRAE_OUTPUT_STYLES_DIR',
+  },
+  'codex': {
+    skillsDir: join(homedir(), '.codex', 'skills'),
+    outputStylesDir: join(homedir(), '.codex', 'output-styles'),
+    envVar: 'PEAKS_CODEX_SKILLS_DIR',
+    outputStylesEnvVar: 'PEAKS_CODEX_OUTPUT_STYLES_DIR',
+  },
+  'cursor': {
+    skillsDir: join(homedir(), '.cursor', 'skills'),
+    outputStylesDir: join(homedir(), '.cursor', 'output-styles'),
+    envVar: 'PEAKS_CURSOR_SKILLS_DIR',
+    outputStylesEnvVar: 'PEAKS_CURSOR_OUTPUT_STYLES_DIR',
+  },
+  'qoder': {
+    skillsDir: join(homedir(), '.qoder', 'skills'),
+    outputStylesDir: join(homedir(), '.qoder', 'output-styles'),
+    envVar: 'PEAKS_QODER_SKILLS_DIR',
+    outputStylesEnvVar: 'PEAKS_QODER_OUTPUT_STYLES_DIR',
+  },
+  'tongyi-lingma': {
+    skillsDir: join(homedir(), '.tongyi-lingma', 'skills'),
+    outputStylesDir: join(homedir(), '.tongyi-lingma', 'output-styles'),
+    envVar: 'PEAKS_TONGYI_SKILLS_DIR',
+    outputStylesEnvVar: 'PEAKS_TONGYI_OUTPUT_STYLES_DIR',
+  },
+  'hermes': {
+    skillsDir: join(homedir(), '.hermes', 'skills'),
+    outputStylesDir: join(homedir(), '.hermes', 'output-styles'),
+    envVar: 'PEAKS_HERMES_SKILLS_DIR',
+    outputStylesEnvVar: 'PEAKS_HERMES_OUTPUT_STYLES_DIR',
+  },
+  'openclaw': {
+    skillsDir: join(homedir(), '.openclaw', 'skills'),
+    outputStylesDir: join(homedir(), '.openclaw', 'output-styles'),
+    envVar: 'PEAKS_OPENCLAW_SKILLS_DIR',
+    outputStylesEnvVar: 'PEAKS_OPENCLAW_OUTPUT_STYLES_DIR',
+  },
 };
 
 function detectInstalledIdeId(projectRoot) {
@@ -657,9 +708,228 @@ export function installBundledOutputStyles(options = {}) {
   return { installed, skipped };
 }
 
+/**
+ * Per-platform fan-out — iterate ALL 8 IdeIds and call
+ * `installBundledSkills` for each. Per peaks-cli 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.
+ *
+ * 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.
+ */
+export function installBundledSkillsForAllPlatforms(options = {}) {
+  const platforms = Object.keys(IDE_SKILL_INSTALL_PROFILES);
+  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
+  // must still honor the PEAKS_CLAUDE_SKILLS_DIR env var
+  // (the legacy back-compat surface from 1.x). The other 7
+  // platforms use their per-IDE profile paths unconditionally.
+  // Without this fix the 8-IDE 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;
+  for (const ideId of platforms) {
+    try {
+      const platformOpts =
+        ideId === 'claude-code' && claudeEnv !== undefined && claudeEnv.length > 0
+          ? { ...options, ideId, targetRoot: claudeEnv }
+          : { ...options, ideId };
+      const result = installBundledSkills(platformOpts);
+      perPlatform.push({
+        ideId,
+        skillsDir: IDE_SKILL_INSTALL_PROFILES[ideId]?.skillsDir ?? '(unknown)',
+        installed: result.installed,
+        skipped: result.skipped,
+      });
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      process.stderr.write(
+        `peaks install-skills: ${ideId} platform failed (continuing): ${message}\n`
+      );
+      perPlatform.push({
+        ideId,
+        skillsDir: IDE_SKILL_INSTALL_PROFILES[ideId]?.skillsDir ?? '(unknown)',
+        installed: [],
+        skipped: [],
+        error: message,
+      });
+    }
+  }
+  return perPlatform;
+}
+
+/**
+ * 1.x → 2.0 detection — sniff for legacy 1.x project state
+ * in `cwd`. Returns a 1.x detection envelope with the
+ * detected signals (so the postinstall can decide whether
+ * to auto-upgrade).
+ *
+ * 1.x signals (any one fires the detection):
+ *   - `~/.peaks/config.json` exists with `version: '1.4.2'` (or
+ *     any '1.x' version that predates the 2.0 schema)
+ *   - `.claude/rules/common/dev-preference.md` exists and
+ *     references "peaks progress" (the 1.x CLI surface
+ *     removed in slice #014)
+ *   - `<cwd>/.peaks/preferences.json` missing OR has no
+ *     `schema_version: '2.0.0'` field
+ *
+ * Returns:
+ *   { isOneX: boolean, signals: string[], projectRoot: string|null,
+ *     configPath: string|null }
+ */
+export function detect1xProjectState(cwd = process.cwd()) {
+  const home = homedir();
+  const signals = [];
+  let projectRoot = null;
+  let configPath = null;
+
+  // Walk up from cwd looking for .peaks/_runtime (signals
+  // we're inside a peaks project).
+  let dir = cwd;
+  for (let i = 0; i < 8; i += 1) {
+    const peaksRuntime = join(dir, '.peaks', '_runtime');
+    if (existsSync(peaksRuntime)) {
+      projectRoot = dir;
+      break;
+    }
+    const parent = dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+
+  // Signal 1: ~/.peaks/config.json with 1.x version
+  const globalConfig = join(home, '.peaks', 'config.json');
+  if (existsSync(globalConfig)) {
+    try {
+      const raw = JSON.parse(readFileSync(globalConfig, 'utf8'));
+      if (typeof raw.version === 'string' && /^1\./.test(raw.version)) {
+        signals.push(`global config at ${globalConfig} is 1.x (${raw.version})`);
+        if (configPath === null) configPath = globalConfig;
+      }
+    } catch {
+      // ignore parse error — the 1.x detection is best-effort
+    }
+  }
+
+  // Signal 2: .claude/rules/common/dev-preference.md with peaks progress
+  if (projectRoot !== null) {
+    const devPref = join(projectRoot, '.claude', 'rules', 'common', 'dev-preference.md');
+    if (existsSync(devPref)) {
+      try {
+        const body = readFileSync(devPref, 'utf8');
+        if (/peaks progress/i.test(body)) {
+          signals.push(`${devPref} references "peaks progress" (1.x CLI surface, removed in slice #014)`);
+        }
+      } catch {
+        // ignore
+      }
+    }
+    // Signal 3: project preferences.json missing or 1.x
+    const prefs = join(projectRoot, '.peaks', 'preferences.json');
+    if (!existsSync(prefs)) {
+      signals.push(`${prefs} does not exist (1.x project never migrated)`);
+    } else {
+      try {
+        const raw = JSON.parse(readFileSync(prefs, 'utf8'));
+        if (raw.schema_version !== '2.0.0') {
+          signals.push(`${prefs} has schema_version ${JSON.stringify(raw.schema_version)}, expected '2.0.0'`);
+        }
+      } catch {
+        signals.push(`${prefs} exists but is not valid JSON`);
+      }
+    }
+  }
+
+  return {
+    isOneX: signals.length > 0,
+    signals,
+    projectRoot,
+    configPath,
+  };
+}
+
+/**
+ * Postinstall auto-upgrade — when the user just ran
+ * `npm i -g peaks-cli@2.0` and `cwd` is a 1.x peaks-cli
+ * project, this shells out to the installed `peaks`
+ * binary to run the umbrella `peaks upgrade --to 2.0 --auto`.
+ *
+ * Per the "minimal-user-operation" tenet, the user should
+ * never have to run a second command after `npm i -g`. The
+ * upgrade CLI (if installed) is at the resolved `peaks`
+ * binary path; if not, the user gets a hint to run it
+ * manually.
+ *
+ * The auto-upgrade is opt-out via:
+ *   PEAKS_SKIP_AUTO_UPGRADE=1
+ * (so a CI box that installs 2.0 but never wants the
+ * project-level migration can suppress the auto-step).
+ */
+export async function autoUpgrade1xProjectIfPresent(options = {}) {
+  if (process.env.PEAKS_SKIP_AUTO_UPGRADE === '1') {
+    return { ran: false, reason: 'PEAKS_SKIP_AUTO_UPGRADE=1' };
+  }
+  const state = detect1xProjectState(options.cwd ?? process.cwd());
+  if (!state.isOneX) {
+    return { ran: false, reason: 'no 1.x project state detected' };
+  }
+  if (state.projectRoot === null) {
+    return { ran: false, reason: 'cwd is not a peaks project (no .peaks/_runtime/)' };
+  }
+  // The peaks binary should be on PATH after `npm i -g`.
+  // We shell out via spawnSync (synchronous; the postinstall
+  // is already synchronous and the umbrella is fast).
+  try {
+    const result = spawnSync('peaks', ['upgrade', '--to', '2.0', '--auto', '--project', state.projectRoot], {
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'pipe'],
+      timeout: 120_000,
+    });
+    return {
+      ran: true,
+      reason: 'auto-upgrade dispatched',
+      signals: state.signals,
+      projectRoot: state.projectRoot,
+      exitCode: result.status,
+      stdout: result.stdout ?? '',
+      stderr: result.stderr ?? '',
+    };
+  } catch (err) {
+    return {
+      ran: true,
+      reason: 'auto-upgrade dispatched but failed',
+      signals: state.signals,
+      projectRoot: state.projectRoot,
+      error: err instanceof Error ? err.message : String(err),
+    };
+  }
+}
+
 if (process.argv[1] !== undefined && import.meta.url === pathToFileURL(resolve(process.argv[1])).href) {
   try {
-    const skillsResult = installBundledSkills();
+    // 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.
+    const perPlatform = installBundledSkillsForAllPlatforms();
+    let totalInstalled = 0;
+    for (const p of perPlatform) {
+      totalInstalled += p.installed.length;
+    }
+    if (totalInstalled > 0) {
+      process.stdout.write(
+        `Peaks skills linked across ${perPlatform.length} platforms ` +
+          `(${totalInstalled} total symlinks)\n`
+      );
+    }
     const outputStylesResult = installBundledOutputStyles();
     let userConfigResult = createConfigResult({ skipped: true });
     try {
@@ -668,12 +938,6 @@ if (process.argv[1] !== undefined && import.meta.url === pathToFileURL(resolve(p
       const message = error instanceof Error ? error.message : String(error);
       process.stderr.write(`Peaks user config was not installed: ${message}\n`);
     }
-    if (skillsResult.installed.length > 0) {
-      process.stdout.write(`Peaks skills linked: ${skillsResult.installed.join(', ')}\n`);
-    }
-    if (skillsResult.skipped.length > 0) {
-      process.stderr.write(`Peaks skills skipped because local files already exist: ${skillsResult.skipped.join(', ')}\n`);
-    }
     if (outputStylesResult.installed.length > 0) {
       process.stdout.write(`Peaks output styles installed: ${outputStylesResult.installed.join(', ')}\n`);
     }
@@ -683,6 +947,26 @@ if (process.argv[1] !== undefined && import.meta.url === pathToFileURL(resolve(p
     if (userConfigResult.created) {
       process.stdout.write('Peaks user config created: ~/.peaks/config.json\n');
     }
+
+    // 2.0 postinstall: auto-detect 1.x project state in cwd
+    // and dispatch the upgrade umbrella. This makes the
+    // user's `npm i -g peaks-cli@2.0` truly one-key.
+    if (process.env.PEAKS_SKIP_AUTO_UPGRADE !== '1') {
+      // Fire-and-forget; the upgrade is async by design so
+      // the npm install output isn't blocked. We print a
+      // one-line hint so the user knows the auto-step
+      // happened.
+      autoUpgrade1xProjectIfPresent().then((result) => {
+        if (result.ran) {
+          process.stdout.write(
+            `\n✓ Detected 1.x peaks-cli project at ${result.projectRoot}\n` +
+              `  → auto-upgraded to 2.0 (${result.signals?.length ?? 0} signals resolved)\n` +
+              `  Run \`peaks audit red-lines --project .\` to verify.\n`
+          );
+        }
+        // When !result.ran we say nothing — silent on success.
+      });
+    }
     if (userConfigResult.updated) {
       process.stdout.write('Peaks user config updated: ~/.peaks/config.json\n');
     }

package/skills/peaks-doctor/SKILL.md

@@ -0,0 +1,59 @@
+---
+name: peaks-doctor
+description: Orchestrate peaks-cli's L3 doctor (peaks audit + peaks doctor + peaks openspec from-doctor) for project health. Use when the user asks for a project health check, doctor report, audit, or wants to convert doctor findings into OpenSpec change records. Coordinates the L2 audit framework + the L3.2 doctor + the L3.3 from-doctor proposal generator. Triggers on `/peaks-doctor`, "peaks doctor", "项目健康", "doctor report", "health check", "check the project", "audit my repo".
+internal: true
+---
+---
+
+# Peaks-Cli Doctor
+
+Peaks-Cli Doctor is the orchestration facade for the L3 doctor workflow. It runs the L2 audit framework (`peaks audit red-lines`) + the L3.2 doctor checks (`peaks doctor`) + the L3.3 from-doctor proposal generator (`peaks openspec from-doctor`). Use it when the user wants a project health check, a red-line audit, or to convert doctor findings into OpenSpec change records.
+
+## Skill-first architecture note (read once, internalise)
+
+This skill is the **primary surface**. The `peaks <cmd>` CLI is **auxiliary** — invoked by the skill prompt only when a primitive is the right tool. Behaviour only an LLM in a skill prompt would use lives **here in the SKILL.md**, not as a new CLI command. See `.claude/rules/common/dev-preference.md` for the decision template.
+
+## Code-Change Red Line (BLOCKING — read before ANY tool call)
+
+**Peaks-Cli Doctor is a doctor orchestrator, NOT an implementer. You MUST NOT write, edit, or modify any application source code directly.**
+
+The doctor workflow is read-only by design. It produces:
+- `peaks audit red-lines` report (121 red lines in the current repo, 6 cli-backed)
+- `peaks doctor` report (69 checks: 68 pass, 1 fail — L3:l3-memory-health)
+- Optional OpenSpec change records via `peaks openspec from-doctor`
+
+If a doctor finding requires a code change, the workflow hands off to `peaks-rd` (or `peaks-solo` for the full pipeline). The doctor itself does NOT modify code.
+
+## Workflow (5 steps)
+
+1. **Anchor**: `peaks workspace init --project <repo> --json` (idempotent; same as every peaks-* skill).
+2. **Run audit**: `peaks audit red-lines --project <repo> --json` — returns the red-line audit (catalog-matched markers + live enforcer findings). Inspect the `enforcerFindings` array for runtime-detected issues.
+3. **Run doctor**: `peaks doctor --json` — returns 69 checks. Pay special attention to:
+   - `L3:l3-orphan-sessions` — invalid sids in .peaks/_runtime/
+   - `L3:l3-memory-health` — .peaks/memory/index.json shape
+   - `integration:gateguard-peaks-conflict` — third-party Edit/Write hook interference
+   - `build:workspace-layout-canonical` — workspace layout
+4. **Triage findings**: For each FAIL check, decide:
+   - **Real bug requiring fix** → hand off to peaks-rd (run `peaks openspec from-doctor` first to generate a draft proposal; then peaks-rd to implement)
+   - **Acceptable false positive** → document in the handoff; do not act
+   - **Configuration drift** → run the suggested recovery command (e.g. `peaks workspace clean`)
+5. **Generate proposals** (per FAIL finding): `peaks openspec from-doctor --project <repo> --check-id <id>` writes `openspec/changes/<date>-fix-<slug>/proposal.md`. Hand off to peaks-rd for implementation.
+
+## CLI primitives the skill composes
+
+- `peaks workspace init` — anchor the workspace (Step 0)
+- `peaks audit red-lines` — L2 audit
+- `peaks doctor` — L3.2 doctor
+- `peaks openspec from-doctor` — L3.3 proposal generator
+- `peaks openspec validate` — gate a draft proposal
+
+## Boundaries
+
+- The doctor is read-only. It does NOT modify code, fix bugs, or clean up sessions.
+- The doctor does NOT install UA or any third-party tool. The opt-in UX is surfaced via `peaks understand opt-in`; the doctor just reports state.
+- The doctor does NOT generate change records automatically; it surfaces findings + the LLM calls `peaks openspec from-doctor` to generate them.
+
+## References
+
+- `references/doctor-check-catalog.md` — every doctor check id + what it means
+- `references/from-doctor-flow.md` — the end-to-end "finding → proposal" path

package/skills/peaks-doctor/references/doctor-check-catalog.md

@@ -0,0 +1,31 @@
+# Doctor check catalog (peaks-doctor skill reference)
+
+Slice L3.2 ships 69 doctor checks. The most user-relevant ones:
+
+## L2 audit (slice #2)
+
+- **`L2:audit:cli-backed`** — count of red lines whose catalog match has a real enforcer
+- **`L2:audit:prose-only`** — count of red lines that need a future enforcer
+
+## L3.2 (slice #9)
+
+- **`L3:l3-orphan-sessions`** — directories in `.peaks/_runtime/` that fail `isValidSessionId`. Recover with `peaks workspace clean`.
+- **`L3:l3-memory-health`** — `.peaks/memory/index.json` must be well-formed JSON with a `schema_version` field and an array `entries`. Recovers by re-running `peaks memory extract`.
+
+## Build / workspace
+
+- **`build:dist-version-matches-source`** — `dist/src/shared/version.js` matches the source `package.json` version
+- **`build:workspace-layout-canonical`** — `.peaks/` follows the canonical `._archive` / `_runtime` / `_sub_agents` layout
+- **`build:workspace-migrate-not-needed`** — when the layout is already canonical
+
+## Integration (third-party hooks)
+
+- **`integration:gateguard-peaks-conflict`** — warns when `gateguard-fact-force` is installed without a `.peaks/**` skip pattern (the 3rd-party hook would block all peaks-qa .peaks/ artifact writes)
+
+## Skills
+
+- **`skill:<required-skill>`** — each required skill (peaks-ide, peaks-prd, peaks-rd, peaks-qa, peaks-sc, peaks-solo, peaks-sop, peaks-txt, peaks-ui, peaks-doctor) must be installed in the bundled skills dir
+
+## Doctor self
+
+- **`doctor-self:check-id-pattern`** — all check IDs match the `doctor-report.schema.json` regex pattern (prevents typos like `L3:l3-orphan-sesions`)

package/skills/peaks-doctor/references/from-doctor-flow.md

@@ -0,0 +1,64 @@
+# from-doctor flow (peaks-doctor skill reference)
+
+End-to-end path from a doctor finding to an OpenSpec change record.
+
+## Flow
+
+```
+peaks doctor --json                  # 1. discover findings
+  ↓
+match: any check where ok=false
+  ↓
+peaks openspec from-doctor \
+  --project <repo> \
+  --check-id <id>                   # 2. generate draft proposal
+  ↓
+openspec/changes/<date>-fix-<slug>/proposal.md   # 3. LLM reviews + edits
+  ↓
+peaks openspec validate <change-id>  # 4. gate
+  ↓
+[next slice: peaks-rd implements the change per the proposal]
+```
+
+## Example
+
+```bash
+# Discover
+$ peaks doctor --json | jq '.data.checks[] | select(.ok==false) | .id'
+"L3:l3-memory-health"
+
+# Generate draft
+$ peaks openspec from-doctor \
+    --project . \
+    --check-id L3:l3-memory-health \
+    --json
+{
+  "ok": true,
+  "command": "openspec.from-doctor",
+  "data": {
+    "changeId": "2026-06-11-fix-l3-l3-memory-health",
+    "proposalPath": ".../openspec/changes/2026-06-11-fix-l3-l3-memory-health/proposal.md",
+    "created": true
+  }
+}
+
+# LLM reviews + edits the draft (in this case: add a Why section
+# explaining the missing schema_version field; add an Acceptance
+# Criterion that requires peaks doctor to return ok=true for the check)
+
+# Validate
+$ peaks openspec validate 2026-06-11-fix-l3-l3-memory-health --json
+{
+  "ok": true,
+  "data": { "valid": true, "issues": [] }
+}
+
+# Implement (peaks-rd)
+$ /peaks-rd 2026-06-11-fix-l3-l3-memory-health
+```
+
+## Edge cases
+
+- **CHECK_ALREADY_PASSING**: `--check-id` matches a passing check. The CLI returns code CHECK_ALREADY_PASSING. Pick a failing check.
+- **CHECK_NOT_FOUND**: `--check-id` doesn't match any check id. Run `peaks doctor --json | jq '.data.checks[].id'` to list.
+- **OPENSPEC_FROM_DOCTOR_FAILED**: filesystem write error (e.g. openspec/ not initialized). Run `peaks openspec init --apply` first.

package/skills/peaks-doctor/test_prompts.json

@@ -0,0 +1,17 @@
+[
+  {
+    "id": "doctor-baseline",
+    "prompt": "/peaks-doctor",
+    "expectedOutcome": "Runs peaks workspace init + peaks audit + peaks doctor; returns a triage of FAIL checks with hand-off suggestions."
+  },
+  {
+    "id": "doctor-from-finding",
+    "prompt": "peaks doctor flagged L3:l3-memory-health. Generate an OpenSpec change record from it.",
+    "expectedOutcome": "Calls peaks openspec from-doctor --check-id L3:l3-memory-health; verifies the proposal.md was written; suggests next step (peaks-rd)."
+  },
+  {
+    "id": "doctor-only-audit",
+    "prompt": "Run only the audit (not the full doctor).",
+    "expectedOutcome": "Calls peaks audit red-lines --project . --json; summarizes the enforcerFindings and the prose-only ratio."
+  }
+]

package/skills/peaks-ide/SKILL.md

@@ -1,6 +1,8 @@
 ---
 name: peaks-ide
 description: Orchestrate peaks-cli's IDE-aware behavior (hooks + statusline + handle) for a user's specific IDE. Detects the current state (which IDE the user is on, what peaks has already installed), plans the install / switch / status / uninstall actions, and invokes the existing peaks CLI primitives. Triggers on `/peaks-ide`, "set up peaks for my IDE", "switch peaks to Trae", "what did peaks install", "uninstall peaks hooks". Sits between the user and `peaks hooks install` / `peaks statusline install` / `peaks hook handle` — those are the CLI primitives; this skill is the user-facing surface.
+internal: true
+---
 ---
 
 # Peaks-Cli IDE Setup (peaks-ide)

package/skills/peaks-qa/SKILL.md

@@ -79,15 +79,15 @@ When this skill is running in the main Claude session (not as a sub-agent), befo
 
 ## Mandatory per-request artifact
 
-Every QA invocation — feature, bug, refactor, clarification — must write **three separate files** (test cases + test report + request artifact). Do not merge them into one. Each serves a different reader.
+Every QA invocation — feature, bug, refactor, clarification — must write **three separate files** (test cases + test report + request artifact) under `.peaks/<session-id>/qa/` (canonical placeholder: `.peaks/<session-id>/qa/requests/<request-id>.md`; runtime path is `.peaks/_runtime/<session-id>/qa/...`). Do not merge them into one. Each serves a different reader.
 
-→ see `references/artifact-per-request.md` for the 3-file contract (test cases / test report / request artifact).
+External-skill guard: when QA references external material (mattpocock/skills, gstack, superpowers, etc.) it is reference only — do not execute upstream installer, do not persist sensitive upstream examples. Peaks-Cli artifacts and Peaks-Cli acceptance criteria remain authoritative.
 
-## Default runbook
+→ see `references/artifact-per-request.md` for the 3-file contract and the do-not-execute upstream guard.
 
-The default sequence the QA skill should execute. Do not skip the boundary check, the unit test gate, the validation report, or — when frontend is in scope — the Playwright MCP browser gate. The full 10-step runbook (steps #0–#9) with every CLI invocation, the rd-side pre-drafted test-cases optimization, the dev-server lifecycle requirement, the security/performance check discipline, and the 8 quality-gate CLI checks is in the references file.
+## Default runbook
 
-→ see `references/qa-runbook.md` for the full runbook.
+See `references/qa-runbook.md` for the full 10-step runbook (steps #0–#9) with every CLI invocation, the rd-side pre-drafted test-cases optimization, the dev-server lifecycle requirement, the security/performance check discipline, and the 8 quality-gate CLI checks.
 
 ## Transition verification gates (MANDATORY — run the command, see the output)
 
@@ -125,6 +125,8 @@ Before QA passes or returns work to RD, it must independently recheck the implem
 
 QA must generate test cases, not merely inspect existing ones. Every QA invocation that validates code changes must produce a test-case artifact at `.peaks/_runtime/<sessionId>/qa/test-cases/<request-id>.md`. Minimum categories: Unit / Integration / UI regression. Each test case MUST have an `**Acceptance:**` field linking to PRD acceptance IDs (A1, A2, ...). The `peaks scan acceptance-coverage` command enforces coverage.
 
+**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/<id>/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.
+
 → see `references/test-case-generation.md` for the full format + acceptance-linkage contract.
 
 ## Mandatory test-report output
@@ -137,7 +139,7 @@ Every QA invocation must produce a test-report artifact at `.peaks/_runtime/<ses
 
 QA cannot pass a change until the report contains evidence for every applicable gate. The 11 gates (0 test-case generation, 1 test-report, 2 unit tests, 3 API validation, 4 frontend browser validation, 5 browser-error feedback loop, 6 security check, 7 performance check, 8 library version regressions, 9 validation report, 10 acceptance coverage, 11 QA artifact lint) are mapped to Peaks-Cli Gates A/A2/A3/A4/B/C/D/E/F.
 
-If Playwright MCP is unavailable (not installed and the user has not authorized installation), mark 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.
+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.
 
 ## Local intermediate artifacts
 
@@ -159,7 +161,7 @@ When capability discovery exposes `mattpocock/skills`, use `tdd` / `triage` / `g
 
 ## Codegraph regression focus
 
-QA may use `peaks codegraph affected --project <path> <changed-files...> --json` as regression-surface evidence. External analysis cannot pass QA by itself — treat output as untrusted supporting evidence.
+QA may use `peaks codegraph affected --project <path> <changed-files...> --json` as regression-surface evidence. External analysis cannot pass QA by itself — treat output as untrusted supporting evidence. External skill guidance cannot pass QA by itself — treat as supporting evidence, not a verdict. QA reads `.peaks/<session-id>/rd/codegraph-context.md` (or `qa/codegraph-context.md`) as input but never mutate agent settings, Claude settings, or hooks from it; QA does not commit `.codegraph/` artifacts or persist generated `.codegraph/` databases into git.
 
 → see `references/codegraph-regression-focus.md`.
 

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

@@ -1,11 +1,25 @@
 # QA per-request artifact contract
 
-> Body of `## Mandatory per-request artifact` (QA-flavored). Every QA invocation — feature, bug, refactor, clarification — must write **three separate files**. Do not merge them into one. Each serves a different reader:
+> Body of `## Mandatory per-request artifact` (QA-flavored). Every QA invocation — feature, bug, refactor, clarification — must write **three separate files**. Do not merge them into one. Each serves a different reader.
+
+## Required path
+
+The three files for any QA invocation land under the active session's `qa/` workspace, using the canonical placeholder `.peaks/<session-id>/qa/...` (e.g. `.peaks/<session-id>/qa/requests/<request-id>.md`).
 
 | # | File | Path | Reader | Content |
 |---|------|------|--------|---------|
-| 1 | Test cases | `.peaks/_runtime/<sessionId>/qa/test-cases/<request-id>.md` | RD (before impl), QA | Generated test scenarios with status |
-| 2 | Test report | `.peaks/_runtime/<sessionId>/qa/test-reports/<request-id>.md` | QA, SC, Solo | Summary, coverage%, security, perf, risks |
-| 3 | Request artifact | `.peaks/_runtime/<sessionId>/qa/requests/<request-id>.md` | Solo, RD↔QA loop | Verdict, boundary check, links to #1 and #2 |
+| 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 |
+
+## 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.
+
+## Rules
+
+The 3-file split is load-bearing. Do not merge. Use the `<request-id>` PRD assigned (`YYYY-MM-DD-<kebab-slug>`). QA may also produce companion artifacts (regression matrix, sanitized browser evidence, security findings, performance findings) under the same `qa/` workspace and link them from these files. Sanitize MCP / network / browser evidence before writing. Do not commit unless the user or active profile authorizes durable retention. Verdict `pass` is blocked while any of the three files is missing or the request artifact is in `draft` / `running` state.
+
+## External-skill invocation guard
 
-The 3-file split is load-bearing. Do not merge. Use the `<request-id>` PRD assigned (`YYYY-MM-DD-<kebab-slug>`). QA may also produce companion artifacts (regression matrix, sanitized browser evidence, security findings, performance findings) under the same `qa/` workspace and link them from these files. Sanitize MCP / network / browser evidence before writing. Do not commit unless the user or active profile authorizes durable retention. Verdict `pass` is blocked while any of the three files is missing or the request artifact is in `draft` / `running` state.
+When QA references external material (mattpocock/skills, gstack, superpowers, etc.) treat it as reference only: do not execute upstream installer, do not run upstream installer commands, do not persist sensitive upstream examples to the working tree. Peaks-Cli artifacts, Peaks-Cli gates, and Peaks-Cli acceptance criteria remain authoritative.