@stonepandastudio/cairn 0.5.0 → 0.6.0

package/README.md

@@ -24,11 +24,32 @@ npx cairn init --stack nestjs,typeorm --tracker jira-server --project-key MYPROJ
 | `cairn doctor` | Cross-repo drift report, plus per-repo generated-file state |
 | `cairn init` | Makes a repo cairn-managed: writes `cairn.config.json`, `_cairn/`, and the shim |
 | `cairn render` | Scaffolds `ai/` + `.claude/commands/` from the bundled presets, from the repo's stack + workflow |
+| `cairn sync` | Re-renders and three-way merges preset changes into a repo that has already rendered |
 
 `cairn render` is **greenfield only**: it writes files that do not exist, records them
-in the manifest, and leaves anything already on disk alone (reporting it). The
-three-way merge that would re-render over local edits — `cairn sync` — is not built
-yet; for a fresh repo there is nothing to merge.
+in the manifest, stores the render in `_cairn/base/`, and leaves anything already on
+disk alone (reporting it).
+
+`cairn sync` is the upgrade path. For each managed file it holds three versions —
+`base` (the last render, in `_cairn/base/`), `ours` (what is on disk), `theirs` (what
+the current presets render) — and runs a 2×2:
+
+| | template unchanged | template changed |
+|---|---|---|
+| **local unchanged** | no-op | fast-forward — write the new render |
+| **local changed** | keep local (`MODIFIED`) | three-way merge |
+
+Three cells are automatic. The merge shells out to `git merge-file`; a clean result
+is written, a conflicted one is written **with markers** and the command exits
+non-zero (`CONFLICT`, a fifth manifest state). Nothing is ever silently overwritten.
+Resolve the markers and run `cairn sync` again — the base has already advanced, so
+the second run is a quiet `MODIFIED`.
+
+```bash
+cairn sync --dry-run          # show the outcome per file, write nothing
+cairn sync                    # apply; exit 3 if any file is left in conflict
+cairn sync --adopt-base       # for files rendered before _cairn/base/ existed
+```
 
 ## The two folders
 
@@ -37,6 +58,7 @@ repo/
   cairn.config.json     you edit this. cairn only ever reads it.
   _cairn/               cairn writes this. nobody hand-edits it.
     manifest.json       what was generated, from which template, at which hash
+    base/               the last render of every managed file — `cairn sync`'s merge base
     scripts/jira.js     vendored tracker shim
   .claude/commands/     rendered from the workflow — one stub per step
   ai/
@@ -47,9 +69,10 @@ repo/
 ```
 
 `cairn render` seeds the rendered files once and records them in the manifest; it
-never rewrites a file you have edited (that is `cairn sync`, not built yet). The
-boundary is the whole design: hand-edited config living inside a generated directory
-is how generated directories acquire state nobody dares regenerate.
+never rewrites a file you have edited. `cairn sync` is what re-renders later preset
+changes over your edits, three-way merging where both moved. The boundary is the
+whole design: hand-edited config living inside a generated directory is how
+generated directories acquire state nobody dares regenerate.
 
 Generated files are **committed**, not gitignored. Claude Code discovers
 `.claude/commands/` and agent docs from disk, and a prompt change should show up in
@@ -132,12 +155,13 @@ match what is on disk?
 |---|---|
 | `MANAGED` | on-disk hash matches what cairn wrote |
 | `MODIFIED` | someone hand-edited a generated file |
-| `OUTDATED` | cairn has newer content for it — needs template hashes; comes with `cairn sync` |
-| `DELETED` | it is gone; a future `cairn sync` will restore it |
+| `OUTDATED` | cairn has newer content for it — needs template hashes threaded through |
+| `DELETED` | it is gone; `cairn sync` restores it from the current render |
+| `CONFLICT` | `cairn sync` left git merge markers in it — resolve, then sync again |
 
-Today the doctor reports `MANAGED`, `MODIFIED` and `DELETED`. `OUTDATED` (needs the
-template hashes threaded through) and `cairn sync` (the three-way merge that acts on
-these states) are still to come — `cairn render` is greenfield-only for now.
+Today the doctor reports `MANAGED`, `MODIFIED`, `DELETED` and `CONFLICT`. `OUTDATED`
+(needs the template hashes threaded through) is still to come. Acting on drift
+between the render and the working tree is `cairn sync`.
 
 A file can be perfectly in sync across repos while being hand-edited away from its
 template, and vice versa. `MODIFIED` outranks `OUTDATED` in the report because
@@ -174,6 +198,7 @@ lib/paint.js           ANSI + table rendering
 lib/tracker/           index (registry), cli, jira-server, youtrack, none
 lib/doctor/            index (analysis + report), scan, normalize, diff
 lib/render/            engine (a small template engine), index (driver), cli
+lib/sync/              index (the 2x2 + git merge-file), cli
 lib/init.js            cairn init
 templates/shims/       vendored shim source
 presets/               core/ + framework/ORM/styling presets rendered by `cairn render`
@@ -181,4 +206,5 @@ schema.json            JSON Schema for cairn.config.json
 test/run.js            dependency-free test runner
 ```
 
-No runtime dependencies. Node >= 18. `npm test` runs 61 tests.
+No runtime dependencies (`cairn sync` shells out to `git`). Node >= 18. `npm test`
+runs 74 tests.

package/bin/cairn.js

@@ -3,14 +3,12 @@
 
 // cairn — shared AI workflow scaffolding for Stone Panda repos.
 //
-// v1 surface:
+// Surface:
 //   cairn tracker <cmd>   issue tracker client (replaces the copied ai/scripts/jira.js)
 //   cairn doctor          cross-repo drift report
 //   cairn init            make a repo cairn-managed
-//
-// Template rendering (command stubs, WORKFLOW.md, agent role contracts) is v2 and
-// deliberately absent: this release swaps the Jira client under five repos, and
-// mixing that with prompt changes would make any regression unattributable.
+//   cairn render          scaffold ai/ from the bundled presets (greenfield)
+//   cairn sync            three-way merge of preset changes into a rendered repo
 
 const HELP = `cairn — shared AI workflow scaffolding
 
@@ -20,6 +18,7 @@ Usage: cairn <command> [options]
   doctor [options]      cross-repo drift report (cairn doctor --help)
   init [options]        make a repo cairn-managed (cairn init --help)
   render [options]      scaffold ai/ from the bundled presets (cairn render --help)
+  sync [options]        merge preset changes into an already-rendered repo (cairn sync --help)
   version               print version
 
 Run \`cairn <command> --help\` for command options.
@@ -45,6 +44,10 @@ function main() {
       process.exitCode = require('../lib/render/cli').main(rest);
       return;
 
+    case 'sync':
+      process.exitCode = require('../lib/sync/cli').main(rest);
+      return;
+
     case 'version':
     case '--version':
     case '-v':

package/lib/doctor/index.js

@@ -40,6 +40,7 @@ const MANAGED_COLOR = {
   OUTDATED: 'yellow',
   MODIFIED: 'red',
   DELETED: 'magenta',
+  CONFLICT: 'red',
 };
 
 // ------------------------------------------------------------------ workspace
@@ -510,7 +511,11 @@ function main(argv = process.argv.slice(2)) {
       .flatMap((s) => s.files)
       .some((f) => f.status === 'DRIFT' || f.status === 'MISSING' || f.status === 'STRANDED');
     const broken = managed.some(
-      (m) => m.error || m.files.some((f) => f.state === 'MODIFIED' || f.state === 'DELETED'),
+      (m) =>
+        m.error ||
+        m.files.some(
+          (f) => f.state === 'MODIFIED' || f.state === 'DELETED' || f.state === 'CONFLICT',
+        ),
     );
     if (drifted || broken) return 1;
   }

package/lib/init.js

@@ -9,6 +9,7 @@ const {
   readManifest,
   record,
   writeManifest,
+  writeBase,
   manifestPath,
   hashContent,
 } = require('./manifest');
@@ -210,7 +211,10 @@ function main(argv = process.argv.slice(2)) {
     fs.writeFileSync(abs, content, 'utf8');
     // cairn.config.json is hand-editable, so it is deliberately not manifested —
     // tracking it would report every legitimate edit as MODIFIED.
-    if (source) record(manifest, rel, source, content);
+    if (source) {
+      record(manifest, rel, source, content);
+      writeBase(repoPath, rel, content);
+    }
   }
   writeManifest(repoPath, manifest);
 

package/lib/manifest.js

@@ -21,11 +21,37 @@ const GENERATOR = require('../package.json').name;
 //   MODIFIED  on-disk hash !== written hash            someone edited it by hand
 //   OUTDATED  written hash !== current template hash   cairn has newer content
 //   DELETED   file is gone                             sync will restore it
+//   CONFLICT  entry.conflict is set                    `cairn sync` left merge markers
+//
+// `_cairn/base/<relPath>` holds the bytes of the last clean template render for
+// each managed file — the merge base `cairn sync` diffs against. The manifest
+// hash is "what is on disk after the last cairn write"; the base file is "what
+// the template produced". They diverge once a merge folds local edits back in.
 
 function manifestPath(repoPath) {
   return path.join(cairnDir(repoPath), MANIFEST_NAME);
 }
 
+const BASE_DIR = 'base';
+
+function basePath(repoPath, relPath) {
+  return path.join(cairnDir(repoPath), BASE_DIR, relPath.replace(/\\/g, '/'));
+}
+
+// The last clean template render for `relPath`. `cairn render` and `cairn init`
+// write it alongside the real file; `cairn sync` reads it as the merge base and
+// rewrites it on every fast-forward or clean merge.
+function readBase(repoPath, relPath) {
+  const file = basePath(repoPath, relPath);
+  return fs.existsSync(file) ? fs.readFileSync(file, 'utf8') : null;
+}
+
+function writeBase(repoPath, relPath, content) {
+  const file = basePath(repoPath, relPath);
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  fs.writeFileSync(file, content, 'utf8');
+}
+
 // Normalize before hashing so a CRLF checkout doesn't read as a hand edit. This
 // matters here specifically: these repos are Windows-side with mixed .gitattributes.
 function hashContent(text) {
@@ -83,6 +109,10 @@ function statusFor(repoPath, manifest, templateHashes = null) {
       continue;
     }
     const onDisk = hashContent(fs.readFileSync(abs, 'utf8'));
+    if (entry.conflict) {
+      results.push({ path: rel, source: entry.source, state: 'CONFLICT' });
+      continue;
+    }
     if (onDisk !== entry.hash) {
       results.push({ path: rel, source: entry.source, state: 'MODIFIED' });
       continue;
@@ -109,12 +139,15 @@ module.exports = {
   CAIRN_DIR,
   MANIFEST_NAME,
   MANIFEST_VERSION,
+  basePath,
   emptyManifest,
   hashContent,
   header,
   manifestPath,
+  readBase,
   readManifest,
   record,
   statusFor,
+  writeBase,
   writeManifest,
 };

package/lib/render/cli.js

@@ -4,7 +4,14 @@ const fs = require('fs');
 const path = require('path');
 
 const { loadRepoConfig, findRepoRoot, ConfigError } = require('../config');
-const { readManifest, emptyManifest, record, writeManifest, manifestPath } = require('../manifest');
+const {
+  readManifest,
+  emptyManifest,
+  record,
+  writeManifest,
+  writeBase,
+  manifestPath,
+} = require('../manifest');
 const { makePaint } = require('../paint');
 const { planRender } = require('./index');
 
@@ -63,6 +70,9 @@ function renderInto(repoPath, { dryRun = false, paint } = {}) {
     fs.mkdirSync(path.dirname(abs), { recursive: true });
     fs.writeFileSync(abs, content, 'utf8');
     record(manifest, rel, source, content);
+    // The merge base `cairn sync` will diff against: what the template produced,
+    // verbatim, this run.
+    writeBase(repoPath, rel, content);
     console.log(`  ${paint.green('wrote')}  ${rel}`);
     wrote++;
   }

package/lib/render/index.js

@@ -129,11 +129,11 @@ function codeGuidelines(stack, presetsDir, ctx, resolvePartial) {
   return blocks.length ? blocks.join('\n\n---\n\n') + '\n' : null;
 }
 
-// Returns { planned: [[rel, content, source, note?]], kept: [{ rel, reason }] }.
-// `manifest` + `repoPath` drive the greenfield guard: a file cairn has not
-// written is never touched, and one it wrote but a human has since edited is
-// kept and reported (the re-render that respects local edits is `cairn sync`).
-function planRender({ config, presetsDir, manifest = { files: {} }, repoPath = null }) {
+// Every file the presets would produce for this config, as
+// [[rel, content, source, note?]] — before any greenfield or manifest guard.
+// `planRender` filters this for `cairn render`; `cairn sync` diffs each entry
+// against the repo's manifest + `_cairn/base/`.
+function renderTargets({ config, presetsDir }) {
   const ctx = buildContext(config, presetsDir);
   const resolvePartial = makeResolvePartial(ctx.stack, presetsDir);
 
@@ -176,10 +176,20 @@ function planRender({ config, presetsDir, manifest = { files: {} }, repoPath = n
       'ai/infrastructure/code-guidelines.md',
       guidelines,
       'presets:<stack>/code-guidelines.md',
-      'seed — fork it, cairn will not re-render over your edits',
+      'seed — fork it; `cairn sync` will three-way merge later changes',
     ]);
   }
 
+  return { targets, context: ctx };
+}
+
+// Returns { planned: [[rel, content, source, note?]], kept: [{ rel, reason }] }.
+// `manifest` + `repoPath` drive the greenfield guard: a file cairn has not
+// written is never touched, and one it wrote but a human has since edited is
+// kept and reported (the re-render that respects local edits is `cairn sync`).
+function planRender({ config, presetsDir, manifest = { files: {} }, repoPath = null }) {
+  const { targets, context: ctx } = renderTargets({ config, presetsDir });
+
   const planned = [];
   const kept = [];
   for (const [rel, content, source, note] of targets) {
@@ -207,4 +217,4 @@ function planRender({ config, presetsDir, manifest = { files: {} }, repoPath = n
   return { planned, kept, context: ctx };
 }
 
-module.exports = { planRender, buildContext, trackerContext, DEFAULT_WORKFLOW };
+module.exports = { planRender, renderTargets, buildContext, trackerContext, DEFAULT_WORKFLOW };

package/lib/sync/cli.js

@@ -0,0 +1,197 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+const { loadRepoConfig, findRepoRoot, ConfigError } = require('../config');
+const {
+  readManifest,
+  record,
+  writeManifest,
+  writeBase,
+  manifestPath,
+} = require('../manifest');
+const { makePaint } = require('../paint');
+const { planSync, OUTCOME } = require('./index');
+
+const PRESETS_DIR = path.join(__dirname, '..', '..', 'presets');
+
+const HELP = `cairn sync — propagate preset changes into an already-rendered repo
+
+Usage: cairn sync [options]
+
+  --repo <path>    repo to sync (default: the repo cairn.config.json is in)
+  --dry-run        print the 2x2 outcome per file, write nothing
+  --adopt-base     for files rendered before cairn tracked a merge base and
+                   hand-edited since: accept the current file as the base
+                   (you lose the ability to merge upstream changes to it)
+  --no-color       disable ANSI colour
+
+Runs a three-way merge per managed file: base (what the template rendered last
+time, in _cairn/base/), ours (what is on disk), theirs (what the current presets
+render). Clean results are written; a conflict is written with git markers and
+exits non-zero. Nothing is ever silently overwritten.
+`;
+
+const COLOR = {
+  [OUTCOME.UNCHANGED]: 'dim',
+  [OUTCOME.MODIFIED]: 'yellow',
+  [OUTCOME.CREATED]: 'green',
+  [OUTCOME.FAST_FORWARD]: 'green',
+  [OUTCOME.MERGED]: 'green',
+  [OUTCOME.RESTORED]: 'green',
+  [OUTCOME.CONFLICT]: 'red',
+  [OUTCOME.ORPHANED]: 'magenta',
+  [OUTCOME.NO_BASE]: 'red',
+};
+
+function parseArgs(argv) {
+  const args = { repo: null, dryRun: false, adoptBase: false, color: process.stdout.isTTY };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === '--repo') args.repo = argv[++i];
+    else if (a === '--dry-run') args.dryRun = true;
+    else if (a === '--adopt-base') args.adoptBase = true;
+    else if (a === '--no-color') args.color = false;
+    else if (a === '-h' || a === '--help') args.help = true;
+    else {
+      console.error(`Unknown argument: ${a}`);
+      return { error: 2 };
+    }
+  }
+  return args;
+}
+
+// Apply a plan to disk. Returns the count of files left in conflict.
+function applyPlan(repoPath, manifest, actions, paint) {
+  let conflicts = 0;
+  let changed = false;
+  for (const act of actions) {
+    if (act.write !== undefined) {
+      const abs = path.join(repoPath, act.rel);
+      fs.mkdirSync(path.dirname(abs), { recursive: true });
+      fs.writeFileSync(abs, act.write, 'utf8');
+    }
+    // record() rebuilds the entry, so it drops any stale `conflict` flag; set the
+    // fresh one back afterwards.
+    if (act.write !== undefined && act.source !== undefined) {
+      record(manifest, act.rel, act.source, act.write);
+      changed = true;
+    }
+    if (act.base !== undefined) writeBase(repoPath, act.rel, act.base);
+    if (act.conflict) {
+      manifest.files[act.rel].conflict = true;
+      conflicts++;
+      changed = true;
+    } else if (act.clearConflict && manifest.files[act.rel] && manifest.files[act.rel].conflict) {
+      delete manifest.files[act.rel].conflict;
+      changed = true;
+    }
+    printAction(act, paint);
+  }
+  return { conflicts, changed };
+}
+
+function printAction(act, paint) {
+  const tag = paint[COLOR[act.outcome] || 'dim'](act.outcome.padEnd(12));
+  const detail = act.detail ? paint.dim(`  ${act.detail}`) : '';
+  console.log(`  ${tag}  ${act.rel}${detail}`);
+}
+
+function main(argv = process.argv.slice(2)) {
+  const args = parseArgs(argv);
+  if (args.error) return args.error;
+  if (args.help) {
+    process.stdout.write(HELP);
+    return 0;
+  }
+
+  const paint = makePaint(args.color);
+  const start = args.repo ? path.resolve(args.repo) : process.cwd();
+  const repoPath = args.repo ? start : findRepoRoot(start);
+  if (!repoPath || !fs.existsSync(path.join(repoPath, 'cairn.config.json'))) {
+    console.error('No cairn.config.json found — run `cairn init` first');
+    return 2;
+  }
+
+  const manifest = readManifest(repoPath);
+  if (!manifest || !Object.keys(manifest.files).length) {
+    console.error('Nothing to sync — this repo has no cairn manifest. Run `cairn render` first.');
+    return 2;
+  }
+
+  let plan;
+  try {
+    const config = loadRepoConfig(repoPath, { required: true });
+    plan = planSync({ config, presetsDir: PRESETS_DIR, manifest, repoPath, adoptBase: args.adoptBase });
+  } catch (e) {
+    if (e instanceof ConfigError) {
+      console.error(e.message);
+      return 2;
+    }
+    throw e;
+  }
+
+  if (args.dryRun) {
+    console.log(paint.bold(`cairn sync --dry-run  ${repoPath}`));
+    for (const act of plan.actions) printAction(act, paint);
+    const conflicts = plan.actions.filter((a) => a.outcome === OUTCOME.CONFLICT).length;
+    const noBase = plan.actions.filter((a) => a.outcome === OUTCOME.NO_BASE).length;
+    console.log('');
+    console.log(summary(plan.actions, paint));
+    return conflicts || noBase ? 3 : 0;
+  }
+
+  console.log(paint.bold(`cairn sync  ${repoPath}`));
+  const { conflicts, changed } = applyPlan(repoPath, manifest, plan.actions, paint);
+  const noBase = plan.actions.filter((a) => a.outcome === OUTCOME.NO_BASE).length;
+
+  if (changed) {
+    writeManifest(repoPath, manifest);
+    console.log(
+      `  ${paint.green('wrote')}  ${path
+        .relative(repoPath, manifestPath(repoPath))
+        .replace(/\\/g, '/')}`,
+    );
+  }
+
+  console.log('');
+  console.log(summary(plan.actions, paint));
+
+  if (conflicts) {
+    console.log('');
+    console.log(
+      paint.red(`  ${conflicts} file(s) left with conflict markers`) +
+        paint.dim(' — resolve them, then run `cairn sync` again'),
+    );
+  }
+  if (noBase) {
+    console.log(
+      paint.red(`  ${noBase} file(s) have no merge base`) +
+        paint.dim(' — re-run with --adopt-base once you have reviewed them'),
+    );
+  }
+  return conflicts || noBase ? 3 : 0;
+}
+
+function summary(actions, paint) {
+  const counts = {};
+  for (const a of actions) counts[a.outcome] = (counts[a.outcome] || 0) + 1;
+  const order = [
+    OUTCOME.CREATED,
+    OUTCOME.FAST_FORWARD,
+    OUTCOME.MERGED,
+    OUTCOME.RESTORED,
+    OUTCOME.MODIFIED,
+    OUTCOME.UNCHANGED,
+    OUTCOME.ORPHANED,
+    OUTCOME.NO_BASE,
+    OUTCOME.CONFLICT,
+  ];
+  const parts = order
+    .filter((k) => counts[k])
+    .map((k) => paint[COLOR[k] || 'dim'](`${k} ${counts[k]}`));
+  return paint.bold('Summary') + '\n  ' + (parts.join('   ') || paint.dim('nothing managed'));
+}
+
+module.exports = { main, applyPlan, HELP, PRESETS_DIR };

package/lib/sync/index.js

@@ -0,0 +1,249 @@
+'use strict';
+
+// cairn sync — propagate preset changes into a repo that has already rendered.
+//
+// `cairn render` is greenfield: it writes files that do not exist and never
+// touches one again. `cairn sync` is the upgrade path. For every managed file it
+// holds three versions —
+//
+//   base    what the template rendered last time      (_cairn/base/<rel>)
+//   ours    what is on disk now                        (the repo's edits)
+//   theirs  what the current presets render
+//
+// — and runs a 2x2:
+//
+//                  template unchanged     template changed
+//   local unchanged   no-op                fast-forward (write theirs)
+//   local changed     keep local (MODIFIED)  three-way merge
+//
+// Three cells are automatic. The bottom-right shells out to `git merge-file`;
+// a clean merge is applied, a conflicted one is written with markers and stops
+// the command with a non-zero exit. Nothing is ever silently overwritten.
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const { spawnSync } = require('child_process');
+
+const { hashContent, readBase } = require('../manifest');
+const render = require('../render');
+
+const SHIM_SOURCE = 'shims/jira.js';
+
+// Outcomes, most-benign first. CONFLICT and NO_BASE are the non-zero exits.
+const OUTCOME = {
+  UNCHANGED: 'unchanged',
+  MODIFIED: 'modified',
+  CREATED: 'created',
+  FAST_FORWARD: 'fast-forward',
+  MERGED: 'merged',
+  RESTORED: 'restored',
+  CONFLICT: 'CONFLICT',
+  ORPHANED: 'orphaned',
+  NO_BASE: 'no base',
+};
+
+function templatesDir() {
+  return path.join(__dirname, '..', '..', 'templates');
+}
+
+// `theirs` for a manifest entry: the preset-rendered file when the presets still
+// emit that path, the vendored template for a tracker shim, or null when neither
+// applies any more (the stack changed and this preset dropped out).
+function resolveTheirs(entry, rel, targetsByRel) {
+  const hit = targetsByRel.get(rel);
+  if (hit) return { content: hit.content, source: hit.source };
+  if (entry.source === SHIM_SOURCE) {
+    const file = path.join(templatesDir(), SHIM_SOURCE);
+    if (fs.existsSync(file)) return { content: fs.readFileSync(file, 'utf8'), source: SHIM_SOURCE };
+  }
+  return null;
+}
+
+// git merge-file --diff3, ours/base/theirs on disk, merged text on stdout. Exit
+// code is the conflict count (0 = clean); a negative code means git failed.
+function gitMergeFile(ours, base, theirs) {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'cairn-merge-'));
+  const write = (name, body) => {
+    const p = path.join(dir, name);
+    fs.writeFileSync(p, body, 'utf8');
+    return p;
+  };
+  try {
+    const res = spawnSync(
+      'git',
+      [
+        'merge-file',
+        '-p',
+        '--diff3',
+        '-L',
+        'ours (your edits)',
+        '-L',
+        'base (cairn wrote this)',
+        '-L',
+        'theirs (new template)',
+        write('ours', ours),
+        write('base', base),
+        write('theirs', theirs),
+      ],
+      { encoding: 'utf8' },
+    );
+    if (res.error && res.error.code === 'ENOENT') {
+      return { ok: false, reason: 'git is not on PATH — cairn sync needs it for the merge step' };
+    }
+    if (typeof res.status !== 'number' || res.status < 0) {
+      return { ok: false, reason: (res.stderr || 'git merge-file failed').trim() };
+    }
+    return { ok: true, merged: res.stdout, conflicts: res.status };
+  } finally {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+}
+
+// One decision per managed file. Returns an action describing what the caller
+// should write; it performs no IO of its own beyond reading ours/base.
+function planFile(rel, entry, repoPath, targetsByRel, { adoptBase }) {
+  const theirs = resolveTheirs(entry, rel, targetsByRel);
+  const absOurs = path.join(repoPath, rel);
+  const ours = fs.existsSync(absOurs) ? fs.readFileSync(absOurs, 'utf8') : null;
+
+  if (!theirs) {
+    return { rel, outcome: OUTCOME.ORPHANED, detail: 'the presets no longer emit this path' };
+  }
+
+  if (ours === null) {
+    // Deleted locally — nothing to preserve, put the current render back.
+    return {
+      rel,
+      outcome: OUTCOME.RESTORED,
+      detail: 'was deleted',
+      write: theirs.content,
+      base: theirs.content,
+      source: theirs.source,
+    };
+  }
+
+  let base = readBase(repoPath, rel);
+  let seededBase = false;
+  if (base === null) {
+    if (hashContent(ours) === entry.hash) {
+      // Untouched since cairn wrote it — the on-disk bytes are a faithful base.
+      base = ours;
+      seededBase = true;
+    } else if (adoptBase) {
+      base = ours;
+      seededBase = true;
+    } else {
+      return {
+        rel,
+        outcome: OUTCOME.NO_BASE,
+        detail: 'rendered before base tracking and edited since — pass --adopt-base or reconcile by hand',
+      };
+    }
+  }
+
+  const hOurs = hashContent(ours);
+  const hBase = hashContent(base);
+  const hTheirs = hashContent(theirs.content);
+  const localChanged = hOurs !== hBase;
+  const templateChanged = hTheirs !== hBase;
+  const hasMarkers = /^<{7} /m.test(ours) && /^>{7} /m.test(ours);
+
+  if (!templateChanged) {
+    // The template has already been folded into the base — anything left is a
+    // local edit. Clear a stale conflict flag once the markers are gone.
+    const unresolved = entry.conflict && hasMarkers;
+    return {
+      rel,
+      outcome: localChanged ? OUTCOME.MODIFIED : OUTCOME.UNCHANGED,
+      detail: unresolved
+        ? 'conflict markers still in the file — resolve them'
+        : localChanged
+          ? 'local edits, template steady — kept'
+          : null,
+      // Persist a base we only inferred this run, so the next sync is cheap.
+      base: seededBase ? base : undefined,
+      clearConflict: entry.conflict && !unresolved,
+    };
+  }
+
+  if (!localChanged) {
+    return {
+      rel,
+      outcome: OUTCOME.FAST_FORWARD,
+      detail: `template moved ${diffMagnitude(base, theirs.content)}`,
+      write: theirs.content,
+      base: theirs.content,
+      source: theirs.source,
+      clearConflict: true,
+    };
+  }
+
+  const merge = gitMergeFile(ours, base, theirs.content);
+  if (!merge.ok) {
+    return { rel, outcome: OUTCOME.CONFLICT, detail: merge.reason };
+  }
+  if (merge.conflicts === 0) {
+    return {
+      rel,
+      outcome: OUTCOME.MERGED,
+      detail: 'local edits + template changes combined cleanly',
+      write: merge.merged,
+      base: theirs.content,
+      source: theirs.source,
+      clearConflict: true,
+    };
+  }
+  // Write the markers, and advance the base to `theirs` so the next run treats
+  // whatever the human leaves behind as a plain local edit rather than merging
+  // the same template change a second time.
+  return {
+    rel,
+    outcome: OUTCOME.CONFLICT,
+    detail: `${merge.conflicts} conflict${merge.conflicts === 1 ? '' : 's'} — markers written, resolve then re-run`,
+    write: merge.merged,
+    base: theirs.content,
+    source: theirs.source,
+    conflict: true,
+  };
+}
+
+function diffMagnitude(a, b) {
+  const la = a.split('\n').length;
+  const lb = b.split('\n').length;
+  const d = lb - la;
+  if (d === 0) return '(same length)';
+  return d > 0 ? `(+${d} lines)` : `(${d} lines)`;
+}
+
+// Plan a sync for the whole repo. Pure except for reading ours/base and invoking
+// `git merge-file`; the caller writes the files and the manifest.
+function planSync({ config, presetsDir, manifest, repoPath, adoptBase = false }) {
+  const { targets } = render.renderTargets({ config, presetsDir });
+  const targetsByRel = new Map(targets.map(([rel, content, source]) => [rel, { content, source }]));
+
+  const actions = [];
+  for (const [rel, entry] of Object.entries(manifest.files)) {
+    actions.push(planFile(rel, entry, repoPath, targetsByRel, { adoptBase }));
+  }
+
+  // Brand-new preset files: a manifested repo that predates a preset addition.
+  // Same greenfield guard as `cairn render` — write it only if nothing is there.
+  for (const [rel, content, source] of targets) {
+    if (manifest.files[rel]) continue;
+    if (fs.existsSync(path.join(repoPath, rel))) continue;
+    actions.push({
+      rel,
+      outcome: OUTCOME.CREATED,
+      detail: 'new preset file',
+      write: content,
+      base: content,
+      source,
+    });
+  }
+
+  actions.sort((a, b) => a.rel.localeCompare(b.rel));
+  return { actions };
+}
+
+module.exports = { planSync, planFile, gitMergeFile, OUTCOME };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stonepandastudio/cairn",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "description": "Shared AI workflow scaffolding for Stone Panda repos — issue tracker client and drift doctor.",
   "license": "UNLICENSED",
   "repository": {