wavework 0.0.0-stage → 0.1.0

package/src/cli/sync.mjs

@@ -0,0 +1,269 @@
+import { createHash } from 'node:crypto';
+import {
+  chmodSync, lstatSync, mkdirSync, readFileSync, renameSync, rmdirSync, unlinkSync, writeFileSync,
+} from 'node:fs';
+import { basename, dirname, join, resolve, sep } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { buildContext } from '../context.mjs';
+import { render } from '../render.mjs';
+import { safeResolve } from './safe-path.mjs';
+import { mergeHooks, parseHookDefs } from './hooks.mjs';
+
+export const LOCK_PATH = 'wavework.lock.json';
+export const SETTINGS_PATH = 'settings.json';
+export const NEW_SUFFIX = '.wavework-new';
+export const PACKAGE_TEMPLATES = fileURLToPath(new URL('../../templates/', import.meta.url));
+const LOCK_FORMAT = 1;
+
+export const sha256 = (data) => createHash('sha256').update(data).digest('hex');
+const isObject = (v) => v !== null && typeof v === 'object' && !Array.isArray(v);
+
+/** Optional features whose hooks (`features.<name>` in hooks.json) the config switches on. */
+export const enabledFeatures = (config) => (config.dashboard?.enabled ? ['dashboard'] : []);
+
+/** Hook definitions: injected object, or templates/settings/hooks.json of the package; feature hooks only when the config enables them. */
+export function loadHookDefs(injected, config) {
+  const json = injected ?? JSON.parse(readFileSync(join(PACKAGE_TEMPLATES, 'settings', 'hooks.json'), 'utf8'));
+  return parseHookDefs(json, config ? enabledFeatures(config) : []);
+}
+
+/** The default target provider is src/targets.mjs, imported lazily so init/update can be tested without it. */
+export async function defaultTargets() {
+  try {
+    return (await import('../targets.mjs')).templateTargets;
+  } catch (e) {
+    if (e.code === 'ERR_MODULE_NOT_FOUND' && /targets\.mjs/.test(e.message)) {
+      throw new Error('this wavework installation is missing src/targets.mjs');
+    }
+    throw e;
+  }
+}
+
+const TARGET_PREFIX = '.claude/';
+const TMP_SUFFIX = '.wavework-tmp';
+
+/** `<file>.wavework-new` and the temp files are wavework's own; no target or lock entry may use those names. */
+function refuseInternalSuffix(rel) {
+  if (rel.endsWith(NEW_SUFFIX) || rel.endsWith(TMP_SUFFIX)) {
+    throw new Error(`unsafe path ${JSON.stringify(rel)}: names ending in ${NEW_SUFFIX} or ${TMP_SUFFIX} are reserved`);
+  }
+}
+
+/**
+ * Renders every target. Does not touch `.claude/`. The provider's `target` is relative to the repo root
+ * and must start with `.claude/`; it is stored (lock, reports) relative to `.claude/`. `vars` are merged
+ * over buildContext(config) (src/targets.mjs contract); `verbatim: true` skips rendering.
+ * @returns {{ target: string, content: string, hash: string, mode: number }[]}
+ */
+export function renderTargets(config, provider, templatesDir, repoName) {
+  const seen = new Set();
+  const root = resolve(templatesDir);
+  const context = buildContext(config, { repoName });
+  return provider(config).map((t) => {
+    if (typeof t?.template !== 'string' || typeof t?.target !== 'string') throw new Error('invalid target definition (template and target must be strings)');
+    if (!t.target.startsWith(TARGET_PREFIX)) throw new Error(`unsafe path ${JSON.stringify(t.target)}: targets must be inside ${TARGET_PREFIX}`);
+    const target = t.target.slice(TARGET_PREFIX.length);
+    refuseInternalSuffix(target);
+    if (seen.has(target.toLowerCase())) throw new Error(`duplicate target ${JSON.stringify(t.target)} (names are compared case-insensitively)`);
+    seen.add(target.toLowerCase());
+    const file = resolve(root, t.template);
+    if (!file.startsWith(root + sep)) throw new Error(`unsafe template path ${JSON.stringify(t.template)}`);
+    // `verbatim` targets (the dashboard runtime) are copied byte for byte: they are JavaScript and CSS, not templates.
+    const text = readFileSync(file, 'utf8');
+    const content = t.verbatim === true ? text : render(text, { ...context, ...(t.vars ?? {}) }, t.template);
+    return { target, content, hash: sha256(content), mode: t.mode ?? 0o644 };
+  });
+}
+
+/**
+ * Reads and validates the lock. Every path in it is checked like a template target: a tampered lock
+ * must not make update touch anything outside `.claude/`.
+ * @returns {{ version: string, files: Record<string, string>, hooks: { event: string, entry: object }[] } | null} null when absent
+ */
+export function readLock(claudeDir) {
+  const file = safeResolve(claudeDir, LOCK_PATH, { allowReserved: true });
+  let text;
+  try {
+    text = readFileSync(file, 'utf8');
+  } catch (e) {
+    if (e.code === 'ENOENT') return null;
+    throw new Error(`cannot read lock file ${file}: ${e.message}`);
+  }
+  const bad = (why) => new Error(`invalid lock file ${file}: ${why}`);
+  let lock;
+  try {
+    lock = JSON.parse(text);
+  } catch (e) {
+    throw bad(`not valid JSON (${e.message})`);
+  }
+  if (!isObject(lock)) throw bad('expected an object');
+  if (lock.lockVersion !== LOCK_FORMAT) throw bad(`unsupported lockVersion ${JSON.stringify(lock.lockVersion)}`);
+  if (typeof lock.version !== 'string') throw bad('"version" must be a string');
+  if (!isObject(lock.files)) throw bad('"files" must be an object');
+  for (const [rel, hash] of Object.entries(lock.files)) {
+    if (typeof hash !== 'string' || !/^[0-9a-f]{64}$/.test(hash)) throw bad(`files.${rel}: expected a sha256 hex digest`);
+    try {
+      refuseInternalSuffix(rel);
+      safeResolve(claudeDir, rel);
+    } catch (e) {
+      throw bad(e.message);
+    }
+  }
+  if (!Array.isArray(lock.hooks)) throw bad('"hooks" must be an array');
+  lock.hooks.forEach((h, i) => {
+    if (!isObject(h) || typeof h.event !== 'string' || !isObject(h.entry)) throw bad(`hooks[${i}]: expected { event, entry }`);
+  });
+  return lock;
+}
+
+/** sha256 of the regular file at `abs`, undefined when missing. */
+function diskHash(abs, rel) {
+  let st;
+  try {
+    st = lstatSync(abs);
+  } catch (e) {
+    if (e.code === 'ENOENT') return undefined;
+    throw e;
+  }
+  if (!st.isFile()) throw new Error(`${rel} exists but is not a regular file`);
+  return sha256(readFileSync(abs));
+}
+
+/**
+ * Decides what to do for every file and for settings.json. Reads, never writes.
+ * Throws on any unsafe path or invalid input, so a failing plan leaves the repo untouched.
+ *
+ * @param {object} p
+ * @param {string} p.claudeDir
+ * @param {ReturnType<typeof renderTargets>} p.rendered
+ * @param {{ files: Record<string, string>, hooks: object[] }} p.lock `{ files: {}, hooks: [] }` for init
+ * @param {{ event: string, entry: object }[]} p.defs
+ */
+export function plan({ claudeDir, rendered, lock, defs }) {
+  const actions = [];
+  const files = {};
+  const wanted = new Set(rendered.map((t) => t.target));
+
+  for (const t of rendered) {
+    const abs = safeResolve(claudeDir, t.target);
+    const disk = diskHash(abs, t.target);
+    const locked = lock.files[t.target];
+    const write = (kind) => { actions.push({ kind, target: t.target, abs, content: t.content, mode: t.mode }); files[t.target] = t.hash; };
+    if (disk === undefined) {
+      write(locked === undefined ? 'create' : 'restore');
+    } else if (disk === t.hash) {
+      files[t.target] = t.hash; // already what we would write: adopt
+      if ((lstatSync(abs).mode & 0o111) !== (t.mode & 0o111)) actions.push({ kind: 'mode', target: t.target, abs, mode: t.mode });
+    } else if (locked !== undefined && disk === locked) {
+      write('update'); // untouched since the last run
+    } else {
+      // Edited locally (or an unknown file sits there). The old lock hash stays, so it is reported until resolved.
+      if (locked !== undefined) files[t.target] = locked;
+      if (locked !== undefined && t.hash === locked) continue; // nothing new upstream, nothing to merge
+      const newAbs = safeResolve(claudeDir, `${t.target}${NEW_SUFFIX}`);
+      actions.push({ kind: 'review', target: t.target, newTarget: `${t.target}${NEW_SUFFIX}`, newAbs, content: t.content });
+    }
+  }
+
+  for (const [rel, locked] of Object.entries(lock.files)) {
+    if (wanted.has(rel)) continue;
+    const abs = safeResolve(claudeDir, rel);
+    const disk = diskHash(abs, rel);
+    if (disk === undefined) continue; // gone already
+    if (disk === locked) {
+      actions.push({ kind: 'delete', target: rel, abs });
+    } else {
+      files[rel] = locked;
+      actions.push({ kind: 'review-removed', target: rel });
+    }
+  }
+
+  const settingsAbs = safeResolve(claudeDir, SETTINGS_PATH, { allowReserved: true });
+  let current = {};
+  let existed = true;
+  try {
+    const text = readFileSync(settingsAbs, 'utf8');
+    try {
+      current = JSON.parse(text);
+    } catch (e) {
+      throw new Error(`${settingsAbs} is not valid JSON (${e.message}); fix it or remove it, nothing was changed`);
+    }
+    if (!isObject(current)) throw new Error(`${settingsAbs}: expected a JSON object`);
+  } catch (e) {
+    if (e.code !== 'ENOENT') throw e;
+    existed = false;
+  }
+  const merged = mergeHooks(current, defs, lock.hooks);
+  const notes = merged.lost.map((h) => `hook ${h.event}: owned entry changed locally, not re-added`);
+  const changed = JSON.stringify(merged.settings) !== JSON.stringify(current) || (!existed && Object.keys(merged.settings).length > 0);
+  if (changed) actions.push({ kind: 'settings', abs: settingsAbs, content: `${JSON.stringify(merged.settings, null, 2)}\n` });
+
+  return { actions, notes, files, hooks: merged.owned, review: actions.filter((a) => a.kind.startsWith('review')).length };
+}
+
+/** Writes via a temp file and rename, so a symlink that appeared meanwhile is replaced, never written through. */
+function writeAtomic(abs, content, mode) {
+  mkdirSync(dirname(abs), { recursive: true });
+  const tmp = join(dirname(abs), `.${basename(abs)}${TMP_SUFFIX}`);
+  try {
+    unlinkSync(tmp);
+  } catch (e) {
+    if (e.code !== 'ENOENT') throw e;
+  }
+  writeFileSync(tmp, content, { flag: 'wx', mode });
+  chmodSync(tmp, mode);
+  renameSync(tmp, abs);
+}
+
+function pruneEmptyDirs(claudeDir, from) {
+  let dir = dirname(from);
+  while (dir.startsWith(resolve(claudeDir) + sep)) {
+    try {
+      rmdirSync(dir);
+    } catch {
+      return; // not empty (or gone): stop
+    }
+    dir = dirname(dir);
+  }
+}
+
+/** Executes a plan and writes the lock last. */
+export function apply(claudeDir, result, version) {
+  for (const a of result.actions) {
+    if (a.kind === 'create' || a.kind === 'update' || a.kind === 'restore') writeAtomic(a.abs, a.content, a.mode);
+    else if (a.kind === 'mode') chmodSync(a.abs, a.mode);
+    else if (a.kind === 'review') writeAtomic(a.newAbs, a.content, 0o644);
+    else if (a.kind === 'delete') {
+      unlinkSync(a.abs);
+      pruneEmptyDirs(claudeDir, a.abs);
+    } else if (a.kind === 'settings') writeAtomic(a.abs, a.content, 0o644);
+  }
+  const files = Object.fromEntries(Object.entries(result.files).sort(([a], [b]) => (a < b ? -1 : 1)));
+  const lock = { lockVersion: LOCK_FORMAT, version, files, hooks: result.hooks };
+  writeAtomic(safeResolve(claudeDir, LOCK_PATH, { allowReserved: true }), `${JSON.stringify(lock, null, 2)}\n`, 0o644);
+}
+
+const LABEL = {
+  create: 'create ', update: 'update ', restore: 'restore', delete: 'delete ', settings: 'update ', mode: 'mode   ',
+};
+
+/** Prints one short line per change; returns the exit code (2 when files need review). */
+export function report(result, stdout, { dryRun, done }) {
+  const prefix = dryRun ? 'dry-run: ' : '';
+  const counts = {};
+  for (const a of result.actions) {
+    counts[a.kind] = (counts[a.kind] ?? 0) + 1;
+    if (a.kind === 'review') {
+      stdout.write(`${prefix}review  ${a.target}: edited locally, kept; new version in ${a.newTarget}\n`);
+    } else if (a.kind === 'review-removed') {
+      stdout.write(`${prefix}review  ${a.target}: removed upstream but edited locally, kept\n`);
+    } else {
+      stdout.write(`${prefix}${LABEL[a.kind]} ${a.kind === 'settings' ? 'settings.json (hooks)' : a.target}\n`);
+    }
+  }
+  for (const note of result.notes) stdout.write(`${prefix}${note}\n`);
+  if (result.review > 0) stdout.write(`${prefix}${result.review} file(s) edited locally need review: merge the .wavework-new files, then delete them\n`);
+  if (result.actions.length === 0 && result.notes.length === 0) stdout.write(`${prefix}nothing to do\n`);
+  else if (!dryRun) stdout.write(`${done}\n`);
+  return result.review > 0 ? 2 : 0;
+}

package/src/cli/update.mjs

@@ -0,0 +1,24 @@
+import { basename, join, resolve } from 'node:path';
+import { loadConfig } from '../config.mjs';
+import {
+  apply, defaultTargets, loadHookDefs, PACKAGE_TEMPLATES, plan, readLock, renderTargets, report,
+} from './sync.mjs';
+
+/**
+ * `wavework update [--dry-run]`: re-renders with the installed version and the current config and
+ * syncs `.claude/` per the lock (see docs/lock.md). Never modifies `.claude/wavework.json`.
+ *
+ * @returns {Promise<number>} exit code
+ */
+export async function update(args, ctx) {
+  const claudeDir = join(ctx.cwd, '.claude');
+  const lock = readLock(claudeDir);
+  if (!lock) throw new Error('no .claude/wavework.lock.json: run `wavework init` first');
+  const config = loadConfig(ctx.cwd);
+  const provider = ctx.targets ?? await defaultTargets();
+  const rendered = renderTargets(config, provider, ctx.templatesDir ?? PACKAGE_TEMPLATES, basename(resolve(ctx.cwd)));
+  const result = plan({ claudeDir, rendered, lock, defs: loadHookDefs(ctx.hooks, config) });
+  const dryRun = args['--dry-run'] === true;
+  if (!dryRun) apply(claudeDir, result, ctx.version);
+  return report(result, ctx.stdout, { dryRun, done: `wavework ${ctx.version}: updated .claude/` });
+}

package/src/cli.mjs

@@ -0,0 +1,78 @@
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { init } from './cli/init.mjs';
+import { update } from './cli/update.mjs';
+import { dashboard } from './cli/dashboard.mjs';
+import { parseArgs, UsageError } from './cli/args.mjs';
+
+const pkg = JSON.parse(
+  readFileSync(fileURLToPath(new URL('../package.json', import.meta.url)), 'utf8'),
+);
+
+export const USAGE = `Usage: wavework <command> [options]
+
+Commands:
+  init        Set up .claude/ in the current repository   [--config <file>] [--dry-run]
+  update      Re-render .claude/ from the installed version [--dry-run]
+  dashboard   Start the pipeline dashboard of this repository (installed by init)
+
+Options:
+  -v, --version   Print the version
+  -h, --help      Print this help
+`;
+
+const COMMANDS = {
+  init: { run: init, options: { '--config': 'value', '--dry-run': 'flag' } },
+  update: { run: update, options: { '--dry-run': 'flag' } },
+  dashboard: { run: dashboard, options: {} },
+};
+
+/**
+ * Runs the CLI with the given arguments (without node and script path).
+ * Writes to the provided streams and returns the exit code; does not exit the process.
+ * Exit codes: 0 ok, 1 error, 2 done, but locally edited files need review.
+ *
+ * `io.cwd` (default: process.cwd()) is the repository root. `io.targets`, `io.templatesDir` and `io.hooks`
+ * replace the packaged target list, templates directory and hook definitions; `io.env` and `io.spawn` replace the
+ * environment and child_process.spawn of `dashboard` (tests).
+ *
+ * @param {string[]} argv
+ * @param {{ stdout: { write(s: string): unknown }, stderr: { write(s: string): unknown }, cwd?: string, targets?: Function, templatesDir?: string, hooks?: object }} io
+ * @returns {Promise<number>}
+ */
+export async function run(argv, io) {
+  const { stdout, stderr } = io;
+  const [command, ...rest] = argv;
+
+  if (command === undefined || command === '--help' || command === '-h') {
+    stdout.write(USAGE);
+    return 0;
+  }
+  if (command === '--version' || command === '-v') {
+    stdout.write(`${pkg.version}\n`);
+    return 0;
+  }
+
+  const spec = Object.hasOwn(COMMANDS, command) ? COMMANDS[command] : undefined;
+  if (!spec) {
+    stderr.write(`wavework: unknown command: ${command}\n\n${USAGE}`);
+    return 1;
+  }
+  try {
+    const args = parseArgs(rest, spec.options);
+    return await spec.run(args, {
+      cwd: io.cwd ?? process.cwd(),
+      stdout,
+      version: pkg.version,
+      targets: io.targets,
+      templatesDir: io.templatesDir,
+      hooks: io.hooks,
+      env: io.env,
+      spawn: io.spawn,
+    });
+  } catch (e) {
+    if (e instanceof UsageError) stderr.write(`wavework ${command}: ${e.message}\n\n${USAGE}`);
+    else stderr.write(`wavework ${command}: ${e.message}\n`);
+    return 1;
+  }
+}

package/src/config.mjs

@@ -0,0 +1,313 @@
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+/** Location of the config file, relative to the repository root. */
+export const CONFIG_PATH = '.claude/wavework.json';
+
+/** Defaults for every optional field with a default. Never mutated; results get deep copies. */
+export const DEFAULTS = Object.freeze({
+  worktree: Object.freeze({
+    pathPattern: '../{repo}-{unit}',
+    branchPattern: '{prefix}/{unit}-{slug}',
+  }),
+  models: Object.freeze({
+    planning: 'opus',
+    orchestration: 'opus',
+    implementers: Object.freeze({
+      default: 'sonnet',
+      rules: Object.freeze({
+        haiku: 'Small, well-specified, low-risk changes: boilerplate, renames, config tweaks, docs, straightforward tests.',
+        sonnet: 'Everything else: multi-file features, non-trivial logic, debugging, refactors. When unsure, use sonnet.',
+      }),
+    }),
+  }),
+  tracker: Object.freeze({ kind: 'beads' }),
+  findings: Object.freeze({
+    epicTitles: Object.freeze({
+      security: 'Findings: Security & authorization',
+      bugs: 'Findings: Bugs & correctness',
+      tests: 'Findings: Tests & CI stability',
+      quality: 'Findings: Code quality, UI & docs',
+    }),
+  }),
+  attribution: Object.freeze({ allowAiTrailer: false }),
+  dashboard: Object.freeze({ enabled: true, port: 4690 }),
+});
+
+const PATH_PLACEHOLDERS = ['repo', 'unit'];
+const BRANCH_PLACEHOLDERS = ['prefix', 'unit', 'slug'];
+const TRACKER_KINDS = ['beads'];
+
+const clone = (v) => structuredClone(v);
+
+function typeName(v) {
+  if (v === null) return 'null';
+  if (Array.isArray(v)) return 'array';
+  return typeof v;
+}
+
+const isObject = (v) => typeName(v) === 'object';
+const join_ = (base, key) => (base ? `${base}.${key}` : key);
+
+// Each helper returns the validated value (or undefined when invalid/absent) and pushes problems.
+
+function str(v, path, errs) {
+  if (typeof v === 'string' && v.trim() !== '') return v;
+  errs.push(`${path}: expected a non-empty string, got ${typeName(v)}`);
+  return undefined;
+}
+
+function bool(v, path, errs) {
+  if (typeof v === 'boolean') return v;
+  errs.push(`${path}: expected a boolean, got ${typeName(v)}`);
+  return undefined;
+}
+
+function strArray(v, path, errs, { minItems = 0, item = str } = {}) {
+  if (!Array.isArray(v)) {
+    errs.push(`${path}: expected an array, got ${typeName(v)}`);
+    return undefined;
+  }
+  if (v.length < minItems) errs.push(`${path}: must contain at least ${minItems} item(s)`);
+  return v.map((entry, i) => item(entry, `${path}[${i}]`, errs));
+}
+
+function port(v, path, errs) {
+  if (Number.isInteger(v) && v >= 1024 && v <= 65535) return v;
+  errs.push(`${path}: expected an integer from 1024 to 65535, got ${JSON.stringify(v)}`);
+  return undefined;
+}
+
+/** Path prefix relative to the repo root: no leading slash, no `..` segments, no `.` segments; `.` alone means the whole repo. */
+function relativePrefix(v, path, errs) {
+  if (str(v, path, errs) === undefined) return undefined;
+  if (v.startsWith('/')) errs.push(`${path}: must be relative to the repo root (no leading /)`);
+  const segments = v.split(/[\\/]/);
+  if (segments.includes('..')) errs.push(`${path}: must not contain .. segments`);
+  if (v !== '.' && segments.includes('.')) errs.push(`${path}: must not contain "." segments (use "." alone for the whole repo)`);
+  return v;
+}
+
+/** Checks that `v` is an object with only `allowed` keys; returns it or undefined. */
+function obj(v, path, errs, allowed) {
+  if (!isObject(v)) {
+    errs.push(`${path || '(root)'}: expected an object, got ${typeName(v)}`);
+    return undefined;
+  }
+  for (const key of Object.keys(v)) {
+    if (!allowed.includes(key)) errs.push(`${join_(path, key)}: unknown key (allowed: ${allowed.join(', ')})`);
+  }
+  return v;
+}
+
+function pattern(v, path, errs, allowed) {
+  if (str(v, path, errs) === undefined) return undefined;
+  for (const [, name] of v.matchAll(/\{([^{}]*)\}/g)) {
+    if (!allowed.includes(name)) {
+      errs.push(`${path}: unknown placeholder {${name}} (allowed: ${allowed.map((p) => `{${p}}`).join(', ')})`);
+    }
+  }
+  if (/[{}]/.test(v.replace(/\{[^{}]*\}/g, ''))) errs.push(`${path}: unbalanced or stray brace`);
+  if (!v.includes('{unit}')) errs.push(`${path}: must contain {unit}`);
+  return v;
+}
+
+/** Reads `key` of `o`: calls `check` when present, otherwise the default (or "required" error). */
+function field(o, key, path, errs, check, { fallback, required = false } = {}) {
+  if (!(key in o)) {
+    if (required) errs.push(`${join_(path, key)}: required`);
+    return fallback === undefined ? undefined : clone(fallback);
+  }
+  const value = check(o[key], join_(path, key), errs);
+  return value === undefined ? fallback && clone(fallback) : value;
+}
+
+function stringMap(v, path, errs) {
+  if (!obj(v, path, errs, Object.keys(v ?? {}))) return undefined;
+  const out = {};
+  for (const [k, val] of Object.entries(v)) {
+    if (k === '__proto__') {
+      errs.push(`${path}.${k}: reserved key`);
+      continue;
+    }
+    out[k] = str(val, `${path}.${k}`, errs);
+  }
+  return out;
+}
+
+function worktree(v, path, errs) {
+  if (!obj(v, path, errs, ['pathPattern', 'branchPattern'])) return undefined;
+  return {
+    pathPattern: field(v, 'pathPattern', path, errs, (x, p, e) => pattern(x, p, e, PATH_PLACEHOLDERS), { fallback: DEFAULTS.worktree.pathPattern }),
+    branchPattern: field(v, 'branchPattern', path, errs, (x, p, e) => pattern(x, p, e, BRANCH_PLACEHOLDERS), { fallback: DEFAULTS.worktree.branchPattern }),
+  };
+}
+
+function area(v, path, errs) {
+  const keys = ['name', 'dir', 'whenPaths', 'focused', 'full', 'lint', 'build', 'e2e'];
+  if (!obj(v, path, errs, keys)) return undefined;
+  const out = {
+    name: field(v, 'name', path, errs, str, { required: true }),
+    dir: field(v, 'dir', path, errs, relativePrefix, { required: true }),
+    whenPaths: field(v, 'whenPaths', path, errs, (x, p, e) => strArray(x, p, e, { minItems: 1, item: relativePrefix }), { required: true }),
+    focused: field(v, 'focused', path, errs, str, { required: true }),
+    full: field(v, 'full', path, errs, str, { required: true }),
+  };
+  for (const optional of ['lint', 'build', 'e2e']) {
+    if (optional in v) out[optional] = str(v[optional], join_(path, optional), errs);
+  }
+  return out;
+}
+
+function checks(v, path, errs) {
+  if (!Array.isArray(v)) {
+    errs.push(`${path}: expected an array, got ${typeName(v)}`);
+    return undefined;
+  }
+  if (v.length === 0) errs.push(`${path}: must contain at least one area`);
+  const seen = new Set();
+  return v.map((item, i) => {
+    const result = area(item, `${path}[${i}]`, errs);
+    if (result?.name !== undefined) {
+      if (seen.has(result.name)) errs.push(`${path}[${i}].name: duplicate area name "${result.name}"`);
+      seen.add(result.name);
+    }
+    return result;
+  });
+}
+
+function models(v, path, errs) {
+  if (!obj(v, path, errs, ['planning', 'orchestration', 'implementers'])) return undefined;
+  const impl = (x, p, e) => {
+    if (!obj(x, p, e, ['default', 'rules'])) return undefined;
+    return {
+      default: field(x, 'default', p, e, str, { fallback: DEFAULTS.models.implementers.default }),
+      rules: field(x, 'rules', p, e, stringMap, { fallback: DEFAULTS.models.implementers.rules }),
+    };
+  };
+  return {
+    planning: field(v, 'planning', path, errs, str, { fallback: DEFAULTS.models.planning }),
+    orchestration: field(v, 'orchestration', path, errs, str, { fallback: DEFAULTS.models.orchestration }),
+    implementers: field(v, 'implementers', path, errs, impl, { fallback: DEFAULTS.models.implementers }),
+  };
+}
+
+function tracker(v, path, errs) {
+  if (!obj(v, path, errs, ['kind'])) return undefined;
+  const kind = field(v, 'kind', path, errs, (x, p, e) => {
+    if (TRACKER_KINDS.includes(x)) return x;
+    e.push(`${p}: must be ${TRACKER_KINDS.map((k) => `"${k}"`).join(' or ')}, got ${JSON.stringify(x)}`);
+    return undefined;
+  }, { fallback: DEFAULTS.tracker.kind });
+  return { kind };
+}
+
+function codeMap(v, path, errs) {
+  if (!obj(v, path, errs, ['path'])) return undefined;
+  return { path: field(v, 'path', path, errs, relativePrefix, { required: true }) };
+}
+
+function uiSkill(v, path, errs) {
+  if (!obj(v, path, errs, ['name', 'appliesTo'])) return undefined;
+  return {
+    name: field(v, 'name', path, errs, str, { required: true }),
+    appliesTo: field(v, 'appliesTo', path, errs, (x, p, e) => strArray(x, p, e, { minItems: 1, item: relativePrefix }), { required: true }),
+  };
+}
+
+function findings(v, path, errs) {
+  if (!obj(v, path, errs, ['epicTitles'])) return undefined;
+  const titles = field(v, 'epicTitles', path, errs, stringMap);
+  // User-given titles override the defaults per category; other categories keep their default.
+  return { epicTitles: { ...clone(DEFAULTS.findings.epicTitles), ...(titles ?? {}) } };
+}
+
+function attribution(v, path, errs) {
+  if (!obj(v, path, errs, ['allowAiTrailer'])) return undefined;
+  return {
+    allowAiTrailer: field(v, 'allowAiTrailer', path, errs, bool, { fallback: DEFAULTS.attribution.allowAiTrailer }),
+  };
+}
+
+function tokensFile(v, path, errs) {
+  if (relativePrefix(v, path, errs) === undefined) return undefined;
+  if (v.includes('\\')) errs.push(`${path}: must not contain a backslash`);
+  if (!v.endsWith('.css')) errs.push(`${path}: must end in .css`);
+  return v;
+}
+
+function dashboard(v, path, errs) {
+  if (!obj(v, path, errs, ['enabled', 'port', 'tokensFile'])) return undefined;
+  const out = {
+    enabled: field(v, 'enabled', path, errs, bool, { fallback: DEFAULTS.dashboard.enabled }),
+    port: field(v, 'port', path, errs, port, { fallback: DEFAULTS.dashboard.port }),
+  };
+  if ('tokensFile' in v) out.tokensFile = tokensFile(v.tokensFile, join_(path, 'tokensFile'), errs);
+  return out;
+}
+
+const TOP_LEVEL = ['baseBranch', 'worktree', 'checks', 'models', 'tracker', 'codeMap', 'uiSkill', 'findings', 'attribution', 'dashboard'];
+
+/**
+ * Validates a parsed wavework config and fills defaults. Pure: does not touch the file system.
+ * Throws one Error listing every problem as `<json.path>: <reason>`.
+ *
+ * @param {unknown} raw parsed JSON
+ * @returns {object} the config with defaults filled in
+ */
+export function validateConfig(raw) {
+  return validate(raw, undefined);
+}
+
+/** Shared by validateConfig and loadConfig; `file` only decorates the error message. */
+function validate(raw, file) {
+  const errs = [];
+  if (!obj(raw, '', errs, TOP_LEVEL)) throw configError(errs, file);
+
+  const config = {
+    baseBranch: field(raw, 'baseBranch', '', errs, str, { required: true }),
+    worktree: field(raw, 'worktree', '', errs, worktree, { fallback: DEFAULTS.worktree }),
+    checks: field(raw, 'checks', '', errs, checks, { required: true }),
+    models: field(raw, 'models', '', errs, models, { fallback: DEFAULTS.models }),
+    tracker: field(raw, 'tracker', '', errs, tracker, { fallback: DEFAULTS.tracker }),
+    findings: field(raw, 'findings', '', errs, findings, { fallback: { epicTitles: DEFAULTS.findings.epicTitles } }),
+    attribution: field(raw, 'attribution', '', errs, attribution, { fallback: DEFAULTS.attribution }),
+    dashboard: field(raw, 'dashboard', '', errs, dashboard, { fallback: DEFAULTS.dashboard }),
+  };
+  for (const [key, check] of [['codeMap', codeMap], ['uiSkill', uiSkill]]) {
+    if (key in raw) config[key] = check(raw[key], key, errs);
+  }
+
+  if (errs.length > 0) throw configError(errs, file);
+  return config;
+}
+
+function configError(errs, file) {
+  const where = file ? ` in ${file}` : '';
+  const noun = errs.length === 1 ? 'problem' : 'problems';
+  return new Error(`invalid wavework config${where} (${errs.length} ${noun}):\n${errs.map((e) => `  - ${e}`).join('\n')}`);
+}
+
+/**
+ * Loads and validates `<repoRoot>/.claude/wavework.json`.
+ *
+ * @param {string} repoRoot
+ * @returns {object} validated config with defaults
+ */
+export function loadConfig(repoRoot) {
+  const file = join(repoRoot, CONFIG_PATH);
+  let text;
+  try {
+    text = readFileSync(file, 'utf8');
+  } catch (e) {
+    if (e.code === 'ENOENT') throw new Error(`wavework config not found: ${file}`);
+    throw new Error(`cannot read wavework config ${file}: ${e.message}`);
+  }
+  let raw;
+  try {
+    raw = JSON.parse(text);
+  } catch (e) {
+    throw new Error(`wavework config is not valid JSON: ${file}: ${e.message}`);
+  }
+  return validate(raw, file);
+}