@crouton-kit/crouter 0.3.28 → 0.3.29

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

@@ -0,0 +1,86 @@
+/**
+ * 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 { writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { ensureDir, pathExists, readText } from '../fs-utils.js';
+import { builtinExportPairs } from './builtins.js';
+const SKIP_SUBCOMMANDS = new Set([
+    'help',
+    '--help',
+    '-h',
+    '--version',
+    '-v',
+]);
+/** Skip provisioning for help/version invocations — never write on `-h`. */
+function shouldSkipForArgv(argv) {
+    const sub = argv[2];
+    if (sub === undefined)
+        return true;
+    return SKIP_SUBCOMMANDS.has(sub);
+}
+/** Whether a host runtime is in use (its root dir exists). crtr writes into a
+ *  host's dirs only when present and never creates `~/.claude` or `~/.pi`. */
+function hostRootExists(host) {
+    if (host === 'claude')
+        return pathExists(join(homedir(), '.claude'));
+    return pathExists(join(homedir(), '.pi', 'agent'));
+}
+/** Resolve the on-disk path for one target from its layout. */
+function targetPath(target, name) {
+    const dir = target.dir();
+    return target.layout === 'bundle'
+        ? join(dir, name, 'SKILL.md')
+        : join(dir, `${name}.md`);
+}
+/** 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 function writeIfOurs(path, content, markerPrefix) {
+    if (pathExists(path)) {
+        const existing = readText(path);
+        if (!existing.includes(markerPrefix))
+            return; // user-owned → never clobber
+        if (existing === content)
+            return; // already current
+    }
+    ensureDir(dirname(path));
+    writeFileSync(path, content, 'utf8');
+}
+/** 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 function provisionExports(root, argv = process.argv) {
+    try {
+        if (process.env.CRTR_NO_EXPORTS === '1')
+            return;
+        if (shouldSkipForArgv(argv))
+            return;
+        for (const pair of builtinExportPairs(root)) {
+            const content = pair.render();
+            for (const target of pair.targets) {
+                if (!hostRootExists(target.host))
+                    continue;
+                writeIfOurs(targetPath(target, pair.name), content, pair.markerPrefix);
+            }
+        }
+    }
+    catch (e) {
+        if (process.env.CRTR_DEBUG === '1') {
+            const msg = e instanceof Error ? e.message : String(e);
+            process.stderr.write(`crtr: exports error: ${msg}\n`);
+        }
+    }
+}

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

@@ -0,0 +1,64 @@
+/**
+ * Layered manifest for bidirectional skill sync (Phase P2).
+ *
+ * Reads the user-scope (`~/.crouter/skill-sync.json`) and project-scope
+ * (`<proj>/.crouter/skill-sync.json`) manifests, validates each against the
+ * R-I1 schema with a hand-rolled strict validator (no new dependency), and
+ * merges them into a single additive, project-wins pair list.
+ *
+ * Contract (R-U7/R-U8/R-U9/R-I1/R-X4):
+ *  - Missing file        → empty layer (absence ≠ malformation).
+ *  - Invalid JSON        → HARD error naming the file (no lenient fallback).
+ *  - Schema-invalid pair → HARD error naming the file (no skip-and-proceed).
+ *  - Merge               → additive union keyed on `id`; a project pair with an
+ *                          `id` present in the user layer REPLACES it entirely.
+ *
+ * The shared data shapes (`Pair`, `Endpoint`, `TranslationOverride`) are
+ * exported from here; P5/P6/P7 import them.
+ */
+/** The scope a sync endpoint resolves within. `plugin` is crtr-side only (a
+ *  skill bundle inside a crtr-registry plugin); `claude-plugin` is Claude-side
+ *  only (a skill IN PLACE inside its Claude plugin's install path). */
+export type EndpointScope = 'user' | 'project' | 'plugin' | 'claude-plugin';
+/** One side of a sync pair — a single SKILL.md bundle on either the crtr or the
+ *  Claude side. Resolves to `<dir>/<name>/SKILL.md` (R-I2, resolved by P6).
+ *  `plugin` is required iff `scope` is `plugin` (crtr) or `claude-plugin`
+ *  (Claude) — it names the owning plugin (a `claude-plugin` value is the
+ *  marketplace-qualified key `<plugin>@<marketplace>`). */
+export interface Endpoint {
+    scope: EndpointScope;
+    name: string;
+    plugin?: string;
+}
+/** Per-pair override of the default translation profile — shallow-merged over
+ *  it by P5's `resolveProfile` (R-I5). The JSON-overridable surface is the
+ *  owned-field lists; P5 performs the profile-shape validation and rejects
+ *  unknown keys, so this manifest validator only checks it is an object. */
+export interface TranslationOverride {
+    crtrOwned?: string[];
+    claudeOwned?: string[];
+}
+/** A single bidirectional sync pair (R-I1). `kind` is optional and, if present,
+ *  MUST be `"skill"` — the other endpoint kinds (`command`/`agent`/`plugin`) are
+ *  built-in export artifacts (skill-sync/builtins.ts), not manifest-enrollable. */
+export interface Pair {
+    id: string;
+    kind?: 'skill';
+    crtr: Endpoint;
+    claude: Endpoint;
+    frontmatter?: TranslationOverride;
+}
+/** The merged, validated manifest. */
+export interface LayeredManifest {
+    pairs: Pair[];
+}
+/**
+ * Read, validate, and merge the user- and project-layer manifests.
+ *
+ * @param cwd  starting directory for project-scope resolution (defaults to the
+ *             process cwd via `findProjectScopeRoot`).
+ * @returns    `{ pairs }` — the additive, project-wins union (R-U8).
+ * @throws     `usage()` error naming the offending file on malformed JSON or a
+ *             schema-invalid layer (R-U7/R-X4). NEVER swallows a bad layer.
+ */
+export declare function readLayeredManifest(cwd?: string): LayeredManifest;

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

@@ -0,0 +1,181 @@
+/**
+ * Layered manifest for bidirectional skill sync (Phase P2).
+ *
+ * Reads the user-scope (`~/.crouter/skill-sync.json`) and project-scope
+ * (`<proj>/.crouter/skill-sync.json`) manifests, validates each against the
+ * R-I1 schema with a hand-rolled strict validator (no new dependency), and
+ * merges them into a single additive, project-wins pair list.
+ *
+ * Contract (R-U7/R-U8/R-U9/R-I1/R-X4):
+ *  - Missing file        → empty layer (absence ≠ malformation).
+ *  - Invalid JSON        → HARD error naming the file (no lenient fallback).
+ *  - Schema-invalid pair → HARD error naming the file (no skip-and-proceed).
+ *  - Merge               → additive union keyed on `id`; a project pair with an
+ *                          `id` present in the user layer REPLACES it entirely.
+ *
+ * The shared data shapes (`Pair`, `Endpoint`, `TranslationOverride`) are
+ * exported from here; P5/P6/P7 import them.
+ */
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { userScopeRoot, findProjectScopeRoot } from '../scope.js';
+import { usage } from '../errors.js';
+// ── Public API ───────────────────────────────────────────────────────────────
+const MANIFEST_FILE = 'skill-sync.json';
+const VALID_SCOPES = ['user', 'project', 'plugin', 'claude-plugin'];
+/**
+ * Read, validate, and merge the user- and project-layer manifests.
+ *
+ * @param cwd  starting directory for project-scope resolution (defaults to the
+ *             process cwd via `findProjectScopeRoot`).
+ * @returns    `{ pairs }` — the additive, project-wins union (R-U8).
+ * @throws     `usage()` error naming the offending file on malformed JSON or a
+ *             schema-invalid layer (R-U7/R-X4). NEVER swallows a bad layer.
+ */
+export function readLayeredManifest(cwd) {
+    const userPath = join(userScopeRoot(), MANIFEST_FILE);
+    const userPairs = readLayer(userPath);
+    const projectRoot = findProjectScopeRoot(cwd);
+    const projectPairs = projectRoot
+        ? readLayer(join(projectRoot, MANIFEST_FILE))
+        : [];
+    // Additive union keyed on `id`; project replaces user on collision (R-U8).
+    // A Map preserves first-insertion order, so a project pair overwriting a user
+    // pair keeps the user pair's position while replacing its value.
+    const merged = new Map();
+    for (const p of userPairs)
+        merged.set(p.id, p);
+    for (const p of projectPairs)
+        merged.set(p.id, p);
+    return { pairs: [...merged.values()] };
+}
+// ── Layer read + strict validation ──────────────────────────────────────────
+/** Read one layer file. Missing → empty (R-U7). Present-but-malformed → throw
+ *  naming the file (R-U7/R-X4). Returns the validated pairs of that one layer. */
+function readLayer(path) {
+    let raw;
+    try {
+        raw = readFileSync(path, 'utf8');
+    }
+    catch (err) {
+        if (err.code === 'ENOENT')
+            return []; // empty layer
+        throw usage(`failed to read ${path}: ${err.message}`);
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch (err) {
+        throw usage(`invalid JSON in ${path}: ${err.message}`);
+    }
+    return validateLayer(parsed, path);
+}
+/** Validate one parsed layer against the R-I1 schema. Throws naming `path` on
+ *  any violation. Duplicate-`id` detection is scoped to THIS layer only —
+ *  cross-layer `id` collisions are the legal project-wins merge, not an error. */
+function validateLayer(doc, path) {
+    if (!isObject(doc)) {
+        throw usage(`malformed manifest ${path}: top level must be a JSON object`);
+    }
+    // Strict-require `version: 2` — any existing manifest MUST declare it (no
+    // advisory hedge). v1 has zero on-disk instances, so this is a clean forward
+    // marker, not a migration.
+    const version = doc.version;
+    if (version !== 2) {
+        throw usage(`malformed manifest ${path}: "version" must be 2 (got ${JSON.stringify(version)})`);
+    }
+    // `pairs` absent → empty manifest; present → must be an array.
+    const rawPairs = doc.pairs;
+    if (rawPairs === undefined)
+        return [];
+    if (!Array.isArray(rawPairs)) {
+        throw usage(`malformed manifest ${path}: "pairs" must be an array`);
+    }
+    const seen = new Set();
+    const pairs = [];
+    rawPairs.forEach((entry, i) => {
+        const pair = validatePair(entry, i, path);
+        if (seen.has(pair.id)) {
+            throw usage(`malformed manifest ${path}: duplicate pair id "${pair.id}" within one layer`);
+        }
+        seen.add(pair.id);
+        pairs.push(pair);
+    });
+    return pairs;
+}
+function validatePair(entry, i, path) {
+    const where = `pairs[${i}]`;
+    if (!isObject(entry)) {
+        throw usage(`malformed manifest ${path}: ${where} must be an object`);
+    }
+    const e = entry;
+    if (typeof e.id !== 'string' || e.id.length === 0) {
+        throw usage(`malformed manifest ${path}: ${where} is missing a non-empty string "id"`);
+    }
+    const id = e.id;
+    // `kind` is optional; absent → "skill". Any value other than "skill" is a hard
+    // error — export kinds (command/agent/plugin) are built-in, not enrollable.
+    let kind;
+    if (e.kind !== undefined) {
+        if (e.kind !== 'skill') {
+            throw usage(`malformed manifest ${path}: ${where}.kind must be "skill" or absent — ` +
+                `kinds like "command"/"agent"/"plugin" are built-in export artifacts, ` +
+                `not manifest-enrollable`);
+        }
+        kind = e.kind;
+    }
+    const crtr = validateEndpoint(e.crtr, `${where}.crtr`, path, 'crtr');
+    const claude = validateEndpoint(e.claude, `${where}.claude`, path, 'claude');
+    let frontmatter;
+    if (e.frontmatter !== undefined) {
+        if (!isObject(e.frontmatter)) {
+            throw usage(`malformed manifest ${path}: ${where}.frontmatter must be an object`);
+        }
+        frontmatter = e.frontmatter;
+    }
+    return { id, kind, crtr, claude, frontmatter };
+}
+function validateEndpoint(value, where, path, side) {
+    if (!isObject(value)) {
+        throw usage(`malformed manifest ${path}: ${where} is missing or not an object`);
+    }
+    const ep = value;
+    if (!isScope(ep.scope)) {
+        throw usage(`malformed manifest ${path}: ${where}.scope must be one of ${VALID_SCOPES.join('|')}`);
+    }
+    const scope = ep.scope;
+    // Scopes are side-specific: `plugin` resolves a crtr-registry plugin, so it is
+    // only legal on the crtr side; `claude-plugin` resolves a Claude install path,
+    // so it is only legal on the Claude side (R-I1).
+    if (scope === 'plugin' && side !== 'crtr') {
+        throw usage(`malformed manifest ${path}: ${where}.scope "plugin" is only valid for a crtr ` +
+            `endpoint — for a Claude plugin skill use "claude-plugin"`);
+    }
+    if (scope === 'claude-plugin' && side !== 'claude') {
+        throw usage(`malformed manifest ${path}: ${where}.scope "claude-plugin" is only valid for a ` +
+            `Claude endpoint`);
+    }
+    if (typeof ep.name !== 'string' || ep.name.length === 0) {
+        throw usage(`malformed manifest ${path}: ${where}.name must be a non-empty string`);
+    }
+    const name = ep.name;
+    // `plugin` required iff scope names a plugin (`plugin` or `claude-plugin`).
+    if (scope === 'plugin' || scope === 'claude-plugin') {
+        if (typeof ep.plugin !== 'string' || ep.plugin.length === 0) {
+            throw usage(`malformed manifest ${path}: ${where} has scope "${scope}" but no non-empty "plugin" name`);
+        }
+        return { scope, name, plugin: ep.plugin };
+    }
+    if (ep.plugin !== undefined) {
+        throw usage(`malformed manifest ${path}: ${where}.plugin is only valid when scope is "plugin" or "claude-plugin"`);
+    }
+    return { scope, name };
+}
+// ── Type guards ──────────────────────────────────────────────────────────────
+function isObject(v) {
+    return typeof v === 'object' && v !== null && !Array.isArray(v);
+}
+function isScope(v) {
+    return typeof v === 'string' && VALID_SCOPES.includes(v);
+}

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

@@ -0,0 +1,76 @@
+/**
+ * Translation profile (Phase P5) — the single home of the crtr ↔ Claude
+ * frontmatter asymmetry.
+ *
+ * Body and asset reconciliation is symmetric (a plain 3-way merge); frontmatter
+ * is the ONLY asymmetric axis, and all of that asymmetry lives here (R-U3). The
+ * forward translator (`claudeToCrtr.description`) reshapes a Claude `description`
+ * into a crtr read-routing `when-and-why-to-read` sentence + `short-form`; the
+ * reverse translator (`crtrToClaude.description`) inverts that back into the
+ * canonical Claude form `"<gist>. Use when <situation>."` so a round-trip is
+ * byte-stable (R-S4 / OD-1).
+ *
+ * The forward string functions (`reshapeWhenAndWhy`, `cleanClause`,
+ * `toShortForm`, `yamlQuote`, `USE_WHEN_RE`) preserve the legacy reshape
+ * behavior exactly — `reshapeWhenAndWhy` output is byte-identical to that
+ * legacy for the same input (R-I4). Frontmatter writing and generator stamping
+ * are intentionally NOT part of this module — the reconcile engine owns all
+ * writes.
+ */
+import type { TranslationOverride } from './manifest.js';
+/** Reshape a Claude `description` into a read-routing sentence per
+ *  taste/why-field-means-why-to-read: "When <situation>, this skill should be
+ *  read [because <gist>]." Claude descriptions are typically
+ *  "<gist>. Use when <situation>." — we lift the use-when clause into the
+ *  situation and the preceding text into the payoff. With no explicit clause,
+ *  the whole description becomes the situation. */
+export declare function reshapeWhenAndWhy(description: string): string;
+/** One-line short-form for the human inventory (never loaded into agent
+ *  context): the source description collapsed to a single line. */
+export declare function toShortForm(description: string): string;
+/** Always-double-quote a YAML scalar, escaping backslashes and quotes. The two
+ *  generated fields are single-line, so this is safe regardless of colons,
+ *  commas, or other YAML-significant characters. */
+export declare function yamlQuote(s: string): string;
+/**
+ * Reverse translator: a crtr `when-and-why-to-read` (plus optional `short-form`
+ * for the gist when the sentence carries none) → the canonical Claude
+ * `description` form `"<gist>. Use when <situation>."`.
+ *
+ * This is the exact inverse of `reshapeWhenAndWhy`, normalized so that
+ * `crtrToClaudeDescription(reshapeWhenAndWhy(d), toShortForm(d))` is a fixed
+ * point under re-application — a round-trip is byte-stable (R-S4 / OD-1). The
+ * `gist` is recovered from the sentence's `because` clause; only when that is
+ * absent do we fall back to the (use-when-stripped) `short-form`, so a
+ * `short-form` that is itself a "Use when …" line contributes nothing and
+ * cannot ping-pong.
+ */
+export declare function crtrToClaudeDescription(whenAndWhy: string, shortForm?: string): string;
+/** The crtr ↔ Claude frontmatter contract: the two translatable `description`
+ *  axes plus the owned-field lists that are NEVER crossed to the other side
+ *  (R-X2). Shape per R-I4. */
+export interface TranslationProfile {
+    claudeToCrtr: {
+        description: (d: string) => {
+            whenAndWhy: string;
+            shortForm: string;
+        };
+    };
+    crtrToClaude: {
+        description: (whenAndWhy: string, shortForm?: string) => string;
+    };
+    crtrOwned: readonly string[];
+    claudeOwned: readonly string[];
+}
+/** The default profile (R-I4). The forward translator reuses
+ *  `reshapeWhenAndWhy`/`toShortForm` verbatim; the reverse uses
+ *  `crtrToClaudeDescription`. Owned-field lists match the field taxonomy. */
+export declare const DEFAULT_PROFILE: TranslationProfile;
+/**
+ * Resolve a pair's effective profile: a SHALLOW merge of its `frontmatter`
+ * override over `DEFAULT_PROFILE`, validated against the profile shape (R-I5).
+ * An unknown key or a non-string-array value is a malformed-manifest error
+ * (R-U7). NEVER mutates `DEFAULT_PROFILE` — the override path returns a fresh
+ * object; the no-override path returns the (unmodified) constant.
+ */
+export declare function resolveProfile(override?: TranslationOverride): TranslationProfile;

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

@@ -0,0 +1,173 @@
+/**
+ * Translation profile (Phase P5) — the single home of the crtr ↔ Claude
+ * frontmatter asymmetry.
+ *
+ * Body and asset reconciliation is symmetric (a plain 3-way merge); frontmatter
+ * is the ONLY asymmetric axis, and all of that asymmetry lives here (R-U3). The
+ * forward translator (`claudeToCrtr.description`) reshapes a Claude `description`
+ * into a crtr read-routing `when-and-why-to-read` sentence + `short-form`; the
+ * reverse translator (`crtrToClaude.description`) inverts that back into the
+ * canonical Claude form `"<gist>. Use when <situation>."` so a round-trip is
+ * byte-stable (R-S4 / OD-1).
+ *
+ * The forward string functions (`reshapeWhenAndWhy`, `cleanClause`,
+ * `toShortForm`, `yamlQuote`, `USE_WHEN_RE`) preserve the legacy reshape
+ * behavior exactly — `reshapeWhenAndWhy` output is byte-identical to that
+ * legacy for the same input (R-I4). Frontmatter writing and generator stamping
+ * are intentionally NOT part of this module — the reconcile engine owns all
+ * writes.
+ */
+import { usage } from '../errors.js';
+// ── Forward translation (Claude `description` → crtr `when-and-why-to-read`) ──
+// "Use when …" / "Use this when …" / "This skill should be used when …" / "Used when …"
+const USE_WHEN_RE = /\b(?:use\s+this\s+skill\s+when|use\s+this\s+when|this\s+skill\s+should\s+be\s+used\s+when|used\s+when|use\s+when)\b\s*/i;
+/** Collapse whitespace, strip surrounding connective punctuation, and lowercase
+ *  a leading Capitalized word (but never an ACRONYM) so the clause reads inline
+ *  after "When " / "because ". */
+function cleanClause(s) {
+    let c = s.replace(/\s+/g, ' ').trim();
+    c = c.replace(/^[,;:.\s]+/, '').replace(/[,;:.\s]+$/, '');
+    if (/^[A-Z][a-z]/.test(c))
+        c = c.charAt(0).toLowerCase() + c.slice(1);
+    return c;
+}
+/** Reshape a Claude `description` into a read-routing sentence per
+ *  taste/why-field-means-why-to-read: "When <situation>, this skill should be
+ *  read [because <gist>]." Claude descriptions are typically
+ *  "<gist>. Use when <situation>." — we lift the use-when clause into the
+ *  situation and the preceding text into the payoff. With no explicit clause,
+ *  the whole description becomes the situation. */
+export function reshapeWhenAndWhy(description) {
+    const desc = description.replace(/\s+/g, ' ').trim();
+    if (desc === '')
+        return 'When this skill applies, this skill should be read.';
+    const m = desc.match(USE_WHEN_RE);
+    if (m && m.index !== undefined) {
+        const gist = cleanClause(desc.slice(0, m.index));
+        const situation = cleanClause(desc.slice(m.index + m[0].length));
+        if (situation !== '') {
+            let out = `When ${situation}, this skill should be read`;
+            if (gist !== '')
+                out += ` because ${gist}`;
+            return out + '.';
+        }
+    }
+    return `When ${cleanClause(desc)}, this skill should be read.`;
+}
+/** One-line short-form for the human inventory (never loaded into agent
+ *  context): the source description collapsed to a single line. */
+export function toShortForm(description) {
+    return description.replace(/\s+/g, ' ').trim();
+}
+/** Always-double-quote a YAML scalar, escaping backslashes and quotes. The two
+ *  generated fields are single-line, so this is safe regardless of colons,
+ *  commas, or other YAML-significant characters. */
+export function yamlQuote(s) {
+    return `"${s.replace(/\\/g, '\\\\').replace(/"/g, '\\"')}"`;
+}
+// ── Reverse translation (crtr `when-and-why-to-read` → Claude `description`) ──
+/** The forward `reshapeWhenAndWhy` form, parsed back into its parts:
+ *  "When <situation>, this skill should be read[ because <gist>]." */
+const RESHAPE_RE = /^When (.+?), this skill should be read(?: because (.+?))?\.?$/s;
+/** Recover `{ situation, gist }` from a `when-and-why-to-read` sentence. A
+ *  value emitted by `reshapeWhenAndWhy` matches `RESHAPE_RE`; anything else is
+ *  treated as a bare situation with no gist. The clauses are normalized through
+ *  `cleanClause` so the reverse is the exact inverse of the forward split. */
+function parseWhenAndWhy(whenAndWhy) {
+    const w = whenAndWhy.replace(/\s+/g, ' ').trim();
+    const m = w.match(RESHAPE_RE);
+    if (m) {
+        return { situation: cleanClause(m[1]), gist: cleanClause(m[2] ?? '') };
+    }
+    return { situation: cleanClause(w), gist: '' };
+}
+/** Pull a gist out of a `short-form` line: the text before any "Use when …"
+ *  clause (mirroring the forward split), or the whole line if there is none. */
+function gistFromShortForm(shortForm) {
+    const s = shortForm.replace(/\s+/g, ' ').trim();
+    const m = s.match(USE_WHEN_RE);
+    if (m && m.index !== undefined)
+        return cleanClause(s.slice(0, m.index));
+    return cleanClause(s);
+}
+/** Capitalize the first character of a clause (no-op for an empty string or a
+ *  leading acronym, which is already upper-case). */
+function capitalizeFirst(s) {
+    return s === '' ? s : s.charAt(0).toUpperCase() + s.slice(1);
+}
+/**
+ * Reverse translator: a crtr `when-and-why-to-read` (plus optional `short-form`
+ * for the gist when the sentence carries none) → the canonical Claude
+ * `description` form `"<gist>. Use when <situation>."`.
+ *
+ * This is the exact inverse of `reshapeWhenAndWhy`, normalized so that
+ * `crtrToClaudeDescription(reshapeWhenAndWhy(d), toShortForm(d))` is a fixed
+ * point under re-application — a round-trip is byte-stable (R-S4 / OD-1). The
+ * `gist` is recovered from the sentence's `because` clause; only when that is
+ * absent do we fall back to the (use-when-stripped) `short-form`, so a
+ * `short-form` that is itself a "Use when …" line contributes nothing and
+ * cannot ping-pong.
+ */
+export function crtrToClaudeDescription(whenAndWhy, shortForm) {
+    const { situation, gist: parsedGist } = parseWhenAndWhy(whenAndWhy);
+    let gist = parsedGist;
+    if (gist === '' && shortForm !== undefined)
+        gist = gistFromShortForm(shortForm);
+    const useWhen = situation === '' ? '' : `Use when ${situation}.`;
+    if (gist === '')
+        return useWhen;
+    const cap = capitalizeFirst(gist);
+    return useWhen === '' ? `${cap}.` : `${cap}. ${useWhen}`;
+}
+/** The default profile (R-I4). The forward translator reuses
+ *  `reshapeWhenAndWhy`/`toShortForm` verbatim; the reverse uses
+ *  `crtrToClaudeDescription`. Owned-field lists match the field taxonomy. */
+export const DEFAULT_PROFILE = {
+    claudeToCrtr: {
+        description: (d) => ({ whenAndWhy: reshapeWhenAndWhy(d), shortForm: toShortForm(d) }),
+    },
+    crtrToClaude: {
+        description: (whenAndWhy, shortForm) => crtrToClaudeDescription(whenAndWhy, shortForm),
+    },
+    crtrOwned: ['kind', 'system-prompt-visibility', 'file-read-visibility', 'gate', 'applies-to'],
+    claudeOwned: ['argument-hint', 'user-invocable', 'paths', 'context', 'model', 'agent', 'keywords', 'type'],
+};
+/** The only fields a per-pair `frontmatter` override may set (R-I5). The
+ *  translators are functions and cannot be expressed in JSON, so the
+ *  overridable surface is exactly the owned-field lists. */
+const OVERRIDABLE_KEYS = ['crtrOwned', 'claudeOwned'];
+/**
+ * Resolve a pair's effective profile: a SHALLOW merge of its `frontmatter`
+ * override over `DEFAULT_PROFILE`, validated against the profile shape (R-I5).
+ * An unknown key or a non-string-array value is a malformed-manifest error
+ * (R-U7). NEVER mutates `DEFAULT_PROFILE` — the override path returns a fresh
+ * object; the no-override path returns the (unmodified) constant.
+ */
+export function resolveProfile(override) {
+    if (override === undefined)
+        return DEFAULT_PROFILE;
+    if (typeof override !== 'object' || override === null || Array.isArray(override)) {
+        throw usage('malformed manifest: pair frontmatter override must be an object');
+    }
+    for (const key of Object.keys(override)) {
+        if (!OVERRIDABLE_KEYS.includes(key)) {
+            throw usage(`malformed manifest: unknown frontmatter override key "${key}" (allowed: ${OVERRIDABLE_KEYS.join(', ')})`);
+        }
+    }
+    return {
+        claudeToCrtr: DEFAULT_PROFILE.claudeToCrtr,
+        crtrToClaude: DEFAULT_PROFILE.crtrToClaude,
+        crtrOwned: validateOwned(override.crtrOwned, 'crtrOwned') ?? DEFAULT_PROFILE.crtrOwned,
+        claudeOwned: validateOwned(override.claudeOwned, 'claudeOwned') ?? DEFAULT_PROFILE.claudeOwned,
+    };
+}
+/** Validate one owned-field override list: undefined → inherit the default;
+ *  anything other than an array of strings → malformed-manifest error. */
+function validateOwned(value, key) {
+    if (value === undefined)
+        return undefined;
+    if (!Array.isArray(value) || !value.every((x) => typeof x === 'string')) {
+        throw usage(`malformed manifest: frontmatter override "${key}" must be an array of strings`);
+    }
+    return value;
+}

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

@@ -0,0 +1,57 @@
+/**
+ * The translatable values recorded for each side at last sync. These are the
+ * ONLY values stored (§Resolved-here-4): owned fields are never recorded —
+ * each side reads its own owned fields through, so they need no merge base.
+ */
+export interface SnapshotMeta {
+    /** ISO 8601 timestamp of the sync that produced this base. */
+    syncedAt: string;
+    /** crtr-side translatable frontmatter at last sync. */
+    crtrFrontmatter: {
+        whenAndWhy?: string;
+        shortForm?: string;
+    };
+    /** Claude-side translatable frontmatter at last sync. */
+    claudeFrontmatter: {
+        description?: string;
+    };
+}
+/** A fully-loaded merge base for one pair. */
+export interface Snapshot {
+    /** Shared body, frontmatter stripped. */
+    body: string;
+    /** Non-SKILL.md base assets, keyed by POSIX-style relpath under `assets/`. */
+    assets: Map<string, Buffer>;
+    /** Recorded translatable values + sync timestamp. */
+    meta: SnapshotMeta;
+}
+/** `~/.crouter/skill-sync/` — the machine-local, uncommitted root (R-U9). */
+export declare function skillSyncRoot(): string;
+/** `~/.crouter/skill-sync/snapshots/<id>/`. */
+export declare function snapshotDir(id: string): string;
+/** `~/.crouter/skill-sync/conflicts/<id>.md`. */
+export declare function conflictReportPath(id: string): string;
+/**
+ * Load the merge base for `id`, or `null` when the snapshot dir is absent
+ * (no prior sync — the engine seeds on first reconcile, R-S1/R-S3).
+ */
+export declare function readSnapshot(id: string): Snapshot | null;
+/**
+ * Write the merge base for `id` byte-for-byte. The snapshot dir is rebuilt
+ * from scratch so stale assets from a prior base never linger — the on-disk
+ * `assets/` always mirrors exactly the passed `assets` map (R-U5/R-I3).
+ */
+export declare function writeSnapshot(id: string, snapshot: Snapshot): void;
+/**
+ * Write the current conflict report for `id` to `conflicts/<id>.md`. The engine
+ * calls this on any true conflict (overlapping body/asset merge or both-sides
+ * non-equivalent frontmatter) after deciding to write nothing for the pair.
+ */
+export declare function writeConflictReport(id: string, text: string): void;
+/**
+ * Delete a stale `conflicts/<id>.md` once the pair reconciles cleanly or
+ * becomes a no-op (OD-4). No-op if absent — never throws on a missing report.
+ */
+export declare function clearConflictReport(id: string): void;
+/** True iff a conflict report currently exists for `id`. */
+export declare function hasConflictReport(id: string): boolean;