peaks-cli 1.2.8 → 1.2.9

package/dist/src/services/scan/libraries-types.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Library version scan types.
+ * Joins the existing scan family (archetype, existing-system, type-sanity,
+ * acceptance-coverage, diff-vs-scope, file-size) but is intentionally scoped
+ * to library version enumeration only. Does NOT extend scan-types.ts —
+ * each scan service ships its own types to keep the scan-types module
+ * focused on the archetype + existing-system pair (see src/services/scan/scan-types.ts).
+ */
+export type Ecosystem = 'npm';
+export type DependencyScope = 'dependencies' | 'devDependencies' | 'peerDependencies' | 'optionalDependencies';
+export type LibraryEntry = {
+    /** npm package name (e.g. "antd", "@mui/material", "react-router-dom"). */
+    name: string;
+    /** Raw version spec as written in package.json (e.g. "^5.18.0", "workspace:*", "git+https://..."). */
+    version: string;
+    /**
+     * Parsed major version, or null when the spec is non-semver (e.g.
+     * "workspace:*", "file:../local", "git+https://..."). The LLM should
+     * treat null as "cannot determine major; consult breaking-changes table
+     * by other signals (e.g. lockfile or import statement shape)".
+     */
+    major: number | null;
+    scope: DependencyScope;
+    ecosystem: Ecosystem;
+};
+/**
+ * Per-workspace provenance for monorepo scans.
+ *
+ * `path` is the absolute path of the `package.json` that contributed
+ * libraries. `count` is the number of `LibraryEntry` rows produced by
+ * reading that single `package.json` (i.e. NOT the aggregate across
+ * the whole monorepo — use `LibraryReport.totalCount` for the aggregate).
+ *
+ * `name` and `version` are the workspace's own `name` / `version` from
+ * its `package.json`, when present. They are optional because some
+ * workspace `package.json` files omit them.
+ */
+export type WorkspaceEntry = {
+    path: string;
+    count: number;
+    name?: string;
+    version?: string;
+};
+export type LibraryReport = {
+    projectRoot: string;
+    libraries: LibraryEntry[];
+    totalCount: number;
+    byScope: Record<DependencyScope, number>;
+    /**
+     * Per-workspace provenance for monorepo (pnpm / npm / yarn workspaces,
+     * lerna) projects. Empty for single-package projects so the field is
+     * always present (additive; consumers can rely on the shape).
+     */
+    workspaces: WorkspaceEntry[];
+    /** ISO timestamp at scan time. */
+    scannedAt: string;
+    /** Soft signals — e.g. "package.json not found" or "package.json is not valid JSON". */
+    warnings: string[];
+};

package/dist/src/services/scan/libraries-types.js

@@ -0,0 +1,9 @@
+/**
+ * Library version scan types.
+ * Joins the existing scan family (archetype, existing-system, type-sanity,
+ * acceptance-coverage, diff-vs-scope, file-size) but is intentionally scoped
+ * to library version enumeration only. Does NOT extend scan-types.ts —
+ * each scan service ships its own types to keep the scan-types module
+ * focused on the archetype + existing-system pair (see src/services/scan/scan-types.ts).
+ */
+export {};

package/dist/src/services/skills/skill-runbook-service.js

@@ -1,3 +1,4 @@
+import { dirname, join } from 'node:path';
 import { readText } from '../../shared/fs.js';
 import { loadSkillRegistry } from './skill-registry.js';
 const DESTRUCTIVE_APPLY_PATTERNS = [
@@ -13,6 +14,38 @@ function extractRunbookSection(body) {
     const match = /## Default runbook\n+([\s\S]*?)(?=\n## |$)/.exec(body);
     return match === null ? null : match[1];
 }
+/**
+ * Load the runbook section, falling back to `references/runbook.md` if the
+ * SKILL.md only has a pointer section. This supports skills (notably
+ * `peaks-solo`) that extracted their 150-line bash runbook to a sibling
+ * reference to keep SKILL.md under the 800-line cap. The CLI
+ * `peaks skill runbook` command uses the same fallback so a human
+ * reviewer sees the full runbook regardless of where it lives.
+ *
+ * Strategy: prefer the LONGER of the two sections. A short pointer section
+ * in SKILL.md (~ 1-2 lines) is treated as a "this runbook is in the
+ * reference" marker; a long inline section (>= the reference length) is
+ * treated as the canonical runbook. This avoids the false positive where
+ * the pointer section's regex match returns a non-null but content-poor
+ * string.
+ */
+async function loadRunbookSection(skillPath, body) {
+    const inline = extractRunbookSection(body);
+    const refPath = join(dirname(skillPath), 'references', 'runbook.md');
+    let refSection = null;
+    try {
+        const refBody = await readText(refPath);
+        refSection = extractRunbookSection(refBody);
+    }
+    catch {
+        // reference file does not exist or is not readable
+    }
+    if (inline === null)
+        return refSection;
+    if (refSection === null)
+        return inline;
+    return inline.length >= refSection.length ? inline : refSection;
+}
 function findDestructiveApplyLines(section) {
     const lines = section.split(/\r?\n/);
     return lines.filter((line) => DESTRUCTIVE_APPLY_PATTERNS.some((pattern) => pattern.test(line)));
@@ -30,7 +63,7 @@ export async function inspectSkillRunbook(name, baseDir) {
         throw new Error(`Skill "${name}" not found under skills directory`);
     }
     const body = await readText(skill.skillPath);
-    const section = extractRunbookSection(body);
+    const section = await loadRunbookSection(skill.skillPath, body);
     if (section === null) {
         return {
             name: skill.name,

package/dist/src/services/workflow/autonomous-resume-writer.js

@@ -1,6 +1,6 @@
 import { mkdir, writeFile } from 'node:fs/promises';
 import { dirname, join } from 'node:path';
-import { buildArtifactRelativePath, validateChangeIdOrThrow } from '../../shared/change-id.js';
+import { buildArtifactRelativePathInRoot, validateChangeIdOrThrow } from '../../shared/change-id.js';
 import { pathExists } from '../../shared/fs.js';
 function defaultClock() {
     return new Date().toISOString();
@@ -109,27 +109,27 @@ Next actions:
 function buildFiles(changeId, goal, createdAt, artifactWorkspacePath) {
     return [
         {
-            path: join(artifactWorkspacePath, buildArtifactRelativePath(changeId, 'prd', 'autonomous-goal-package.json')),
+            path: join(artifactWorkspacePath, buildArtifactRelativePathInRoot(artifactWorkspacePath, changeId, 'prd', 'autonomous-goal-package.json')),
             content: renderGoalPackage(changeId, goal)
         },
         {
-            path: join(artifactWorkspacePath, buildArtifactRelativePath(changeId, 'rd', 'swarm', 'autonomous-rd-plan.json')),
+            path: join(artifactWorkspacePath, buildArtifactRelativePathInRoot(artifactWorkspacePath, changeId, 'rd', 'swarm', 'autonomous-rd-plan.json')),
             content: renderRdPlan(changeId)
         },
         {
-            path: join(artifactWorkspacePath, buildArtifactRelativePath(changeId, 'rd', 'swarm', 'checkpoints', 'checkpoint-1.json')),
+            path: join(artifactWorkspacePath, buildArtifactRelativePathInRoot(artifactWorkspacePath, changeId, 'rd', 'swarm', 'checkpoints', 'checkpoint-1.json')),
             content: renderCheckpoint(changeId, createdAt)
         },
         {
-            path: join(artifactWorkspacePath, buildArtifactRelativePath(changeId, 'rd', 'swarm', 'evidence', 'unit-tests.md')),
+            path: join(artifactWorkspacePath, buildArtifactRelativePathInRoot(artifactWorkspacePath, changeId, 'rd', 'swarm', 'evidence', 'unit-tests.md')),
             content: renderUnitTestsEvidence(changeId)
         },
         {
-            path: join(artifactWorkspacePath, buildArtifactRelativePath(changeId, 'rd', 'swarm', 'evidence', 'validation-report.md')),
+            path: join(artifactWorkspacePath, buildArtifactRelativePathInRoot(artifactWorkspacePath, changeId, 'rd', 'swarm', 'evidence', 'validation-report.md')),
             content: renderValidationReport(changeId)
         },
         {
-            path: join(artifactWorkspacePath, buildArtifactRelativePath(changeId, 'rd', 'swarm', 'resume-instructions.md')),
+            path: join(artifactWorkspacePath, buildArtifactRelativePathInRoot(artifactWorkspacePath, changeId, 'rd', 'swarm', 'resume-instructions.md')),
             content: renderResumeInstructions(changeId)
         }
     ];

package/dist/src/shared/change-id.d.ts

@@ -11,6 +11,30 @@ export declare class ChangeIdValidationError extends Error {
     constructor(changeId: string);
 }
 export declare function isUnsafeArtifactPath(path: string): boolean;
+/**
+ * Build an artifact-relative path using a caller-supplied project root, so
+ * the helper does not need to walk `process.cwd()` to find a session.
+ *
+ * If a session exists for `projectRoot`, files are stored in:
+ *   .peaks/<sessionId>/<role>/<number>-<changeId>.md
+ *
+ * If no session exists, falls back to legacy behavior:
+ *   .peaks/<changeId>/<segments>
+ *
+ * Use this from callers that have a workspace or `artifactWorkspacePath` in
+ * hand (e.g. CLI subcommands that received `--project`, or test fixtures
+ * that created a tmpdir workspace). Legacy callers without an explicit
+ * `projectRoot` should continue to use `buildArtifactRelativePath`.
+ *
+ * @param projectRoot - The project root to use for session lookup and dirPath
+ *   computation. Must be an absolute path. Falls back to `process.cwd()` if
+ *   the empty string is passed (defensive only; should not happen via the
+ *   public API).
+ * @param changeId - Used as file description/slug (e.g., "auth-system", "add-user-auth")
+ * @param segments - Optional path segments (first segment is typically the role: 'prd', 'rd', 'qa', etc.)
+ * @returns Relative path to the artifact file
+ */
+export declare function buildArtifactRelativePathInRoot(projectRoot: string, changeId: string, ...segments: string[]): string;
 /**
  * Build an artifact-relative path using session-based storage.
  *
@@ -20,6 +44,12 @@ export declare function isUnsafeArtifactPath(path: string): boolean;
  * If no session exists, falls back to legacy behavior:
  *   .peaks/<changeId>/<segments>
  *
+ * This function walks `process.cwd()` to find the project root and reads
+ * `.peaks/.session.json` from it. Callers that already have an explicit
+ * `projectRoot` (workspace handle, test fixture, or CLI `--project` flag)
+ * should prefer `buildArtifactRelativePathInRoot(projectRoot, ...)` to
+ * avoid being polluted by the host environment's session binding.
+ *
  * @param changeId - Used as file description/slug (e.g., "auth-system", "add-user-auth")
  * @param segments - Optional path segments (first segment is typically the role: 'prd', 'rd', 'qa', etc.)
  * @returns Relative path to the artifact file

package/dist/src/shared/change-id.js

@@ -62,25 +62,37 @@ export function isUnsafeArtifactPath(path) {
     return isUnsafePathInput(path);
 }
 /**
- * Build an artifact-relative path using session-based storage.
+ * Build an artifact-relative path using a caller-supplied project root, so
+ * the helper does not need to walk `process.cwd()` to find a session.
  *
- * If a session exists, files are stored in:
+ * If a session exists for `projectRoot`, files are stored in:
  *   .peaks/<sessionId>/<role>/<number>-<changeId>.md
  *
  * If no session exists, falls back to legacy behavior:
  *   .peaks/<changeId>/<segments>
  *
+ * Use this from callers that have a workspace or `artifactWorkspacePath` in
+ * hand (e.g. CLI subcommands that received `--project`, or test fixtures
+ * that created a tmpdir workspace). Legacy callers without an explicit
+ * `projectRoot` should continue to use `buildArtifactRelativePath`.
+ *
+ * @param projectRoot - The project root to use for session lookup and dirPath
+ *   computation. Must be an absolute path. Falls back to `process.cwd()` if
+ *   the empty string is passed (defensive only; should not happen via the
+ *   public API).
  * @param changeId - Used as file description/slug (e.g., "auth-system", "add-user-auth")
  * @param segments - Optional path segments (first segment is typically the role: 'prd', 'rd', 'qa', etc.)
  * @returns Relative path to the artifact file
  */
-export function buildArtifactRelativePath(changeId, ...segments) {
+export function buildArtifactRelativePathInRoot(projectRoot, changeId, ...segments) {
     validateChangeIdOrThrow(changeId);
-    const projectRoot = findProjectRoot(process.cwd()) ?? process.cwd();
-    const sessionId = getSessionId(projectRoot);
+    const resolvedProjectRoot = projectRoot && projectRoot.length > 0
+        ? projectRoot
+        : (findProjectRoot(process.cwd()) ?? process.cwd());
+    const sessionId = getSessionId(resolvedProjectRoot);
     if (sessionId && segments.length > 0 && segments[0]) {
         const role = normalizeForwardSlashes(segments[0]);
-        const dirPath = join(projectRoot, '.peaks', sessionId, role);
+        const dirPath = join(resolvedProjectRoot, '.peaks', sessionId, role);
         if (isUnsafeArtifactPath(role) || isUnsafeArtifactPath(sessionId)) {
             throw new ChangeIdValidationError(changeId);
         }
@@ -97,6 +109,28 @@ export function buildArtifactRelativePath(changeId, ...segments) {
     }
     return normalizeArtifactPath(candidatePath);
 }
+/**
+ * Build an artifact-relative path using session-based storage.
+ *
+ * If a session exists, files are stored in:
+ *   .peaks/<sessionId>/<role>/<number>-<changeId>.md
+ *
+ * If no session exists, falls back to legacy behavior:
+ *   .peaks/<changeId>/<segments>
+ *
+ * This function walks `process.cwd()` to find the project root and reads
+ * `.peaks/.session.json` from it. Callers that already have an explicit
+ * `projectRoot` (workspace handle, test fixture, or CLI `--project` flag)
+ * should prefer `buildArtifactRelativePathInRoot(projectRoot, ...)` to
+ * avoid being polluted by the host environment's session binding.
+ *
+ * @param changeId - Used as file description/slug (e.g., "auth-system", "add-user-auth")
+ * @param segments - Optional path segments (first segment is typically the role: 'prd', 'rd', 'qa', etc.)
+ * @returns Relative path to the artifact file
+ */
+export function buildArtifactRelativePath(changeId, ...segments) {
+    return buildArtifactRelativePathInRoot(findProjectRoot(process.cwd()) ?? process.cwd(), changeId, ...segments);
+}
 export function isPathInsideArtifactRoot(path, artifactRoot) {
     if (!path || !artifactRoot)
         return false;

package/dist/src/shared/paths.d.ts

@@ -3,4 +3,4 @@ export declare const skillsDir: string;
 export declare const schemasDir: string;
 export declare const templatesDir: string;
 export declare const requiredSkillNames: readonly ["peaks-solo", "peaks-prd", "peaks-ui", "peaks-rd", "peaks-qa", "peaks-sc", "peaks-txt", "peaks-sop"];
-export declare const requiredSchemaFiles: readonly ["artifact-manifest.schema.json", "context-capsule.schema.json", "approval-record.schema.json", "change-impact.schema.json", "refactor-slice-spec.schema.json", "artifact-retention-report.schema.json", "capability-source.schema.json", "capability-item.schema.json", "capability-availability.schema.json", "recommendation-plan.schema.json", "artifact-workspace.schema.json", "mcp-server.schema.json", "mcp-install-spec.schema.json", "mcp-install-plan.schema.json", "mcp-apply-result.schema.json", "openspec-change-summary.schema.json", "openspec-render-request.schema.json", "openspec-validation-result.schema.json", "doctor-report.schema.json"];
+export declare const requiredSchemaFiles: readonly ["artifact-manifest.schema.json", "context-capsule.schema.json", "approval-record.schema.json", "change-impact.schema.json", "refactor-slice-spec.schema.json", "artifact-retention-report.schema.json", "capability-source.schema.json", "capability-item.schema.json", "capability-availability.schema.json", "recommendation-plan.schema.json", "artifact-workspace.schema.json", "mcp-server.schema.json", "mcp-install-spec.schema.json", "mcp-install-plan.schema.json", "mcp-apply-result.schema.json", "openspec-change-summary.schema.json", "openspec-render-request.schema.json", "openspec-validation-result.schema.json", "doctor-report.schema.json", "library-breaking-changes.schema.json"];

package/dist/src/shared/paths.js

@@ -45,5 +45,6 @@ export const requiredSchemaFiles = [
     'openspec-change-summary.schema.json',
     'openspec-render-request.schema.json',
     'openspec-validation-result.schema.json',
-    'doctor-report.schema.json'
+    'doctor-report.schema.json',
+    'library-breaking-changes.schema.json'
 ];

package/dist/src/shared/version.d.ts

@@ -1 +1 @@
-export declare const CLI_VERSION = "1.2.8";
+export declare const CLI_VERSION = "1.2.9";

package/dist/src/shared/version.js

@@ -1 +1 @@
-export const CLI_VERSION = "1.2.8";
+export const CLI_VERSION = "1.2.9";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "peaks-cli",
-  "version": "1.2.8",
+  "version": "1.2.9",
   "description": "Peaks CLI and short skill family for Claude Code automation.",
   "author": "SquabbyZ",
   "license": "MIT",

package/schemas/library-breaking-changes.data.json

@@ -0,0 +1,141 @@
+[
+  {
+    "library": "antd",
+    "fromMajor": 4,
+    "toMajor": 5,
+    "breakingChanges": [
+      { "api": "Drawer.width", "replacement": "Drawer.size", "since": "5.0.0" },
+      { "api": "Modal.width (string)", "replacement": "Modal.width (number) or styles.body.width (number)", "since": "5.0.0" },
+      { "api": "Form.create()", "replacement": "App.useForm() (under <App>)", "since": "5.0.0" },
+      { "api": "message.useMessage()", "replacement": "App.useApp().message (under <App>)", "since": "5.0.0" },
+      { "api": "notification.useNotification()", "replacement": "App.useApp().notification (under <App>)", "since": "5.0.0" },
+      { "api": "import 'antd/dist/antd.css'", "replacement": "import 'antd/dist/reset.css'", "since": "5.0.0" },
+      { "api": "<Form.Item {...layout}", "replacement": "<Form layout='vertical' | 'horizontal'> (no per-item layout prop)", "since": "5.0.0" }
+    ]
+  },
+  {
+    "library": "@antv/g6",
+    "fromMajor": 4,
+    "toMajor": 5,
+    "breakingChanges": [
+      { "api": "new G6.Graph({ mode: 'default' })", "replacement": "new G6.Graph({ type: 'graph' })", "since": "5.0.0" },
+      { "api": "graph.read(data)", "replacement": "graph.setData(data); graph.render()", "since": "5.0.0" },
+      { "api": "graph.changeData(data)", "replacement": "graph.setData(data); graph.render()", "since": "5.0.0" },
+      { "api": "G6.registerBehavior('drag-canvas', { getEvents() { return { ... } } })", "replacement": "G6.registerBehavior({ key: 'drag-canvas', type: 'drag-canvas', getEvents() { return { ... } } })", "since": "5.0.0" }
+    ]
+  },
+  {
+    "library": "@mui/material",
+    "fromMajor": 4,
+    "toMajor": 5,
+    "breakingChanges": [
+      { "api": "import { Grid } from '@mui/material'", "replacement": "import Grid from '@mui/material/Grid2' (Grid renamed Grid2, separate import path)", "since": "5.0.0" },
+      { "api": "createTheme({ unstable_createRheaTheme: true })", "replacement": "createTheme({ cssVariables: true })", "since": "5.0.0" },
+      { "api": "<DialogTitle disableTypography>", "replacement": "<DialogTitle component='div'> (disableTypography removed; use component prop)", "since": "5.0.0" },
+      { "api": "<TextField variant='standard' InputLabelProps={{ shrink: true }}>", "replacement": "<TextField variant='standard' slotProps={{ inputLabel: { shrink: true } }}>", "since": "5.0.0" }
+    ]
+  },
+  {
+    "library": "react-router-dom",
+    "fromMajor": 5,
+    "toMajor": 6,
+    "breakingChanges": [
+      { "api": "<Switch>", "replacement": "<Routes>", "since": "6.0.0" },
+      { "api": "<Redirect>", "replacement": "<Navigate>", "since": "6.0.0" },
+      { "api": "useHistory()", "replacement": "useNavigate()", "since": "6.0.0" },
+      { "api": "match.params", "replacement": "useParams()", "since": "6.0.0" },
+      { "api": "withRouter(Component)", "replacement": "useNavigate() + useLocation() + useParams() hooks", "since": "6.0.0" },
+      { "api": "<Route component={Component} />", "replacement": "<Route element={<Component />} /> (component prop renamed element)", "since": "6.0.0" },
+      { "api": "<Route path='/:id' exact />", "replacement": "<Route path='/:id' /> (exact prop removed; paths match exactly by default)", "since": "6.0.0" }
+    ]
+  },
+  {
+    "library": "tailwindcss",
+    "fromMajor": 2,
+    "toMajor": 3,
+    "breakingChanges": [
+      { "api": "tailwind.config.js (CommonJS, no 'type' in package.json)", "replacement": "tailwind.config.cjs (CommonJS) or tailwind.config.ts (ESM)", "since": "3.0.0" },
+      { "api": "content: ['./src/**/*.{html,js}']", "replacement": "content: ['./src/**/*.{html,js,jsx,ts,tsx,vue,svelte}']", "since": "3.0.0" },
+      { "api": "@tailwindcss/typography (default import)", "replacement": "import typography from '@tailwindcss/typography' (named default; config: { plugins: [typography] })", "since": "3.0.0" },
+      { "api": "colors: { 'custom-blue': '#1da1f2' }", "replacement": "colors: { custom: { blue: '#1da1f2' } } (nested under named palette; tailwind.config reads as 'text-custom-blue' = 'text-custom-blue' still works but is a single nesting level removed)", "since": "3.0.0" }
+    ]
+  },
+  {
+    "library": "@reduxjs/toolkit",
+    "fromMajor": 1,
+    "toMajor": 2,
+    "breakingChanges": [
+      { "api": "import { createAsyncThunk, createReducer } from '@reduxjs/toolkit' (with manual pending/fulfilled/rejected handlers)", "replacement": "import { createAsyncThunk, createSlice } from '@reduxjs/toolkit'; createSlice auto-generates pending/fulfilled/rejected matchers", "since": "2.0.0" },
+      { "api": "createSlice({ reducers: { ... }, extraReducers: (builder) => builder.addCase(...) })", "replacement": "createSlice({ reducers, extraReducers: (builder) => builder.addCase(...) }) — unchanged shape; check RTK 2.0 matchers for createAsyncThunk with builder.addMatcher", "since": "2.0.0" },
+      { "api": "configureStore({ reducer, middleware: (gDM) => gDM().concat(logger) })", "replacement": "configureStore({ reducer, middleware: (gDM) => gDM({ serializableCheck: false }).concat(logger) })", "since": "2.0.0" }
+    ]
+  },
+  {
+    "library": "next",
+    "fromMajor": 14,
+    "toMajor": 15,
+    "breakingChanges": [
+      { "api": "params (in pages/)", "replacement": "await params (params is now a Promise; await it before reading properties)", "since": "15.0.0" },
+      { "api": "searchParams (in pages/)", "replacement": "await searchParams (searchParams is now a Promise)", "since": "15.0.0" },
+      { "api": "cookies().get('name') (synchronous)", "replacement": "await cookies() (cookies() now returns a Promise; await before calling .get)", "since": "15.0.0" },
+      { "api": "headers().get('name') (synchronous)", "replacement": "await headers() (headers() now returns a Promise)", "since": "15.0.0" },
+      { "api": "fetch(url, { cache: 'force-cache' })", "replacement": "fetch(url, { cache: 'force-cache' }) + export const dynamic = 'force-static' OR use a Server Action", "since": "15.0.0" }
+    ]
+  },
+  {
+    "library": "react",
+    "fromMajor": 17,
+    "toMajor": 18,
+    "breakingChanges": [
+      { "api": "ReactDOM.render(<App />, container)", "replacement": "createRoot(container).render(<App />)", "since": "18.0.0" },
+      { "api": "ReactDOM.hydrate(<App />, container)", "replacement": "hydrateRoot(container, <App />)", "since": "18.0.0" },
+      { "api": "import { render } from 'react-dom'", "replacement": "import { createRoot } from 'react-dom/client' (separate entry point)", "since": "18.0.0" },
+      { "api": "ReactDOM.unmountComponentAtNode(container)", "replacement": "root.unmount() (returned from createRoot)", "since": "18.0.0" },
+      { "api": "defaultProps on function components", "replacement": "default parameters (defaultProps will be removed in a future major; use destructuring defaults: function Foo({ x = 1 } = {}) {})", "since": "18.3.0" }
+    ]
+  },
+  {
+    "library": "typescript",
+    "fromMajor": 4,
+    "toMajor": 5,
+    "breakingChanges": [
+      { "api": "import type { ... } from 'mod' (mixed type + value import without explicit type modifier)", "replacement": "Add `type` modifier to type-only imports explicitly (TS 5.0 enforces with verbatimModuleSyntax)", "since": "5.0.0" },
+      { "api": "namespace X { function f(): X.Type }", "replacement": "Use `import type` or `export type` from namespaces (TS 5.0 changes how namespaces interop with modules)", "since": "5.0.0" },
+      { "api": "experimentalDecorators metadata emit", "replacement": "Use the new TC39 stage-3 decorators; experimentalDecorators flag will be removed", "since": "5.0.0" },
+      { "api": "enum X { A, B = A * 2 } (numeric enum with computed member before non-computed)", "replacement": "Reorder enum members: place all non-computed members before computed ones", "since": "5.0.0" }
+    ]
+  },
+  {
+    "library": "prisma",
+    "fromMajor": 4,
+    "toMajor": 5,
+    "breakingChanges": [
+      { "api": "previewFeatures = ['xxx'] (in schema.prisma)", "replacement": "Move preview features to a separate block; some promoted to stable without flag", "since": "5.0.0" },
+      { "api": "prisma.user.findMany({ include: { posts: true } }) (implicit include via relation)", "replacement": "Use `with: { posts: true }` (include renamed to with)", "since": "5.0.0" },
+      { "api": "prisma.user.findMany({ relationJumps: { ... } })", "replacement": "Use `include` with `_count: { select: ... }` or nested select on relation fields", "since": "5.0.0" },
+      { "api": "@prisma/client v4 ESM/CJS interop (require vs import)", "replacement": "Pure ESM in v5; use `import` syntax only; dynamic require() of generated client throws", "since": "5.0.0" }
+    ]
+  },
+  {
+    "library": "eslint",
+    "fromMajor": 8,
+    "toMajor": 9,
+    "breakingChanges": [
+      { "api": ".eslintrc.json (legacy config)", "replacement": "eslint.config.js (flat config; legacy mode requires @eslint/eslintrc)", "since": "9.0.0" },
+      { "api": "module.exports = { rules: { ... } } (CommonJS rules)", "replacement": "export default [{ rules: { ... } }] (ESM flat config; rules must be inside an array entry)", "since": "9.0.0" },
+      { "api": "context.getSourceCode()", "replacement": "context.sourceCode (renamed; ESLint 9 deprecates getSourceCode)", "since": "9.0.0" },
+      { "api": "rule.create({ visitor }) without meta.schema or meta.type", "replacement": "rule.create({ meta: { schema: [...], type: 'problem'|'suggestion'|'layout' }, visitor }) (ESLint 9 requires meta)", "since": "9.0.0" }
+    ]
+  },
+  {
+    "library": "react-hook-form",
+    "fromMajor": 6,
+    "toMajor": 7,
+    "breakingChanges": [
+      { "api": "useForm({ defaultValues: { ... } }) (defaultValues is now required when using field arrays)", "replacement": "Always provide defaultValues; v7 removed the implicit empty default", "since": "7.0.0" },
+      { "api": "Controller({ name, control, render: ({ field }) => ... }) (Controller is now a generic — must pass field type)", "replacement": "Controller<FieldValues, TFieldPath>({ name: 'field' as TFieldPath, ... }) (cast path to TFieldPath)", "since": "7.0.0" },
+      { "api": "useFormContext() (no generic)", "replacement": "useFormContext<FieldValues>() (generic required for type inference)", "since": "7.0.0" },
+      { "api": "formState.errors.foo (loose type)", "replacement": "formState.errors.foo (typed as FieldError | undefined; use ?.message for safe access)", "since": "7.0.0" }
+    ]
+  }
+]

package/schemas/library-breaking-changes.meta.json

@@ -0,0 +1,6 @@
+{
+  "lastUpdated": "2026-06-04",
+  "freshnessPolicyDays": 180,
+  "libraryCount": 12,
+  "rowCount": 55
+}

package/schemas/library-breaking-changes.schema.json

@@ -0,0 +1,50 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "Peaks Library Breaking Changes",
+  "description": "Manually-curated table of known breaking changes per (library, fromMajor, toMajor). Used by peaks-rd/qa to warn the LLM about deprecated APIs when writing code for projects on a newer major than the LLM's training data. Read by the LLM via the Read tool; the data file at library-breaking-changes.data.json holds the actual rows. Doctor validates parse-ability of this schema file.",
+  "type": "array",
+  "items": {
+    "type": "object",
+    "required": ["library", "fromMajor", "toMajor", "breakingChanges"],
+    "properties": {
+      "library": {
+        "type": "string",
+        "minLength": 1,
+        "description": "npm package name, e.g. 'antd', '@mui/material', 'react-router-dom'."
+      },
+      "fromMajor": {
+        "type": "integer",
+        "minimum": 0,
+        "description": "The major version the breaking change applies FROM. LLM cross-references (project major === toMajor) to fire the warning."
+      },
+      "toMajor": {
+        "type": "integer",
+        "minimum": 1,
+        "description": "The major version the breaking change applies TO (i.e. the new major where the API changed)."
+      },
+      "breakingChanges": {
+        "type": "array",
+        "items": {
+          "type": "object",
+          "required": ["api", "replacement", "since"],
+          "properties": {
+            "api": {
+              "type": "string",
+              "minLength": 1,
+              "description": "The deprecated/removed API call, e.g. 'Drawer.width'. Should be a substring that the LLM can grep for in the diff's import + JSX blocks."
+            },
+            "replacement": {
+              "type": "string",
+              "description": "The v2 API to use instead, e.g. 'Drawer.size'. If empty, the API is removed entirely (no v2 equivalent)."
+            },
+            "since": {
+              "type": "string",
+              "pattern": "^[0-9]+\\.[0-9]+(\\.[0-9]+)?$",
+              "description": "The semver string where this breaking change took effect, e.g. '5.0.0'. Matches the toMajor."
+            }
+          }
+        }
+      }
+    }
+  }
+}

package/skills/peaks-qa/SKILL.md

@@ -168,6 +168,17 @@ peaks openspec validate <change-id> --project <repo> --prefer-external --json
 
 # 4. generate test cases — MANDATORY, write to .peaks/<session-id>/qa/test-cases/<request-id>.md
 #    categories: unit, integration, UI regression (frontend only)
+#
+#    Optimization (slice 004): peaks-rd's parallel fan-out now includes a 4th
+#    sub-agent (`qa-test-cases-writer`) that pre-drafts this file at the
+#    end of RD implementation. If `.peaks/<sid>/qa/test-cases/<rid>.md`
+#    already exists when QA's main loop reaches this step, **QA does NOT
+#    re-draft it** — it just verifies the file is present and the
+#    per-criterion `ts` snippets are syntactically valid, then proceeds
+#    to step 5 (EXECUTE). The wall-clock win: QA's first action is
+#    "execute pre-drafted test plan" instead of "draft + execute".
+#    Fallback: if the file is missing (sub-agent failed / degraded to
+#    inline), QA drafts it inline as before.
 
 # 5. EXECUTE tests against the actual implementation — Peaks-Cli Gate A2
 #    Run the project test command. Record output. Tests on paper are worthless.
@@ -458,6 +469,7 @@ QA cannot pass a change until the report contains evidence for every applicable
 5. **Browser-error feedback loop** — if Playwright MCP observation surfaces a page error, console exception, broken network request, hydration/render failure, or visible regression, return the work to RD/development with the exact evidence. Do not pass QA until the fixed build is retested in the browser.
 6. **Security check** — run security review for the changed surface and dependency/config changes. Record findings, fixes, and unresolved risks.
 7. **Performance check** — run the project’s available performance check, build-size check, Lighthouse-equivalent check, or browser performance inspection appropriate to the change. Record baseline/after numbers when available.
+8. **Library version regressions** — when the slice's diff contains an `import` statement that matches a `breakingChanges[].api` entry in `schemas/library-breaking-changes.data.json` for the library's installed major (read from the RD-handoff's `## Library versions` section), record a `## Library version regressions` block in `qa/test-reports/<rid>.md` listing each hit. Per row: `<api>` → `<replacement>`, source `schemas/library-breaking-changes.data.json`. Treat each unreplaced hit as a **return-to-rd** reason — the LLM should fix the diff before re-handoff. (This is the QA-side counterpart of the RD `## Library version awareness` preflight; the two together form a check-and-verify pair.)
 8. **Validation report** — write or link a report containing scope, environment, commands, sanitized browser evidence, security/performance results, pass/fail summary, residual risks, and next action.
 9. **Acceptance coverage** — every PRD acceptance item has at least one linked QA test case (`peaks scan acceptance-coverage --rid <rid>`). **→ verified by Peaks-Cli Gate E**. This is the deterministic check that no requirement was forgotten between PRD and verdict.
 10. **QA artifact lint** — the QA request artifact body has no unfilled placeholders (`peaks request lint <rid> --role qa`). **→ verified by Peaks-Cli Gate F**. Catches the "wrote the template, forgot to fill it" failure mode that template-style reports invite.