peaks-loop 3.0.0

package/schemas/decomposition-v2.json

@@ -0,0 +1,193 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://peaks-cli.dev/schemas/decomposition-v2.json",
+  "title": "Peaks Decomposition Result v2 (multi-pass)",
+  "description": "v2 multi-pass slice decomposition output. Emitted by `peaks-slice-decompose` and the new `MultiPassOrchestrator`. Discriminated by `schemaVersion: 'v2'`. v1 files (no schemaVersion) remain readable via SchemaRouter.",
+  "type": "object",
+  "required": [
+    "schemaVersion",
+    "rid",
+    "generatedAt",
+    "passes",
+    "crossPassEdges",
+    "llmArbitrations",
+    "codegraph",
+    "understandAnything",
+    "partial"
+  ],
+  "properties": {
+    "schemaVersion": {
+      "type": "string",
+      "const": "v2"
+    },
+    "rid": {
+      "type": "string",
+      "description": "Request id; e.g. \"008-2026-06-25\"."
+    },
+    "generatedAt": {
+      "type": "string",
+      "format": "date-time",
+      "description": "ISO 8601 UTC; e.g. \"2026-06-25T12:00:00.000Z\"."
+    },
+    "passes": {
+      "type": "array",
+      "description": "One entry per decomposition pass (Pass 1 = service, Pass 2 = file, Pass 3 = sub-file reserved).",
+      "items": { "$ref": "#/$defs/PassResult" }
+    },
+    "crossPassEdges": {
+      "type": "array",
+      "description": "Edges connecting slices in different passes. Static (type-shares, fixture-shares, import-re-export) and LLM-arbitrated.",
+      "items": { "$ref": "#/$defs/CrossPassEdge" }
+    },
+    "llmArbitrations": {
+      "type": "array",
+      "description": "Trace of every LLM call made during decomposition. Capped at 2 calls per peaks slice decompose invocation per the global LLM 兜底 budget.",
+      "items": { "$ref": "#/$defs/LlmArbitration" }
+    },
+    "codegraph": { "$ref": "#/$defs/CodegraphEnvelope" },
+    "understandAnything": { "$ref": "#/$defs/UnderstandAnythingEnvelope" },
+    "partial": {
+      "type": "boolean",
+      "description": "True iff any pass failed to complete and the result is a partial decomposition."
+    }
+  },
+  "$defs": {
+    "PassConfig": {
+      "type": "object",
+      "description": "Configuration for a single decomposition pass. Currently informational; the orchestrator picks pass configs.",
+      "required": ["passNumber", "granularity"],
+      "properties": {
+        "passNumber": { "type": "integer", "enum": [1, 2, 3] },
+        "granularity": { "type": "string", "enum": ["service", "file", "sub-file"] },
+        "scopeFilter": {
+          "type": "array",
+          "items": { "type": "string" },
+          "description": "Optional list of files (or semantic anchors) to scope this pass to."
+        }
+      }
+    },
+    "SliceV2": {
+      "type": "object",
+      "description": "A single v2 slice, scoped to one pass. Pass 2/3 slices have a non-null parentSliceId; Pass 1 slices have parentSliceId: null.",
+      "required": ["id", "label", "granularity", "files", "loc", "parentSliceId", "semanticAnchor"],
+      "properties": {
+        "id": {
+          "type": "string",
+          "description": "Stable id within this pass (e.g. \"S1\" for Pass 1, \"S1.3\" for Pass 2 child of S1)."
+        },
+        "label": { "type": "string" },
+        "granularity": { "type": "string", "enum": ["service", "file", "sub-file"] },
+        "files": {
+          "type": "array",
+          "items": { "type": "string" }
+        },
+        "loc": { "type": "integer", "minimum": 0 },
+        "parentSliceId": {
+          "type": ["string", "null"],
+          "description": "Parent slice id from the previous pass, or null for Pass 1."
+        },
+        "semanticAnchor": {
+          "type": "string",
+          "description": "Domain anchor; \"domain:<name>\" if understand-anything indexed, else \"file:<path>\"."
+        }
+      }
+    },
+    "InternalEdge": {
+      "type": "object",
+      "description": "Edge connecting two slices within the same pass.",
+      "required": ["from", "to", "kind", "weight", "evidence", "confidence"],
+      "properties": {
+        "from": { "type": "string" },
+        "to": { "type": "string" },
+        "kind": { "type": "string", "enum": ["imports", "calls", "depends_on", "contains_flow", "flow_step"] },
+        "weight": { "type": "number", "description": "Edge weight for downstream min-cut / dispatch-ordering heuristics." },
+        "evidence": { "type": "string" },
+        "confidence": { "type": "string", "enum": ["structural", "semantic"] }
+      }
+    },
+    "CrossPassEdge": {
+      "type": "object",
+      "description": "Edge connecting a slice in one pass to a slice in another pass. Static (type-shares, fixture-shares, import-re-export) or LLM-arbitrated.",
+      "required": ["fromPass", "toPass", "fromSliceId", "toSliceId", "kind", "confidence", "evidence", "arbitratedBy"],
+      "properties": {
+        "fromPass": { "type": "integer", "enum": [1, 2, 3] },
+        "toPass": { "type": "integer", "enum": [1, 2, 3] },
+        "fromSliceId": { "type": "string" },
+        "toSliceId": { "type": "string" },
+        "kind": { "type": "string", "enum": ["type-shares", "fixture-shares", "import-re-export", "llm-arbitrated"] },
+        "confidence": {
+          "type": "string",
+          "enum": ["structural", "semantic", "llm"],
+          "description": "`llm` is only valid for `kind: 'llm-arbitrated'`."
+        },
+        "evidence": { "type": "string", "description": "Human-readable evidence: the import line, shared fixture id, etc." },
+        "arbitratedBy": {
+          "type": ["string", "null"],
+          "description": "The LlmArbitration.callId that produced this edge, or null for static edges."
+        }
+      }
+    },
+    "LlmArbitration": {
+      "type": "object",
+      "description": "Record of one LLM call made during decomposition.",
+      "required": ["callId", "promptHash", "input", "output", "confidence", "tokens"],
+      "properties": {
+        "callId": { "type": "string" },
+        "promptHash": { "type": "string", "description": "sha256 hex of the prompt (used for content-hash cache lookup)." },
+        "input": { "type": "string" },
+        "output": { "type": "string" },
+        "confidence": { "type": "string", "enum": ["high", "medium", "low"] },
+        "tokens": {
+          "type": "object",
+          "required": ["input", "output"],
+          "properties": {
+            "input": { "type": "integer", "minimum": 0 },
+            "output": { "type": "integer", "minimum": 0 }
+          }
+        }
+      }
+    },
+    "PassResult": {
+      "type": "object",
+      "description": "The slices + internal edges produced by one decomposition pass.",
+      "required": ["passNumber", "granularity", "slices", "internalEdges"],
+      "properties": {
+        "passNumber": { "type": "integer", "enum": [1, 2, 3] },
+        "granularity": { "type": "string", "enum": ["service", "file", "sub-file"] },
+        "slices": {
+          "type": "array",
+          "items": { "$ref": "#/$defs/SliceV2" }
+        },
+        "internalEdges": {
+          "type": "array",
+          "items": { "$ref": "#/$defs/InternalEdge" }
+        }
+      }
+    },
+    "CodegraphEnvelope": {
+      "type": "object",
+      "description": "Local project-analysis evidence envelope. Untrusted supporting evidence, never authoritative for QA verdict.",
+      "required": ["nodes", "edges", "dbMB", "freshness", "affectedCrossFile", "note"],
+      "properties": {
+        "nodes": { "type": "integer", "minimum": 0 },
+        "edges": { "type": "integer", "minimum": 0 },
+        "dbMB": { "type": "number", "minimum": 0 },
+        "freshness": { "type": "string", "description": "Git commit SHA at which the codegraph index was built, or 'unindexed'." },
+        "affectedCrossFile": { "type": "boolean" },
+        "note": { "type": "string" }
+      }
+    },
+    "UnderstandAnythingEnvelope": {
+      "type": "object",
+      "description": "Understand-anything knowledge-graph envelope. `available: false` means semantic-only downstream behaviour is disabled.",
+      "required": ["kgNodes", "kgEdges", "available", "fallback", "note"],
+      "properties": {
+        "kgNodes": { "type": "integer", "minimum": 0 },
+        "kgEdges": { "type": "integer", "minimum": 0 },
+        "available": { "type": "boolean" },
+        "fallback": { "type": "string", "enum": ["semantic", "structural-only"] },
+        "note": { "type": "string" }
+      }
+    }
+  }
+}

package/schemas/doctor-report.schema.json

@@ -0,0 +1,34 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "Peaks Doctor Report",
+  "description": "The envelope emitted by `peaks doctor --json` (data field). Each check.id uses a `<prefix>:<target>` form so callers can route follow-up actions per category.",
+  "type": "object",
+  "required": ["checks", "summary"],
+  "properties": {
+    "checks": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["id", "ok", "message"],
+        "properties": {
+          "id": {
+            "type": "string",
+            "pattern": "^(skill|skill-name|skill-parse|skill-runbook|skill-apply-note|skill-presence|statusline|schema|config|doctor-self|capability|build|integration|L3):[A-Za-z0-9][A-Za-z0-9._-]*$",
+            "description": "Stable check id. Known prefixes: skill:<name> (required skill present), skill-name:<dir> (directory matches declared name), skill-parse:<dir> (skill metadata parsed), skill-runbook:<name> (Default runbook section exists), skill-apply-note:<name> (destructive --apply lines carry an authorization/--dry-run note), skill-presence:<topic> (status of .peaks/.active-skill.json — current/freshness/workspace), statusline:<topic> (out-of-band Claude Code statusLine — install/runtime), schema:<file> (schema file exists and is valid JSON), config:<scope> (optional config locations), doctor-self:<topic> (doctor validates its own output against this schema), capability:<name> (third-party capability is resolvable at the pinned version), build:<topic> (build-hygiene checks — dist/source version consistency), integration:<name> (third-party integration probe — e.g. gateguard-fact-force PreToolUse hook conflict on .peaks/**)."
+          },
+          "ok": { "type": "boolean" },
+          "message": { "type": "string", "minLength": 1 }
+        }
+      }
+    },
+    "summary": {
+      "type": "object",
+      "required": ["ok", "passed", "failed"],
+      "properties": {
+        "ok": { "type": "boolean" },
+        "passed": { "type": "integer", "minimum": 0 },
+        "failed": { "type": "integer", "minimum": 0 }
+      }
+    }
+  }
+}

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/schemas/mcp-apply-result.schema.json

@@ -0,0 +1,46 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "Peaks MCP Apply Result",
+  "type": "object",
+  "required": ["capabilityId", "action", "backup", "written", "envCheck"],
+  "properties": {
+    "capabilityId": { "type": "string", "minLength": 1 },
+    "action": {
+      "type": "string",
+      "enum": ["add", "update", "claimed", "noop"],
+      "description": "claimed is returned when an existing non-peaks-managed entry was overwritten with --claim."
+    },
+    "backup": {
+      "type": "object",
+      "required": ["path", "skipped"],
+      "properties": {
+        "path": {
+          "oneOf": [
+            { "type": "null" },
+            { "type": "string", "minLength": 1 }
+          ],
+          "description": "Absolute path to the backup settings.json copy. Null when no prior settings existed or skipped is true."
+        },
+        "skipped": {
+          "type": "boolean",
+          "description": "True when action was noop and no write occurred."
+        }
+      }
+    },
+    "written": {
+      "type": "object",
+      "required": ["settingsPath", "managedMarkerPath"],
+      "properties": {
+        "settingsPath": { "type": "string", "minLength": 1 },
+        "managedMarkerPath": { "type": "string", "minLength": 1 }
+      }
+    },
+    "envCheck": {
+      "type": "object",
+      "required": ["missing"],
+      "properties": {
+        "missing": { "type": "array", "items": { "type": "string" } }
+      }
+    }
+  }
+}

package/schemas/mcp-install-plan.schema.json

@@ -0,0 +1,71 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "Peaks MCP Install Plan",
+  "type": "object",
+  "required": ["capabilityId", "action", "spec", "current", "envCheck", "diff", "nextActions"],
+  "properties": {
+    "capabilityId": { "type": "string", "minLength": 1 },
+    "action": {
+      "type": "string",
+      "enum": ["add", "update", "noop", "conflict", "unknown-capability"]
+    },
+    "spec": {
+      "oneOf": [
+        { "type": "null" },
+        { "$ref": "mcp-install-spec.schema.json" }
+      ]
+    },
+    "current": {
+      "oneOf": [
+        { "type": "null" },
+        { "$ref": "mcp-server.schema.json" }
+      ]
+    },
+    "envCheck": {
+      "type": "object",
+      "required": ["missing"],
+      "properties": {
+        "missing": {
+          "type": "array",
+          "items": { "type": "string" },
+          "description": "Env var keys that are not set or are empty."
+        }
+      }
+    },
+    "diff": {
+      "oneOf": [
+        { "type": "null" },
+        {
+          "type": "object",
+          "properties": {
+            "command": {
+              "type": "object",
+              "required": ["before", "after"],
+              "properties": {
+                "before": { "type": "string" },
+                "after": { "type": "string" }
+              }
+            },
+            "args": {
+              "type": "object",
+              "required": ["before", "after"],
+              "properties": {
+                "before": { "type": "array", "items": { "type": "string" } },
+                "after": { "type": "array", "items": { "type": "string" } }
+              }
+            },
+            "envKeys": {
+              "type": "object",
+              "required": ["before", "after"],
+              "properties": {
+                "before": { "type": "array", "items": { "type": "string" } },
+                "after": { "type": "array", "items": { "type": "string" } }
+              }
+            }
+          }
+        }
+      ]
+    },
+    "nextActions": { "type": "array", "items": { "type": "string" } }
+  }
+}

package/schemas/mcp-install-spec.schema.json

@@ -0,0 +1,29 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "Peaks MCP Install Spec",
+  "type": "object",
+  "required": ["capabilityId", "name", "scope", "command", "args", "envKeys"],
+  "properties": {
+    "capabilityId": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Capability id from the Peaks capability map (e.g. context7.docs-lookup)."
+    },
+    "name": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Server key written into .claude/settings.json mcpServers."
+    },
+    "scope": {
+      "type": "string",
+      "enum": ["global", "project"]
+    },
+    "command": { "type": "string", "minLength": 1 },
+    "args": { "type": "array", "items": { "type": "string" } },
+    "envKeys": {
+      "type": "array",
+      "items": { "type": "string" },
+      "description": "Required env var names. Values are sourced from process.env at runtime and written as ${VAR} placeholders into settings.json."
+    }
+  }
+}

package/schemas/mcp-server.schema.json

@@ -0,0 +1,29 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "Peaks MCP Server Config",
+  "type": "object",
+  "required": ["name", "command", "args", "envKeys", "source", "scope"],
+  "properties": {
+    "name": { "type": "string", "minLength": 1 },
+    "command": { "type": "string", "minLength": 1 },
+    "args": { "type": "array", "items": { "type": "string" } },
+    "envKeys": {
+      "type": "array",
+      "items": { "type": "string" },
+      "description": "Names of env vars referenced by the server config. Values are never stored here."
+    },
+    "source": {
+      "type": "string",
+      "enum": ["peaks", "cc-switch", "user", "plugin", "unknown"]
+    },
+    "scope": {
+      "type": "string",
+      "enum": ["global", "project", "plugin"]
+    },
+    "pluginName": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Plugin id (e.g. playwright@claude-plugins-official) when source is plugin."
+    }
+  }
+}