bossbuild 0.97.0

package/src/map.js

@@ -0,0 +1,103 @@
+// boss map — the live cheatsheet (IDEA-018). Where you are on the ladder, what
+// you can run right now (grouped by the rung that unlocked it), and what's one
+// unlock away. Like `boss board`, it's a pure render of state the project
+// already holds — the .boss stamp + the installed SKILL.md files — so there is
+// nothing to maintain and nothing to drift.
+
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { STAGE_ORDER } from './paths.js';
+import { loadModes, packageSkillMd, skillGloss, modeWord } from './modes.js';
+
+function projectSkillMd(projectDir, name) {
+  return join(projectDir, '.claude', 'skills', name, 'SKILL.md');
+}
+
+// Gloss for an installed skill: prefer the project's OWN copy (truthful about
+// local edits), fall back to the package stage that defines it.
+function installedGloss(projectDir, name, definedIn) {
+  const own = projectSkillMd(projectDir, name);
+  if (existsSync(own)) return skillGloss(own);
+  if (definedIn) return skillGloss(packageSkillMd(definedIn, name));
+  return { gloss: '', usage: '' };
+}
+
+export function renderMap(projectDir, stamp) {
+  const modes = loadModes();
+  const byId = Object.fromEntries(modes.map((m) => [m.id, m]));
+  // skill name -> the stage id that first introduces it (ladder order).
+  const skillStage = {};
+  for (const m of modes) for (const s of m.skills || []) if (!(s in skillStage)) skillStage[s] = m.id;
+
+  const installed = stamp.installedLayers || [stamp.stage];
+  const deepest = installed[installed.length - 1];
+
+  // Scannable, single-line glosses. Substitute the project name into any
+  // not-yet-installed (package) gloss so the "one unlock away" preview reads as
+  // what the founder would actually get; cap width so a long sentence can't
+  // dominate the terminal.
+  const fit = (g) => {
+    let t = (g || '').replace(/\{\{PROJECT_NAME\}\}/g, stamp.name).replace(/\{\{[^}]+\}\}/g, '');
+    if (t.length > 64) t = t.slice(0, 63).trimEnd() + '…';
+    return t;
+  };
+
+  const lines = [];
+  lines.push('');
+  lines.push(`  ${stamp.name} · map`);
+  lines.push(`  ▸ You are here: ${stamp.mode || stamp.stage}  (${installed.join(' → ')})`);
+  lines.push('');
+
+  // Available now — grouped by the rung that unlocked each skill, ladder order.
+  lines.push('  Available now');
+  for (const layerId of STAGE_ORDER) {
+    if (!installed.includes(layerId)) continue;
+    const mode = byId[layerId];
+    const skillsHere = (stamp.skills || []).filter((s) => skillStage[s] === layerId).sort();
+    if (!skillsHere.length) continue;
+    lines.push(`    ${mode.name}`);
+    for (const s of skillsHere) {
+      const { gloss } = installedGloss(projectDir, s, layerId);
+      lines.push(`      /${s.padEnd(18)} ${fit(gloss)}`);
+    }
+  }
+  lines.push('');
+
+  // One unlock away — read the next rung's skills from the package (not yet
+  // installed here), so the founder sees what they'd gain before committing.
+  const idx = STAGE_ORDER.indexOf(deepest);
+  const nextId = idx >= 0 ? STAGE_ORDER[idx + 1] : null;
+  if (nextId) {
+    const next = byId[nextId];
+    if (next && next.authored) {
+      lines.push(`  One unlock away: ${next.name}   →  boss unlock ${modeWord(nextId)}`);
+      for (const s of next.skills || []) {
+        const { gloss } = skillGloss(packageSkillMd(nextId, s));
+        lines.push(`      /${s.padEnd(18)} ${fit(gloss)}`);
+      }
+      if (next.graduationHint) lines.push(`    ${next.graduationHint}`);
+    } else if (next) {
+      lines.push(`  One unlock away: ${next.name} — not authored yet.`);
+    }
+    lines.push('');
+  }
+
+  // Standing controls — always available, mode-independent (the git-cheatsheet core).
+  lines.push('  Anytime');
+  lines.push('    boss board [--html]              what\'s in flight (captured → shipped); --html = visual kanban');
+  lines.push('    boss brain                       the conscience\'s read on this venture');
+  lines.push('    boss insights                    how far your ventures have gotten (local)');
+  lines.push('    boss team [add @user]            who\'s on the venture — add a cofounder (solo by default)');
+  lines.push('    boss status --conscience         loop states + cohort + recent overrides');
+  lines.push('    boss conscience pause --for 8h   silence the whole conscience for a sprint');
+  lines.push('    boss conscience mute <moment>    turn down just one nudge (drift|caution|…)');
+  lines.push('    /boss-sync                       pull the latest BOSS practices into this project');
+  lines.push('');
+  lines.push('  The map is a read of your install. To change it, climb a rung: boss unlock <mode>.');
+  lines.push('');
+  return lines.join('\n');
+}
+
+export function map(projectDir, stamp) {
+  console.log(renderMap(projectDir, stamp));
+}

package/src/modes.js

@@ -0,0 +1,82 @@
+// Shared mode + skill metadata — the SINGLE source both `boss map` (live, in a
+// founder's project) and scripts/gen-docs.js (static, in the BOSS repo) read,
+// so the live map and the generated cheatsheet can never disagree about what a
+// mode adds. This is the de-rot mechanism (IDEA-018): the per-mode lists are
+// derived from the manifests + SKILL.md frontmatter, never hand-typed.
+
+import { readFileSync, existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { STAGES_DIR, STAGE_ORDER } from './paths.js';
+import { readStageManifest } from './scaffold.js';
+
+// Display name for a rung even when it isn't authored yet (no manifest.json).
+const STAGE_NAMES = {
+  'L0-quickstart': 'Quickstart',
+  'L1-mvp': 'MVP',
+  'L2-v1': 'V1',
+  'L3-scale': 'Scale',
+};
+
+// The mode word a user types into `boss unlock` (strips the L#- level prefix).
+export function modeWord(stageId) {
+  return stageId.replace(/^l\d+-/i, '');
+}
+
+// The ordered ladder. Unauthored stages (no manifest — e.g. Scale today) come
+// back as { authored: false } so callers can show the rung without faking
+// content for it.
+export function loadModes() {
+  return STAGE_ORDER.map((id) => {
+    try {
+      const m = readStageManifest(id);
+      return {
+        authored: true,
+        id,
+        name: m.name || STAGE_NAMES[id] || id,
+        summary: m.summary || '',
+        agents: m.agents || [],
+        skills: m.skills || [],
+        loops: m.loops || [],
+        hooks: m.hooks || [],
+        requires: m.requires || null,
+        unlocksNext: m.unlocksNext || null,
+        graduationHint: m.graduationHint || '',
+      };
+    } catch {
+      return { authored: false, id, name: STAGE_NAMES[id] || id, agents: [], skills: [], loops: [] };
+    }
+  });
+}
+
+// The SKILL.md for a skill inside the PACKAGE (a given stage's template).
+export function packageSkillMd(stageId, name) {
+  return join(STAGES_DIR, stageId, 'template', '.claude', 'skills', name, 'SKILL.md');
+}
+
+function frontmatterDescription(text) {
+  const m = text.match(/^---\n([\s\S]*?)\n---/);
+  if (!m) return '';
+  for (const line of m[1].split('\n')) {
+    const i = line.indexOf(':');
+    if (i === -1) continue;
+    if (line.slice(0, i).trim() === 'description') return line.slice(i + 1).trim();
+  }
+  return '';
+}
+
+// Split a SKILL.md description into a one-line gloss + a usage hint. Descriptions
+// follow the house format "<gloss sentence>. … Usage - /name <args>". Returns
+// { gloss, usage } — empty strings when the file is missing or has no description.
+export function skillGloss(skillMdPath) {
+  if (!existsSync(skillMdPath)) return { gloss: '', usage: '' };
+  const desc = frontmatterDescription(readFileSync(skillMdPath, 'utf8'));
+  if (!desc) return { gloss: '', usage: '' };
+  const u = desc.search(/\bUsage\s*[-:]/i);
+  const body = (u === -1 ? desc : desc.slice(0, u)).trim();
+  const usage = u === -1 ? '' : desc.slice(u).replace(/^Usage\s*[-:]\s*/i, '').trim();
+  // First sentence of the body is the gloss.
+  const dot = body.indexOf('. ');
+  let gloss = dot === -1 ? body : body.slice(0, dot + 1);
+  gloss = gloss.replace(/\.$/, '').trim();
+  return { gloss, usage };
+}

package/src/paths.js

@@ -0,0 +1,36 @@
+import { fileURLToPath } from 'node:url';
+import { dirname, resolve, join } from 'node:path';
+import { readFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+
+// BOSS install root — resolves correctly even when `boss` is globally linked,
+// because import.meta.url points at the real file in src/. This is the PACKAGE
+// (immutable, what gets published). Never write into it at runtime.
+export const BOSS_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '..');
+
+export const STAGES_DIR = join(BOSS_ROOT, 'stages');
+
+// Mutable, machine-local state lives in the user's home — NOT in the package.
+// This keeps the published package immutable and keeps a user's project list
+// (with absolute paths) out of the repo.
+export const BOSS_HOME = join(homedir(), '.boss');
+export const REGISTRY_FILE = join(BOSS_HOME, 'registry.json');
+
+export function bossVersion() {
+  return readFileSync(join(BOSS_ROOT, 'VERSION'), 'utf8').trim();
+}
+
+// Stage order — index = maturity level. Used to validate `unlock` jumps.
+// Each stage is a "mode" in the user's vocabulary: Quickstart → MVP → V1 → Scale.
+export const STAGE_ORDER = ['L0-quickstart', 'L1-mvp', 'L2-v1', 'L3-scale'];
+
+// Resolve a user-typed layer to a canonical stage id.
+// Accepts the full id ('L1-mvp'), the level ('L1'), or the mode name ('mvp').
+export function resolveStageId(input) {
+  if (!input) return undefined;
+  const q = input.toLowerCase();
+  return STAGE_ORDER.find((s) => {
+    const sl = s.toLowerCase();
+    return sl === q || sl.startsWith(q + '-') || sl.replace(/^l\d+-/, '') === q;
+  });
+}

package/src/registry.js

@@ -0,0 +1,34 @@
+import { readFileSync, writeFileSync, existsSync, mkdirSync } from 'node:fs';
+import { dirname } from 'node:path';
+import { REGISTRY_FILE } from './paths.js';
+
+function load() {
+  if (!existsSync(REGISTRY_FILE)) return { projects: [] };
+  try {
+    return JSON.parse(readFileSync(REGISTRY_FILE, 'utf8'));
+  } catch {
+    return { projects: [] };
+  }
+}
+
+function save(data) {
+  mkdirSync(dirname(REGISTRY_FILE), { recursive: true }); // ensure ~/.boss exists
+  writeFileSync(REGISTRY_FILE, JSON.stringify(data, null, 2) + '\n');
+}
+
+export function listProjects() {
+  return load().projects;
+}
+
+// Upsert by absolute path — a project is identified by where it lives on disk.
+export function registerProject(entry) {
+  const data = load();
+  const idx = data.projects.findIndex((p) => p.path === entry.path);
+  if (idx >= 0) data.projects[idx] = { ...data.projects[idx], ...entry };
+  else data.projects.push(entry);
+  save(data);
+}
+
+export function findByPath(absPath) {
+  return load().projects.find((p) => p.path === absPath);
+}

package/src/scaffold.js

@@ -0,0 +1,138 @@
+import {
+  cpSync, readdirSync, statSync, readFileSync, writeFileSync, existsSync, rmSync, mkdirSync,
+} from 'node:fs';
+import { join } from 'node:path';
+import { STAGES_DIR } from './paths.js';
+
+// A stage template may carry this file. Instead of being copied verbatim, its
+// (substituted) contents are APPENDED to the project's CLAUDE.md under an
+// idempotent marker — so unlocking a mode adds its working rules without ever
+// clobbering rules the project (or earlier modes) already wrote.
+const CLAUDE_APPEND = 'claude-append.md';
+
+const TEXT_EXT = new Set([
+  '.md', '.json', '.js', '.ts', '.tsx', '.txt', '.yaml', '.yml',
+  '.sh', '.toml', '.gitignore', '.css', '.html',
+]);
+
+function isTextFile(name) {
+  if (name.startsWith('.')) return true; // dotfiles like .gitignore
+  const dot = name.lastIndexOf('.');
+  return dot >= 0 && TEXT_EXT.has(name.slice(dot));
+}
+
+export function readStageManifest(stageId) {
+  const file = join(STAGES_DIR, stageId, 'manifest.json');
+  if (!existsSync(file)) {
+    throw new Error(`Stage ${stageId} has no manifest.json (not authored yet).`);
+  }
+  return JSON.parse(readFileSync(file, 'utf8'));
+}
+
+function substituteInTree(dir, vars) {
+  for (const name of readdirSync(dir)) {
+    const full = join(dir, name);
+    if (statSync(full).isDirectory()) {
+      substituteInTree(full, vars);
+    } else if (isTextFile(name)) {
+      let body = readFileSync(full, 'utf8');
+      for (const [k, v] of Object.entries(vars)) {
+        body = body.replaceAll(`{{${k}}}`, v);
+      }
+      writeFileSync(full, body);
+    }
+  }
+}
+
+// Append a marked block to a file, once. Idempotent: keyed by a marker id, so
+// re-applying is a no-op. Creates the file from the block if absent. The marker
+// is an HTML comment (stripped from Claude's context, kept in the file).
+export function appendMarkedBlock(filePath, markerId, body) {
+  const startMark = `<!-- boss:${markerId} start -->`;
+  const endMark = `<!-- boss:${markerId} end -->`;
+  const existing = existsSync(filePath) ? readFileSync(filePath, 'utf8') : '';
+  if (existing.includes(startMark)) return false; // already applied
+  const block = `${startMark}\n${body.trim()}\n${endMark}\n`;
+  const sep = existing && !existing.endsWith('\n\n')
+    ? (existing.endsWith('\n') ? '\n' : '\n\n')
+    : '';
+  writeFileSync(filePath, existing + sep + block);
+  return true;
+}
+
+// Append a stage's claude-append.md block to the project's CLAUDE.md, once.
+export function appendClaudeBlock(stageId, targetDir, body) {
+  return appendMarkedBlock(join(targetDir, 'CLAUDE.md'), stageId, body);
+}
+
+// Recursive copy-if-absent: copy every template file that doesn't already exist
+// in the target, skipping (never clobbering) any the founder already has. The
+// non-destructive half of `boss adopt`. Records copied + skipped paths.
+function cpSafeTree(srcDir, destDir, copied, skipped) {
+  mkdirSync(destDir, { recursive: true });
+  for (const name of readdirSync(srcDir)) {
+    const s = join(srcDir, name);
+    const d = join(destDir, name);
+    if (statSync(s).isDirectory()) {
+      cpSafeTree(s, d, copied, skipped);
+    } else if (existsSync(d)) {
+      skipped.push(d);
+    } else {
+      cpSync(s, d);
+      copied.push(d);
+    }
+  }
+}
+
+// Adopt a stage into an EXISTING repo non-destructively: copy only files that
+// don't collide, substitute placeholders in just those (never touch the
+// founder's own files), and fold any claude-append.md block into CLAUDE.md.
+// Returns { copied, skipped, claudePreexisted, appendedClaude } for reporting.
+export function applyStageSafe(stageId, targetDir, vars) {
+  const templateDir = join(STAGES_DIR, stageId, 'template');
+  if (!existsSync(templateDir)) {
+    throw new Error(`Stage ${stageId} has no template/ dir (not authored yet).`);
+  }
+  const claudePreexisted = existsSync(join(targetDir, 'CLAUDE.md'));
+  const copied = [];
+  const skipped = [];
+  cpSafeTree(templateDir, targetDir, copied, skipped);
+
+  // Substitute placeholders only in the files we actually wrote.
+  for (const f of copied) {
+    if (!isTextFile(f.slice(f.lastIndexOf('/') + 1))) continue;
+    let body = readFileSync(f, 'utf8');
+    for (const [k, v] of Object.entries(vars)) body = body.replaceAll(`{{${k}}}`, v);
+    writeFileSync(f, body);
+  }
+
+  // Fold a stray claude-append.md (L1/L2 carry one) into CLAUDE.md, then remove it.
+  let appendedClaude = false;
+  const stray = join(targetDir, CLAUDE_APPEND);
+  if (existsSync(stray)) {
+    appendedClaude = appendClaudeBlock(stageId, targetDir, readFileSync(stray, 'utf8'));
+    rmSync(stray);
+  }
+  return { copied, skipped, claudePreexisted, appendedClaude };
+}
+
+// Copy a stage's template/ tree into targetDir and fill placeholders.
+// Returns { appendedClaude } so callers can report what changed.
+export function applyStage(stageId, targetDir, vars) {
+  const templateDir = join(STAGES_DIR, stageId, 'template');
+  if (!existsSync(templateDir)) {
+    throw new Error(`Stage ${stageId} has no template/ dir (not authored yet).`);
+  }
+  cpSync(templateDir, targetDir, { recursive: true });
+  substituteInTree(targetDir, vars);
+
+  // Handle the additive CLAUDE.md block: the file was copied into the project
+  // by cpSync; lift it out and fold it into CLAUDE.md instead of leaving it.
+  let appendedClaude = false;
+  const stray = join(targetDir, CLAUDE_APPEND);
+  if (existsSync(stray)) {
+    appendedClaude = appendClaudeBlock(stageId, targetDir, readFileSync(stray, 'utf8'));
+    rmSync(stray);
+  }
+  return { appendedClaude };
+}

package/src/sync.js

@@ -0,0 +1,292 @@
+import {
+  readFileSync, writeFileSync, existsSync, mkdirSync, readdirSync,
+} from 'node:fs';
+import { join, dirname } from 'node:path';
+import {
+  STAGES_DIR, bossVersion, resolveStageId,
+} from './paths.js';
+import { readStageManifest } from './scaffold.js';
+
+// Resolve a possibly-stale layer id (e.g. an old "L0-sketch" pin) to the
+// canonical current stage id by its level prefix. Returns undefined if it
+// can't be mapped at all.
+export function canonicalLayer(layerId) {
+  return (
+    resolveStageId(layerId) ||
+    resolveStageId((String(layerId).match(/^l\d+/i) || [])[0]) ||
+    undefined
+  );
+}
+
+// The files BOSS manages for a stage: one .md per agent, one SKILL.md per skill.
+// Each entry maps a source template file → its path inside the project.
+function managedFiles(stageId, manifest) {
+  const stageRoot = join(STAGES_DIR, stageId, 'template');
+  const base = join(stageRoot, '.claude');
+  const out = [];
+  for (const a of manifest.agents || []) {
+    out.push({
+      kind: 'agent',
+      name: a,
+      src: join(base, 'agents', `${a}.md`),
+      rel: join('.claude', 'agents', `${a}.md`),
+    });
+  }
+  for (const s of manifest.skills || []) {
+    out.push({
+      kind: 'skill',
+      name: s,
+      src: join(base, 'skills', s, 'SKILL.md'),
+      rel: join('.claude', 'skills', s, 'SKILL.md'),
+    });
+  }
+  for (const h of manifest.hooks || []) {
+    // Hook scripts may be .js (v0.18.0+ Node-based) or .sh (legacy). Prefer .js
+    // when present; fall back to .sh for backwards-compatibility with legacy stages.
+    const jsSrc = join(base, 'hooks', `${h}.js`);
+    const shSrc = join(base, 'hooks', `${h}.sh`);
+    const ext = existsSync(jsSrc) ? 'js' : 'sh';
+    out.push({
+      kind: 'hook',
+      name: h,
+      src: ext === 'js' ? jsSrc : shSrc,
+      rel: join('.claude', 'hooks', `${h}.${ext}`),
+    });
+  }
+  // Hook library files (helpers like loop-runtime, yaml parser) — non-manifest;
+  // discovered by scanning the template's hooks/lib/ dir if present.
+  const libDir = join(base, 'hooks', 'lib');
+  if (existsSync(libDir)) {
+    for (const f of readdirSync(libDir)) {
+      if (!f.endsWith('.js')) continue;
+      out.push({
+        kind: 'hook-lib',
+        name: f,
+        src: join(libDir, f),
+        rel: join('.claude', 'hooks', 'lib', f),
+      });
+    }
+  }
+  // Loop specs (IDEA-008, v0.18.0+) live in docs/loops/. Each is a managed
+  // markdown file with YAML frontmatter that the runtime parses.
+  for (const l of manifest.loops || []) {
+    out.push({
+      kind: 'loop',
+      name: l,
+      src: join(stageRoot, 'docs', 'loops', `${l}.md`),
+      rel: join('docs', 'loops', `${l}.md`),
+    });
+  }
+  return out;
+}
+
+// Hook *scripts* sync like any managed file (above). Their *registration* lives in
+// settings.json — a user-editable file — so we merge it in additively instead of
+// overwriting: BOSS owns the hook entries it ships, the user owns everything else
+// (permissions, their own hooks). Matched by command, so re-syncing is idempotent.
+function templateHooks(stageId) {
+  const f = join(STAGES_DIR, stageId, 'template', '.claude', 'settings.json');
+  if (!existsSync(f)) return {};
+  try { return JSON.parse(readFileSync(f, 'utf8')).hooks || {}; } catch { return {}; }
+}
+
+function eventCommands(entries) {
+  const cmds = new Set();
+  for (const entry of entries || []) {
+    for (const h of entry.hooks || []) if (h.command) cmds.add(h.command);
+  }
+  return cmds;
+}
+
+// One-time hook-command migrations: when BOSS refactors a hook (e.g. bash → node
+// in v0.18.0), existing projects need their old command entries replaced, not
+// merely supplemented (otherwise both old + new fire, and the old points at a
+// file that's been removed). Each migration matches the old command and either
+// rewrites or removes that entry. Keep the list short and dated — these are
+// load-bearing for in-the-wild projects.
+const HOOK_MIGRATIONS = [
+  {
+    // v0.18.0 — conscience hook moved from bash to node. The shipped file
+    // (conscience.sh) is no longer in the template; leaving its registration
+    // would mean Claude Code invokes a missing script. Drop the stale entry;
+    // the additive merge then registers the new node command.
+    matches: (cmd) => /conscience\.sh/i.test(cmd),
+    action: 'drop',
+    note: 'v0.18.0 migration: conscience hook moved from bash to node',
+  },
+];
+
+function applyHookMigrations(merged) {
+  if (!merged.hooks) return false;
+  let changed = false;
+  for (const event of Object.keys(merged.hooks)) {
+    const entries = merged.hooks[event] || [];
+    for (const entry of entries) {
+      const before = entry.hooks ? entry.hooks.length : 0;
+      entry.hooks = (entry.hooks || []).filter((h) => {
+        for (const m of HOOK_MIGRATIONS) {
+          if (m.matches(h.command || '')) return m.action !== 'drop';
+        }
+        return true;
+      });
+      if ((entry.hooks?.length || 0) !== before) changed = true;
+    }
+    // Remove empty entry containers (an entry with no hooks left).
+    merged.hooks[event] = entries.filter((e) => (e.hooks || []).length > 0);
+  }
+  return changed;
+}
+
+// Merge BOSS-owned hook registrations from the installed layers into the project's
+// settings.json. Returns { changed, merged, rel } — caller writes `merged` on apply.
+export function computeSettingsMerge(projectDir, layers) {
+  const rel = join('.claude', 'settings.json');
+  const dest = join(projectDir, rel);
+  let merged = {};
+  if (existsSync(dest)) {
+    try { merged = JSON.parse(readFileSync(dest, 'utf8')); } catch { merged = {}; }
+  }
+  let changed = false;
+  // Apply hook-command migrations first (e.g. v0.18.0 bash→node) so stale entries
+  // don't masquerade as already-present and block the new entry from being added.
+  if (applyHookMigrations(merged)) changed = true;
+  for (const stageId of layers) {
+    for (const [event, tEntries] of Object.entries(templateHooks(stageId))) {
+      merged.hooks ||= {};
+      merged.hooks[event] ||= [];
+      const present = eventCommands(merged.hooks[event]);
+      for (const entry of tEntries) {
+        const cmds = (entry.hooks || []).map((h) => h.command).filter(Boolean);
+        if (cmds.length && cmds.every((c) => present.has(c))) continue; // already registered
+        merged.hooks[event].push(JSON.parse(JSON.stringify(entry)));
+        cmds.forEach((c) => present.add(c));
+        changed = true;
+      }
+    }
+  }
+  return { changed, merged, rel };
+}
+
+function substitute(body, vars) {
+  for (const [k, v] of Object.entries(vars)) body = body.replaceAll(`{{${k}}}`, v);
+  return body;
+}
+
+// A cheap, dependency-free change signal: how many lines differ between two
+// versions (positional compare + length delta). Enough to flag a file as worth
+// reviewing; the /boss-sync skill does the real side-by-side read.
+function lineDelta(oldText, newText) {
+  const a = oldText.split('\n');
+  const b = newText.split('\n');
+  let diff = Math.abs(a.length - b.length);
+  for (let i = 0; i < Math.min(a.length, b.length); i++) {
+    if (a[i] !== b[i]) diff++;
+  }
+  return diff;
+}
+
+// Compute what a sync would do for a project, without writing anything.
+// Returns { entries, layers, pin, current, drift }.
+export function planSync(projectDir, stamp) {
+  const current = bossVersion();
+  const vars = {
+    PROJECT_NAME: stamp.name,
+    DATE: new Date().toISOString().slice(0, 10),
+    BOSS_VERSION: current,
+  };
+
+  // Canonicalize + dedupe the installed layers, preserving order.
+  const layers = [];
+  for (const raw of stamp.installedLayers || [stamp.stage]) {
+    const c = canonicalLayer(raw);
+    if (c && !layers.includes(c)) layers.push(c);
+  }
+
+  const entries = [];
+  for (const stageId of layers) {
+    let manifest;
+    try {
+      manifest = readStageManifest(stageId);
+    } catch {
+      continue; // stage not authored in this BOSS version — skip
+    }
+    for (const f of managedFiles(stageId, manifest)) {
+      if (!existsSync(f.src)) continue; // manifest lists it but template lacks it
+      const next = substitute(readFileSync(f.src, 'utf8'), {
+        ...vars, STAGE: stageId, MODE: manifest.name,
+      });
+      const dest = join(projectDir, f.rel);
+      const exists = existsSync(dest);
+      const cur = exists ? readFileSync(dest, 'utf8') : '';
+      let status = 'ok';
+      if (!exists) status = 'new';
+      else if (cur !== next) status = 'changed';
+      entries.push({ ...f, stageId, status, next, delta: exists ? lineDelta(cur, next) : 0 });
+    }
+  }
+
+  return {
+    entries,
+    layers,
+    pin: stamp.bossVersion,
+    current,
+    drift: stamp.bossVersion !== current,
+    settings: computeSettingsMerge(projectDir, layers),
+  };
+}
+
+// Apply a plan: write new/changed files and return the canonicalized stamp
+// fields the caller should persist (it owns writeStamp + registry).
+export function applySync(projectDir, plan, stamp) {
+  const written = [];
+  for (const e of plan.entries) {
+    if (e.status === 'ok') continue;
+    const dest = join(projectDir, e.rel);
+    mkdirSync(dirname(dest), { recursive: true });
+    writeFileSync(dest, e.next);
+    written.push(e);
+  }
+
+  // Merge BOSS-owned hook registrations into settings.json (additive — preserves
+  // the user's permissions and their own hooks).
+  if (plan.settings && plan.settings.changed) {
+    const dest = join(projectDir, plan.settings.rel);
+    mkdirSync(dirname(dest), { recursive: true });
+    writeFileSync(dest, JSON.stringify(plan.settings.merged, null, 2) + '\n');
+    written.push({ kind: 'settings', name: 'settings.json', rel: plan.settings.rel });
+  }
+
+  // Reconcile the stamp to current canonical layers + the union of their
+  // agents/skills/hooks/loops, and bump the pin. Mode/stage track the most-mature layer.
+  const agents = new Set();
+  const skills = new Set();
+  const hooks = new Set();
+  const loops = new Set();
+  for (const stageId of plan.layers) {
+    try {
+      const m = readStageManifest(stageId);
+      (m.agents || []).forEach((a) => agents.add(a));
+      (m.skills || []).forEach((s) => skills.add(s));
+      (m.hooks || []).forEach((h) => hooks.add(h));
+      (m.loops || []).forEach((l) => loops.add(l));
+    } catch { /* skip unauthored */ }
+  }
+  const top = plan.layers[plan.layers.length - 1];
+  let topMode = stamp.mode;
+  try { topMode = readStageManifest(top).name; } catch { /* keep */ }
+
+  return {
+    written,
+    stamp: {
+      ...stamp,
+      stage: top,
+      mode: topMode,
+      installedLayers: plan.layers,
+      agents: [...agents],
+      skills: [...skills],
+      hooks: [...hooks],
+      loops: [...loops],
+      bossVersion: plan.current,
+    },
+  };
+}