@ulysses-ai/create-workspace 0.14.0-beta.3 → 0.15.0-beta.0

package/template/.claude/scripts/migrate-to-workspace-context.test.mjs

@@ -0,0 +1,325 @@
+#!/usr/bin/env node
+// Unit tests for migrate-to-workspace-context.mjs
+// Run: node template/.claude/scripts/migrate-to-workspace-context.test.mjs
+
+import {
+  mkdtempSync,
+  mkdirSync,
+  writeFileSync,
+  rmSync,
+  readFileSync,
+  existsSync,
+  cpSync,
+} from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join, dirname } from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { migrate, dirLooksLikeUserScope } from './migrate-to-workspace-context.mjs';
+
+let failed = 0;
+let passed = 0;
+
+function assert(cond, msg) {
+  if (cond) { passed++; } else { failed++; console.error(`  FAIL: ${msg}`); }
+}
+
+function assertEq(actual, expected, msg) {
+  const a = JSON.stringify(actual);
+  const e = JSON.stringify(expected);
+  if (a === e) { passed++; } else {
+    failed++;
+    console.error(`  FAIL: ${msg}\n    expected: ${e}\n    actual:   ${a}`);
+  }
+}
+
+function setupGitRoot() {
+  const root = mkdtempSync(join(tmpdir(), 'mig-test-'));
+  spawnSync('git', ['init', '-q'], { cwd: root });
+  spawnSync('git', ['config', 'user.email', 'test@example.com'], { cwd: root });
+  spawnSync('git', ['config', 'user.name', 'Test'], { cwd: root });
+  // Install the generator and capture-context scripts so step12 can run
+  mkdirSync(join(root, '.claude', 'scripts'), { recursive: true });
+  mkdirSync(join(root, '.claude', 'lib'), { recursive: true });
+  cpSync(
+    new URL('./build-workspace-context.mjs', import.meta.url).pathname,
+    join(root, '.claude', 'scripts', 'build-workspace-context.mjs'),
+  );
+  cpSync(
+    new URL('./generate-claude-local.mjs', import.meta.url).pathname,
+    join(root, '.claude', 'scripts', 'generate-claude-local.mjs'),
+  );
+  cpSync(
+    new URL('../lib/session-frontmatter.mjs', import.meta.url).pathname,
+    join(root, '.claude', 'lib', 'session-frontmatter.mjs'),
+  );
+  // Configure user for CLAUDE.local.md generation
+  writeFileSync(
+    join(root, '.claude', 'settings.local.json'),
+    JSON.stringify({ workspace: { user: 'alice' } }),
+  );
+  return root;
+}
+
+function cleanup(root) {
+  rmSync(root, { recursive: true, force: true });
+}
+
+function writeFM(path, fm, body = 'body\n') {
+  mkdirSync(dirname(path), { recursive: true });
+  const yaml = Object.entries(fm).map(([k, v]) => `${k}: ${v}`).join('\n');
+  writeFileSync(path, `---\n${yaml}\n---\n\n${body}`);
+}
+
+function gitAddCommit(root) {
+  spawnSync('git', ['add', '-A'], { cwd: root });
+  spawnSync('git', ['commit', '-q', '-m', 'fixture'], { cwd: root });
+}
+
+function summarize(results) {
+  return Object.fromEntries(results.map((r) => [r.name, r.status]));
+}
+
+console.log('# fresh template (no shared-context, no release-notes)');
+
+{
+  const root = setupGitRoot();
+  // Just CLAUDE.md and workspace.json present
+  writeFileSync(
+    join(root, 'CLAUDE.md'),
+    '# Fresh\n\n## Workspace Config\n@workspace.json\n',
+  );
+  writeFileSync(
+    join(root, 'workspace.json'),
+    JSON.stringify({ workspace: { name: 'fresh' } }, null, 2) + '\n',
+  );
+  gitAddCommit(root);
+
+  const results = migrate(root);
+  const s = summarize(results);
+  assertEq(s['rename-shared-context'], 'noop', 'no shared-context to migrate');
+  assertEq(s['consolidate-locked'], 'noop', 'noop on fresh');
+  assertEq(s['move-release-notes'], 'noop', 'no release-notes to move');
+  // No source dirs, but workspace.json still gets the new fields
+  assertEq(s['update-workspace-json'], 'applied', 'workspace.json gets workspaceContextDir');
+  cleanup(root);
+}
+
+console.log('# full migration of pre-v0.15 layout');
+
+{
+  const root = setupGitRoot();
+  // Old layout
+  writeFM(
+    join(root, OLD_FILE('locked', 'naming.md')),
+    { state: 'locked', type: 'reference', topic: 'naming' },
+    '# Naming\n',
+  );
+  writeFM(
+    join(root, OLD_FILE('inventory.md')),
+    { state: 'ephemeral', type: 'reference', description: 'Inventory.' },
+    '# Inventory\n',
+  );
+  writeFM(
+    join(root, OLD_FILE('alice', 'mythoughts.md')),
+    { state: 'ephemeral', type: 'braindump', topic: 'mythoughts', author: 'alice' },
+    '# Thoughts\n',
+  );
+  writeFM(
+    join(root, OLD_FILE('product-x', 'feature-design.md')),
+    { state: 'ephemeral', type: 'design', description: 'Feature design.' },
+    'design\n',
+  );
+  // release-notes at root
+  mkdirSync(join(root, 'release-notes', 'unreleased'), { recursive: true });
+  writeFileSync(
+    join(root, 'release-notes', 'unreleased', 'note.md'),
+    '## Note\n',
+  );
+  // CLAUDE.md with broken import
+  writeFileSync(
+    join(root, 'CLAUDE.md'),
+    '# Workspace\n\n## Team Knowledge (always loaded)\n@shared-context/locked/\n',
+  );
+  // workspace.json with old field
+  writeFileSync(
+    join(root, 'workspace.json'),
+    JSON.stringify({
+      workspace: {
+        name: 'demo',
+        sharedContextDir: 'shared-context',
+        releaseNotesDir: 'release-notes',
+      },
+    }, null, 2) + '\n',
+  );
+  // .indexignore with legacy header
+  writeFileSync(
+    join(root, OLD_FILE('.indexignore')),
+    '# Shared-context paths excluded from shared-context/index.md.\nscaffolder-release-history/\n',
+  );
+  gitAddCommit(root);
+
+  const results = migrate(root);
+  const s = summarize(results);
+
+  // Step 1
+  assertEq(s['rename-shared-context'], 'applied', 'shared-context renamed');
+  assert(existsSync(join(root, 'workspace-context')), 'workspace-context dir present');
+  assert(!existsSync(join(root, 'shared-context')), 'shared-context dir gone');
+
+  // Step 2: locked moved into shared/
+  assert(
+    existsSync(join(root, 'workspace-context', 'shared', 'locked', 'naming.md')),
+    'locked file under shared/locked/',
+  );
+
+  // Step 3: root .md moved into shared/
+  assert(
+    existsSync(join(root, 'workspace-context', 'shared', 'inventory.md')),
+    'root md moved to shared/',
+  );
+
+  // Step 4: alice (user dir, has author: alice) → team-member/alice/
+  assert(
+    existsSync(join(root, 'workspace-context', 'team-member', 'alice', 'mythoughts.md'))
+      // post-step5 it may be renamed to braindump_mythoughts.md; check both
+      || existsSync(join(root, 'workspace-context', 'team-member', 'alice', 'braindump_mythoughts.md')),
+    'alice dir → team-member/alice/',
+  );
+  // product-x (no author match) → shared/product-x/
+  assert(
+    existsSync(join(root, 'workspace-context', 'shared', 'product-x', 'feature-design.md')),
+    'product-x dir → shared/product-x/',
+  );
+
+  // Step 5: braindump file got prefixed
+  assert(
+    existsSync(join(root, 'workspace-context', 'team-member', 'alice', 'braindump_mythoughts.md')),
+    'braindump_ prefix applied',
+  );
+
+  // Step 6: release-notes moved
+  assert(
+    existsSync(join(root, 'workspace-context', 'release-notes', 'unreleased', 'note.md')),
+    'release-notes moved under workspace-context/',
+  );
+  assert(!existsSync(join(root, 'release-notes')), 'old release-notes/ gone');
+
+  // Step 7: CLAUDE.md updated
+  const claudeMd = readFileSync(join(root, 'CLAUDE.md'), 'utf-8');
+  assert(claudeMd.includes('@workspace-context/canonical.md'), 'CLAUDE.md imports canonical');
+  assert(claudeMd.includes('@workspace-context/index.md'), 'CLAUDE.md imports index');
+  assert(!claudeMd.includes('@shared-context/locked/'), 'broken import gone');
+
+  // Step 8: workspace.json
+  const ws = JSON.parse(readFileSync(join(root, 'workspace.json'), 'utf-8'));
+  assertEq(ws.workspace.workspaceContextDir, 'workspace-context', 'workspaceContextDir set');
+  assert(!('sharedContextDir' in ws.workspace), 'sharedContextDir removed');
+  assertEq(ws.workspace.releaseNotesDir, 'workspace-context/release-notes', 'releaseNotesDir updated');
+
+  // Step 9: .indexignore
+  const ii = readFileSync(join(root, 'workspace-context', '.indexignore'), 'utf-8');
+  assert(ii.includes('workspace-context'), '.indexignore header updated');
+  // scaffolder-release-history/ stays at workspace-context root (it's reserved),
+  // so its .indexignore entry stays as a bare prefix relative to workspace-context/
+  assert(ii.includes('scaffolder-release-history/'), 'scaffolder entry preserved');
+  assert(!ii.includes('shared/scaffolder-release-history/'), 'no incorrect prefix-shift');
+  assert(ii.includes('release-notes/'), 'release-notes/ added');
+
+  // Step 10: CLAUDE.local.md
+  assert(existsSync(join(root, 'CLAUDE.local.md')), 'CLAUDE.local.md generated');
+  const local = readFileSync(join(root, 'CLAUDE.local.md'), 'utf-8');
+  assert(local.includes('alice/index.md'), 'CLAUDE.local.md has alice import');
+
+  // Step 12: auto-files exist
+  assert(existsSync(join(root, 'workspace-context', 'index.md')), 'index.md generated');
+  assert(existsSync(join(root, 'workspace-context', 'canonical.md')), 'canonical.md generated');
+
+  cleanup(root);
+}
+
+console.log('# idempotence: re-running migration is a no-op');
+
+{
+  const root = setupGitRoot();
+  writeFM(
+    join(root, OLD_FILE('locked', 'rule.md')),
+    { state: 'locked', type: 'reference' },
+    '# Rule\n',
+  );
+  writeFileSync(join(root, 'CLAUDE.md'), '@shared-context/locked/\n');
+  writeFileSync(join(root, 'workspace.json'),
+    JSON.stringify({ workspace: { sharedContextDir: 'shared-context' } }, null, 2) + '\n',
+  );
+  gitAddCommit(root);
+
+  const first = migrate(root);
+  const firstApplied = first.filter((r) => r.status === 'applied').map((r) => r.name);
+  assert(firstApplied.length > 0, 'first run applied changes');
+
+  // Commit the migration so step5 can re-mv files
+  spawnSync('git', ['add', '-A'], { cwd: root });
+  spawnSync('git', ['commit', '-q', '-m', 'migrated'], { cwd: root });
+
+  const second = migrate(root);
+  const secondApplied = second.filter((r) => r.status === 'applied').map((r) => r.name);
+  // Step 12 re-runs the generator (it always applies if outputs differ from disk).
+  // Anything else applied a second time is a bug.
+  for (const name of secondApplied) {
+    assert(name === 'build-auto-files', `step "${name}" should be idempotent`);
+  }
+  cleanup(root);
+}
+
+console.log('# dirLooksLikeUserScope heuristic');
+
+{
+  const root = mkdtempSync(join(tmpdir(), 'mig-uscope-'));
+  // alice/ has a file with author: alice
+  mkdirSync(join(root, 'alice'), { recursive: true });
+  writeFM(
+    join(root, 'alice', 'note.md'),
+    { type: 'braindump', author: 'alice' },
+  );
+  // bob/ has files but author is unknown
+  mkdirSync(join(root, 'bob'), { recursive: true });
+  writeFM(
+    join(root, 'bob', 'design.md'),
+    { type: 'design' },
+  );
+  // empty dir
+  mkdirSync(join(root, 'empty'), { recursive: true });
+
+  assert(dirLooksLikeUserScope(join(root, 'alice'), 'alice'), 'alice dir detected as user');
+  assert(!dirLooksLikeUserScope(join(root, 'bob'), 'bob'), 'bob dir not detected as user');
+  assert(!dirLooksLikeUserScope(join(root, 'empty'), 'empty'), 'empty dir not detected');
+  cleanup(root);
+}
+
+console.log('# project repo (no release-notes/, no shared-context/)');
+
+{
+  const root = setupGitRoot();
+  writeFileSync(join(root, 'CLAUDE.md'), '# Project\n');
+  writeFileSync(join(root, 'workspace.json'),
+    JSON.stringify({ workspace: { name: 'p' } }, null, 2) + '\n',
+  );
+  gitAddCommit(root);
+  const results = migrate(root);
+  const s = summarize(results);
+  // No source content to migrate
+  assertEq(s['rename-shared-context'], 'noop');
+  assertEq(s['move-release-notes'], 'noop');
+  // No errors
+  for (const r of results) assert(r.status !== 'error', `step ${r.name} did not error`);
+  cleanup(root);
+}
+
+console.log('');
+console.log(`${passed} passed, ${failed} failed`);
+process.exit(failed > 0 ? 1 : 0);
+
+// helpers
+
+function OLD_FILE(...parts) {
+  return join('shared-context', ...parts);
+}

package/template/.claude/scripts/sweep-references.mjs

@@ -0,0 +1,177 @@
+#!/usr/bin/env node
+// Sed-style scripted find-replace across a target tree.
+//
+// Mechanizes the long-tail string updates in rule prose, skill instructions,
+// hooks, and code so we don't burn LLM tokens (and chances for typo) doing
+// it by hand. Used by:
+//   - the v0.15 template PR (run on template/)
+//   - the migrator (run on the dogfood workspace itself)
+//
+// Replacement rules are ordered longest-pattern-first so we don't get
+// cascading double-replacements (e.g. shared-context/locked → workspace-context/shared/locked
+// must run before shared-context/ → workspace-context/).
+//
+// Usage:
+//   node sweep-references.mjs --check  --target <dir>
+//   node sweep-references.mjs --write  --target <dir>
+//
+// Skips:
+//   - any path containing /release-notes/archive/
+//   - any path containing /scaffolder-release-history/
+//   - .git/, node_modules/
+//   - the script's own file (avoids self-rewrite)
+//   - binary files (detected via null-byte heuristic)
+
+import { readdirSync, readFileSync, statSync, writeFileSync, realpathSync } from 'node:fs';
+import { join, relative, resolve, sep } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+function isMainModule(metaUrl) {
+  if (!process.argv[1]) return false;
+  try {
+    return realpathSync(fileURLToPath(metaUrl)) === realpathSync(process.argv[1]);
+  } catch { return false; }
+}
+
+const DEFAULT_RULES = [
+  // Order matters — longest patterns first.
+  { from: 'shared-context/locked', to: 'workspace-context/shared/locked' },
+  { from: 'shared-context/', to: 'workspace-context/' },
+  { from: 'shared-context', to: 'workspace-context' },
+  { from: 'sharedContextDir', to: 'workspaceContextDir' },
+];
+
+const SKIP_PATH_FRAGMENTS = [
+  `${sep}release-notes${sep}archive${sep}`,
+  `${sep}scaffolder-release-history${sep}`,
+  `${sep}.git${sep}`,
+  `${sep}node_modules${sep}`,
+];
+
+// Scripts whose contents intentionally contain the literal "before" strings as
+// part of their behavior (the migrator's constants, test fixtures verifying
+// rule firing). Skipping by basename keeps the sweeper from mangling them.
+const SKIP_BASENAMES = new Set([
+  'migrate-to-workspace-context.mjs',
+  'migrate-to-workspace-context.test.mjs',
+  'sweep-references.test.mjs',
+]);
+
+function parseArgs(argv) {
+  const args = { mode: null, target: null };
+  for (let i = 2; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === '--check') args.mode = 'check';
+    else if (a === '--write') args.mode = 'write';
+    else if (a === '--target') args.target = argv[++i];
+    else throw new Error(`Unknown arg: ${a}`);
+  }
+  if (!args.mode) throw new Error('Specify --check or --write');
+  if (!args.target) throw new Error('--target <dir> is required');
+  return args;
+}
+
+function shouldSkip(absPath, scriptPath) {
+  if (absPath === scriptPath) return true;
+  for (const frag of SKIP_PATH_FRAGMENTS) {
+    if (absPath.includes(frag)) return true;
+  }
+  const base = absPath.split(sep).pop();
+  if (SKIP_BASENAMES.has(base)) return true;
+  return false;
+}
+
+function* walk(dir) {
+  const entries = readdirSync(dir);
+  for (const name of entries) {
+    const full = join(dir, name);
+    let st;
+    try { st = statSync(full); } catch { continue; }
+    if (st.isDirectory()) {
+      yield* walk(full);
+    } else if (st.isFile()) {
+      yield full;
+    }
+  }
+}
+
+function isLikelyBinary(buffer) {
+  // Quick null-byte heuristic, sampling the first 4 KiB
+  const sample = buffer.slice(0, Math.min(4096, buffer.length));
+  for (let i = 0; i < sample.length; i++) {
+    if (sample[i] === 0) return true;
+  }
+  return false;
+}
+
+function applyRules(content, rules = DEFAULT_RULES) {
+  let out = content;
+  let total = 0;
+  const perRule = [];
+  for (const rule of rules) {
+    let count = 0;
+    let idx = out.indexOf(rule.from);
+    while (idx !== -1) {
+      count++;
+      idx = out.indexOf(rule.from, idx + rule.from.length);
+    }
+    if (count > 0) {
+      out = out.split(rule.from).join(rule.to);
+      total += count;
+      perRule.push({ from: rule.from, to: rule.to, count });
+    }
+  }
+  return { content: out, total, perRule };
+}
+
+function sweep(targetDir, { rules = DEFAULT_RULES, write = false, scriptPath = '' } = {}) {
+  const absTarget = resolve(targetDir);
+  const changes = [];
+  for (const path of walk(absTarget)) {
+    if (shouldSkip(path, scriptPath)) continue;
+    let buf;
+    try { buf = readFileSync(path); } catch { continue; }
+    if (isLikelyBinary(buf)) continue;
+    const text = buf.toString('utf-8');
+    const result = applyRules(text, rules);
+    if (result.total === 0) continue;
+    changes.push({
+      path: relative(absTarget, path),
+      total: result.total,
+      perRule: result.perRule,
+    });
+    if (write) writeFileSync(path, result.content);
+  }
+  return changes;
+}
+
+function main() {
+  const args = parseArgs(process.argv);
+  const scriptPath = process.argv[1];
+  const changes = sweep(args.target, {
+    rules: DEFAULT_RULES,
+    write: args.mode === 'write',
+    scriptPath,
+  });
+  process.stdout.write(
+    JSON.stringify({
+      mode: args.mode,
+      target: args.target,
+      filesChanged: changes.length,
+      totalReplacements: changes.reduce((acc, c) => acc + c.total, 0),
+      changes,
+    }, null, 2) + '\n',
+  );
+  if (args.mode === 'check' && changes.length > 0) process.exit(1);
+}
+
+if (isMainModule(import.meta.url)) {
+  try {
+    main();
+  } catch (err) {
+    process.stderr.write(`sweep-references: ${err.message}\n`);
+    process.exit(2);
+  }
+}
+
+export { applyRules, sweep, DEFAULT_RULES };

package/template/.claude/scripts/sweep-references.test.mjs

@@ -0,0 +1,184 @@
+#!/usr/bin/env node
+// Unit tests for sweep-references.mjs
+// Run: node template/.claude/scripts/sweep-references.test.mjs
+
+import { mkdtempSync, mkdirSync, writeFileSync, rmSync, readFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { applyRules, sweep, DEFAULT_RULES } from './sweep-references.mjs';
+
+let failed = 0;
+let passed = 0;
+
+function assert(cond, msg) {
+  if (cond) { passed++; } else { failed++; console.error(`  FAIL: ${msg}`); }
+}
+
+function assertEq(actual, expected, msg) {
+  const a = JSON.stringify(actual);
+  const e = JSON.stringify(expected);
+  if (a === e) { passed++; } else {
+    failed++;
+    console.error(`  FAIL: ${msg}\n    expected: ${e}\n    actual:   ${a}`);
+  }
+}
+
+function setupTree() {
+  return mkdtempSync(join(tmpdir(), 'sweep-test-'));
+}
+
+function cleanup(root) {
+  rmSync(root, { recursive: true, force: true });
+}
+
+console.log('# applyRules ordering');
+
+{
+  const input = 'See shared-context/locked/x.md and shared-context/y.md and shared-context';
+  const { content, total, perRule } = applyRules(input);
+  assert(content.includes('workspace-context/shared/locked/x.md'), 'locked path expanded correctly');
+  assert(content.includes('workspace-context/y.md'), 'plain shared-context/ rewritten');
+  assert(content.includes('workspace-context'), 'bare shared-context rewritten');
+  assert(!content.includes('shared-context'), 'no leftover shared-context');
+  assertEq(total, 3, 'three replacements counted');
+  assertEq(perRule.length, 3, 'three rule entries');
+}
+
+{
+  // longest-first: shared-context/locked must NOT be touched by the shorter rules first
+  const input = 'shared-context/locked/foo';
+  const out = applyRules(input).content;
+  assertEq(out, 'workspace-context/shared/locked/foo', 'longest-first wins');
+}
+
+{
+  // sharedContextDir → workspaceContextDir
+  const input = '"sharedContextDir": "shared-context"';
+  const out = applyRules(input).content;
+  assert(out.includes('workspaceContextDir'), 'config key renamed');
+  assert(out.includes('"workspace-context"'), 'value renamed');
+}
+
+{
+  // no replacements when input has nothing matching
+  const input = 'totally unrelated content';
+  const result = applyRules(input);
+  assertEq(result.content, input, 'no-op leaves content alone');
+  assertEq(result.total, 0, 'zero replacements');
+}
+
+console.log('# sweep walks tree');
+
+{
+  const root = setupTree();
+  mkdirSync(join(root, 'rules'), { recursive: true });
+  mkdirSync(join(root, 'skills', 'aside'), { recursive: true });
+  writeFileSync(join(root, 'rules', 'a.md'), 'See shared-context/locked/x.md');
+  writeFileSync(join(root, 'skills', 'aside', 'SKILL.md'), '`shared-context/{user}/`');
+  writeFileSync(join(root, 'unrelated.md'), 'no matches here');
+  const changes = sweep(root, { write: true });
+  assertEq(changes.length, 2, 'two files changed');
+  const a = readFileSync(join(root, 'rules', 'a.md'), 'utf-8');
+  assert(a.includes('workspace-context/shared/locked/x.md'), 'a.md rewritten');
+  const skill = readFileSync(join(root, 'skills', 'aside', 'SKILL.md'), 'utf-8');
+  assert(skill.includes('workspace-context/{user}/'), 'SKILL.md rewritten');
+  const unrelated = readFileSync(join(root, 'unrelated.md'), 'utf-8');
+  assertEq(unrelated, 'no matches here', 'unrelated file unchanged');
+  cleanup(root);
+}
+
+console.log('# sweep skip rules');
+
+{
+  const root = setupTree();
+  mkdirSync(join(root, 'release-notes', 'archive', 'v0.1'), { recursive: true });
+  mkdirSync(join(root, 'scaffolder-release-history'), { recursive: true });
+  mkdirSync(join(root, 'live'), { recursive: true });
+  writeFileSync(join(root, 'release-notes', 'archive', 'v0.1', 'old.md'), 'shared-context/x');
+  writeFileSync(join(root, 'scaffolder-release-history', 'log.md'), 'shared-context/y');
+  writeFileSync(join(root, 'live', 'doc.md'), 'shared-context/z');
+  const changes = sweep(root, { write: true });
+  assertEq(changes.length, 1, 'only live/ touched');
+  assertEq(changes[0].path, join('live', 'doc.md'), 'live/doc.md is the only change');
+  const archived = readFileSync(join(root, 'release-notes', 'archive', 'v0.1', 'old.md'), 'utf-8');
+  assertEq(archived, 'shared-context/x', 'archive untouched');
+  cleanup(root);
+}
+
+console.log('# sweep skips binary files');
+
+{
+  const root = setupTree();
+  // Insert a literal null byte in the buffer
+  const binary = Buffer.from([0x73, 0x68, 0x61, 0x72, 0x65, 0x64, 0x2d, 0x63, 0x6f, 0x6e, 0x74, 0x65, 0x78, 0x74, 0x00, 0x00]);
+  writeFileSync(join(root, 'fake.bin'), binary);
+  writeFileSync(join(root, 'real.md'), 'shared-context');
+  const changes = sweep(root, { write: true });
+  assertEq(changes.length, 1, 'only the text file changed');
+  assertEq(changes[0].path, 'real.md', 'real.md identified');
+  cleanup(root);
+}
+
+console.log('# sweep --check vs --write semantics');
+
+{
+  const root = setupTree();
+  writeFileSync(join(root, 'a.md'), 'shared-context/locked/foo');
+
+  // --check (write: false) reports but does not modify
+  const checkChanges = sweep(root, { write: false });
+  assertEq(checkChanges.length, 1, 'check reports one file');
+  const stillOriginal = readFileSync(join(root, 'a.md'), 'utf-8');
+  assertEq(stillOriginal, 'shared-context/locked/foo', 'check did not write');
+
+  // --write applies
+  sweep(root, { write: true });
+  const updated = readFileSync(join(root, 'a.md'), 'utf-8');
+  assertEq(updated, 'workspace-context/shared/locked/foo', 'write applied');
+  cleanup(root);
+}
+
+console.log('# CLI end-to-end');
+
+{
+  const root = setupTree();
+  writeFileSync(join(root, 'a.md'), 'shared-context/locked/foo and shared-context/bar');
+  const scriptPath = new URL('./sweep-references.mjs', import.meta.url).pathname;
+
+  // --check exits 1 when changes pending
+  const check = spawnSync('node', [scriptPath, '--check', '--target', root], { encoding: 'utf-8' });
+  assertEq(check.status, 1, '--check exits 1 with changes pending');
+  const checkOut = JSON.parse(check.stdout);
+  assertEq(checkOut.filesChanged, 1, 'reports one file');
+
+  // --write exits 0 and modifies
+  const write = spawnSync('node', [scriptPath, '--write', '--target', root], { encoding: 'utf-8' });
+  assertEq(write.status, 0, '--write exits 0');
+  const updated = readFileSync(join(root, 'a.md'), 'utf-8');
+  assertEq(
+    updated,
+    'workspace-context/shared/locked/foo and workspace-context/bar',
+    'sweep wrote both rules in correct order',
+  );
+
+  // --check after --write exits 0 (no changes pending)
+  const recheck = spawnSync('node', [scriptPath, '--check', '--target', root], { encoding: 'utf-8' });
+  assertEq(recheck.status, 0, '--check after --write exits 0');
+
+  cleanup(root);
+}
+
+console.log('# DEFAULT_RULES order is intentional');
+
+{
+  // Sanity: rule[0] is longer than rule[1] (locked goes first)
+  assert(
+    DEFAULT_RULES[0].from.length > DEFAULT_RULES[1].from.length,
+    'first rule is longest',
+  );
+}
+
+console.log('');
+console.log(`${passed} passed, ${failed} failed`);
+process.exit(failed > 0 ? 1 : 0);