simt-dev 0.3.1 → 0.4.0

package/src/commands/lessons.mjs

@@ -0,0 +1,127 @@
+// `simt lessons [list|review]` — deterministic lesson candidates and promotion to
+// `docs/lessons/NNNN-<slug>.md` (plan 0003 R32).
+
+import { resolve } from 'node:path';
+
+import { EXIT, emit, emitJson, fail, isJson, note, writeMode } from '../output/index.mjs';
+import { CLI } from '../name.mjs';
+import { parsePathList } from '../argv.mjs';
+import {
+  LESSONS_DIR,
+  LESSONS_FILE,
+  captureFromLedger,
+  captureRevertedCommits,
+  listPromotedLessons,
+  promoteLesson,
+  readLessonCandidates,
+} from '../memory/lessons.mjs';
+
+export async function lessonsListCommand(args, flags) {
+  if (args.length > 0) {
+    return fail(`unknown lessons argument ${args[0]}`, EXIT.USAGE, `run: ${CLI} lessons`);
+  }
+  const root = resolve(flags.root ?? process.cwd());
+  await captureFromLedger(root);
+  await captureRevertedCommits(root);
+
+  const [{ candidates, errors }, promoted] = await Promise.all([
+    readLessonCandidates(root),
+    listPromotedLessons(root),
+  ]);
+
+  const payload = {
+    ok: errors.length === 0,
+    command: 'lessons list',
+    root,
+    ledgerFile: LESSONS_FILE,
+    lessonsDir: LESSONS_DIR,
+    candidateCount: candidates.length,
+    promotedCount: promoted.length,
+    candidates,
+    promoted,
+    errors,
+  };
+
+  if (isJson(flags)) {
+    emitJson(payload, { pretty: flags.pretty === true, maxBytes: flags.maxBytes ?? 0 });
+    return errors.length === 0 ? EXIT.OK : EXIT.FAIL;
+  }
+
+  const lines = [
+    `candidates  ${candidates.length} (${LESSONS_FILE})`,
+    `promoted    ${promoted.length} (${LESSONS_DIR})`,
+  ];
+
+  if (candidates.length > 0) {
+    lines.push('', 'CANDIDATES');
+    for (const c of candidates) {
+      const sigShort = c.signature.slice(0, 19);
+      const state = c.status === 'promoted' ? `promoted -> ${c.promotedTo}` : 'candidate';
+      lines.push(`  ${c.id}  ${c.kind.padEnd(14)}  ${sigShort}  ${state}  ${c.summary}`);
+    }
+  }
+
+  if (promoted.length > 0) {
+    lines.push('', 'LESSONS');
+    for (const l of promoted) {
+      lines.push(`  ${l.id.padEnd(28)}  ${(l.signature ?? 'no-signature').slice(0, 19)}  ${l.title}`);
+    }
+  }
+
+  for (const err of errors) lines.push(`error       ${err}`);
+
+  emit(lines.join('\n'), { maxBytes: flags.maxBytes ?? 0 });
+  return errors.length === 0 ? EXIT.OK : EXIT.FAIL;
+}
+
+export async function lessonsReviewCommand(args, flags) {
+  if (args.length > 1) {
+    return fail(`unknown lessons review argument ${args[1]}`, EXIT.USAGE, `run: ${CLI} lessons review [<id>] [--yes]`);
+  }
+  const root = resolve(flags.root ?? process.cwd());
+  const mode = writeMode(flags);
+  const parsedPaths = parsePathList(flags.paths);
+  const paths = parsedPaths.length > 0 ? parsedPaths : undefined;
+  const title = flags.task ? String(flags.task) : undefined;
+
+  const result = await promoteLesson(root, {
+    id: args[0],
+    apply: mode.apply,
+    paths,
+    title,
+  });
+
+  if (!result.ok) {
+    return fail(result.error, EXIT.FAIL, `record a session failure-then-fix or run: ${CLI} lessons`);
+  }
+
+  const payload = {
+    ok: true,
+    command: 'lessons review',
+    root,
+    dryRun: mode.dryRun,
+    written: result.written,
+    path: result.path,
+    candidate: result.candidate,
+    markdown: result.markdown,
+  };
+
+  if (isJson(flags)) {
+    emitJson(payload, { pretty: flags.pretty === true, maxBytes: flags.maxBytes ?? 0 });
+    return EXIT.OK;
+  }
+
+  const lines = [
+    `promote     ${result.candidate.id} (${result.candidate.kind}) -> ${result.path}`,
+    `signature   ${result.candidate.signature}`,
+    `mode        ${mode.apply ? 'applied' : mode.dryRun ? 'dry-run (writes nothing)' : `preview (pass --yes to write ${result.path})`}`,
+    '',
+    result.markdown.trimEnd(),
+  ];
+
+  emit(lines.join('\n'), { maxBytes: flags.maxBytes ?? 0 });
+  if (!mode.apply) {
+    note(`note    dry-run  nothing written; apply with: ${CLI} lessons review --yes`);
+  }
+  return EXIT.OK;
+}

package/src/commands/local.mjs

@@ -0,0 +1,97 @@
+// `simt local doctor` — probe configured local model endpoints (plan 0003 R37).
+//
+// Reads `local: { chat: { url, model }, embed: { url, model } }` from `simt.json`.
+// When `local` is unset, opens no socket and exits 0. Refuses non-loopback URLs
+// without `--allow-remote` (ADR-075).
+
+import { resolve } from 'node:path';
+import { EXIT, emit, emitJson, fail, isJson } from '../output/index.mjs';
+import { CLI, MANIFEST_FILE } from '../name.mjs';
+import { probeLocal } from '../local/client.mjs';
+
+function formatRoleLine(role, report) {
+  if (!report) return `${role.padEnd(8)} (unset)`;
+  if (report.status === 'refused-remote') {
+    return `${role.padEnd(8)} refused-remote  ${report.model} @ ${report.url}`;
+  }
+  if (!report.ok) {
+    return `${role.padEnd(8)} ${report.status}  ${report.model} @ ${report.url} (${report.error})`;
+  }
+  const extra =
+    role === 'embed' && Number.isInteger(report.dimensions)
+      ? `  dimensions=${report.dimensions}`
+      : '';
+  const listed =
+    report.modelListed === true
+      ? '  listed=yes'
+      : report.modelListed === false
+        ? '  listed=no'
+        : '';
+  return `${role.padEnd(8)} ok  ${report.model} @ ${report.url}${extra}${listed}`;
+}
+
+function remedyFor(result) {
+  if (result.status === 'refused-remote') {
+    return `set a loopback URL (http://127.0.0.1:<port>/v1) in ${MANIFEST_FILE}, or run: ${CLI} local doctor --allow-remote`;
+  }
+  if (result.status === 'invalid-config' || result.status === 'invalid-manifest') {
+    return `fix the \`local\` configuration in ${MANIFEST_FILE}`;
+  }
+  if (result.status === 'unreachable') {
+    return `start the local model server at the URL in ${MANIFEST_FILE}, then rerun: ${CLI} local doctor`;
+  }
+  return null;
+}
+
+export async function localDoctorCommand(args, flags) {
+  const root = resolve(flags.root ?? args[0] ?? process.cwd());
+  const allowRemote = flags.allowRemote === true;
+  const result = await probeLocal(root, { allowRemote });
+
+  const code = result.ok
+    ? EXIT.OK
+    : result.status === 'refused-remote' ||
+        result.status === 'invalid-config' ||
+        result.status === 'invalid-manifest'
+      ? EXIT.CONFIG
+      : EXIT.FAIL;
+
+  const error = result.ok ? null : result.findings[0] ?? `local model probe failed (${result.status})`;
+  const remedy = result.ok ? null : remedyFor(result);
+
+  if (isJson(flags)) {
+    emitJson(
+      {
+        ok: code === EXIT.OK,
+        command: 'local doctor',
+        root,
+        configured: result.configured,
+        status: result.status,
+        allowRemote: result.allowRemote,
+        remoteBlocked: result.remoteBlocked,
+        socketsOpened: result.socketsOpened,
+        chat: result.chat,
+        embed: result.embed,
+        findings: result.findings,
+        ...(error ? { error, remedy, exitCode: code } : {}),
+      },
+      { maxBytes: flags.maxBytes ?? 0 },
+    );
+    return code;
+  }
+
+  const lines = [
+    `root     ${root}`,
+    `local    ${result.configured ? result.status : '(unset)  optional adapter is off; no socket opened'}`,
+    formatRoleLine('chat', result.chat),
+    formatRoleLine('embed', result.embed),
+    `sockets  ${result.socketsOpened}`,
+  ];
+
+  emit(lines.join('\n'), { maxBytes: flags.maxBytes ?? 0 });
+
+  if (!result.ok) {
+    return fail(error, code, remedy);
+  }
+  return EXIT.OK;
+}

package/src/commands/map.mjs

@@ -5,8 +5,15 @@
 
 import { EXIT, emit, emitJson, fail, isJson } from '../output/index.mjs';
 import { CLI } from '../name.mjs';
-import { readEdges, readFiles, readSymbols, reindex } from '../index/store.mjs';
-import { DEFAULT_BUDGET, formatRecall, measureRecall, rankFiles, renderMap } from '../index/map.mjs';
+import { readEdges, readEmbeddings, readFiles, readFts, readSymbols, reindex, searchFtsBm25 } from '../index/store.mjs';
+import {
+  DEFAULT_BUDGET,
+  embedTaskQuery,
+  formatRecall,
+  measureRecall,
+  rankFiles,
+  renderMap,
+} from '../index/map.mjs';
 
 const LEVELS = new Set(['outline', 'names', 'signatures']);
 
@@ -25,7 +32,15 @@ export async function mapCommand(args, flags) {
   const loaded = await loadGraph(root);
   if (loaded.error) return loaded.error;
   const task = typeof flags.task === 'string' ? flags.task : '';
-  const ranked = rankFiles({ ...loaded, task });
+  const bm25 = task.trim().length > 0 ? await searchFtsBm25(root, task, { fts: loaded.fts }) : [];
+  const queryVector =
+    flags.embed === true && loaded.embeddings.length > 0
+      ? await embedTaskQuery(root, task, {
+          embed: true,
+          allowRemote: flags.allowRemote === true,
+        })
+      : null;
+  const ranked = rankFiles({ ...loaded, bm25, queryVector, task });
   const rendered = renderMap(ranked, loaded.symbols, { level, budget });
   const payload = {
     ok: true,
@@ -57,7 +72,10 @@ export async function mapCommand(args, flags) {
 async function recall(root, flags) {
   let result;
   try {
-    result = await measureRecall(root);
+    result = await measureRecall(root, {
+      embed: flags.embed === true,
+      allowRemote: flags.allowRemote === true,
+    });
   } catch (error) {
     return fail(`could not measure recall (${error.message})`, EXIT.UNSUPPORTED, `run ${CLI} index in a git repository`);
   }
@@ -70,9 +88,21 @@ async function recall(root, flags) {
   return EXIT.OK;
 }
 
-async function loadGraph(root) {
+/**
+ * The files, symbols, edges, FTS rows and stored vector embeddings the index holds,
+ * building the index once when it is empty.
+ *
+ * `build: false` refuses that rebuild and answers with `cold: true` instead. The one
+ * caller that passes it is the prompt-submit hook (R29), and the reason is the bar that
+ * hook has to meet: a delivered packet that built an index would make a person's first
+ * prompt in a fresh clone wait on a walk of the whole repository, and a prompt that takes
+ * a minute to appear is how a hook gets uninstalled. The next prompt gets the packet, and
+ * a command a person typed at a terminal always builds what it needs.
+ */
+export async function loadGraph(root, { build = true } = {}) {
   let files = await readFiles(root);
   if (files.length === 0) {
+    if (!build) return { files: [], symbols: [], edges: [], fts: [], embeddings: [], cold: true };
     try {
       await reindex(root);
     } catch (error) {
@@ -86,6 +116,11 @@ async function loadGraph(root) {
     }
     files = await readFiles(root);
   }
-  const [symbols, edges] = await Promise.all([readSymbols(root), readEdges(root)]);
-  return { files, symbols, edges };
+  const [symbols, edges, fts, embeddings] = await Promise.all([
+    readSymbols(root),
+    readEdges(root),
+    readFts(root),
+    readEmbeddings(root),
+  ]);
+  return { files, symbols, edges, fts, embeddings };
 }

package/src/commands/repoindex.mjs

@@ -13,7 +13,10 @@ export async function indexCommand(args, flags) {
   const root = flags.root ?? process.cwd();
   let result;
   try {
-    result = await reindex(root);
+    result = await reindex(root, {
+      embed: flags.embed === true,
+      allowRemote: flags.allowRemote === true,
+    });
   } catch (error) {
     return fail(
       `could not index this repository (${error.message})`,

package/src/commands/rules.mjs

@@ -14,6 +14,8 @@
 // one, because "this rule has no decision behind it" is exactly the fact a
 // reviewer needs and exactly the fact an empty output would hide.
 
+import { readdir } from 'node:fs/promises';
+import { join } from 'node:path';
 import { EXIT, emit, emitJson, fail, isJson } from '../output/index.mjs';
 import { loadRules, select } from '../projection/project.mjs';
 import { loadMdcRules } from '../projection/mdc.mjs';
@@ -217,10 +219,17 @@ export async function whyCommand(args, flags) {
   if (!what) return fail('rules why needs a rule id or an ADR id', EXIT.USAGE, `usage: ${CLI} rules why <rule-id|ADR-NNN>`);
 
   const { rules, broken } = await load(flags.root ?? null);
-  const { ok, decisions, errors } = await loadDecisions({ all: flags.all === true });
+  const localDir = flags.root ? join(flags.root, 'docs', 'decisions') : null;
+  const hasLocal = localDir
+    ? (await readdir(localDir).catch(() => [])).some((n) => /^ADR-\d{3,}-.*\.md$/i.test(n))
+    : false;
+  const { ok, decisions, errors } = await loadDecisions({
+    all: flags.all === true,
+    ...(hasLocal ? { dir: localDir } : {}),
+  });
   if (!ok) return fail(errors[0], EXIT.CONFIG, 'the decision records must be readable for provenance to work');
 
-  return what.match(/^ADR-\d{3}$/i)
+  return what.match(/^ADR-\d{3,}$/i)
     ? adrDirection(what.toUpperCase(), rules, decisions, flags)
     : ruleDirection(what, rules, decisions, flags, broken);
 }
@@ -326,6 +335,12 @@ async function adrDirection(adr, rules, decisions, flags) {
   ];
   if (d.supersededBy) lines.push(`SUPERSEDED by ${d.supersededBy} - this record is retained as evidence, not as policy.`);
   if (d.supersedes.length > 0) lines.push(`supersedes  ${d.supersedes.join(', ')}`);
+  const partialForward = (d.supersedesRulings ?? []).filter((s) => s.ruling !== null);
+  if (partialForward.length > 0) {
+    lines.push(
+      `supersedes  ${partialForward.map((s) => `${s.adr} ruling ${s.ruling} (${s.kind})`).join('; ')}`,
+    );
+  }
   // A partial supersession is named here as well as on the ruling it moved, because the
   // two print different sets: this prints every ruling the record lost, and the
   // annotation prints the ones inside the excerpt below. A ruling past the excerpt

package/src/commands/skills.mjs

@@ -22,6 +22,9 @@ import { fingerprint } from '../resolve/fingerprint.mjs';
 import { tokenize, rankSkills, closure, selectWithinBudget, resolveAlias, scoreSkill, selectionVerdict, stackCompatible } from '../resolve/resolve.mjs';
 import { nearMatches } from '../resolve/near.mjs';
 import { CLI } from '../name.mjs';
+import { parsePathList } from '../argv.mjs';
+
+export { parsePathList };
 
 const DEFAULT_BUDGET = 20480;
 
@@ -42,23 +45,6 @@ export async function dirtyPaths(root) {
   }
 }
 
-export function parsePathList(value) {
-  return String(value ?? '')
-    .split(',')
-    .map((s) => s.trim())
-    .filter(Boolean);
-}
-
-/**
- * Read a list flag in both the forms this tool ships.
- *
- * `--skill` accepts `--skill a --skill b` and `--skill a,b`, and arrives here as an
- * array in the first case and a string in the second. `String(['a','b'])` happens to
- * produce `'a,b'`, so the old one-line reader would have kept working by accident — and
- * would have started throwing the moment a skill name contained the character the
- * join inserts. Both shapes are handled rather than one being relied upon, because
- * relying on it is the same class of bug as the one being fixed here.
- */
 export function listFlag(value) {
   return (Array.isArray(value) ? value : [value])
     .flatMap((v) => parsePathList(v))

package/src/commands/skillscompile.mjs

@@ -0,0 +1,255 @@
+// `simt skills compile [<name>]` - compile skills to Agent Skills standard, flag bodies
+// over 5k tokens with a progressive-disclosure split plan, and report per-skill trigger
+// recall and precision from R02 transcripts (plan 0003 R30).
+
+import { existsSync } from 'node:fs';
+import { mkdir, readdir, readFile, writeFile } from 'node:fs/promises';
+import { dirname, join, resolve } from 'node:path';
+
+import { EXIT, emit, emitJson, fail, isJson, note, writeMode } from '../output/index.mjs';
+import { loadRegistry } from '../graph/load.mjs';
+import {
+  BODY_TOKEN_BUDGET,
+  compileSkill,
+  evaluateSkillTriggers,
+  proposeSkillDescription,
+} from '../graph/compile.mjs';
+import { loadRunRecords } from '../bench/report.mjs';
+import { extractPatchFiles } from '../bench/grade.mjs';
+import { resolveVaultDir } from '../bench/mine.mjs';
+import { locateSource, sourceHeldLocally } from '../resolve/source.mjs';
+import { nearMatches } from '../resolve/near.mjs';
+import { resolveWorkspace, WORKSPACE_REMEDY } from '../workspace.mjs';
+import { CLI, CONFIG_DIR } from '../name.mjs';
+
+const STATE_DIR = `.${CONFIG_DIR}`;
+
+async function readSkillRawText(skill, workspaceRoot, root) {
+  const canonical = skill.sources?.find((s) => s.role === 'canonical') ?? skill.sources?.[0];
+  let full = null;
+  if (canonical) {
+    const found = await locateSource(canonical, { workspaceRoot, root });
+    if (found.path) full = found.path;
+  }
+  if (!full) {
+    const held = await sourceHeldLocally(skill, root, { workspaceRoot });
+    if (held && !held.ambiguous) full = held.path;
+  }
+  if (!full || !existsSync(full)) return null;
+  try {
+    const target = existsSync(join(full, 'SKILL.md')) ? join(full, 'SKILL.md') : full;
+    return await readFile(target, 'utf8');
+  } catch {
+    return null;
+  }
+}
+
+async function loadGoldPathsByTask(root) {
+  const map = new Map();
+  const tasksDir = join(root, STATE_DIR, 'bench', 'tasks');
+  const vaultRoot = resolveVaultDir(root);
+  const entries = (await readdir(tasksDir).catch(() => [])).filter((f) => f.endsWith('.json')).sort();
+  for (const entry of entries) {
+    try {
+      const task = JSON.parse(await readFile(join(tasksDir, entry), 'utf8'));
+      const patch = await readFile(join(vaultRoot, task.id, 'gold.patch'), 'utf8').catch(() => '');
+      if (patch) map.set(task.id, extractPatchFiles(patch));
+    } catch {
+      // ignore unreadable task
+    }
+  }
+  return map;
+}
+
+function fmtMetric(v) {
+  return v === null || v === undefined ? 'n/a' : v.toFixed(3);
+}
+
+export async function compileCommand(args, flags) {
+  const { registry, errors, ok } = await loadRegistry(null, flags);
+  if (!ok) return fail(errors[0], EXIT.REGISTRY, WORKSPACE_REMEDY);
+
+  const root = resolve(flags.root ?? process.cwd());
+  const ws = await resolveWorkspace(flags);
+  const targetName = args[0] ?? null;
+
+  if (targetName) {
+    const skill = registry.skills.find((s) => s.name === targetName);
+    if (!skill) {
+      const near = nearMatches(targetName, registry.skills.map((s) => s.name));
+      return fail(
+        `no skill named "${targetName}"${near.length ? ` (did you mean ${near.join(', ')}?)` : ''}`,
+        EXIT.USAGE,
+        `run: ${CLI} skills find <query>`,
+      );
+    }
+    return runSingleSkillCompile(skill, registry, { root, workspaceRoot: ws.root, flags });
+  }
+
+  const [runs, goldPathsByTask] = await Promise.all([
+    loadRunRecords(root),
+    loadGoldPathsByTask(root),
+  ]);
+
+  const bodiesBySkill = new Map();
+  for (const skill of registry.skills) {
+    const raw = await readSkillRawText(skill, ws.root, root);
+    if (raw) bodiesBySkill.set(skill.name, raw);
+  }
+
+  const report = evaluateSkillTriggers(registry, runs, { bodiesBySkill, goldPathsByTask });
+  const flagged = report.skills.filter((s) => s.flagged);
+
+  if (isJson(flags)) {
+    emitJson(
+      {
+        ok: true,
+        command: 'skills compile',
+        root,
+        tokenBudget: BODY_TOKEN_BUDGET,
+        runCount: report.runCount,
+        skillCount: report.skillCount,
+        flaggedCount: report.flaggedCount,
+        skills: report.skills,
+        flagged: flagged.map((s) => ({
+          name: s.name,
+          bytes: s.bytes,
+          tokens: s.tokens,
+          splitPlan: s.splitPlan,
+        })),
+      },
+      { maxBytes: flags.maxBytes ?? 0 },
+    );
+    return EXIT.OK;
+  }
+
+  const lines = [
+    `skills   ${report.skillCount} total, ${report.flaggedCount} over ${BODY_TOKEN_BUDGET} tokens (flagged with split plan)`,
+    `runs     ${report.runCount} benchmark run(s) in ${root}`,
+    '',
+    'TRIGGER REPORT',
+    'name                          tokens  exp  open  recall  precision  split',
+    ...report.skills.map((s) => {
+      const name = s.name.padEnd(28);
+      const tok = String(s.tokens).padStart(6);
+      const exp = String(s.expected).padStart(4);
+      const opn = String(s.opened).padStart(5);
+      const rec = fmtMetric(s.recall).padStart(7);
+      const prec = fmtMetric(s.precision).padStart(10);
+      const split = s.flagged ? `SPLIT (${s.splitPlan.references.length} refs)` : 'ok';
+      return `${name} ${tok} ${exp} ${opn} ${rec} ${prec}  ${split}`;
+    }),
+  ];
+
+  if (flagged.length > 0) {
+    lines.push('', `SPLIT PLANS (${flagged.length} over ${BODY_TOKEN_BUDGET} tokens)`);
+    for (const s of flagged) {
+      const refs = s.splitPlan.references.map((r) => `${r.path} (~${r.tokens}t)`).join(', ');
+      lines.push(
+        `  ${s.name.padEnd(26)} ~${s.tokens}t (${s.bytes} B) -> SKILL.md (~${s.splitPlan.mainTokens}t) + ${s.splitPlan.references.length} ref(s): ${refs}`,
+      );
+    }
+  }
+
+  emit(lines.join('\n'), { maxBytes: flags.maxBytes ?? 0 });
+  return EXIT.OK;
+}
+
+async function runSingleSkillCompile(skill, registry, { root, workspaceRoot, flags }) {
+  const mode = writeMode(flags);
+  const [rawText, runs, goldPathsByTask] = await Promise.all([
+    readSkillRawText(skill, workspaceRoot, root),
+    loadRunRecords(root),
+    loadGoldPathsByTask(root),
+  ]);
+
+  const bodiesBySkill = new Map();
+  if (rawText) bodiesBySkill.set(skill.name, rawText);
+
+  const triggerReport = evaluateSkillTriggers(registry, runs, { bodiesBySkill, goldPathsByTask });
+  const triggerStats = triggerReport.skills.find((s) => s.name === skill.name) ?? null;
+  const compiled = compileSkill(skill, rawText);
+  const proposal = await proposeSkillDescription(skill, {
+    currentDescription: compiled.description,
+    triggerStats,
+  });
+
+  const outDir = join(root, STATE_DIR, 'compiled', 'skills', skill.name);
+  const proposalPath = join(root, STATE_DIR, 'proposals', 'skills', `${skill.name}.json`);
+  const writtenFiles = [];
+
+  if (mode.apply) {
+    await mkdir(outDir, { recursive: true });
+    await writeFile(join(outDir, 'SKILL.md'), compiled.mainText, 'utf8');
+    writtenFiles.push(`${STATE_DIR}/compiled/skills/${skill.name}/SKILL.md`);
+
+    for (const ref of compiled.references) {
+      if (!ref.content) continue;
+      const refFull = join(outDir, ref.path);
+      await mkdir(dirname(refFull), { recursive: true });
+      await writeFile(refFull, ref.content, 'utf8');
+      writtenFiles.push(`${STATE_DIR}/compiled/skills/${skill.name}/${ref.path}`);
+    }
+
+    await mkdir(dirname(proposalPath), { recursive: true });
+    await writeFile(proposalPath, `${JSON.stringify(proposal, null, 2)}\n`, 'utf8');
+    writtenFiles.push(`${STATE_DIR}/proposals/skills/${skill.name}.json`);
+  }
+
+  if (isJson(flags)) {
+    emitJson(
+      {
+        ok: true,
+        command: 'skills compile',
+        root,
+        skill: skill.name,
+        dryRun: mode.dryRun,
+        written: mode.apply,
+        files: writtenFiles,
+        description: compiled.description,
+        mainBytes: compiled.mainBytes,
+        mainTokens: compiled.mainTokens,
+        conformance: compiled.conformance,
+        splitPlan: compiled.splitPlan,
+        trigger: triggerStats
+          ? {
+              expected: triggerStats.expected,
+              opened: triggerStats.opened,
+              tp: triggerStats.tp,
+              fp: triggerStats.fp,
+              fn: triggerStats.fn,
+              recall: triggerStats.recall,
+              precision: triggerStats.precision,
+            }
+          : null,
+        proposal,
+      },
+      { maxBytes: flags.maxBytes ?? 0 },
+    );
+    return EXIT.OK;
+  }
+
+  const lines = [
+    `compile     ${skill.name}`,
+    `mode        ${mode.apply ? 'applied' : mode.dryRun ? 'dry-run (writes nothing)' : `preview (pass --yes to write compiled skill)`}`,
+    `source      ${rawText ? 'body on disk' : 'registry metadata'}`,
+    `tokens      ~${compiled.splitPlan.totalTokens} (${compiled.splitPlan.totalBytes} bytes)`,
+    `split       ${compiled.splitPlan.flagged ? `flagged (${compiled.splitPlan.reason}) -> SKILL.md (~${compiled.splitPlan.mainTokens}t) + ${compiled.splitPlan.references.length} reference(s)` : 'within 5000-token budget'}`,
+    `conformance ${compiled.conformance.errors.length === 0 ? 'pass' : `fail (${compiled.conformance.errors.length})`}`,
+    `trigger     expected=${triggerStats?.expected ?? 0}  opened=${triggerStats?.opened ?? 0}  recall=${fmtMetric(triggerStats?.recall)}  precision=${fmtMetric(triggerStats?.precision)}`,
+    `proposal    ${proposal.provenance.model} (${proposal.provenance.digest})`,
+  ];
+
+  if (compiled.splitPlan.references.length > 0) {
+    lines.push('', 'REFERENCES');
+    for (const ref of compiled.splitPlan.references) {
+      lines.push(`  ${ref.path.padEnd(36)} ~${String(ref.tokens).padStart(5)}t  (${ref.bytes} B)  ${ref.title}`);
+    }
+  }
+
+  emit(lines.join('\n'), { maxBytes: flags.maxBytes ?? 0 });
+  if (!mode.apply) {
+    note(`note    dry-run  nothing written; apply with: ${CLI} skills compile ${skill.name} --yes`);
+  }
+  return EXIT.OK;
+}

package/src/commands/sync.mjs

@@ -30,6 +30,8 @@ import { assertVersionPin, packageVersion } from '../package-version.mjs';
 import { resolvePacks } from '../packs.mjs';
 import { computeLock, readLock, LOCK_FILE } from '../projection/lock.mjs';
 import { runDeclaredChecks } from '../kernel/checks.mjs';
+import { DECISIONS_DIR } from '../decisions/index.mjs';
+import { lintDecisions } from '../memory/decide.mjs';
 
 /** Findings `sync` reports and does not fail on.
  *
@@ -528,6 +530,19 @@ export async function checkCommand(positional, flags) {  const root = flags.root
   const { selected } = select(rules.filter((r) => r.error === null), fp.stack ?? [], fp.facts ?? []);
   findings.push(...(await runDeclaredChecks(root, selected, manifest ?? null)));
 
+  const decisionsDir = join(root, 'docs', 'decisions');
+  const decisionLint = await lintDecisions(decisionsDir, {
+    allowHistorical: resolve(decisionsDir) === DECISIONS_DIR,
+  });
+  findings.push(
+    ...decisionLint.findings.map((f) => ({
+      file: ['docs', 'decisions', f.file].join('/'),
+      status: f.status,
+      detail: f.detail,
+      remedy: f.remedy,
+    })),
+  );
+
   // `CHECK_NON_BLOCKING`, not the union. This is the gate whose exit code a repository
   // acts on, so a finding it reports and does not fail on is a decision recorded in a
   // set — not one inherited from the writer that shares this file (ADR-051).