wavework 0.0.0-stage → 0.1.1

package/CHANGELOG.md

@@ -0,0 +1,34 @@
+# Changelog
+
+All notable changes to this project are documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.1] - 2026-11-13
+
+### Added
+
+- `wavework init --adopt` for repositories that already have hand-written pipeline files: existing files with identical content are kept and locked, differing files are kept untouched with the rendered version written to `<file>.wavework-new` and listed with a short `+N -M` line diff summary, missing files are created, and a script whose content matches but whose exec bit is wrong gets the bit fixed. The lock records the rendered hash for every target, so `update` keeps reporting unresolved files (exit code 2) until you merge and delete the `.wavework-new` file or make the file equal to the rendered one. `--adopt` needs `.claude/wavework.json` or `--config` (no starter config for adoption), refuses an existing lock, supports `--dry-run`, and applies the same path safety as `init`.
+
+### Changed
+
+- `update` reports a file whose `.wavework-new` still exists even when upstream did not change since the last run, so unresolved review files no longer go silent, and it fails closed (exit 1, nothing written) when a symlink sits at a `.wavework-new` path.
+
+## [0.1.0] - 2026-11-13
+
+### Added
+
+- Package skeleton: `wavework` CLI with `--version` and `--help`, test setup with `node:test`, and CI on Node 22 and 24.
+- Config: `src/config.mjs` validates and loads `.claude/wavework.json` (defaults, unknown-key rejection, errors as `<json.path>: <reason>`), documented in `docs/config.md` with Shipir's values as `examples/shipir.wavework.json`.
+- Skill templates: the 14 `next-task*` skills as `templates/skills/<name>/SKILL.md`, rendered by `src/render.mjs` (`{{var}}`, `{{#if}}`/`{{else}}`) from `src/context.mjs`; golden test against Shipir's skills with reviewed differences in `docs/porting.md`.
+- Agent, skill and script templates: the implementer agents (one file per implementer model), the `text-to-task` and `watch-ci` skills and `red-green-check.sh` with its test; `src/targets.mjs` maps every template to its `.claude/` target. `red-green-check.sh` needs only bash, git and node, discovers Maven and Vitest tests and prints `SKIP <area>: unsupported` for other areas.
+- `wavework init` and `wavework update`: render the templates into `.claude/`, record a sha256 lock (`docs/lock.md`), keep locally edited files and write `<file>.wavework-new`, restore lost exec bits, merge hooks into `.claude/settings.json` without touching foreign entries, `--dry-run`, exit code 2 when files need review. Every path stays inside `.claude/` (no `..`, absolute paths or symlinks, also for a tampered lock). Config path fields (`checks[].dir`, `whenPaths`, `codeMap.path`, `uiSkill.appliesTo`) must be repo-relative; `.` means the whole repo.
+- Pipeline dashboard: `init`/`update` install the recorder, hooks, server and UI into `.claude/wavework/dashboard/` (committed, works in worktrees without `node_modules`) and register its `SessionStart`/`SubagentStop` hooks while `dashboard.enabled`; `dashboard.port` and `dashboard.tokensFile` in the config; `wavework dashboard` starts the server; the skills' `Record:` lines follow the config; neutral default theme; disabling removes its hooks and unedited runtime files on `update` (`docs/dashboard.md`).
+- README: install, daily use, configuration, upgrading, dashboard and a sourced comparison with Sous Factory. `scripts/smoke.sh` runs the README commands against the packed package in CI (`smoke` job), and `test/readme.test.mjs` fails when a README command has no smoke step or test.
+
+[Unreleased]: https://github.com/csSTK/wavework/compare/v0.1.1...HEAD
+[0.1.1]: https://github.com/csSTK/wavework/releases/tag/v0.1.1
+[0.1.0]: https://github.com/csSTK/wavework/releases/tag/v0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Paul Bethge
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,145 @@
-# Temporary Holding Version
+# wavework
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+wavework is a versioned Claude Code pipeline for repositories that use [beads](https://github.com/steveyegge/beads) (`bd`) for task tracking. It installs the `/next-task*` skills, implementer agents and helper scripts into `.claude/` of your repository and keeps them up to date with a lock file.
+
+The pipeline works like this:
+
+- **Waves of parallel sub-agents.** An epic's tasks are planned into waves; each task is implemented by a sub-agent, and each run works in its own git worktree.
+- **Independent review.** A fresh, read-only sub-agent reviews every task's diff against the bead's acceptance criteria and the project's rules.
+- **Red before green.** Tests are written first, and `red-green-check.sh` checks that new tests fail on the old code.
+- **Findings backlog.** Problems found outside a task's scope are filed as beads under a few standing epics, so they can be run later with the same pipeline.
+
+**Status: 0.1.0, first release. Expect changes before 1.0.** The commands below describe the CLI as released.
+
+## Requirements
+
+- Node.js 22 or newer (npm)
+- git
+- [beads](https://github.com/steveyegge/beads) (`bd`), with the repository set up for it
+- [Claude Code](https://claude.com/claude-code)
+- bash (for `red-green-check.sh`)
+- [GitHub CLI](https://cli.github.com) (`gh`), only for `/watch-ci`
+
+## Install
+
+From the root of a git repository:
+
+```bash
+npm i -D wavework
+npx wavework --version
+npx wavework init
+```
+
+Without `--config`, `init` writes a starter config: `baseBranch` comes from `origin/HEAD`, and the one check runs `npm test` when `package.json` has a `test` script; otherwise it is a placeholder that fails until you replace it. Without `--config` and without `origin/HEAD`, `init` exits with code 1 and asks for `--config`. To start from a complete config file instead (never overwritten once it exists):
+
+```bash
+npx wavework init --config <file>
+```
+
+To adopt a repository that already has hand-written pipeline files (it never overwrites them):
+
+```bash
+npx wavework init --adopt --dry-run --config <file>
+npx wavework init --adopt --config <file>
+```
+
+For each file `init` would write that already exists: identical content is kept and locked; different content is kept untouched and the rendered version is written to `<file>.wavework-new`, listed with a short `+N -M` line summary (diff it yourself: `diff <file> <file>.wavework-new`; a file with CRLF line endings against the LF rendered version shows every line as changed); missing files are created. `--dry-run` prints this plan and writes nothing. Exit code 0 when everything matched or was created, 2 when files differ. `--adopt` needs `.claude/wavework.json` or `--config <file>` (a starter config would be a guess, so every rendered file would differ) and refuses when a lock exists. Afterwards `npx wavework update` keeps reporting the differing files until you merge them and delete the `.wavework-new` files, or make the file equal to the rendered one. See [docs/lock.md](docs/lock.md).
+
+`init` writes:
+
+- `.claude/skills/`: the 16 skills (`next-task`, `next-task-*`, `text-to-task`, `watch-ci`)
+- `.claude/agents/implementer-<model>.md`: one implementer agent per model in the config (the default config gives `implementer-sonnet` and `implementer-haiku`)
+- `.claude/scripts/red-green-check.sh` and its test
+- `.claude/wavework/dashboard/`: the pipeline dashboard (with `dashboard.enabled`, the default)
+- `.claude/settings.json`: the dashboard's two hooks, merged into your settings without touching other entries
+- `.claude/wavework.json`: your configuration (never overwritten)
+- `.claude/wavework.lock.json`: the hashes of what wavework wrote (see [docs/lock.md](docs/lock.md))
+
+Commit `.claude/`, including the lock file and the dashboard runtime. Each run works in a git worktree, which has no `node_modules`, so the committed files are what the skills run.
+
+## Daily use
+
+Start these from Claude Code:
+
+- `/next-task <epic-id>`: implements a whole beads epic end to end and pushes it to the base branch.
+- `/next-task-beads <id> [<id> ...]`: the same for individual beads (tasks, bugs, chores, findings), without an epic.
+- `/next-task-batch <epic-id> <epic-id> ...`: runs `/next-task` for several epics one after another, ordered by their dependencies, and watches CI once at the end.
+- `/text-to-task`: turns a free-text feature request into an epic with child tasks, asking questions first when the request is too vague.
+- `/watch-ci`: reports the GitHub Actions result for the current commit, branch or run, read-only.
+
+The other `next-task-*` skills are steps that these commands use; you do not start them directly.
+
+## Configuration
+
+The configuration is `.claude/wavework.json`. It names the base branch, the test commands of each area of the codebase and the model per role. The required fields are `baseBranch` and `checks`:
+
+```json
+{
+  "baseBranch": "main",
+  "checks": [
+    { "name": "app", "dir": ".", "whenPaths": ["src/"], "focused": "npm test", "full": "npm test" }
+  ]
+}
+```
+
+Every field, its default and its validation rules are in [docs/config.md](docs/config.md). A complete example for a multi-area project is [examples/shipir.wavework.json](examples/shipir.wavework.json).
+
+## Upgrading
+
+Upgrade the package, preview the changes, then apply them:
+
+```bash
+npm i -D wavework@latest
+npx wavework update --dry-run
+npx wavework update
+```
+
+`update` re-renders `.claude/` from the installed version and your config. It never changes `.claude/wavework.json`. `--dry-run` prints the plan and writes nothing.
+
+Exit codes:
+
+- `0`: done.
+- `1`: error. The plan is checked before anything is written, so a failing run leaves the repository unchanged.
+- `2`: done, but some files need your review.
+
+A file needs review when you edited it and the new version changed it too. `update` keeps your file and writes the new version next to it as `<file>.wavework-new`. To resolve it, merge what you want into your file, delete the `.wavework-new` file, and make the file either match the new version or hold the old content again. The next `update` then clears the report; until then every `update` reports it and exits with `2`. The rules are in [docs/lock.md](docs/lock.md).
+
+## Dashboard
+
+The pipeline dashboard shows every `/next-task*` run live: steps, waves, sub-agents with model, duration, tokens and estimated cost, reviews, tests and the CI state of the pushed commit. Its `SessionStart` hook starts the server and prints its URL. To run it in the foreground yourself:
+
+```bash
+npx wavework dashboard
+```
+
+It listens on `127.0.0.1` at port 4690 by default (`dashboard.port`). Set `dashboard.enabled` to `false` and run `update` to remove it. Details are in [docs/dashboard.md](docs/dashboard.md).
+
+## Comparison with Sous Factory
+
+[Sous Factory](https://sousfactory.com/) (MIT, npm package `sous-factory`) is another tool for running beads tasks through agents. The wavework author trialled Sous Factory on Shipir, the project wavework was ported from, against Shipir's own `/next-task*` pipeline. The numbers below are copied from that trial's handoff notes (`docs/sous-handoff.md` in Shipir, a private repository, so they are cited by run rather than linked). They measure Shipir's pipeline, not wavework; wavework is a port of that pipeline and has not been measured as a whole.
+
+| Run (source) | Tool | Bead | Wall clock | Agent time | Cost | Review |
+|---|---|---|---|---|---|---|
+| 1 (Run 1, setup 2026-10-24, run date not recorded) | Sous | `shipr-hae` | ~36 min | ~5.5 min | not measured | diff review, then 3 whole-branch rounds |
+| 2 (Run 2, date not recorded) | `/next-task-beads` | `shipr-8qd` | ~5 min | API time 2m28s | $1.34 Sonnet, plus $0.56 for a first attempt on Opus that was refused | 1 round, PASS |
+| 3 (Run 3, 2026-11-13) | Sous 0.8.0 | `shipr-kipv.2` | ~28 min | ~2.5 min | $1.37 | review-full, 1 round |
+
+Most of the wall clock in both Sous runs was the project's full checks (Maven `verify`), not agent work: Run 1 had about 30 of its ~36 minutes in checks ("~30 min was full Maven `verify` after every step"), and Run 3's implement step had 25m15s of checks out of 26m08s (agent 53s), so about 25 of its ~28 minutes. The wall-clock gap therefore mostly reflects when and how often the full checks run, not agent speed. Run 2's source gives no split between checks and agent time. Run 3's cost is listed per step (check-issue $0.45, plan $0.24, implement $0.27, review $0.22, review-full $0.19); Run 2's source gives one total of $1.34 without a per-step breakdown, so whether it includes planning or orchestration is unknown. The handoff's conclusion was to keep the `/next-task*` pipeline and to take over the one thing Sous did better, a check that new tests fail on the old code. wavework ships that check as `red-green-check.sh`.
+
+Limitations of this comparison:
+
+- One run per tool, on different beads of unrecorded size. The numbers are anecdotes, not a benchmark.
+- Sous Run 1 hit a hard-coded `main` branch that cost a stop and a second attempt, and Run 1 was on an earlier Sous version (not recorded). Run 3 used Sous 0.8.0.
+- Run 1 has no cost, so the two tools' costs are compared only for Runs 2 and 3.
+- The review results compare different review designs, and the Run 2 red-before-green check was done by hand afterwards.
+- No neutral party: the same person ran the Sous trial, built the pipeline it was compared with (Shipir's, which wavework was ported from) and made the decision. The project is a Java and React codebase; other repositories would give other numbers.
+
+## Development
+
+`npm test` runs the unit tests (`node:test`, no dependencies). `bash scripts/smoke.sh` packs the package and runs the commands from this README against it in two temporary repositories; CI runs it on Node 22 and 24. The dashboard's server, hooks and UI are tested in `test/dashboard/`; `test/dashboard-cli.test.mjs` covers `wavework dashboard`.
+
+Releases are published to npm by `.github/workflows/publish.yml` when a `v*` tag is pushed, using npm trusted publishing (no npm token). The maintainer steps are in [docs/releasing.md](docs/releasing.md).
+
+## License
+
+MIT. See [LICENSE](LICENSE).

package/bin/wavework.mjs

@@ -0,0 +1,7 @@
+#!/usr/bin/env node
+import { run } from '../src/cli.mjs';
+
+process.exitCode = await run(process.argv.slice(2), {
+  stdout: process.stdout,
+  stderr: process.stderr,
+});

package/examples/shipir.wavework.json

@@ -0,0 +1,54 @@
+{
+  "baseBranch": "dev",
+  "worktree": {
+    "pathPattern": "../{repo}-{unit}",
+    "branchPattern": "{prefix}/{unit}-{slug}"
+  },
+  "checks": [
+    {
+      "name": "backend",
+      "dir": "backend",
+      "whenPaths": ["backend/"],
+      "focused": "./backend/mvnw -f backend/pom.xml test -Dtest='dev.bethge.shipir.<pkg>.**' -Dsurefire.failIfNoSpecifiedTests=false",
+      "full": "./backend/mvnw -f backend/pom.xml verify"
+    },
+    {
+      "name": "frontend",
+      "dir": "frontend",
+      "whenPaths": ["frontend/"],
+      "focused": "pnpm vitest run <changed dirs>",
+      "full": "pnpm lint && pnpm test && pnpm build",
+      "lint": "pnpm lint",
+      "build": "pnpm build",
+      "e2e": "pnpm e2e"
+    }
+  ],
+  "models": {
+    "planning": "opus",
+    "orchestration": "opus",
+    "implementers": {
+      "default": "sonnet",
+      "rules": {
+        "haiku": "Small, well-specified, low-risk changes: boilerplate, renames, simple DTOs or entities, config tweaks, docs, straightforward tests. Never for auth, permissions, remote host access or the audit log.",
+        "sonnet": "Everything else: multi-file features, non-trivial logic, debugging, refactors, concurrency and streaming, and anything touching auth, permissions, remote host access or the audit log. When unsure, use sonnet."
+      }
+    }
+  },
+  "tracker": { "kind": "beads" },
+  "codeMap": { "path": "docs/CODE_MAP.md" },
+  "uiSkill": { "name": "apple-design", "appliesTo": ["frontend/"] },
+  "findings": {
+    "epicTitles": {
+      "security": "Findings: Security & authorization",
+      "bugs": "Findings: Bugs & correctness",
+      "tests": "Findings: Tests & CI stability",
+      "quality": "Findings: Code quality, UI & docs"
+    }
+  },
+  "attribution": { "allowAiTrailer": false },
+  "dashboard": {
+    "enabled": true,
+    "port": 4690,
+    "tokensFile": "frontend/src/shared/styles/tokens.css"
+  }
+}

package/package.json

@@ -1,6 +1,37 @@
 {
   "name": "wavework",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.1",
+  "description": "Versioned Claude Code pipeline for beads repos: waves of parallel sub-agents, independent review, red-before-green, findings backlog.",
+  "type": "module",
+  "bin": {
+    "wavework": "bin/wavework.mjs"
+  },
+  "files": [
+    "bin/",
+    "src/",
+    "templates/",
+    "examples/",
+    "CHANGELOG.md"
+  ],
+  "engines": {
+    "node": ">=22"
+  },
+  "scripts": {
+    "test": "node --test"
+  },
+  "keywords": [
+    "claude-code",
+    "beads",
+    "sub-agents",
+    "pipeline"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/csSTK/wavework.git"
+  },
+  "homepage": "https://github.com/csSTK/wavework#readme",
+  "bugs": {
+    "url": "https://github.com/csSTK/wavework/issues"
+  }
+}

package/src/cli/args.mjs

@@ -0,0 +1,28 @@
+/** A mistake in how the command line was written; the CLI answers with the usage text. */
+export class UsageError extends Error {}
+
+/**
+ * Minimal option parser. `spec` maps option name to 'flag' or 'value'; `--name=value` is accepted too.
+ * Positional arguments are not allowed.
+ *
+ * @param {string[]} argv
+ * @param {Record<string, 'flag' | 'value'>} spec
+ * @returns {Record<string, string | boolean>}
+ */
+export function parseArgs(argv, spec) {
+  const out = {};
+  for (let i = 0; i < argv.length; i++) {
+    const [name, inline] = argv[i].startsWith('--') ? argv[i].split(/=(.*)/s, 2) : [argv[i]];
+    const kind = Object.hasOwn(spec, name) ? spec[name] : undefined;
+    if (kind === undefined) throw new UsageError(`unknown option or argument: ${argv[i]}`);
+    if (kind === 'flag') {
+      if (inline !== undefined) throw new UsageError(`${name} does not take a value`);
+      out[name] = true;
+    } else {
+      const value = inline ?? argv[++i];
+      if (value === undefined || value === '') throw new UsageError(`${name} needs a value`);
+      out[name] = value;
+    }
+  }
+  return out;
+}

package/src/cli/dashboard.mjs

@@ -0,0 +1,41 @@
+import { spawn as nodeSpawn } from 'node:child_process';
+import { statSync } from 'node:fs';
+import { join } from 'node:path';
+import { loadConfig } from '../config.mjs';
+import { safeResolve } from './safe-path.mjs';
+
+/**
+ * `wavework dashboard`: runs this repository's installed dashboard server (`.claude/wavework/dashboard/server.mjs`)
+ * in the foreground until it is stopped. The server is the repo's own copy, versioned with the lock like every
+ * other file, so it needs no node_modules and no installed wavework.
+ *
+ * @param {object} _args
+ * @param {{ cwd: string, env?: object, spawn?: Function }} ctx `spawn` and `env` replace child_process.spawn and process.env (tests)
+ * @returns {Promise<number>} the server's exit code
+ */
+export async function dashboard(_args, ctx) {
+  const claudeDir = join(ctx.cwd, '.claude');
+  const config = loadConfig(ctx.cwd);
+  if (!config.dashboard.enabled) {
+    throw new Error('the dashboard is disabled ("dashboard.enabled": false in .claude/wavework.json); enable it and run `wavework update`');
+  }
+  const server = safeResolve(claudeDir, 'wavework/dashboard/server.mjs');
+  let isFile = false;
+  try { isFile = statSync(server).isFile(); } catch { /* missing */ }
+  if (!isFile) throw new Error('the dashboard is not installed in this repository (.claude/wavework/dashboard/server.mjs is missing); run `wavework update`');
+
+  const env = { ...(ctx.env ?? process.env) };
+  env.PIPELINE_DASHBOARD_PORT ??= String(config.dashboard.port);
+  const child = (ctx.spawn ?? nodeSpawn)(process.execPath, [server], { cwd: ctx.cwd, env, stdio: 'inherit' });
+  const forward = (signal) => () => child.kill?.(signal);
+  const handlers = ctx.spawn ? [] : ['SIGINT', 'SIGTERM'].map((sig) => [sig, forward(sig)]);
+  for (const [sig, fn] of handlers) process.once(sig, fn);
+  try {
+    return await new Promise((resolve, reject) => {
+      child.once('error', reject);
+      child.once('exit', (code, signal) => resolve(code ?? (signal ? 1 : 0)));
+    });
+  } finally {
+    for (const [sig, fn] of handlers) process.removeListener(sig, fn);
+  }
+}

package/src/cli/diff-stat.mjs

@@ -0,0 +1,41 @@
+/** Lines of a text as an array; a trailing newline does not add an empty last line. */
+const lines = (text) => (text === '' ? [] : text.replace(/\n$/, '').split('\n'));
+
+/** Above this many cells the exact LCS is skipped (memory); the stat then counts the middle section as replaced. */
+const MAX_CELLS = 4_000_000;
+
+/**
+ * Short line diff summary between two texts: how many lines the new text adds and the old text removes
+ * (longest-common-subsequence based, dependency-free). A full diff is the user's job.
+ *
+ * @param {string} from existing content
+ * @param {string} to rendered content
+ * @param {{ maxCells?: number }} [options] LCS size cap (tests lower it)
+ * @returns {{ added: number, removed: number, approx?: true, whitespaceOnly?: true }}
+ *   `approx`: over the cap, the numbers are an upper bound. `whitespaceOnly`: texts differ but no line does (trailing newline).
+ */
+export function lineDiffStat(from, to, { maxCells = MAX_CELLS } = {}) {
+  const a = lines(from);
+  const b = lines(to);
+  let start = 0;
+  while (start < a.length && start < b.length && a[start] === b[start]) start++;
+  let endA = a.length;
+  let endB = b.length;
+  while (endA > start && endB > start && a[endA - 1] === b[endB - 1]) { endA--; endB--; }
+  const x = a.slice(start, endA);
+  const y = b.slice(start, endB);
+  if (x.length === 0 && y.length === 0) return from === to ? { added: 0, removed: 0 } : { added: 0, removed: 0, whitespaceOnly: true };
+  if (x.length === 0 || y.length === 0) return { added: y.length, removed: x.length };
+  if (x.length * y.length > maxCells) return { added: y.length, removed: x.length, approx: true };
+
+  let prev = new Uint32Array(y.length + 1);
+  let cur = new Uint32Array(y.length + 1);
+  for (let i = 1; i <= x.length; i++) {
+    for (let j = 1; j <= y.length; j++) {
+      cur[j] = x[i - 1] === y[j - 1] ? prev[j - 1] + 1 : Math.max(prev[j], cur[j - 1]);
+    }
+    [prev, cur] = [cur, prev];
+  }
+  const common = prev[y.length];
+  return { added: y.length - common, removed: x.length - common };
+}

package/src/cli/hooks.mjs

@@ -0,0 +1,109 @@
+/**
+ * Merging of wavework's hook entries into `.claude/settings.json`.
+ *
+ * A definition file has the same shape as the `hooks` key of settings.json:
+ * `{ "hooks": { "<Event>": [ <entry>, ... ] } }`. An entry is one element of an event's array
+ * (usually `{ matcher?, hooks: [...] }`). Ownership is per entry: wavework owns an entry when it is
+ * deep-equal to one it was told to add. Foreign entries are never touched, reordered or removed.
+ */
+
+const isObject = (v) => v !== null && typeof v === 'object' && !Array.isArray(v);
+
+/** JSON with sorted keys, so deep equality ignores key order. */
+function canonical(value) {
+  if (Array.isArray(value)) return `[${value.map(canonical).join(',')}]`;
+  if (isObject(value)) {
+    return `{${Object.keys(value).sort().map((k) => `${JSON.stringify(k)}:${canonical(value[k])}`).join(',')}}`;
+  }
+  return JSON.stringify(value);
+}
+
+const same = (a, b) => canonical(a) === canonical(b);
+
+function eventEntries(hooks, where, defs) {
+  if (!isObject(hooks)) throw new Error(`hook definitions: ${where} must be an object`);
+  for (const [event, entries] of Object.entries(hooks)) {
+    if (!Array.isArray(entries)) throw new Error(`hook definitions: ${where}.${event} must be an array`);
+    entries.forEach((entry, i) => {
+      if (!isObject(entry)) throw new Error(`hook definitions: ${where}.${event}[${i}] must be an object`);
+      defs.push({ event, entry });
+    });
+  }
+}
+
+/**
+ * `hooks` always apply. `features.<name>.hooks` apply only when `<name>` is in `enabled` (the CLI passes the
+ * features the config switches on, e.g. "dashboard"); a disabled feature's entries are simply not defined, so
+ * `mergeHooks` removes them again. Every part is validated, enabled or not.
+ *
+ * @param {unknown} json parsed definition file
+ * @param {string[]} [enabled] names of the enabled features
+ * @returns {{ event: string, entry: object }[]}
+ */
+export function parseHookDefs(json, enabled = []) {
+  if (!isObject(json) || !isObject(json.hooks)) throw new Error('hook definitions: expected an object with a "hooks" object');
+  const defs = [];
+  eventEntries(json.hooks, 'hooks', defs);
+  if (json.features !== undefined) {
+    if (!isObject(json.features)) throw new Error('hook definitions: "features" must be an object');
+    for (const [name, feature] of Object.entries(json.features)) {
+      const featureDefs = [];
+      if (!isObject(feature) || !isObject(feature.hooks)) throw new Error(`hook definitions: features.${name} must be an object with a "hooks" object`);
+      eventEntries(feature.hooks, `features.${name}.hooks`, featureDefs);
+      if (enabled.includes(name)) defs.push(...featureDefs);
+    }
+  }
+  return defs;
+}
+
+/**
+ * Pure. Removes previously owned entries that are no longer defined, adds missing defined ones.
+ *
+ * @param {object} settings parsed settings.json (not mutated)
+ * @param {{ event: string, entry: object }[]} defs entries wavework defines now
+ * @param {{ event: string, entry: object }[]} previouslyOwned from the lock
+ * @returns {{ settings: object, owned: { event: string, entry: object }[], lost: { event: string, entry: object }[] }} `lost`: owned entries not found in settings (changed or removed by the user), not re-added
+ */
+export function mergeHooks(settings, defs, previouslyOwned) {
+  const next = structuredClone(settings);
+  if (next.hooks !== undefined && !isObject(next.hooks)) throw new Error('settings.json: "hooks" must be an object');
+  const hooks = next.hooks;
+  const events = () => next.hooks ?? {};
+  const eventArray = (event) => {
+    const value = events()[event];
+    if (value !== undefined && !Array.isArray(value)) throw new Error(`settings.json: hooks.${event} must be an array`);
+    return value;
+  };
+
+  let removedAny = false;
+  for (const old of previouslyOwned) {
+    if (defs.some((d) => d.event === old.event && same(d.entry, old.entry))) continue;
+    const list = eventArray(old.event);
+    const at = list?.findIndex((e) => same(e, old.entry)) ?? -1;
+    if (at === -1) continue;
+    list.splice(at, 1);
+    removedAny = true;
+    if (list.length === 0) delete next.hooks[old.event];
+  }
+  if (removedAny && hooks && Object.keys(next.hooks).length === 0) delete next.hooks;
+
+  const owned = [];
+  const lost = [];
+  for (const { event, entry } of defs) {
+    let list = eventArray(event);
+    const wasOwned = previouslyOwned.some((o) => o.event === event && same(o.entry, entry));
+    const kept = { event, entry: structuredClone(entry) };
+    if (list?.some((e) => same(e, entry))) {
+      if (wasOwned) owned.push(kept); // an identical entry that was there before us stays foreign
+    } else if (wasOwned) {
+      owned.push(kept); // we added it before, now it is gone or changed by the user: do not add a second copy
+      lost.push(kept);
+    } else {
+      if (next.hooks === undefined) next.hooks = {};
+      list ??= (next.hooks[event] = []);
+      list.push(structuredClone(entry));
+      owned.push(kept);
+    }
+  }
+  return { settings: next, owned, lost };
+}

package/src/cli/init.mjs

@@ -0,0 +1,104 @@
+import { execFileSync } from 'node:child_process';
+import { existsSync, readFileSync } from 'node:fs';
+import { basename, join, resolve } from 'node:path';
+import { loadConfig, validateConfig, CONFIG_PATH } from '../config.mjs';
+import {
+  apply, defaultTargets, loadHookDefs, PACKAGE_TEMPLATES, plan, readLock, renderTargets, report,
+} from './sync.mjs';
+import { safeResolve } from './safe-path.mjs';
+
+/** Default branch from `refs/remotes/origin/HEAD`, or undefined when there is no such ref. */
+function detectBaseBranch(cwd) {
+  try {
+    const ref = execFileSync('git', ['symbolic-ref', '--short', 'refs/remotes/origin/HEAD'], {
+      cwd, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'],
+    }).trim();
+    return ref.replace(/^origin\//, '') || undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * The config has no usable default for `checks`, so a starter config only exists to be edited:
+ * one area whose commands fail loudly until the user fills them in (or `npm test` when package.json has it).
+ */
+function starterConfig(cwd, baseBranch) {
+  let command = 'echo "wavework: set the checks in .claude/wavework.json" >&2; exit 1';
+  try {
+    if (JSON.parse(readFileSync(join(cwd, 'package.json'), 'utf8'))?.scripts?.test) command = 'npm test';
+  } catch { /* no package.json */ }
+  return { baseBranch, checks: [{ name: 'project', dir: '.', whenPaths: ['.'], focused: command, full: command }] };
+}
+
+/** Resolves where the config comes from; returns it plus the text to write (null when it already exists). */
+function resolveConfig(args, ctx, out, adopt) {
+  const existing = existsSync(join(ctx.cwd, CONFIG_PATH));
+  const from = args['--config'];
+  if (existing) {
+    if (from) throw new Error(`${CONFIG_PATH} already exists; drop --config to use it (it is never overwritten)`);
+    return { config: loadConfig(ctx.cwd), text: null };
+  }
+  if (from) {
+    let text;
+    try {
+      text = readFileSync(resolve(ctx.cwd, from), 'utf8');
+    } catch (e) {
+      throw new Error(`cannot read --config file ${from}: ${e.message}`);
+    }
+    let raw;
+    try {
+      raw = JSON.parse(text);
+    } catch (e) {
+      throw new Error(`--config file ${from} is not valid JSON: ${e.message}`);
+    }
+    return { config: validateConfig(raw), text: text.endsWith('\n') ? text : `${text}\n` };
+  }
+  if (adopt) {
+    throw new Error(
+      `--adopt requires --config <file> when ${CONFIG_PATH} does not exist: adopting existing hand-written files only makes sense `
+      + 'against a config that describes your repository (checks, models); a starter config would be a guess, and every file '
+      + `rendered from it would differ. Create ${CONFIG_PATH} (see docs/config.md) or pass --config <file>.`,
+    );
+  }
+  const baseBranch = detectBaseBranch(ctx.cwd);
+  if (!baseBranch) {
+    throw new Error(
+      `no ${CONFIG_PATH} and no default branch to take baseBranch from (git has no refs/remotes/origin/HEAD). `
+      + `Create ${CONFIG_PATH} (see docs/config.md) or pass --config <file>.`,
+    );
+  }
+  const raw = starterConfig(ctx.cwd, baseBranch);
+  out.write(`no ${CONFIG_PATH}: writing a starter config (baseBranch "${baseBranch}" from origin/HEAD); edit "checks" in it\n`);
+  return { config: validateConfig(raw), text: `${JSON.stringify(raw, null, 2)}\n` };
+}
+
+/**
+ * `wavework init [--config <file>] [--adopt] [--dry-run]`: first-time setup of `.claude/` in the repo at `ctx.cwd`.
+ * With `--adopt`, existing files are kept: identical ones are locked, differing ones get a `.wavework-new` next to them.
+ *
+ * @returns {Promise<number>} exit code
+ */
+export async function init(args, ctx) {
+  if (!existsSync(join(ctx.cwd, '.git'))) throw new Error('not at a git repository root (no .git here): run wavework from the repository root');
+  const claudeDir = join(ctx.cwd, '.claude');
+  if (readLock(claudeDir)) throw new Error('.claude/wavework.lock.json exists: wavework is already set up here; run `wavework update`');
+
+  const dryRun = args['--dry-run'] === true;
+  const adopt = args['--adopt'] === true;
+  const { config, text } = resolveConfig(args, ctx, ctx.stdout, adopt);
+  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: { files: {}, hooks: [] }, defs: loadHookDefs(ctx.hooks, config), adopt });
+
+  if (!dryRun) {
+    if (text !== null) {
+      const configPath = safeResolve(claudeDir, 'wavework.json', { allowReserved: true });
+      result.actions.unshift({ kind: 'create', target: 'wavework.json', abs: configPath, content: text, mode: 0o644 });
+    }
+    apply(claudeDir, result, ctx.version);
+  } else if (text !== null) {
+    result.actions.unshift({ kind: 'create', target: 'wavework.json' });
+  }
+  return report(result, ctx.stdout, { dryRun, adopt, done: `wavework ${ctx.version}: ${adopt ? 'adopted' : 'initialized'} .claude/` });
+}