contextdevkit 1.8.0

package/templates/contextkit/runtime/config/defaults.mjs

@@ -0,0 +1,215 @@
+/**
+ * Built-in default configuration for ContextDevKit — STACK-AGNOSTIC.
+ *
+ * This object is the fallback whenever `contextkit/config.json` is missing,
+ * malformed, or only partially overrides the tree. It carries ZERO runtime
+ * dependencies (no zod) so the Level 1–3 hooks work in a brand-new project
+ * with nothing installed. Level 5 validation (`/context-config`) layers an
+ * optional zod schema on top — see `schema.mjs`.
+ *
+ * The defaults intentionally describe a *generic* repository (`src/`, `lib/`,
+ * `app/`, `packages/`, ...). The installer tunes these per detected stack and
+ * the user refines them with `/context-config`.
+ */
+
+/**
+ * `level` (1–7) gates which subsystems are active. 1–5 add Claude hooks; 6–7 are
+ * capability tiers (no new hook — commands/tooling on top of the L5 gates):
+ *   1 Memory      — boot context + session log + ADRs + changelog
+ *   2 Ledger      — drift detection (PostToolUse + Stop nudge)
+ *   3 Multi       — claims, worktrees, derived indices, git hooks
+ *   4 Squads      — specialized sub-agents
+ *   5 Proactive   — simulate-impact gate, tech-debt sweep, contract drift
+ *   6 Autonomy    — /ship pipeline, /retro, metrics (capability tier)
+ *   7 Ecosystem   — fleet (multi-repo), agent-tuning, visual tests, playbooks,
+ *                   token/cost insight, security automation (capability tier)
+ */
+export const DEFAULT_CONFIG = Object.freeze({
+  level: 2,
+
+  /**
+   * First-run onboarding state. The installer writes `completed: false` into a
+   * fresh project's config so the SessionStart hook fires the `/setupcontextdevkit`
+   * trigger on the first session. `/setupcontextdevkit` flips it to `true` when
+   * onboarding finishes. The DEFAULT is `true` so a missing/corrupt config never
+   * nags — only an installer-written `false` triggers the banner.
+   */
+  setup: { completed: true },
+
+  /** Best-practices skill (contextkit/best-practices.md). When active, boot reminds + /analyze-code-ia-practices is encouraged. */
+  practices: { active: false },
+
+  /**
+   * Behavioral discipline (contextkit/behaviors.md, ADR-0029) — how the agent ACTS
+   * while coding: think-before-coding (surface assumptions / ask when ambiguous),
+   * simplicity-first, surgical changes, goal-driven (reproduce-test first). When
+   * `active`, the SessionStart hook reminds you each session. ON by default — it's
+   * universal, cheap, and the constitution §8 already states it.
+   */
+  behaviors: { active: true },
+
+  /**
+   * Path classification for the L2 ledger. Override per stack via config.
+   *   - `important`: an edit here can trigger the Stop drift nudge.
+   *   - `irrelevant`: never tracked (build output, caches, runtime state).
+   *   - `registration`: an edit here counts AS registering the session.
+   */
+  ledger: {
+    important: [
+      'src/',
+      'lib/',
+      'app/',
+      'apps/',
+      'packages/',
+      'components/',
+      'pages/',
+      'server/',
+      'contextkit/',
+      '.claude/',
+      '.github/',
+      'CLAUDE.md',
+      'package.json',
+      'tsconfig.json',
+      'pyproject.toml',
+      'go.mod',
+      'Cargo.toml',
+    ],
+    irrelevant: [
+      'node_modules/',
+      'dist/',
+      'build/',
+      'out/',
+      '.next/',
+      '.turbo/',
+      '.expo/',
+      '.svelte-kit/',
+      'coverage/',
+      '__pycache__/',
+      'target/',
+      'vendor/',
+      '.context-snapshot.md',
+      '.claude/.sessions/',
+      '.claude/.workspace/',
+    ],
+    registration: ['contextkit/memory/SESSIONS.md', 'docs/CHANGELOG.md'],
+  },
+
+  /** L3 — Multi-session. `mainBranch` is the upstream the pre-push conflict check compares against. */
+  l3: { mainBranch: 'main' },
+
+  /**
+   * QA squad config (used by /test-plan, /scaffold-tests, /qa-signoff and the
+   * qa-* agents at Level >= 4). `criticalPaths` get the highest coverage
+   * priority; `coverageTarget` is the floor a sign-off aims for.
+   */
+  qa: {
+    criticalPaths: [],
+    coverageTarget: { lines: 80, branches: 70 },
+  },
+
+  /**
+   * DevPipeline prioritization (WSJF / SAFe) + bug severity + SLA + WIP eviction.
+   *   - `wsjfBands`: WSJF score ≥ value → priority (P0/P1/P2, else P3).
+   *   - `severityPriority`: ITIL bug severity S1–S4 → priority.
+   *   - `slaDays`: resolution target (days) per priority → the task's SLA due date.
+   *   - `bugTypes`: the bug taxonomy used to classify bug tasks.
+   *   - `workingStaleAfterMinutes`: ADR-0015 §B — a task auto-evicts from `working/`
+   *     back to `backlog/` when its owning session is silent past this threshold.
+   */
+  pipeline: {
+    framework: 'wsjf',
+    wsjfBands: { p0: 8, p1: 5, p2: 2 },
+    severityPriority: { S1: 'P0', S2: 'P1', S3: 'P2', S4: 'P3' },
+    slaDays: { P0: 1, P1: 3, P2: 14, P3: 60 },
+    bugTypes: ['functional', 'regression', 'security', 'performance', 'data', 'integration', 'ui', 'build', 'flaky', 'other'],
+    workingStaleAfterMinutes: 90,
+  },
+
+  /**
+   * Security mode — proactive analysis cadence. When `active`, the SessionStart
+   * hook reminds you to run `/deep-analysis` every `everyNSessions` sessions.
+   * ACTIVE by default; set `active: false` to disable.
+   */
+  securityMode: { active: true, everyNSessions: 10 },
+
+  /**
+   * Token economy & usage insight (L6). `/token-report` reads Claude Code's local
+   * session transcripts (`~/.claude/projects/…`) and aggregates token usage for this
+   * project — advisory, read-only, aggregated counts only.
+   *   - `budgetPerSession`: total tokens/session that triggers a ⚠️ warning (0 = off).
+   *   - `warnAtPct`: warn once a session reaches this % of the budget.
+   */
+  tokens: { budgetPerSession: 0, warnAtPct: 80 },
+
+  /**
+   * Predictions-review cadence (L5/L6). When `active`, the SessionStart hook reminds you
+   * to run `/predictions-review` every `everyNSessions` sessions — but ONLY when there are
+   * unreviewed `/simulate-impact` predictions, so it stays silent otherwise.
+   */
+  predictionsReview: { active: true, everyNSessions: 10 },
+
+  /**
+   * Proactive Advisor (L6, ADR-0028) — the six-lane improvement engine. When
+   * `active`, `/advise` fans out to the owning agent per lane and emits ONE
+   * classified digest (`--before` = opportunities/risks, `--after` = improvements)
+   * whose findings flow into the DevPipeline backlog. `nudgeOnStop` makes the Stop
+   * hook suggest `/advise` after a productive session (≥ 2 important paths touched,
+   * debounced 24h). Each lane is `{ owner }` — the agent/command that owns it, or
+   * `null` to mute a lane. All six ship with an owner; a muted lane is reported as
+   * *skipped*, never faked (rule 8/9). `growth` is the growth-team lead (pairs with
+   * `retention` + `seo-specialist` for acquisition); `deepen` is product-owner's
+   * depth lens (maturing existing features, distinct from greenfield `features`).
+   */
+  advisor: {
+    active: true,
+    nudgeOnStop: true,
+    lanes: {
+      architecture: { owner: 'architect' },
+      features: { owner: 'product-owner' },
+      deepen: { owner: 'product-owner' },
+      security: { owner: 'security' },
+      ux: { owner: 'ux-designer' },
+      growth: { owner: 'growth' },
+    },
+  },
+
+  /**
+   * Dependency policy for `/deps-audit` (security-team). All advisory — findings
+   * flow into the DevPipeline backlog, they don't block by default.
+   *   - `requireLockfile`: flag a manifest with deps but no committed lockfile.
+   *   - `licenses.allow`: if non-empty, a dependency whose license is NOT listed
+   *     is flagged (allow-list mode). SPDX ids, case-insensitive.
+   *   - `licenses.deny`: a dependency whose license IS listed is always flagged.
+   *   - `maxAgeDays`: reserved for registry-backed staleness (not enforced yet).
+   */
+  deps: {
+    requireLockfile: true,
+    licenses: { allow: [], deny: ['GPL-3.0', 'AGPL-3.0'] },
+    maxAgeDays: null,
+  },
+
+  /** L5 — Proactive Engineering. Inert unless `level >= 5`. */
+  l5: {
+    /** Editing any of these without a prior `/simulate-impact` is gated.
+     *  agent-packages/** is included by default — swapping a forged agent's primary
+     *  model is high blast radius (ADR-0012 + Fase 5). Remove if you don't ship agents. */
+    highRiskPaths: ['agent-packages/**'],
+    /** Line-budget thresholds used by the tech-debt scanner. */
+    lineBudget: { yellow: 240, red: 308 },
+    /** Files whose exported symbols form the public contract (drift gate). Empty = off. */
+    contractGlobs: [],
+    /** Auto-distill cadence (CLAUDE.md self-refinement loop). */
+    distill: {
+      observeWindow: 10,
+      proposeAfterSessions: 30,
+      archiveLedgersOlderThanDays: 7,
+    },
+    techDebtSweep: {
+      default: 'full',
+      profiles: {
+        full: { cadenceDays: 14, scope: 'all' },
+        quick: { cadenceDays: 3, scope: 'red-zone-only' },
+      },
+    },
+  },
+});

package/templates/contextkit/runtime/config/levels.mjs

@@ -0,0 +1,42 @@
+/**
+ * Canonical level taxonomy — the SINGLE source of truth for ContextDevKit's
+ * activation levels. Every place that names a level range or label imports from
+ * here so they can never drift: `getLevel` (load.mjs), the optional config
+ * schema (schema.mjs), the installer labels (tools/install/cli.mjs) and the
+ * in-project `/context-level` helper. Zero third-party deps (hot-path safe).
+ *
+ * Levels 1–5 add Claude hooks; 6–7 are capability tiers (no new hook — commands
+ * and tooling layered on the L5 gates). See ADR-0010.
+ */
+
+/** Lowest selectable level. */
+export const MIN_LEVEL = 1;
+
+/** Highest selectable level. Bump this (and add a LEVEL_LABELS entry) to add a tier. */
+export const MAX_LEVEL = 7;
+
+/**
+ * Human-readable label per level — the ONE table. The installer and `/context-level`
+ * both render from this; keep the wording here and nowhere else.
+ */
+export const LEVEL_LABELS = {
+  1: 'L1 Memory — boot context, session log, ADRs, changelog',
+  2: 'L2 Ledger — + drift detection (PostToolUse + Stop nudge)',
+  3: 'L3 Multi — + claims, worktrees, derived indices, git hooks (recommended for a NEW/empty project)',
+  4: 'L4 Squads — + specialized sub-agents (.claude/agents)',
+  5: 'L5 Proactive — + simulate-impact gate, tech-debt sweep, contract drift',
+  6: 'L6 Autonomy & Insight — + /ship pipeline, /retro learning loop, metrics',
+  7: 'L7 Ecosystem & Scale — + fleet (multi-repo), agent-tuning, visual tests, playbooks, token/cost insight (recommended for an EXISTING project with code)',
+};
+
+/** True when `n` is an integer within the valid level range. */
+export function isValidLevel(n) {
+  return Number.isInteger(n) && n >= MIN_LEVEL && n <= MAX_LEVEL;
+}
+
+/** Clamps any number into the valid level range (rounds non-integers). */
+export function clampLevel(n) {
+  const i = Math.round(Number(n));
+  if (!Number.isFinite(i)) return MIN_LEVEL;
+  return Math.min(MAX_LEVEL, Math.max(MIN_LEVEL, i));
+}

package/templates/contextkit/runtime/config/load.mjs

@@ -0,0 +1,105 @@
+/**
+ * Zero-dependency config loader for ContextDevKit.
+ *
+ * Contract:
+ *   - `loadConfig()` / `loadConfigSync()` MUST NEVER throw. Hooks depend on
+ *     them and a broken config file cannot be allowed to block real work.
+ *     On any failure they log to stderr and return the deep-merged defaults.
+ *   - No third-party deps. JSON.parse + a small recursive merge only. This is
+ *     what lets Levels 1–3 run in a project that has installed nothing.
+ *   - Strict validation (zod) is OPTIONAL and lives in `schema.mjs`, used
+ *     solely by `/context-config`. It is never imported on a hook path.
+ */
+import { existsSync, readFileSync } from 'node:fs';
+import { readFile, writeFile } from 'node:fs/promises';
+import { resolve } from 'node:path';
+import { DEFAULT_CONFIG } from './defaults.mjs';
+import { isValidLevel } from './levels.mjs';
+import { CONFIG_FILE } from './paths.mjs';
+
+export function configPathFor(root = process.cwd()) {
+  return resolve(root, CONFIG_FILE);
+}
+
+/**
+ * Deep-merges a partial override onto a base object. Arrays REPLACE (so a
+ * project can fully redefine `ledger.important`), objects merge recursively.
+ *
+ * @param {Record<string, any>} base
+ * @param {Record<string, any>} override
+ */
+function deepMerge(base, override) {
+  if (!override || typeof override !== 'object') return base;
+  const out = Array.isArray(base) ? [...base] : { ...base };
+  for (const [key, value] of Object.entries(override)) {
+    if (
+      value &&
+      typeof value === 'object' &&
+      !Array.isArray(value) &&
+      out[key] &&
+      typeof out[key] === 'object' &&
+      !Array.isArray(out[key])
+    ) {
+      out[key] = deepMerge(out[key], value);
+    } else {
+      out[key] = value;
+    }
+  }
+  return out;
+}
+
+function parseRaw(buf, path) {
+  try {
+    // Strip a leading UTF-8 BOM — common when a file is written by a Windows
+    // editor or PowerShell's `Set-Content -Encoding utf8` (PS 5.1 adds one).
+    return JSON.parse(buf.replace(/^/, ''));
+  } catch (err) {
+    process.stderr.write(`[context-config] malformed JSON in ${path} — using defaults: ${err?.message ?? err}\n`);
+    return null;
+  }
+}
+
+/** Async load + deep-merge over defaults. Never throws. */
+export async function loadConfig(root = process.cwd()) {
+  const path = configPathFor(root);
+  let buf;
+  try {
+    buf = await readFile(path, 'utf-8');
+  } catch {
+    return structuredClone(DEFAULT_CONFIG);
+  }
+  const raw = parseRaw(buf, path);
+  if (raw === null) return structuredClone(DEFAULT_CONFIG);
+  return deepMerge(structuredClone(DEFAULT_CONFIG), raw);
+}
+
+/** Synchronous variant for hooks that cannot await. Never throws. */
+export function loadConfigSync(root = process.cwd()) {
+  const path = configPathFor(root);
+  if (!existsSync(path)) return structuredClone(DEFAULT_CONFIG);
+  let buf;
+  try {
+    buf = readFileSync(path, 'utf-8');
+  } catch {
+    return structuredClone(DEFAULT_CONFIG);
+  }
+  const raw = parseRaw(buf, path);
+  if (raw === null) return structuredClone(DEFAULT_CONFIG);
+  return deepMerge(structuredClone(DEFAULT_CONFIG), raw);
+}
+
+/** Reads only the active level (MIN_LEVEL..MAX_LEVEL). Defensive — defaults to 2. */
+export function getLevel(root = process.cwd()) {
+  const lvl = Number(loadConfigSync(root)?.level);
+  return isValidLevel(lvl) ? lvl : 2;
+}
+
+/**
+ * Persists a config object. Used by `/context-config set`. NOT defensive by
+ * design — surfaces write errors so the slash command can report them.
+ */
+export async function writeConfig(candidate, root = process.cwd()) {
+  const payload = `${JSON.stringify(candidate, null, 2)}\n`;
+  await writeFile(configPathFor(root), payload, 'utf-8');
+  return candidate;
+}

package/templates/contextkit/runtime/config/paths.mjs

@@ -0,0 +1,92 @@
+/**
+ * Canonical path constants for the ContextDevKit platform.
+ *
+ * Single source of truth so every hook, script and slash command agrees on
+ * where memory artifacts live. `.claude/` is fixed by Claude Code (it reads
+ * settings/commands/agents from hardcoded locations). Everything else lives
+ * under `contextkit/` — the rebrandable platform bounded context.
+ *
+ * To rebrand the platform folder (e.g. back to `devAItools/`), change
+ * `PLATFORM_DIR` here and run the installer's `--rewire` step. Nothing else
+ * references the literal folder name.
+ */
+import { resolve } from 'node:path';
+
+/** Platform bounded-context folder (everything except `.claude/`). */
+export const PLATFORM_DIR = 'contextkit';
+
+/** Memory root — ADRs, sessions, glossary, indices. */
+export const MEMORY_DIR = `${PLATFORM_DIR}/memory`;
+
+/** One markdown file per work session. */
+export const SESSIONS_DIR = `${MEMORY_DIR}/sessions`;
+
+/** Auto-generated reverse-chronological index of sessions. */
+export const SESSIONS_INDEX = `${MEMORY_DIR}/SESSIONS.md`;
+
+/** Auto-generated aggregate of active workspace claims. */
+export const WORKSPACE_INDEX = `${MEMORY_DIR}/WORKSPACE.md`;
+
+/** Architecture Decision Records (immutable once accepted). */
+export const DECISIONS_DIR = `${MEMORY_DIR}/decisions`;
+
+/** Domain glossary — UI/business term ↔ code identifier. */
+export const GLOSSARY = `${MEMORY_DIR}/GLOSSARY.md`;
+
+/** L5 prediction artifacts (Blast Radius Reports). */
+export const PREDICTIONS_DIR = `${MEMORY_DIR}/predictions`;
+
+/** Factual release chronology (Keep a Changelog format). */
+export const CHANGELOG = 'docs/CHANGELOG.md';
+
+/** Platform config (level, ledger overrides, L5 params). */
+export const CONFIG_FILE = `${PLATFORM_DIR}/config.json`;
+
+/** Per-session ledger files (gitignored runtime state). */
+export const LEDGER_DIR = '.claude/.sessions';
+
+/** Per-session workspace claim files (gitignored runtime state). */
+export const WORKSPACE_STATE_DIR = '.claude/.workspace';
+
+/** On-demand full-project snapshot (gitignored). */
+export const CONTEXT_SNAPSHOT = '.context-snapshot.md';
+
+/**
+ * Resolves every canonical location to an ABSOLUTE path under `root`. This is the
+ * single helper scripts/hooks use instead of hardcoding `resolve(ROOT, 'contextkit/…')`
+ * literals — so the platform folder name lives only in `PLATFORM_DIR` (immutable
+ * rule 4). One-off files under memory use `resolve(p.memory, '<name>')`.
+ *
+ * @param {string} [root] project root (default cwd)
+ */
+export function pathsFor(root = process.cwd()) {
+  const at = (rel) => resolve(root, rel);
+  return {
+    root,
+    platform: at(PLATFORM_DIR),
+    memory: at(MEMORY_DIR),
+    sessions: at(SESSIONS_DIR),
+    sessionsIndex: at(SESSIONS_INDEX),
+    workspaceIndex: at(WORKSPACE_INDEX),
+    decisions: at(DECISIONS_DIR),
+    glossary: at(GLOSSARY),
+    predictions: at(PREDICTIONS_DIR),
+    changelog: at(CHANGELOG),
+    config: at(CONFIG_FILE),
+    ledgerDir: at(LEDGER_DIR),
+    workspaceStateDir: at(WORKSPACE_STATE_DIR),
+    contextSnapshot: at(CONTEXT_SNAPSHOT),
+    pipeline: at(`${PLATFORM_DIR}/pipeline`),
+    runtime: at(`${PLATFORM_DIR}/runtime`),
+    tools: at(`${PLATFORM_DIR}/tools`),
+    scripts: at(`${PLATFORM_DIR}/tools/scripts`),
+    squads: at(`${PLATFORM_DIR}/squads`),
+    workflows: at(`${PLATFORM_DIR}/workflows`),
+    playbooks: at(`${PLATFORM_DIR}/workflows/playbooks`),
+    detectors: at(`${PLATFORM_DIR}/detectors`),
+    businessRules: at(`${MEMORY_DIR}/business-rules`),
+    roadmap: at(`${MEMORY_DIR}/roadmap.md`),
+    contractBaseline: at(`${MEMORY_DIR}/contract-baseline.json`),
+    bestPractices: at(`${PLATFORM_DIR}/best-practices.md`),
+  };
+}

package/templates/contextkit/runtime/config/presets.mjs

@@ -0,0 +1,47 @@
+/**
+ * Stack presets — opt-in config fragments that tune ContextDevKit to a stack.
+ *
+ * Applied by `install.mjs --preset <name>` (and offered by `/setupcontextdevkit`).
+ * Each preset UNIONS its array fields onto the config (stack paths ADD to the
+ * generic defaults, they don't replace them) and sets stack-specific high-risk /
+ * QA-critical paths. Zero-dependency.
+ */
+export const PRESETS = {
+  next: {
+    ledger: { important: ['app/', 'components/', 'lib/', 'pages/', 'src/'] },
+    l5: { highRiskPaths: ['app/api/', 'middleware.ts'] },
+    qa: { criticalPaths: ['app/', 'components/'] },
+  },
+  go: {
+    ledger: { important: ['cmd/', 'internal/', 'pkg/'] },
+    l5: { highRiskPaths: ['internal/auth/'] },
+    qa: { criticalPaths: ['internal/', 'pkg/'] },
+  },
+  python: {
+    ledger: { important: ['src/', 'app/', 'tests/'] },
+    l5: { highRiskPaths: ['*/auth/', '*/security/'] },
+    qa: { criticalPaths: ['src/'] },
+  },
+};
+
+export function listPresets() {
+  return Object.keys(PRESETS);
+}
+
+const uniq = (arr) => [...new Set(arr)];
+
+/**
+ * Returns a NEW config with the named preset merged in (array fields unioned).
+ * Unknown name → the config is returned unchanged. Every preset field is read
+ * with optional chaining so a partial/custom preset that omits `ledger`, `l5`,
+ * or `qa` merges what it has instead of crashing on `undefined.field`.
+ */
+export function applyPreset(config, name) {
+  const preset = PRESETS[name];
+  if (!preset) return config;
+  const cfg = { ...config };
+  cfg.ledger = { ...(cfg.ledger || {}), important: uniq([...(cfg.ledger?.important || []), ...(preset.ledger?.important || [])]) };
+  cfg.l5 = { ...(cfg.l5 || {}), highRiskPaths: uniq([...(cfg.l5?.highRiskPaths || []), ...(preset.l5?.highRiskPaths || [])]) };
+  cfg.qa = { ...(cfg.qa || {}), criticalPaths: uniq([...(cfg.qa?.criticalPaths || []), ...(preset.qa?.criticalPaths || [])]) };
+  return cfg;
+}

package/templates/contextkit/runtime/config/schema.mjs

@@ -0,0 +1,88 @@
+/**
+ * OPTIONAL strict config schema (zod) for `/context-config`.
+ *
+ * The hot path (hooks) NEVER imports this — it uses the zero-dependency
+ * loader in `load.mjs`. This module is loaded ONLY by `/context-config` when the
+ * user wants strict validation before persisting an edit, and it degrades
+ * gracefully when `zod` is not installed (the slash command catches the import
+ * error and falls back to structural checks).
+ *
+ * Install `zod` in the target project to enable strict validation:
+ *   npm i -D zod   (or pnpm/yarn/bun equivalent)
+ */
+import { z } from 'zod';
+import { MAX_LEVEL, MIN_LEVEL } from './levels.mjs';
+
+const PathString = z
+  .string()
+  .min(1, 'path must not be empty')
+  .refine((p) => !p.startsWith('/') && !p.includes('\\'), {
+    message: 'use forward-slashed, repo-relative paths (no leading /, no backslashes)',
+  });
+
+const Profile = z.object({
+  cadenceDays: z.number().int().positive(),
+  scope: z.string().min(1),
+});
+
+const LedgerSchema = z
+  .object({
+    important: z.array(PathString).min(1),
+    irrelevant: z.array(PathString),
+    registration: z.array(PathString),
+  })
+  .partial()
+  .default({});
+
+const L5Schema = z
+  .object({
+    highRiskPaths: z.array(PathString).default([]),
+    distill: z
+      .object({
+        observeWindow: z.number().int().positive().default(10),
+        proposeAfterSessions: z.number().int().positive().default(30),
+        archiveLedgersOlderThanDays: z.number().int().positive().default(7),
+      })
+      .default({}),
+    techDebtSweep: z
+      .object({ default: z.string().min(1), profiles: z.record(z.string(), Profile) })
+      .default({ default: 'full', profiles: { full: { cadenceDays: 14, scope: 'all' } } }),
+  })
+  .default({});
+
+const DepsSchema = z
+  .object({
+    requireLockfile: z.boolean().default(true),
+    licenses: z
+      .object({ allow: z.array(z.string()).default([]), deny: z.array(z.string()).default([]) })
+      .default({}),
+    maxAgeDays: z.number().int().positive().nullable().default(null),
+  })
+  .default({});
+
+// `.passthrough()` keeps every section the defaults define (qa, pipeline,
+// securityMode, tokens, predictionsReview, l3, setup, practices, …) instead of
+// silently dropping the ones not modelled here — the alternative to re-declaring
+// the whole config tree in zod. The level bound is single-sourced from
+// levels.mjs so it can never drift from getLevel again. See ADR-0010.
+export const ConfigSchema = z
+  .object({
+    level: z.number().int().min(MIN_LEVEL).max(MAX_LEVEL).default(2),
+    ledger: LedgerSchema,
+    l5: L5Schema,
+    deps: DepsSchema,
+  })
+  .passthrough()
+  .default({});
+
+export function validateConfig(raw) {
+  const parsed = ConfigSchema.safeParse(raw ?? {});
+  if (parsed.success) return { ok: true, config: parsed.data };
+  return { ok: false, error: parsed.error };
+}
+
+export function formatZodError(error) {
+  return error.issues
+    .map((i) => `  - ${i.path.length ? i.path.join('.') : '(root)'}: ${i.message}`)
+    .join('\n');
+}

package/templates/contextkit/runtime/config/settings-compose.mjs

@@ -0,0 +1,55 @@
+/**
+ * Composes `.claude/settings.json` hook wiring for a given activation level.
+ *
+ * Shared by the installer (`install.mjs`) and the in-project `/context-level`
+ * helper so they can never drift. It preserves the user's own hooks and
+ * top-level keys, stripping only previously-installed ContextDevKit entries
+ * (so re-running at a lower level cleanly removes now-disabled hooks).
+ *
+ * Level → hooks:
+ *   1  SessionStart
+ *   2  + PostToolUse (Edit|Write|MultiEdit), Stop
+ *   3  + PreToolUse  (concurrency-guard) — and git hooks (installed separately)
+ *   5  + PreToolUse  (simulate-gate)
+ * (Level 4 adds agents — not Claude hooks.)
+ *
+ * @param {Record<string, any> | null} existing parsed settings.json (or null)
+ * @param {number} level 1–7
+ * @returns {Record<string, any>}
+ */
+export function composeSettings(existing, level) {
+  const settings = existing && typeof existing === 'object' ? existing : {};
+  if (!settings['$schema']) settings['$schema'] = 'https://json.schemastore.org/claude-code-settings.json';
+  const hooks = settings.hooks && typeof settings.hooks === 'object' ? settings.hooks : {};
+
+  for (const evt of ['SessionStart', 'PostToolUse', 'Stop', 'PreToolUse']) {
+    if (!Array.isArray(hooks[evt])) continue;
+    hooks[evt] = hooks[evt]
+      .map((g) => ({ ...g, hooks: (g.hooks || []).filter((h) => !String(h.command || '').includes('contextkit/runtime/hooks')) }))
+      .filter((g) => (g.hooks || []).length > 0);
+    if (hooks[evt].length === 0) delete hooks[evt];
+  }
+
+  const add = (evt, matcher, script) => {
+    const entry = { hooks: [{ type: 'command', command: `node contextkit/runtime/hooks/${script}` }] };
+    if (matcher) entry.matcher = matcher;
+    (hooks[evt] = hooks[evt] || []).push(entry);
+  };
+
+  // Status-line widget (level >= 1). Preserve a user's own statusLine — only set
+  // or replace a previously-installed ContextDevKit one.
+  if (level >= 1 && (!settings.statusLine || String(settings.statusLine.command || '').includes('contextkit/runtime/statusline'))) {
+    settings.statusLine = { type: 'command', command: 'node contextkit/runtime/statusline.mjs', padding: 0 };
+  }
+
+  if (level >= 1) add('SessionStart', null, 'session-start.mjs');
+  if (level >= 2) {
+    add('PostToolUse', 'Edit|Write|MultiEdit', 'track-edits.mjs');
+    add('Stop', null, 'check-registration.mjs');
+  }
+  if (level >= 3) add('PreToolUse', 'Edit|Write|MultiEdit', 'concurrency-guard.mjs');
+  if (level >= 5) add('PreToolUse', 'Edit|Write|MultiEdit', 'simulate-gate.mjs');
+
+  settings.hooks = hooks;
+  return settings;
+}