simt-dev 0.4.0 → 0.5.0

package/src/commands/skills.mjs

@@ -15,7 +15,7 @@ import { existsSync } from 'node:fs';
 
 import { EXIT, emit, emitJson, fail, isJson, note as emitNote } from '../output/index.mjs';
 import { loadRegistry } from '../graph/load.mjs';
-import { locateSource, sourceHeldLocally } from '../resolve/source.mjs';
+import { bodyFile, sourcePath } from '../resolve/body.mjs';
 import { unknownSkills, scoreCorpus } from '../resolve/eval.mjs';
 import { PACKAGE_ROOT, resolveWorkspace, WORKSPACE_REMEDY } from '../workspace.mjs';
 import { fingerprint } from '../resolve/fingerprint.mjs';
@@ -656,36 +656,6 @@ export async function evalCommand(positional, flags) {
 
 // --- bodies -------------------------------------------------------------------
 
-/**
- * Resolve a skill's body to an absolute path.
- *
- * Sources are declared as `repo/path`, so finding one needs the workspace that
- * CONTAINS the repos. That used to be `resolve(here, '..', '..', '..')`, which is
- * right in the checkout and wrong in `node_modules` - so every source resolved to a
- * path that could not exist and `skills` failed with 38 ENOENT lines. Now it comes
- * from configuration, and `null` is a legitimate answer meaning "this installation
- * has no workspace" (ADR-014).
- *
- * A second location exists and is not a fallback: the repo being read is itself a
- * location for a declared source, matched on bytes rather than on hope (ADR-015).
- * The canonical source is still tried first, so a workspace body always wins.
- */
-async function sourcePath(skill, workspaceRoot, root) {
-  const canonical = skill.sources?.find((s) => s.role === 'canonical') ?? skill.sources?.[0];
-
-  if (canonical) {
-    const found = await locateSource(canonical, { workspaceRoot, root });
-    if (found.path) return found.path;
-  }
-
-  const held = await sourceHeldLocally(skill, root, { workspaceRoot });
-  if (held && !held.ambiguous) return held.path;
-
-  // A skill with no canonical source, or one whose bytes match nothing, has no
-  // body. Say so rather than printing an empty section.
-  return canonical && workspaceRoot ? join(workspaceRoot, canonical.repo, canonical.path) : null;
-}
-
 /** A one-line pointer. The reasons stay, so a brief that cannot inline still says why. */
 function pointerLine(entry) {
   const why = [...entry.reasons, ...[...entry.via].map((v) => `requires:${v}`)];
@@ -705,8 +675,7 @@ export async function readBody(skill, workspaceRoot, root) {
   }
   if (!existsSync(full)) return `(body unavailable: ${full} is not on this machine)`;
   try {
-    const target = existsSync(join(full, 'SKILL.md')) ? join(full, 'SKILL.md') : full;
-    return (await readFile(target, 'utf8')).trimEnd();
+    return (await readFile(bodyFile(full), 'utf8')).trimEnd();
   } catch (error) {
     return `(body unreadable: ${error.message})`;
   }

package/src/commands/why.mjs

@@ -63,7 +63,9 @@ function reportUnresolved(root, flags, unresolved) {
   return EXIT.OK;
 }
 
-async function tracked(root) {
+// `async function tracked(root)` (read by `simt why`) becomes `export async`:
+// the critic's brief resolves governance the same way without a second copy.
+export async function tracked(root) {
   try {
     const { stdout } = await exec('git', ['ls-files'], { cwd: root, maxBuffer: 16 << 20 });
     return { files: stdout.split('\n').filter(Boolean) };
@@ -98,7 +100,8 @@ export async function decisionRecords(root) {
   return records;
 }
 
-async function loadCorpus(root) {
+// `async function loadCorpus(root)` (read by `simt why`) becomes `export async`.
+export async function loadCorpus(root) {
   const [rules, skills, lessons, commands] = await Promise.all([
     ruleScopes(root),
     skillScopes(root),

package/src/distill/distill.mjs

@@ -0,0 +1,246 @@
+// The distiller's orchestrator (plan 0003 R38): one target in, one proposal out.
+//
+// R37 gave this repository a local model client, and R38 is the first consumer of
+// it: distillation is the cheapest thing a local model can do that the
+// deterministic engine cannot — abstractive compression — and the one that most
+// needs the guardrails here, because its output is the kind a reader would paste
+// into a pack and forget to check.
+//
+// Nothing here writes outside `.simt-dev/distilled/`, and nothing here edits a
+// source file (ADR-090, ADR-075). A proposal that a human did not merge is a dead
+// file, which is the intended failure mode: proposals expire, projections do not.
+
+import { readFile, mkdir, writeFile } from 'node:fs/promises';
+import { isAbsolute, join, relative, resolve, sep } from 'node:path';
+
+import { EXIT, fail } from '../output/index.mjs';
+import { CLI } from '../name.mjs';
+import { loadRegistry } from '../graph/load.mjs';
+import { nearMatches } from '../resolve/near.mjs';
+import { bodyFile, sourcePath } from '../resolve/body.mjs';
+import { resolveWorkspace } from '../workspace.mjs';
+import { readLocalConfig, chatEndpoint } from '../local/config.mjs';
+import { localChat } from '../local/client.mjs';
+import {
+  ENGINE_LOCAL,
+  ENGINE_OUTLINE,
+  buildLocalPrompt,
+  digestOf,
+  outlineSummary,
+  proposalFrontmatter,
+  promptHash,
+  sourceDigest,
+  verifyCitations,
+} from './engine.mjs';
+
+export const DEFAULT_BUDGET = 2048;
+const DISTILL_DIR = '.simt-dev/distilled';
+
+/**
+ * The row's acceptance metric, stated where a caller reads results (ADR-076):
+ * "bench shows distilled body plus references match the full body on R at lower
+ * C, or the feature stays experimental." It is the second of the two until the
+ * bench measures it, so every report says so rather than implying parity.
+ */
+const METRIC_NOTE = 'parity at lower C unmeasured on R; experimental (plan 0003 R38)';
+
+/**
+ * Resolve `<skill|doc>` to an absolute source path.
+ *
+ * A name first: `distill core-rule` is read as the skill that `skills show` would
+ * read, so both commands answering differently is the defect. A path second:
+ * everything else is a file under the root, and one that escapes the root is
+ * refused — a proposal whose provenance names `../../etc` is provenance nobody
+ * should trust.
+ */
+async function resolveTarget(target, root, flags) {
+  const { registry, errors, ok } = await loadRegistry(null, flags);
+  if (!ok) return { exit: fail(errors[0], EXIT.REGISTRY) };
+
+  const skill = registry.skills.find((s) => s.name === target);
+  if (skill) {
+    const ws = await resolveWorkspace(flags);
+    const full = await sourcePath(skill, ws.root ?? null, root);
+    const readable = full !== null && (full === root || bodyFile(full).startsWith(root + sep));
+    if (!readable) {
+      const near = nearMatches(target, registry.skills.map((s) => s.name));
+      return {
+        exit: fail(
+          `skill "${target}" resolved to ${full ?? 'no body'} and that body is not under ${root}`,
+          EXIT.FAIL,
+          `run ${CLI} skills show ${target} to see how the body resolves, or distill a doc path`,
+        ),
+      };
+    }
+    const canonical = skill.sources?.find((s) => s.role === 'canonical') ?? skill.sources?.[0];
+    return {
+      path: bodyFile(full),
+      name: canonical ? `${canonical.repo}/${canonical.path}` : skill.name,
+      how: 'skill',
+    };
+  }
+
+  const candidate = isAbsolute(target) ? target : resolve(root, target);
+  if (candidate !== root && !candidate.startsWith(root + sep)) {
+    return {
+      exit: fail(`${target} is outside ${root}`, EXIT.FAIL, 'distill reads docs under the repository root only'),
+    };
+  }
+  try {
+    const text = await readFile(bodyFile(candidate), 'utf8');
+    return {
+      path: candidate,
+      name: relative(root, candidate) || target,
+      how: 'doc',
+      text,
+    };
+  } catch {
+    const near = nearMatches(target, registry.skills.map((s) => s.name));
+    return {
+      exit: fail(
+        `no skill named "${target}" and no file ${relative(root, candidate) ?? target}`,
+        EXIT.FAIL,
+        near.length ? `did you mean the skill ${near.join(', ')}?` : `run ${CLI} skills index`,
+      ),
+    };
+  }
+}
+
+/**
+ * The engine dispatch, including the model path's guardrails.
+ *
+ * `--local` without a usable `local.chat` is a configuration error, not a silent
+ * fallback to the deterministic engine: a caller who asked for the model and got
+ * the outline would read the outline's confidence as the model's — and the
+ * reverse, reading model output as deterministic, is worse.
+ */
+async function runEngine(kind, text, budget, context) {
+  if (kind === ENGINE_OUTLINE) return outlineSummary(text, budget);
+
+  const { root, allowRemote, name } = context;
+  const config = await readLocalConfig(root, { allowRemote });
+  // The shared guard arrived from `local/config.mjs` when the critic became the
+  // second real user of the same rules (plan 0003 R39, ADR-002).
+  const endpoint = chatEndpoint(config);
+  if (endpoint.exit !== undefined) return endpoint;
+
+  const prompt = buildLocalPrompt(name, text, budget);
+  const chat = await localChat(config.chat, {
+    system: 'You compress documents for software agents. Follow the rules the user message states exactly.',
+    prompt,
+    temperature: 0,
+    maxTokens: budget === 0 ? 2048 : Math.min(2048, Math.max(256, Math.ceil(budget / 4))),
+    allowRemote,
+  });
+  if (!chat.ok) {
+    return {
+      exit: fail(
+        `local chat failed: ${chat.error}`,
+        EXIT.FAIL,
+        'fix the endpoint, or run without --local for the deterministic engine',
+      ),
+    };
+  }
+  return { engine: ENGINE_LOCAL, model: chat.model, body: String(chat.content).trim(), prompt };
+}
+
+function parseExistingFrontmatter(text) {
+  if (!text.startsWith('---\n')) return {};
+  const head = text.split('\n---', 1)[0];
+  const fields = {};
+  for (const line of head.split('\n').slice(1)) {
+    const m = /^([a-z]+):\s?(.*)$/.exec(line);
+    if (m) fields[m[1]] = m[2];
+  }
+  return fields;
+}
+
+function countCitations(text) {
+  return (text.match(/\[L\d+(-L\d+)?\]/g) ?? []).length;
+}
+
+/**
+ * Returns either the report object (ok) or an exit code (fail) — the same shape
+ * the command layer returns, so a failure passes through unchanged.
+ */
+export async function distillTarget(args, flags) {
+  const target = args[0];
+  if (!target) {
+    return fail(
+      'distill needs a skill name or a doc path',
+      EXIT.USAGE,
+      `usage: ${CLI} distill <skill|doc> [--budget <bytes>]`,
+    );
+  }
+
+  const root = resolve(flags.root ?? process.cwd());
+  const source = await resolveTarget(target, root, flags);
+  if (source.exit !== undefined) return source.exit;
+
+  const text = source.text ?? (await readFile(bodyFile(source.path), 'utf8'));
+  const bytes = Buffer.byteLength(text, 'utf8');
+  const budget = Number.isInteger(flags.budget) ? flags.budget : DEFAULT_BUDGET;
+  const allowRemote = flags.allowRemote === true;
+  const engineKind = flags.local === true ? ENGINE_LOCAL : ENGINE_OUTLINE;
+  const digest = digestOf(text, engineKind, budget);
+  const relProposal = `${DISTILL_DIR}/${digest}.md`;
+  const absProposal = join(root, relProposal);
+  const lineCount = text.split('\n').length;
+
+  const cached = flags.refresh === true ? null : await readFile(absProposal, 'utf8').catch(() => null);
+  if (cached !== null) {
+    const fields = parseExistingFrontmatter(cached);
+    return {
+      ok: true,
+      command: 'distill',
+      target: { kind: source.how, source: source.name, bytes, lines: lineCount },
+      digest: sourceDigest(text),
+      engine: fields.engine ?? ENGINE_OUTLINE,
+      budget: Number(fields.budget ?? budget),
+      citations: countCitations(cached),
+      verified: fields.verified !== 'false',
+      metric: { note: METRIC_NOTE },
+      proposal: { path: relProposal, state: 'cached', bytes: Buffer.byteLength(cached, 'utf8') },
+    };
+  }
+
+  const outcome = await runEngine(engineKind, text, budget, { root, allowRemote, name: source.name });
+  if (outcome.exit !== undefined) return outcome.exit;
+
+  const check = verifyCitations(outcome.body, lineCount);
+  const faults = [...check.faults];
+  const bodyBytes = Buffer.byteLength(outcome.body, 'utf8');
+  if (budget > 0 && bodyBytes > budget) {
+    faults.push(`summary is ${bodyBytes} bytes against a ${budget}-byte budget`);
+  }
+
+  const provenance =
+    outcome.engine === ENGINE_LOCAL
+      ? `${ENGINE_LOCAL}:${outcome.model} (prompt ${promptHash(outcome.prompt)})`
+      : ENGINE_OUTLINE;
+  const proposal =
+    proposalFrontmatter({
+      source: source.name,
+      digest,
+      engine: provenance,
+      budget,
+      verified: faults.length === 0,
+    }) + `\n${outcome.body}\n`;
+
+  await mkdir(join(root, DISTILL_DIR), { recursive: true });
+  await writeFile(absProposal, proposal);
+
+  return {
+    ok: true,
+    command: 'distill',
+    target: { kind: source.how, source: source.name, bytes, lines: lineCount },
+    digest: sourceDigest(text),
+    engine: provenance,
+    budget,
+    citations: check.ranges.length,
+    verified: faults.length === 0,
+    ...(faults.length > 0 ? { faults } : {}),
+    metric: { note: METRIC_NOTE },
+    proposal: { path: relProposal, state: 'fresh', bytes: Buffer.byteLength(proposal, 'utf8') },
+  };
+}

package/src/distill/engine.mjs

@@ -0,0 +1,187 @@
+// The distiller's engines (plan 0003 R38).
+//
+// `simt distill` writes a budgeted summary of a skill body or doc, with every claim
+// citing the source line range it rests on. Two engines produce that shape:
+//
+//   - `outline` (default): a deterministic, extractive summary — the heading
+//     skeleton plus the first content of each section, cut to the budget. No
+//     model, no network, byte-stable: the same text at the same budget produces
+//     the same bytes forever (P1, P4).
+//   - `local`: the configured local chat model (R37) proposes a abstractive
+//     summary. It is opt-in (`--local`), loopback-only by default, and its output
+//     is verified against the source before anything is written.
+//
+// Both engines write the same artefact: a *proposal*, never a projection. The
+// proposal file carries its provenance in frontmatter (source, digest, engine,
+// prompt hash for the model path); a human merges it into the pack or repo, and
+// nothing in this module ever edits a source file (ADR-090/ADR-075, principle P2).
+
+import { createHash } from 'node:crypto';
+
+export const ENGINE_OUTLINE = 'outline';
+export const ENGINE_LOCAL = 'local';
+
+/**
+ * The cache key: source digest plus the recipe that shaped the output. Two
+ * proposals of the same text at different budgets are different answers, so one
+ * key carries both rather than letting a second write collide with the first.
+ */
+export function digestOf(text, engine, budget) {
+  const h = createHash('sha256');
+  h.update(`${engine}\0${budget}\0${text}`);
+  return `sha256-${h.digest('hex').slice(0, 16)}`;
+}
+
+/** Same function for the source itself, where the recipe does not apply. */
+export function sourceDigest(text) {
+  return `sha256-${createHash('sha256').update(text).digest('hex').slice(0, 16)}`;
+}
+
+/** The hash of the prompt sent to a model engine — the provenance P2 asks for. */
+export function promptHash(prompt) {
+  return `sha256-${createHash('sha256').update(prompt).digest('hex').slice(0, 16)}`;
+}
+
+const FENCE = /^\s*(```|~~~)/;
+const HEADING = /^#{1,6}\s/;
+
+/**
+ * Build the prompt a local model receives (ENGINE_LOCAL only).
+ *
+ * The source ships with line numbers printed, because the only citation format
+ * the verifier can check is `[L<n>-<m>]` against those numbers. A model asked to
+ * "cite the source" but given unnumbered text can only guess, and every guess is
+ * a citation that looks true and cannot be checked — which is the defect this
+ * command exists to prevent.
+ */
+export function buildLocalPrompt(fileName, text, budget) {
+  const numbered = text
+    .split('\n')
+    .map((line, i) => `${i + 1}: ${line}`)
+    .join('\n');
+  return [
+    'Distill the document below into what an agent must know to act on it.',
+    `The summary must not exceed ${budget} bytes. Rules:`,
+    '- Every claim ends with a citation to a source line range, written [L12] or [L12-L15], using the line numbers printed below.',
+    '- Cite only lines that exist in the source. Never cite a line you cannot see.',
+    '- Copy commands, paths, thresholds and names verbatim; do not paraphrase them.',
+    '- Do not invent content, and do not add advice the source does not contain.',
+    `- Reply with the summary only; nothing else.`,
+    '',
+    `SOURCE ${fileName}`,
+    numbered,
+  ].join('\n');
+}
+
+/**
+ * The deterministic extractive engine (ENGINE_OUTLINE).
+ *
+ * Selection, readable as a score: every heading first (they are the document's
+ * own structure), then the immediate non-empty content under each heading. The
+ * result is the document in its own words, in document order, at a fraction of
+ * the bytes — which is the comparison the acceptance criterion asks the bench to
+ * run, and the honest thing an offline engine can claim.
+ *
+ * Bounds: the returned body never exceeds `budget` bytes (0 = unlimited), and
+ * every line it renders carries a citation the verifier below can check.
+ */
+export function outlineSummary(text, budget) {
+  const lines = text.split('\n');
+  const picks = [];
+  let inline = false;
+
+  // Pass 1: headings.
+  for (let i = 0; i < lines.length; i += 1) {
+    const line = lines[i];
+    if (FENCE.test(line)) inline = !inline;
+    if (inline) continue;
+    if (HEADING.test(line)) picks.push(i);
+  }
+
+  // Pass 2: the first content line under each heading.
+  for (const i of [...picks]) {
+    for (let j = i + 1; j < lines.length; j += 1) {
+      if (FENCE.test(lines[j])) break;
+      if (HEADING.test(lines[j])) break;
+      if (lines[j].trim() === '') continue;
+      picks.push(j);
+      break;
+    }
+  }
+
+  if (picks.length === 0 && lines.some((l) => l.trim() !== '')) {
+    // No headings at all: a doc of prose. The whole thing is one section, so the
+    // first content line is the citation anchor rather than an empty summary.
+    const first = lines.findIndex((l) => l.trim() !== '' && !FENCE.test(l));
+    if (first !== -1) picks.push(first);
+  }
+
+  picks.sort((a, b) => a - b);
+
+  const body = [];
+  let used = 0;
+  for (const i of picks) {
+    const text = lines[i].trimEnd();
+    const bullet = `>[L${i + 1}] ${text}`;
+    const cost = Buffer.byteLength(`${bullet}\n`, 'utf8');
+    if (budget > 0 && used + cost > budget) break;
+    used += cost;
+    body.push(bullet);
+  }
+
+  return { engine: ENGINE_OUTLINE, body: body.join('\n'), citations: body.length, budgetUsed: used };
+}
+
+/**
+ * Check a summary's citations against the source that supposedly backs them.
+ *
+ * A citation naming a line past the end of the source is fabricated; a summary
+ * with any such citation is returned with `--json` detailed faults and is never
+ * silently trusted. The proposal still writes (it is only a proposal), but its
+ * provenance records `verified: false` so a reader cannot mistake it for checked
+ * output (ADR-083).
+ */
+export function verifyCitations(body, sourceLineCount) {
+  const faults = [];
+  const ranges = [];
+  const re = /\[L(\d+)(?:-L?(\d+))?\]/g;
+  let match;
+  while ((match = re.exec(body)) !== null) {
+    const start = Number(match[1]);
+    const end = match[2] === undefined ? start : Number(match[2]);
+    const kind =
+      start < 1 || start > sourceLineCount
+        ? `start`
+        : end < start
+          ? `order`
+          : end > sourceLineCount
+            ? `end`
+            : null;
+    if (kind !== null) {
+      faults.push(`citation [L${start}-L${end}] ${kind} outside the source (1..${sourceLineCount})`);
+      continue;
+    }
+    ranges.push({ start, end });
+  }
+  return { ok: faults.length === 0, ranges, faults };
+}
+
+/** The proposal file's frontmatter. No wall-clock value here: byte-stable (P4). */
+export function proposalFrontmatter({ source, digest, engine, budget, prompt, verified, verdict, advisory }) {
+  return [
+    '---',
+    `source: ${source}`,
+    `digest: ${digest}`,
+    `engine: ${engine}`,
+    `budget: ${budget}`,
+    prompt ? `prompt: ${prompt}` : null,
+    verdict ? `verdict: ${verdict}` : null,
+    advisory ? 'advisory: true' : null,
+    verified === false ? 'verified: false' : 'verified: true',
+    'status: proposal',
+    '---',
+    '',
+  ]
+    .filter((l) => l !== null)
+    .join('\n');
+}

package/src/local/config.mjs

@@ -10,6 +10,7 @@
 //
 // Non-loopback URLs are refused unless `--allow-remote` is explicitly passed (ADR-075).
 
+import { EXIT, fail } from '../output/index.mjs';
 import { MANIFEST_FILE } from '../name.mjs';
 import { readManifest } from '../projection/manifest.mjs';
 
@@ -232,3 +233,37 @@ export async function readLocalConfig(root, { allowRemote = false } = {}) {
     manifestError: null,
   };
 }
+
+/**
+ * The guard every model consumer shares (R37's distill, R39's critic and bench).
+ *
+ * A `--local`-shaped call without a usable chat endpoint is a configuration
+ * error, never a silent fallback to the deterministic path: a caller who asked
+ * for the model and got the deterministic answer would read that answer as the
+ * model's — and the reverse, reading model output as deterministic, is worse.
+ * Second real user arrived with the critic, so the guard moved here from the
+ * distiller's `runEngine` (ADR-002).
+ *
+ * Returns `{ chat }` on success or `{ exit }` with the failure already shaped
+ * (the same pass-through shape the command layer returns).
+ */
+export function chatEndpoint(config) {
+  if (config.manifestError !== null) {
+    return { exit: fail(`${MANIFEST_FILE}: ${config.manifestError}`, EXIT.CONFIG) };
+  }
+  if (!config.configured || !config.chat || config.findings.length > 0) {
+    const detail = !config.configured
+      ? 'no local model is configured'
+      : config.remoteBlocked
+        ? 'the configured chat endpoint is non-loopback and was refused'
+        : 'the local configuration has errors';
+    return {
+      exit: fail(
+        `--local needs a usable local chat endpoint: ${detail}`,
+        EXIT.CONFIG,
+        `configure local.chat in ${MANIFEST_FILE} (plan 0003 R37), or run without --local for the deterministic path`,
+      ),
+    };
+  }
+  return { chat: config.chat };
+}

package/src/resolve/body.mjs

@@ -0,0 +1,46 @@
+// Where a skill's body lives, and how a path the registry names becomes a file.
+//
+// Extracted from src/commands/skills.mjs when the distiller (plan 0003 R38) became
+// the second real caller: two commands that resolve the same body differently would
+// print two answers to one question, and ADR-002 refuses the third copy rather than
+// the second use.
+//
+// Sources are declared as `repo/path`, so finding one needs the workspace that
+// CONTAINS the repos. That used to be `resolve(here, '..', '..', '..')`, which is
+// right in the checkout and wrong in `node_modules` - so every source resolved to a
+// path that could not exist and `skills` failed with 38 ENOENT lines. Now it comes
+// from configuration, and `null` is a legitimate answer meaning "this installation
+// has no workspace" (ADR-014).
+//
+// A second location exists and is not a fallback: the repo being read is itself a
+// location for a declared source, matched on bytes rather than on hope (ADR-015).
+// The canonical source is still tried first, so a workspace body always wins.
+
+import { join } from 'node:path';
+import { existsSync } from 'node:fs';
+
+import { locateSource, sourceHeldLocally } from './source.mjs';
+
+export async function sourcePath(skill, workspaceRoot, root) {
+  const canonical = skill.sources?.find((s) => s.role === 'canonical') ?? skill.sources?.[0];
+
+  if (canonical) {
+    const found = await locateSource(canonical, { workspaceRoot, root });
+    if (found.path) return found.path;
+  }
+
+  const held = await sourceHeldLocally(skill, root, { workspaceRoot });
+  if (held && !held.ambiguous) return held.path;
+
+  // A skill with no canonical source, or one whose bytes match nothing, has no
+  // body. Say so rather than printing an empty section.
+  return canonical && workspaceRoot ? join(workspaceRoot, canonical.repo, canonical.path) : null;
+}
+
+/**
+ * The file a source path points at. A path may be a directory that carries its
+ * body as SKILL.md, the Agent Skills layout; SKILL.md wins when both exist.
+ */
+export function bodyFile(full) {
+  return existsSync(join(full, 'SKILL.md')) ? join(full, 'SKILL.md') : full;
+}