wavework 0.1.0 → 0.1.1

package/CHANGELOG.md

@@ -7,6 +7,16 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [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
@@ -19,5 +29,6 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - 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.0...HEAD
+[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/README.md

@@ -36,6 +36,15 @@ Without `--config`, `init` writes a starter config: `baseBranch` comes from `ori
 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`)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wavework",
-  "version": "0.1.0",
+  "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": {

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/init.mjs

@@ -32,7 +32,7 @@ function starterConfig(cwd, baseBranch) {
 }
 
 /** Resolves where the config comes from; returns it plus the text to write (null when it already exists). */
-function resolveConfig(args, ctx, out) {
+function resolveConfig(args, ctx, out, adopt) {
   const existing = existsSync(join(ctx.cwd, CONFIG_PATH));
   const from = args['--config'];
   if (existing) {
@@ -54,6 +54,13 @@ function resolveConfig(args, ctx, out) {
     }
     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(
@@ -67,7 +74,8 @@ function resolveConfig(args, ctx, out) {
 }
 
 /**
- * `wavework init [--config <file>] [--dry-run]`: first-time setup of `.claude/` in the repo at `ctx.cwd`.
+ * `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
  */
@@ -77,10 +85,11 @@ export async function init(args, ctx) {
   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 { config, text } = resolveConfig(args, ctx, ctx.stdout);
+  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) });
+  const result = plan({ claudeDir, rendered, lock: { files: {}, hooks: [] }, defs: loadHookDefs(ctx.hooks, config), adopt });
 
   if (!dryRun) {
     if (text !== null) {
@@ -91,5 +100,5 @@ export async function init(args, ctx) {
   } else if (text !== null) {
     result.actions.unshift({ kind: 'create', target: 'wavework.json' });
   }
-  return report(result, ctx.stdout, { dryRun, done: `wavework ${ctx.version}: initialized .claude/` });
+  return report(result, ctx.stdout, { dryRun, adopt, done: `wavework ${ctx.version}: ${adopt ? 'adopted' : 'initialized'} .claude/` });
 }

package/src/cli/sync.mjs

@@ -8,6 +8,7 @@ import { buildContext } from '../context.mjs';
 import { render } from '../render.mjs';
 import { safeResolve } from './safe-path.mjs';
 import { mergeHooks, parseHookDefs } from './hooks.mjs';
+import { lineDiffStat } from './diff-stat.mjs';
 
 export const LOCK_PATH = 'wavework.lock.json';
 export const SETTINGS_PATH = 'settings.json';
@@ -129,6 +130,16 @@ function diskHash(abs, rel) {
   return sha256(readFileSync(abs));
 }
 
+const exists = (abs) => {
+  try {
+    lstatSync(abs);
+    return true;
+  } catch (e) {
+    if (e.code === 'ENOENT') return false;
+    throw e;
+  }
+};
+
 /**
  * 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.
@@ -138,9 +149,12 @@ function diskHash(abs, rel) {
  * @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
+ * @param {boolean} [p.adopt] `init --adopt`: existing files that differ are kept, their lock entry is the RENDERED hash,
+ *   and the result carries `adoption` (identical / differing with diff stats / created). Nothing else changes.
  */
-export function plan({ claudeDir, rendered, lock, defs }) {
+export function plan({ claudeDir, rendered, lock, defs, adopt = false }) {
   const actions = [];
+  const adoption = { identical: [], differing: [], created: [] };
   const files = {};
   const wanted = new Set(rendered.map((t) => t.target));
 
@@ -151,17 +165,27 @@ export function plan({ claudeDir, rendered, lock, defs }) {
     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');
+      adoption.created.push(t.target);
     } else if (disk === t.hash) {
       files[t.target] = t.hash; // already what we would write: adopt
+      adoption.identical.push(t.target);
       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 });
+      const review = { kind: 'review', target: t.target, newTarget: `${t.target}${NEW_SUFFIX}`, newAbs, content: t.content };
+      if (adopt) {
+        // Adopted: the lock records the rendered hash, so `update` reports the file for as long as its .wavework-new exists.
+        files[t.target] = t.hash;
+        review.stat = lineDiffStat(readFileSync(abs, 'utf8'), t.content);
+        adoption.differing.push({ target: t.target, ...review.stat });
+      } else if (locked !== undefined && t.hash === locked && !exists(newAbs)) {
+        continue; // nothing new upstream, nothing to merge (a still existing .wavework-new means it is not resolved yet)
+      }
+      actions.push(review);
     }
   }
 
@@ -198,7 +222,7 @@ export function plan({ claudeDir, rendered, lock, defs }) {
   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 };
+  return { actions, notes, files, adoption, 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. */
@@ -248,13 +272,17 @@ const LABEL = {
 };
 
 /** Prints one short line per change; returns the exit code (2 when files need review). */
-export function report(result, stdout, { dryRun, done }) {
+export function report(result, stdout, { dryRun, done, adopt = false }) {
   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`);
+      const st = a.stat;
+      const note = st?.approx ? ', upper bound' : st?.whitespaceOnly ? ', whitespace/newline only' : '';
+      const stat = st ? ` (+${st.added} -${st.removed}${note})` : '';
+      const why = a.stat ? 'differs from the rendered version, kept untouched; rendered version in' : 'edited locally, kept; new version in';
+      stdout.write(`${prefix}review  ${a.target}: ${why} ${a.newTarget}${stat}\n`);
     } else if (a.kind === 'review-removed') {
       stdout.write(`${prefix}review  ${a.target}: removed upstream but edited locally, kept\n`);
     } else {
@@ -262,6 +290,11 @@ export function report(result, stdout, { dryRun, done }) {
     }
   }
   for (const note of result.notes) stdout.write(`${prefix}${note}\n`);
+  if (adopt) {
+    const { identical, differing, created } = result.adoption;
+    stdout.write(`${prefix}adopt: ${identical.length} identical, ${differing.length} differing, ${created.length} new\n`);
+    if (differing.length > 0) stdout.write(`${prefix}for a full diff run: diff <file> <file>${NEW_SUFFIX}  (+N -M = lines the rendered version adds / the kept file has extra)\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`);

package/src/cli.mjs

@@ -12,7 +12,7 @@ const pkg = JSON.parse(
 export const USAGE = `Usage: wavework <command> [options]
 
 Commands:
-  init        Set up .claude/ in the current repository   [--config <file>] [--dry-run]
+  init        Set up .claude/ in the current repository   [--config <file>] [--adopt] [--dry-run]
   update      Re-render .claude/ from the installed version [--dry-run]
   dashboard   Start the pipeline dashboard of this repository (installed by init)
 
@@ -22,7 +22,7 @@ Options:
 `;
 
 const COMMANDS = {
-  init: { run: init, options: { '--config': 'value', '--dry-run': 'flag' } },
+  init: { run: init, options: { '--config': 'value', '--adopt': 'flag', '--dry-run': 'flag' } },
   update: { run: update, options: { '--dry-run': 'flag' } },
   dashboard: { run: dashboard, options: {} },
 };