@crouton-kit/crouter 0.3.28 → 0.3.29

package/dist/core/skill-sync/engine.js

@@ -0,0 +1,633 @@
+/**
+ * Reconcile engine (Phase P6) — the single, per-pair, direction-agnostic
+ * reconcile for bidirectional crtr ↔ Claude skill sync.
+ *
+ * `reconcilePair` is the ONLY reconcile routine (R-U3): there is no forward
+ * path + reverse path. Body and asset reconciliation is a symmetric 3-way merge
+ * (base = snapshot, ours = crtr, theirs = claude); frontmatter is the only
+ * asymmetric axis and all of that asymmetry lives in the translation profile
+ * (P5). The snapshot (P3) is the sole change-detector (R-U4): nothing here reads
+ * mtimes, fingerprints, or a stamp file.
+ *
+ * Strictness (R-U6): a conflict — overlapping body/asset merge, a both-sides
+ * non-equivalent frontmatter divergence, an asset deleted-on-one ∧ edited-on-the
+ * other, or a first-sync divergence with no common base — writes NOTHING for the
+ * pair, leaves both endpoints + the snapshot byte-untouched, and surfaces a
+ * git-style conflict report. There is no "best-effort" partial write and no
+ * silent side-pick.
+ *
+ * `--dry-run` (R-O1): every merge is computed and the would-be status returned,
+ * but no endpoint file, snapshot, or conflict report is touched.
+ */
+import { spawnSync } from 'node:child_process';
+import { existsSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, rmSync, writeFileSync, } from 'node:fs';
+import { homedir, tmpdir } from 'node:os';
+import { dirname, join, relative, sep } from 'node:path';
+import { stringify as stringifyYaml } from 'yaml';
+import { usage } from '../errors.js';
+import { parseFrontmatterGeneric } from '../frontmatter.js';
+import { findPluginByName } from '../resolver.js';
+import { resolveClaudePluginInstallPath } from './claude-plugins.js';
+import { findProjectScopeRoot, pluginMemoryDir, scopeMemoryDir, } from '../scope.js';
+import { SKILLS_DIR, SKILL_ENTRY_FILE } from '../../types.js';
+import { clearConflictReport, readSnapshot, snapshotDir, writeConflictReport, writeSnapshot, } from './snapshot.js';
+/**
+ * Reconcile a single enrolled pair (R-E2). Resolves both endpoints, loads (or
+ * seeds) the snapshot, 3-way merges body + assets and translate-and-owns the
+ * frontmatter, then either writes through cleanly to both sides or reports the
+ * conflict and skips. Never throws on a *content* conflict (that is a reported
+ * outcome); throws only on a structural/configuration error (an unresolvable
+ * endpoint, both endpoints missing) so the caller surfaces it as a hard stop.
+ */
+export function reconcilePair(pair, profile, opts) {
+    const crtrDir = resolveCrtrBundleDir(pair.crtr);
+    const claudeDir = resolveClaudeBundleDir(pair.claude);
+    const crtr = readSide(crtrDir);
+    const claude = readSide(claudeDir);
+    const snapshot = readSnapshot(pair.id);
+    if (snapshot === null) {
+        return seed(pair, profile, opts, crtr, claude, crtrDir, claudeDir);
+    }
+    return reconcileWithBase(pair, profile, opts, snapshot, crtr, claude, crtrDir, claudeDir);
+}
+// ── Endpoint resolution (§Resolved-here-6) ───────────────────────────────────
+/** crtr endpoint → its bundle dir `<memoryDir>/<name>/`. */
+function resolveCrtrBundleDir(ep) {
+    let memoryDir;
+    if (ep.scope === 'plugin') {
+        const plugin = findPluginByName(ep.plugin);
+        if (!plugin) {
+            throw usage(`skill-sync: crtr plugin "${ep.plugin}" not installed`);
+        }
+        memoryDir = pluginMemoryDir(plugin);
+    }
+    else if (ep.scope === 'user' || ep.scope === 'project') {
+        memoryDir = scopeMemoryDir(ep.scope);
+    }
+    else {
+        throw usage(`skill-sync: scope "${ep.scope}" is not valid for a crtr endpoint ` +
+            `(use user, project, or plugin)`);
+    }
+    if (!memoryDir) {
+        throw usage(`skill-sync: no crtr ${ep.scope} memory dir available for "${ep.name}"`);
+    }
+    return join(memoryDir, ep.name);
+}
+/** Claude endpoint → its bundle dir `<skillsRoot>/<name>/`. The per-scope Claude
+ *  skills roots: user `~/.claude/skills`, project `<proj>/.claude/skills`, and
+ *  `claude-plugin` the owning plugin's actual install path
+ *  `<installPath>/skills` (resolved from Claude's own registry, in place — no
+ *  user-scope copy). */
+function resolveClaudeBundleDir(ep) {
+    let skillsRoot;
+    if (ep.scope === 'user') {
+        skillsRoot = join(homedir(), '.claude', SKILLS_DIR);
+    }
+    else if (ep.scope === 'project') {
+        const projScopeRoot = findProjectScopeRoot();
+        if (!projScopeRoot) {
+            throw usage(`skill-sync: no project scope for Claude endpoint "${ep.name}"`);
+        }
+        // `<proj>/.crouter` → the project dir is its parent; Claude skills sit at
+        // `<proj>/.claude/skills`.
+        skillsRoot = join(dirname(projScopeRoot), '.claude', SKILLS_DIR);
+    }
+    else if (ep.scope === 'claude-plugin') {
+        skillsRoot = join(resolveClaudePluginInstallPath(ep.plugin), SKILLS_DIR);
+    }
+    else {
+        throw usage(`skill-sync: scope "${ep.scope}" is not valid for a Claude endpoint ` +
+            `(use user, project, or claude-plugin)`);
+    }
+    return join(skillsRoot, ep.name);
+}
+const EMPTY_SIDE = {
+    exists: false,
+    rawFrontmatter: '',
+    frontmatter: null,
+    body: '',
+    assets: new Map(),
+};
+function readSide(bundleDir) {
+    const skillPath = join(bundleDir, SKILL_ENTRY_FILE);
+    if (!existsSync(skillPath))
+        return { ...EMPTY_SIDE, assets: new Map() };
+    const parsed = parseFrontmatterGeneric(readFileSync(skillPath, 'utf8'));
+    return {
+        exists: true,
+        rawFrontmatter: parsed.raw,
+        frontmatter: parsed.data,
+        body: parsed.body,
+        assets: readBundleAssets(bundleDir),
+    };
+}
+/** Every file under `bundleDir` EXCEPT the top-level SKILL.md, keyed by POSIX
+ *  relpath. Mirrors the snapshot store's asset-map key shape. */
+function readBundleAssets(bundleDir) {
+    const out = new Map();
+    const walk = (cur) => {
+        let entries;
+        try {
+            entries = readdirSync(cur, { withFileTypes: true });
+        }
+        catch {
+            return;
+        }
+        for (const entry of entries) {
+            const full = join(cur, entry.name);
+            if (entry.isDirectory()) {
+                walk(full);
+            }
+            else if (entry.isFile()) {
+                const rel = relative(bundleDir, full).split(sep).join('/');
+                if (rel === SKILL_ENTRY_FILE)
+                    continue; // the doc, not an asset
+                out.set(rel, readFileSync(full));
+            }
+        }
+    };
+    walk(bundleDir);
+    return out;
+}
+// ── Frontmatter field access ─────────────────────────────────────────────────
+const CRTR_WHENWHY = 'when-and-why-to-read';
+const CRTR_SHORTFORM = 'short-form';
+const CLAUDE_DESC = 'description';
+function strField(rec, key) {
+    if (!rec)
+        return undefined;
+    const v = rec[key];
+    if (v === undefined || v === null)
+        return undefined;
+    return typeof v === 'string' ? v : String(v);
+}
+function readCrtrFm(side) {
+    return {
+        whenAndWhy: strField(side.frontmatter, CRTR_WHENWHY),
+        shortForm: strField(side.frontmatter, CRTR_SHORTFORM),
+    };
+}
+function readClaudeDesc(side) {
+    return strField(side.frontmatter, CLAUDE_DESC);
+}
+function sameStr(a, b) {
+    return (a ?? undefined) === (b ?? undefined);
+}
+function sameCrtrFm(a, b) {
+    return sameStr(a.whenAndWhy, b.whenAndWhy) && sameStr(a.shortForm, b.shortForm);
+}
+/**
+ * 3-way the single translatable concept (description ↔ when-and-why/short-form)
+ * against the recorded `meta.json` base (R-E4). Owned fields are never touched
+ * here — each side reads them through, so they appear in neither input nor
+ * output (R-X2). Equivalence (OD-1) is round-trip equality through the canonical
+ * Claude side.
+ */
+function resolveFrontmatter(profile, meta, crtrCur, claudeCur) {
+    const baseCrtr = {
+        whenAndWhy: meta.crtrFrontmatter.whenAndWhy,
+        shortForm: meta.crtrFrontmatter.shortForm,
+    };
+    const baseClaude = meta.claudeFrontmatter.description;
+    const crtrChanged = !sameCrtrFm(crtrCur, baseCrtr);
+    const claudeChanged = !sameStr(claudeCur, baseClaude);
+    if (!crtrChanged && !claudeChanged) {
+        return { crtr: crtrCur, claudeDesc: claudeCur };
+    }
+    if (crtrChanged && !claudeChanged) {
+        // crtr is the sole edit → translate it onto the Claude side.
+        return { crtr: crtrCur, claudeDesc: translateCrtrToClaude(profile, crtrCur) };
+    }
+    if (!crtrChanged && claudeChanged) {
+        // Claude is the sole edit → translate it onto the crtr side.
+        return { crtr: translateClaudeToCrtr(profile, claudeCur), claudeDesc: claudeCur };
+    }
+    // Both sides changed — equivalent iff each translated to the canonical Claude
+    // side yields a byte-identical string (§Resolved-here-5 / OD-1).
+    const crtrAsClaude = translateCrtrToClaude(profile, crtrCur);
+    const claudeAsClaude = translateCrtrToClaude(profile, translateClaudeToCrtr(profile, claudeCur));
+    if (crtrAsClaude === claudeAsClaude) {
+        // Equivalent → no real divergence; keep each side's current value (EC-8).
+        return { crtr: crtrCur, claudeDesc: claudeCur };
+    }
+    return {
+        crtr: crtrCur,
+        claudeDesc: claudeCur,
+        conflict: `frontmatter "${CLAUDE_DESC}" / "${CRTR_WHENWHY}" changed on both sides to ` +
+            `non-equivalent values:\n` +
+            `  crtr  when-and-why-to-read: ${JSON.stringify(crtrCur.whenAndWhy ?? '')}\n` +
+            `  crtr  short-form:           ${JSON.stringify(crtrCur.shortForm ?? '')}\n` +
+            `  claude description:         ${JSON.stringify(claudeCur ?? '')}`,
+    };
+}
+function translateCrtrToClaude(profile, fm) {
+    return profile.crtrToClaude.description(fm.whenAndWhy ?? '', fm.shortForm);
+}
+function translateClaudeToCrtr(profile, desc) {
+    const { whenAndWhy, shortForm } = profile.claudeToCrtr.description(desc ?? '');
+    return { whenAndWhy, shortForm };
+}
+// ── Seeding (first sync — no snapshot) ───────────────────────────────────────
+function seed(pair, profile, opts, crtr, claude, crtrDir, claudeDir) {
+    if (crtr.exists && claude.exists) {
+        const sharedIdentical = crtr.body === claude.body && assetsEqual(crtr.assets, claude.assets);
+        if (sharedIdentical) {
+            // R-S1 — endpoints already identical; seed the base, no merge, no-op.
+            const meta = buildMeta(readCrtrFm(crtr), readClaudeDesc(claude));
+            if (!opts.dryRun) {
+                writeSnapshot(pair.id, { body: crtr.body, assets: crtr.assets, meta });
+                clearConflictReport(pair.id);
+            }
+            return { id: pair.id, status: 'noop', wrote: 0 };
+        }
+        // R-S2 — divergent with no common ancestor → initial conflict, no write.
+        if (!opts.dryRun) {
+            writeConflictReport(pair.id, buildReport(pair.id, [
+                'first sync: both endpoints exist but their shared content differs, ' +
+                    'and there is no snapshot base to merge against. Reconcile the two ' +
+                    'sides by hand (make them identical) and re-run.',
+            ]));
+        }
+        return { id: pair.id, status: 'conflict', wrote: 0 };
+    }
+    if (!crtr.exists && !claude.exists) {
+        throw usage(`skill-sync: pair "${pair.id}" has no skill on either side ` +
+            `(crtr ${join(crtrDir, SKILL_ENTRY_FILE)} / claude ${join(claudeDir, SKILL_ENTRY_FILE)})`);
+    }
+    // R-S3 — one-sided bootstrap: materialize the existing side onto the other,
+    // translating the new side's frontmatter, and seed the base.
+    const crtrIsSource = crtr.exists;
+    const source = crtrIsSource ? crtr : claude;
+    let crtrFm;
+    let claudeDesc;
+    if (crtrIsSource) {
+        crtrFm = readCrtrFm(source);
+        claudeDesc = translateCrtrToClaude(profile, crtrFm);
+    }
+    else {
+        claudeDesc = readClaudeDesc(source);
+        crtrFm = translateClaudeToCrtr(profile, claudeDesc);
+    }
+    const desired = {
+        body: source.body,
+        assets: source.assets,
+        crtrFmInner: frontmatterInner(crtr, crtrFm, true, pair.crtr),
+        claudeFmInner: frontmatterInner(claude, claudeDesc, false, pair.claude),
+        meta: buildMeta(crtrFm, claudeDesc),
+    };
+    const wrote = applyAndSnapshot(pair, opts, desired, crtrDir, claudeDir, null);
+    return { id: pair.id, status: 'synced', wrote };
+}
+// ── Reconcile against an existing base ───────────────────────────────────────
+function reconcileWithBase(pair, profile, opts, snapshot, crtr, claude, crtrDir, claudeDir) {
+    // Whole-bundle presence first: a side whose SKILL.md vanished since the base
+    // is a deletion. Propagate it iff the surviving side is unchanged vs base;
+    // otherwise it is a delete ∧ edit conflict.
+    if (!crtr.exists || !claude.exists) {
+        return reconcileDeletion(pair, opts, snapshot, crtr, claude, crtrDir, claudeDir);
+    }
+    const conflicts = [];
+    // Body — both sides present, base is the snapshot body.
+    const bodyRes = mergeContent('SKILL.md (body)', Buffer.from(snapshot.body, 'utf8'), Buffer.from(crtr.body, 'utf8'), Buffer.from(claude.body, 'utf8'));
+    let mergedBody = snapshot.body;
+    if (bodyRes.kind === 'conflict')
+        conflicts.push(bodyRes.detail);
+    else if (bodyRes.kind === 'present')
+        mergedBody = bodyRes.content.toString('utf8');
+    // Assets — base-union, per-file 3-way.
+    const mergedAssets = new Map();
+    for (const rel of unionKeys(snapshot.assets, crtr.assets, claude.assets)) {
+        const res = mergeSlot(rel, snapshot.assets.get(rel), crtr.assets.get(rel), claude.assets.get(rel));
+        if (res.kind === 'present')
+            mergedAssets.set(rel, res.content);
+        else if (res.kind === 'conflict')
+            conflicts.push(res.detail);
+        // 'absent' → deleted on both / clean delete → omit from the merged set.
+    }
+    // Frontmatter — the single translatable concept, 3-way vs meta.json.
+    const fm = resolveFrontmatter(profile, snapshot.meta, readCrtrFm(crtr), readClaudeDesc(claude));
+    if (fm.conflict)
+        conflicts.push(fm.conflict);
+    if (conflicts.length > 0) {
+        if (!opts.dryRun)
+            writeConflictReport(pair.id, buildReport(pair.id, conflicts));
+        return { id: pair.id, status: 'conflict', wrote: 0 };
+    }
+    const desired = {
+        body: mergedBody,
+        assets: mergedAssets,
+        crtrFmInner: frontmatterInner(crtr, fm.crtr, true, pair.crtr),
+        claudeFmInner: frontmatterInner(claude, fm.claudeDesc, false, pair.claude),
+        meta: buildMeta(fm.crtr, fm.claudeDesc),
+    };
+    // Decide synced vs no-op by comparing the desired end-state to what is already
+    // on both endpoints AND the snapshot (R-S4 idempotency).
+    const counts = applyEndpoints(opts.dryRun, desired, crtrDir, claudeDir, /*write*/ !opts.dryRun);
+    const snapDiffers = snapshotDiffers(snapshot, desired);
+    const changed = counts.writes > 0 || counts.deletions > 0 || snapDiffers;
+    if (!changed) {
+        if (!opts.dryRun)
+            clearConflictReport(pair.id); // OD-4 — clear any stale report
+        return { id: pair.id, status: 'noop', wrote: 0 };
+    }
+    if (!opts.dryRun) {
+        writeSnapshot(pair.id, { body: desired.body, assets: desired.assets, meta: desired.meta });
+        clearConflictReport(pair.id); // OD-4
+    }
+    // `wrote` counts ACTUAL endpoint files written — 0 under --dry-run, even
+    // though `counts.writes` above carries the would-be total used for the
+    // synced/noop decision (contract: `sys sync -h` promises 0 under --dry-run).
+    return { id: pair.id, status: 'synced', wrote: opts.dryRun ? 0 : counts.writes };
+}
+/** Handle the case where at least one side's SKILL.md is gone in a 3-way. */
+function reconcileDeletion(pair, opts, snapshot, crtr, claude, crtrDir, claudeDir) {
+    // Both gone → the skill was removed everywhere; clear the base, no-op.
+    if (!crtr.exists && !claude.exists) {
+        if (!opts.dryRun) {
+            rmSync(snapshotDir(pair.id), { recursive: true, force: true });
+            clearConflictReport(pair.id);
+        }
+        return { id: pair.id, status: 'noop', wrote: 0 };
+    }
+    const surviving = crtr.exists ? crtr : claude;
+    const survivingUnchanged = surviving.body === snapshot.body && assetsEqual(surviving.assets, snapshot.assets);
+    const survivingDir = crtr.exists ? crtrDir : claudeDir;
+    const deletedLabel = crtr.exists ? 'claude' : 'crtr';
+    if (survivingUnchanged) {
+        // Clean deletion → remove the surviving bundle and the base.
+        if (!opts.dryRun) {
+            rmSync(survivingDir, { recursive: true, force: true });
+            rmSync(snapshotDir(pair.id), { recursive: true, force: true });
+            clearConflictReport(pair.id);
+        }
+        return { id: pair.id, status: 'synced', wrote: 0 };
+    }
+    // delete ∧ edit → conflict, no write.
+    if (!opts.dryRun) {
+        writeConflictReport(pair.id, buildReport(pair.id, [
+            `the skill was deleted on the ${deletedLabel} side but edited on the other ` +
+                `side since the last sync. Resolve by hand (restore or finish the deletion) ` +
+                `and re-run.`,
+        ]));
+    }
+    return { id: pair.id, status: 'conflict', wrote: 0 };
+}
+/** Apply the desired state to both endpoints (when `write`), counting files
+ *  written and deleted across both sides. With `write=false` it only computes
+ *  the counts (the dry-run path) and touches nothing. */
+function applyEndpoints(_dryRun, desired, crtrDir, claudeDir, write) {
+    const a = applyEndpoint(crtrDir, desired.crtrFmInner, desired.body, desired.assets, write);
+    const b = applyEndpoint(claudeDir, desired.claudeFmInner, desired.body, desired.assets, write);
+    return { writes: a.writes + b.writes, deletions: a.deletions + b.deletions };
+}
+function applyEndpoint(bundleDir, fmInner, body, assets, write) {
+    let writes = 0;
+    let deletions = 0;
+    // SKILL.md
+    const skillPath = join(bundleDir, SKILL_ENTRY_FILE);
+    const desiredSkill = renderSkill(fmInner, body);
+    const curSkill = existsSync(skillPath) ? readFileSync(skillPath, 'utf8') : null;
+    if (curSkill !== desiredSkill) {
+        writes++;
+        if (write) {
+            mkdirSync(bundleDir, { recursive: true });
+            writeFileSync(skillPath, desiredSkill, 'utf8');
+        }
+    }
+    // Assets: remove on-disk strays not in the desired set, then write the rest.
+    const curAssets = existsSync(bundleDir) ? readBundleAssets(bundleDir) : new Map();
+    for (const rel of curAssets.keys()) {
+        if (!assets.has(rel)) {
+            deletions++;
+            if (write)
+                rmSync(join(bundleDir, ...rel.split('/')), { force: true });
+        }
+    }
+    for (const [rel, buf] of assets) {
+        const cur = curAssets.get(rel);
+        if (!cur || !cur.equals(buf)) {
+            writes++;
+            if (write) {
+                const full = join(bundleDir, ...rel.split('/'));
+                mkdirSync(dirname(full), { recursive: true });
+                writeFileSync(full, buf);
+            }
+        }
+    }
+    return { writes, deletions };
+}
+/** Seed/materialize helper: apply both endpoints and the snapshot, returning the
+ *  endpoint files written. `_priorSnapshot` is unused today but documents that
+ *  callers pass null on a fresh seed. */
+function applyAndSnapshot(pair, opts, desired, crtrDir, claudeDir, _priorSnapshot) {
+    const counts = applyEndpoints(opts.dryRun, desired, crtrDir, claudeDir, !opts.dryRun);
+    if (!opts.dryRun) {
+        writeSnapshot(pair.id, { body: desired.body, assets: desired.assets, meta: desired.meta });
+        clearConflictReport(pair.id);
+    }
+    // Actual writes only — 0 under --dry-run (see reconcileWithBase note).
+    return opts.dryRun ? 0 : counts.writes;
+}
+/** A SKILL.md document = its frontmatter block + shared body. */
+function renderSkill(fmInner, body) {
+    if (fmInner === '')
+        return body;
+    return `---\n${fmInner}\n---\n${body}`;
+}
+/**
+ * The inner YAML for a side's SKILL.md frontmatter. A side is reserialized ONLY
+ * when its translatable value actually changes (or it is being materialized);
+ * otherwise its original raw frontmatter block is preserved byte-for-byte so a
+ * re-run never normalizes hand-authored formatting into a phantom diff (R-S4).
+ */
+function frontmatterInner(side, resolved, isCrtr, ep) {
+    if (isCrtr) {
+        const target = resolved;
+        if (side.exists && sameCrtrFm(target, readCrtrFm(side))) {
+            return side.rawFrontmatter; // unchanged → verbatim
+        }
+        return buildCrtrFrontmatter(side, target);
+    }
+    const desc = resolved;
+    if (side.exists && sameStr(desc, readClaudeDesc(side))) {
+        return side.rawFrontmatter; // unchanged → verbatim
+    }
+    return buildClaudeFrontmatter(side, desc, ep);
+}
+/** Reconstruct the crtr frontmatter record with the resolved translatable
+ *  fields set, preserving every existing (owned/other) field. A freshly
+ *  materialized bundle defaults `kind: knowledge` — the valid substrate kind a
+ *  crtr-side doc must carry (the merged skill+reference kind). */
+function buildCrtrFrontmatter(side, fm) {
+    const rec = side.frontmatter ? { ...side.frontmatter } : {};
+    if (!side.exists && rec.kind === undefined)
+        rec.kind = 'knowledge';
+    setOrDelete(rec, CRTR_WHENWHY, fm.whenAndWhy);
+    setOrDelete(rec, CRTR_SHORTFORM, fm.shortForm);
+    return serializeInner(rec);
+}
+/** Reconstruct the Claude frontmatter record with the resolved description set,
+ *  preserving every existing (owned/other) field. A freshly materialized bundle
+ *  carries `name: <ep.name>`. */
+function buildClaudeFrontmatter(side, desc, ep) {
+    const rec = side.frontmatter ? { ...side.frontmatter } : {};
+    if (!side.exists && rec.name === undefined)
+        rec.name = ep.name;
+    setOrDelete(rec, CLAUDE_DESC, desc);
+    return serializeInner(rec);
+}
+function setOrDelete(rec, key, value) {
+    if (value === undefined)
+        delete rec[key];
+    else
+        rec[key] = value;
+}
+/** Serialize a frontmatter record to inner YAML (no trailing newline). */
+function serializeInner(rec) {
+    if (Object.keys(rec).length === 0)
+        return '';
+    return stringifyYaml(rec).replace(/\n$/, '');
+}
+function buildMeta(crtr, claudeDesc) {
+    const crtrFrontmatter = {};
+    if (crtr.whenAndWhy !== undefined)
+        crtrFrontmatter.whenAndWhy = crtr.whenAndWhy;
+    if (crtr.shortForm !== undefined)
+        crtrFrontmatter.shortForm = crtr.shortForm;
+    const claudeFrontmatter = {};
+    if (claudeDesc !== undefined)
+        claudeFrontmatter.description = claudeDesc;
+    return { syncedAt: new Date().toISOString(), crtrFrontmatter, claudeFrontmatter };
+}
+/** True iff the desired shared content or translatable values differ from the
+ *  snapshot base (syncedAt is bookkeeping and intentionally ignored). */
+function snapshotDiffers(snapshot, desired) {
+    if (snapshot.body !== desired.body)
+        return true;
+    if (!assetsEqual(snapshot.assets, desired.assets))
+        return true;
+    const m = snapshot.meta;
+    if (!sameStr(m.crtrFrontmatter.whenAndWhy, desired.meta.crtrFrontmatter.whenAndWhy))
+        return true;
+    if (!sameStr(m.crtrFrontmatter.shortForm, desired.meta.crtrFrontmatter.shortForm))
+        return true;
+    if (!sameStr(m.claudeFrontmatter.description, desired.meta.claudeFrontmatter.description))
+        return true;
+    return false;
+}
+/** File-level 3-way for one asset relpath, resolving presence by the base-union
+ *  rule (add-both / delete-both / delete ∧ edit → conflict) then content. */
+function mergeSlot(rel, base, ours, theirs) {
+    if (base) {
+        if (!ours && !theirs)
+            return { kind: 'absent' }; // deleted both sides
+        if (!ours) {
+            // deleted on crtr
+            if (theirs.equals(base))
+                return { kind: 'absent' }; // untouched other → delete both
+            return { kind: 'conflict', detail: `asset ${rel}: deleted on crtr, edited on claude` };
+        }
+        if (!theirs) {
+            // deleted on claude
+            if (ours.equals(base))
+                return { kind: 'absent' };
+            return { kind: 'conflict', detail: `asset ${rel}: deleted on claude, edited on crtr` };
+        }
+        return mergeContent(`asset ${rel}`, base, ours, theirs);
+    }
+    // Not in base.
+    if (!ours && !theirs)
+        return { kind: 'absent' };
+    if (ours && !theirs)
+        return { kind: 'present', content: ours }; // added on crtr
+    if (!ours && theirs)
+        return { kind: 'present', content: theirs }; // added on claude
+    if (ours.equals(theirs))
+        return { kind: 'present', content: ours }; // added identically
+    // Both added divergently → merge against an empty base.
+    return mergeContent(`asset ${rel}`, Buffer.alloc(0), ours, theirs);
+}
+/** Content 3-way for a slot present on all three of base/ours/theirs. Text →
+ *  `git merge-file`; binary (NUL in first 8 KB, §Resolved-here-3) → whole-file
+ *  identity 3-way, never line-merged (OD-2). */
+function mergeContent(label, base, ours, theirs) {
+    if (base.equals(ours) && base.equals(theirs))
+        return { kind: 'present', content: ours };
+    if (base.equals(ours))
+        return { kind: 'present', content: theirs }; // only theirs changed
+    if (base.equals(theirs))
+        return { kind: 'present', content: ours }; // only ours changed
+    if (ours.equals(theirs))
+        return { kind: 'present', content: ours }; // both → same value
+    if (isBinary(base) || isBinary(ours) || isBinary(theirs)) {
+        return { kind: 'conflict', detail: `${label}: binary content changed on both sides` };
+    }
+    const { merged, conflicts } = mergeFile3(base, ours, theirs);
+    if (conflicts) {
+        return { kind: 'conflict', detail: `${label}:\n${merged.toString('utf8')}` };
+    }
+    return { kind: 'present', content: merged };
+}
+/** An asset is binary iff a NUL byte appears in its first 8 KB (§Resolved-here-3). */
+function isBinary(buf) {
+    const n = Math.min(buf.length, 8192);
+    for (let i = 0; i < n; i++)
+        if (buf[i] === 0)
+            return true;
+    return false;
+}
+/**
+ * Synthetic 3-way text merge via `git merge-file -p` (§Resolved-here-2). The
+ * three inputs are written to a private temp dir; stdout carries the merged
+ * result (with git-style conflict markers when overlapping), and the exit
+ * status is the conflict count (0 = clean; ≥128 / 255 / null = a real failure,
+ * which throws — never a silent best-effort).
+ */
+function mergeFile3(base, ours, theirs) {
+    const dir = mkdtempSync(join(tmpdir(), 'crtr-skill-sync-'));
+    try {
+        const oursPath = join(dir, 'ours');
+        const basePath = join(dir, 'base');
+        const theirsPath = join(dir, 'theirs');
+        writeFileSync(oursPath, ours);
+        writeFileSync(basePath, base);
+        writeFileSync(theirsPath, theirs);
+        const res = spawnSync('git', ['merge-file', '-p', '-L', 'crtr', '-L', 'base', '-L', 'claude', oursPath, basePath, theirsPath], { maxBuffer: 1 << 28 });
+        const status = res.status;
+        if (res.error || status === null || status < 0 || status >= 128) {
+            throw usage(`skill-sync: git merge-file failed (${res.error?.message ?? `status ${status}`})`);
+        }
+        return { merged: res.stdout, conflicts: status > 0 };
+    }
+    finally {
+        rmSync(dir, { recursive: true, force: true });
+    }
+}
+// ── Small utilities ──────────────────────────────────────────────────────────
+function assetsEqual(a, b) {
+    if (a.size !== b.size)
+        return false;
+    for (const [rel, buf] of a) {
+        const other = b.get(rel);
+        if (!other || !other.equals(buf))
+            return false;
+    }
+    return true;
+}
+function unionKeys(...maps) {
+    const out = new Set();
+    for (const m of maps)
+        for (const k of m.keys())
+            out.add(k);
+    return out;
+}
+/** Assemble a human-readable conflict report (R-E6 / R-X1). */
+function buildReport(id, entries) {
+    const lines = [`# skill-sync conflict: ${id}`, ''];
+    lines.push('This pair was NOT written. Resolve the conflicts below by editing the ' +
+        'endpoints, then re-run `crtr sys sync`.', '');
+    for (const e of entries) {
+        lines.push('---', '', e, '');
+    }
+    return lines.join('\n');
+}

package/dist/core/skill-sync/export.d.ts

@@ -0,0 +1,23 @@
+/**
+ * One-way export of crtr-generated host artifacts — the sole writer of
+ * generated content to `~/.claude/skills`, `~/.claude/commands`, and
+ * `~/.pi/agent/prompts`. Replaces the two host-dir writers that lived in
+ * bootstrap.ts (`ensureBootSkill` + `ensureSlashCommands`), collapsing their
+ * two clobber-guards into one `writeIfOurs` and their two kill-switches
+ * (`CRTR_NO_BOOT_SKILL` / `CRTR_NO_MODE_CMDS`) into one `CRTR_NO_EXPORTS`.
+ *
+ * Triggered per-run by cli.ts (argv-gated, exactly as the old writers were) so
+ * first-run provisioning is preserved. Best-effort: a provisioning fault must
+ * never break an unrelated `crtr` command (the deliberate, pre-existing
+ * behavior of the deleted writers).
+ */
+import type { RootDef } from '../command.js';
+/** Write `content` to `path` unless a user-customized file is already there.
+ *  Rolls forward our own (marker-bearing) versions; skips if identical. Creates
+ *  only the leaf dir, never the host root. The single generalization of
+ *  bootstrap.ts's two clobber-guards. */
+export declare function writeIfOurs(path: string, content: string, markerPrefix: string): void;
+/** Render and write every built-in export artifact to every present host.
+ *  Best-effort: swallows errors (debug-logged) so a provisioning fault never
+ *  breaks an unrelated `crtr` command. Kill switch: `CRTR_NO_EXPORTS=1`. */
+export declare function provisionExports(root: RootDef, argv?: string[]): void;