simt-dev 0.6.2 → 0.7.0

package/src/memory/decide.mjs

@@ -7,6 +7,8 @@ import { execFile } from 'node:child_process';
 import { mkdir, readFile, readdir, writeFile } from 'node:fs/promises';
 import { join } from 'node:path';
 import { promisify } from 'node:util';
+import { recordCreatedFile } from '../journal.mjs';
+import { decisionsDir } from '../decisions/dir.mjs';
 
 const exec = promisify(execFile);
 
@@ -335,15 +337,19 @@ function renderDecisionScaffold({
   ].join('\n');
 }
 
-/** Scaffold a new ADR in `<root>/docs/decisions` with structured frontmatter. */
+/**
+ * Scaffold a new ADR in the repository's decisions directory with structured frontmatter.
+ *
+ * The number is claimed with `O_EXCL`: two concurrent scaffolds that both read
+ * the same maximum must not land on the same number, and a check-then-write
+ * would let the second silently overwrite the first. On collision the number is
+ * re-read and the next free one taken, so the retry always terminates.
+ */
 export async function scaffoldDecision(root, options = {}) {
-  const decisionsDir = options.decisionsDir ?? join(root, 'docs', 'decisions');
-  const { number, id } = await nextDecisionNumber(decisionsDir);
+  const relDir = options.decisionsDir ?? (await decisionsDir(root));
+  const absDir = join(root, relDir);
   const title = String(options.title ?? 'Untitled decision').trim() || 'Untitled decision';
   const slug = slugifyTitle(title);
-  const file = `${id}-${slug}.md`;
-  const relPath = ['docs', 'decisions', file].join('/');
-  const fullPath = join(decisionsDir, file);
   const affects = Array.isArray(options.affects)
     ? options.affects.map((p) => String(p).trim()).filter(Boolean)
     : await diffAffectedPaths(root);
@@ -351,34 +357,58 @@ export async function scaffoldDecision(root, options = {}) {
   const { entries: supersedes, errors } = parseSupersedesSpec(options.supersedes);
   if (errors.length > 0) return { ok: false, errors };
 
-  const text = renderDecisionScaffold({
-    id,
-    title,
-    date: options.date,
-    status: options.status,
-    affects,
-    supersedes,
-  });
-
-  if (options.write) {
-    await mkdir(decisionsDir, { recursive: true });
-    await writeFile(fullPath, text, 'utf8');
+  // A dry run names the number without claiming it: the file must not exist
+  // afterwards, so no exclusive create happens here.
+  if (!options.write) {
+    const { number, id } = await nextDecisionNumber(absDir);
+    const file = `${id}-${slug}.md`;
+    return {
+      ok: true,
+      id,
+      number,
+      title,
+      slug,
+      file,
+      relPath: [relDir, file].join('/'),
+      path: join(absDir, file),
+      affects,
+      supersedes,
+      text: renderDecisionScaffold({ id, title, date: options.date, status: options.status, affects, supersedes }),
+      written: false,
+    };
   }
 
-  return {
-    ok: true,
-    id,
-    number,
-    title,
-    slug,
-    file,
-    relPath,
-    path: fullPath,
-    affects,
-    supersedes,
-    text,
-    written: Boolean(options.write),
-  };
+  await mkdir(absDir, { recursive: true });
+  for (let attempt = 0; attempt < 100; attempt += 1) {
+    const { number, id } = await nextDecisionNumber(absDir);
+    const file = `${id}-${slug}.md`;
+    const fullPath = join(absDir, file);
+    const text = renderDecisionScaffold({ id, title, date: options.date, status: options.status, affects, supersedes });
+    try {
+      await writeFile(fullPath, text, { flag: 'wx' });
+    } catch (error) {
+      if (error.code !== 'EEXIST') throw error;
+      continue;
+    }
+    // The exclusive create is the journal entry's `before: null`: the file did
+    // not exist a moment ago, by construction rather than by re-reading.
+    if (options.journal) recordCreatedFile(root, options.journal, fullPath, text);
+    return {
+      ok: true,
+      id,
+      number,
+      title,
+      slug,
+      file,
+      relPath: [relDir, file].join('/'),
+      path: fullPath,
+      affects,
+      supersedes,
+      text,
+      written: true,
+    };
+  }
+  return { ok: false, errors: ['could not claim a free ADR number after 100 attempts'] };
 }
 
 /** Extract partial supersession claims stated in prose (`Status:` and header paragraphs). */
@@ -410,8 +440,15 @@ function prosePartialSupersessions(body) {
   return claims;
 }
 
-/** Lint a single ADR document for structured supersession conformance (plan 0003 R34). */
-export function lintDecision(text, { file = 'ADR-000.md', allowHistorical = false } = {}) {
+/**
+ * Lint a single ADR document for structured supersession conformance (plan 0003 R34).
+ *
+ * `historicalCutoff` exempts the first N records from the frontmatter requirement:
+ * they predate it, and demanding it retroactively would fail a history nobody can
+ * rewrite without rewriting history. Q55: the number lives in the repository's
+ * config (`decisions.historicalCutoff`, resolved by the caller), never in code.
+ */
+export function lintDecision(text, { file = 'ADR-000.md', historicalCutoff = 0 } = {}) {
   const fileMatch = file !== 'ADR-000.md' ? /^(ADR-\d{3,})/i.exec(file) : null;
   const headMatch = /^#\s+(ADR-\d{3,})\b/m.exec(String(text ?? ''));
   const id = (fileMatch?.[1] ?? headMatch?.[1] ?? /^(ADR-\d{3,})/i.exec(file)?.[1] ?? '').toUpperCase() || null;
@@ -427,7 +464,7 @@ export function lintDecision(text, { file = 'ADR-000.md', allowHistorical = fals
     remedy: 'fix simt-supersedes frontmatter to use [{ adr: "ADR-NNN", ruling: N }]',
   }));
 
-  if (allowHistorical && !fm.hasFrontmatter && num !== null && num > 0 && num <= 96) {
+  if (!fm.hasFrontmatter && num !== null && num > 0 && num <= historicalCutoff) {
     return { ok: findings.length === 0, findings };
   }
 
@@ -450,13 +487,36 @@ export function lintDecision(text, { file = 'ADR-000.md', allowHistorical = fals
   return { ok: findings.length === 0, findings };
 }
 
-/** Lint all ADR records in a decisions directory. */
-export async function lintDecisions(decisionsDir, { allowHistorical = false } = {}) {
+/**
+ * Lint all ADR records in a decisions directory.
+ *
+ * Duplicate ids are a lint finding, not a silent keep-first: two files claiming
+ * one number means `byId` answers for only one of them, and the reader of the
+ * other gets a record the index cannot see. The kept record is the first in
+ * numeric filename order — the same one the loader keeps — so lint and load
+ * never name different winners.
+ */
+export async function lintDecisions(decisionsDir, { historicalCutoff = 0 } = {}) {
   const names = (await readdir(decisionsDir).catch(() => [])).filter((n) => /^ADR-\d{3,}-.*\.md$/i.test(n)).sort();
   const findings = [];
+  const seen = new Map();
   for (const file of names) {
+    const id = /^(ADR-\d{3,})/i.exec(file)?.[1]?.toUpperCase() ?? null;
+    if (id !== null) {
+      if (seen.has(id)) {
+        findings.push({
+          file,
+          id,
+          status: 'duplicate-decision-id',
+          detail: `decision id ${id} is claimed by ${seen.get(id)} and ${file}; the index only sees the first`,
+          remedy: 'renumber the newer record to a free number, then rerun the check',
+        });
+        continue;
+      }
+      seen.set(id, file);
+    }
     const text = await readFile(join(decisionsDir, file), 'utf8');
-    findings.push(...lintDecision(text, { file, allowHistorical }).findings);
+    findings.push(...lintDecision(text, { file, historicalCutoff }).findings);
   }
   return { ok: findings.length === 0, findings };
 }

package/src/memory/lessons.mjs

@@ -13,20 +13,64 @@
 
 import { createHash } from 'node:crypto';
 import { execFile } from 'node:child_process';
-import { mkdir, readdir, readFile, writeFile } from 'node:fs/promises';
+import { mkdir, open, readdir, readFile, writeFile } from 'node:fs/promises';
 import { dirname, join } from 'node:path';
 import { promisify } from 'node:util';
 
 import { postDeliveryJson } from '../agenthooks/render.mjs';
 import { lessonPaths } from '../index/govern.mjs';
+import { recordCreatedFile } from '../journal.mjs';
+import { redactText } from '../secrets.mjs';
+import { localRel, readStateFile } from '../state.mjs';
 import { splitFrontmatter } from './decide.mjs';
 
 const exec = promisify(execFile);
 
-export const LESSONS_FILE = '.simt/lessons.jsonl';
+export const LESSONS_FILE = localRel('lessons.jsonl');
+const LESSONS_FILE_LEGACY = '.simt/lessons.jsonl';
+const LEDGER_REL = localRel('ledger.jsonl');
+const LEDGER_REL_LEGACY = '.simt/ledger.jsonl';
 export const LESSONS_DIR = 'docs/lessons';
 export const LESSON_KEYS = new Set(['simt-trigger', 'simt-evidence', 'simt-expires']);
-const DEFAULT_EXPIRES = '2027-04-01';
+
+/**
+ * A stored `fixDiff` is evidence, not an archive: the diff that proved the fix,
+ * capped so one generated-file revert cannot bloat every read of the ledger.
+ * Truncation keeps the head (the hunk headers that name the files) and says so.
+ */
+const FIX_DIFF_BUDGET = 20000;
+
+/**
+ * The default expiry is relative to the promotion, not a date in the source:
+ * a fixed date rots (every lesson written today expires on someone else's
+ * schedule) and a missing one lives forever because nothing reads the field.
+ * Half a year is long enough to recur and short enough to re-earn.
+ */
+const EXPIRY_DAYS = 180;
+
+export function defaultExpires(from = new Date()) {
+  const at = new Date(from);
+  at.setUTCDate(at.getUTCDate() + EXPIRY_DAYS);
+  return at.toISOString().slice(0, 10);
+}
+
+/**
+ * Whether a `simt-expires` value has passed. Unparseable values are NOT expired:
+ * a malformed date is a data error the reader should see, and hiding the lesson
+ * would turn it into a silent one (review 0003 Q36).
+ *
+ * @param {string|null|undefined} expires
+ * @param {Date} [now]
+ * @returns {boolean}
+ */
+export function isExpired(expires, now = new Date()) {
+  if (expires === null || expires === undefined || String(expires).trim() === '') return false;
+  const at = new Date(String(expires).trim());
+  if (Number.isNaN(at.getTime())) return false;
+  const today = new Date(now);
+  today.setUTCHours(0, 0, 0, 0);
+  return at.getTime() < today.getTime();
+}
 
 const STOP_WORDS = new Set([
   'the', 'and', 'for', 'with', 'that', 'this', 'from', 'into', 'when', 'were',
@@ -143,13 +187,14 @@ function slugify(text) {
  * @returns {Promise<{candidates: Array<object>, errors: string[]}>}
  */
 export async function readLessonCandidates(root) {
+  // The pre-move path is a fallback for one release (review 0003 Q19).
   let text;
   try {
-    text = await readFile(join(root, LESSONS_FILE), 'utf8');
+    ({ text } = await readStateFile(root, LESSONS_FILE, [LESSONS_FILE_LEGACY]));
   } catch (error) {
-    if (error.code === 'ENOENT') return { candidates: [], errors: [] };
     throw error;
   }
+  if (text === null) return { candidates: [], errors: [] };
   const candidates = [];
   const errors = [];
   for (const [i, raw] of text.split('\n').entries()) {
@@ -175,15 +220,69 @@ async function writeLessonCandidates(root, candidates) {
   await writeFile(full, body ? `${body}\n` : '', 'utf8');
 }
 
+/**
+ * Append one record with `O_APPEND`: the ledger is written by concurrent
+ * processes (gates, hooks, the CLI), and a read-modify-write loses one of two
+ * simultaneous appends. The position is the kernel's, not a length read earlier.
+ *
+ * @param {string} root
+ * @param {object} record
+ */
+async function appendCandidateLine(root, record) {
+  const full = join(root, LESSONS_FILE);
+  await mkdir(dirname(full), { recursive: true });
+  const handle = await open(full, 'a');
+  try {
+    await handle.appendFile(`${JSON.stringify(record)}\n`, 'utf8');
+  } finally {
+    await handle.close();
+  }
+}
+
+/**
+ * The candidate id is a content hash, not a counter. Ids were `c-${length+1}`:
+ * two processes appending concurrently computed the same next index, and a
+ * hand-edited or truncated file renumbered everything after it. The hash covers
+ * the fields that make a candidate distinct, so the same candidate always maps
+ * to the same id and two different ones never share it (review 0003 Q36).
+ *
+ * @param {{kind: string, signature: string, evidence: string[], cmd: string|null}} parts
+ * @returns {string}
+ */
+export function lessonIdFor({ kind, signature, evidence = [], cmd = null }) {
+  const digest = createHash('sha256')
+    .update([kind, signature, ...evidence, cmd ?? ''].join('\n'), 'utf8')
+    .digest('hex');
+  return `l-${digest.slice(0, 12)}`;
+}
+
+/**
+ * Truncate an unbounded diff to the evidence budget, keeping the head: the hunk
+ * headers that name the files are the part a reader acts on.
+ *
+ * @param {string} diff
+ * @returns {string}
+ */
+function capFixDiff(diff) {
+  const text = String(diff ?? '');
+  if (text.length <= FIX_DIFF_BUDGET) return text;
+  return `${text.slice(0, FIX_DIFF_BUDGET)}\n… (truncated to ${FIX_DIFF_BUDGET} chars)`;
+}
+
 function sameEvidence(a = [], b = []) {
   if (a.length !== b.length) return false;
   return a.every((v, i) => v === b[i]);
 }
 
 /**
- * Append one deterministic candidate to `.simt/lessons.jsonl`, deduplicating by
+ * Append one deterministic candidate to the lessons ledger, deduplicating by
  * `(kind, signature, evidence)`.
  *
+ * The stored text is redacted before anything else: candidates keep the raw
+ * commands that failed, and a command can carry a token. Redaction runs before
+ * the signature is hashed so the same failure redacts to the same signature
+ * (review 0003 Q36).
+ *
  * @param {string} root
  * @param {object} candidate
  * @returns {Promise<object>}
@@ -191,15 +290,22 @@ function sameEvidence(a = [], b = []) {
 export async function appendLessonCandidate(root, candidate) {
   const { candidates } = await readLessonCandidates(root);
   const kind = String(candidate.kind ?? 'fail-then-fix');
-  const errorLine = normaliseErrorLine(candidate.errorLine ?? firstErrorLine(candidate.output ?? candidate.summary ?? ''));
+  // Redact first: the signature must be a function of the stored bytes, not of
+  // a secret nobody can reproduce (and must never be stored).
+  const errorLine = redactText(
+    normaliseErrorLine(candidate.errorLine ?? firstErrorLine(candidate.output ?? candidate.summary ?? '')),
+  );
   const signature = candidate.signature ?? errorSignature(errorLine);
-  const evidence = Array.isArray(candidate.evidence) ? candidate.evidence.map(String).filter(Boolean) : [];
+  const evidence = Array.isArray(candidate.evidence)
+    ? candidate.evidence.map((e) => redactText(String(e)).trim()).filter(Boolean)
+    : [];
+  const cmd = candidate.cmd === null || candidate.cmd === undefined ? null : redactText(String(candidate.cmd));
 
   const existing = candidates.find(
     (c) =>
       c.kind === kind &&
       c.signature === signature &&
-      (sameEvidence(c.evidence ?? [], evidence) || (c.cmd && candidate.cmd && c.cmd === candidate.cmd && c.evidence?.[0] === evidence[0])),
+      (sameEvidence(c.evidence ?? [], evidence) || (c.cmd && cmd && c.cmd === cmd && c.evidence?.[0] === evidence[0])),
   );
   if (existing) return existing;
 
@@ -208,28 +314,26 @@ export async function appendLessonCandidate(root, candidate) {
     : [];
   const keywords = Array.isArray(candidate.keywords) && candidate.keywords.length > 0
     ? [...new Set(candidate.keywords.map(String).filter(Boolean))]
-    : extractKeywords(`${errorLine} ${candidate.cmd ?? ''}`, paths);
+    : extractKeywords(`${errorLine} ${cmd ?? ''}`, paths);
 
-  const nextIndex = candidates.length + 1;
   const record = {
     v: 1,
-    id: candidate.id ?? `c-${String(nextIndex).padStart(4, '0')}`,
+    id: candidate.id ?? lessonIdFor({ kind, signature, evidence, cmd }),
     ts: candidate.ts ?? new Date().toISOString().replace(/\.\d{3}Z$/, 'Z'),
     kind,
     signature,
     errorLine,
-    summary: String(candidate.summary ?? (errorLine || `${kind} candidate`)).trim(),
-    cmd: candidate.cmd ?? null,
+    summary: redactText(String(candidate.summary ?? (errorLine || `${kind} candidate`))).trim(),
+    cmd,
     paths,
     keywords,
     evidence,
-    fixDiff: String(candidate.fixDiff ?? ''),
+    fixDiff: capFixDiff(redactText(candidate.fixDiff ?? '')),
     status: candidate.status ?? 'candidate',
     promotedTo: candidate.promotedTo ?? null,
   };
 
-  candidates.push(record);
-  await writeLessonCandidates(root, candidates);
+  await appendCandidateLine(root, record);
   return record;
 }
 
@@ -306,8 +410,8 @@ export async function captureFromLedger(root, entries = null) {
   let list = entries;
   if (!Array.isArray(list)) {
     try {
-      const raw = await readFile(join(root, '.simt', 'ledger.jsonl'), 'utf8');
-      list = raw
+      const { text } = await readStateFile(root, LEDGER_REL, [LEDGER_REL_LEGACY]);
+      list = (text ?? '')
         .split('\n')
         .map((s) => s.trim())
         .filter(Boolean)
@@ -481,12 +585,13 @@ export async function recordHookDenial(root, denial) {
  * @returns {string}
  */
 export function renderLessonMarkdown(candidate, options = {}) {
+  // No `**` fallback: a trigger with no paths is a promotion the caller
+  // refused, not a lesson about everything. `promoteLesson` rejects those;
+  // this renders exactly the paths it was given (review 0003 Q36).
   const paths =
     Array.isArray(options.paths) && options.paths.length > 0
       ? options.paths
-      : Array.isArray(candidate.paths) && candidate.paths.length > 0
-        ? candidate.paths
-        : ['**'];
+      : (Array.isArray(candidate.paths) ? candidate.paths : []);
   const keywords =
     Array.isArray(options.keywords) && options.keywords.length > 0
       ? options.keywords
@@ -494,7 +599,7 @@ export function renderLessonMarkdown(candidate, options = {}) {
         ? candidate.keywords
         : extractKeywords(candidate.errorLine ?? candidate.summary ?? '', paths);
   const evidence = Array.isArray(candidate.evidence) ? candidate.evidence : [];
-  const expires = options.expires ?? DEFAULT_EXPIRES;
+  const expires = options.expires ?? defaultExpires();
   const title = String(options.title ?? candidate.summary ?? candidate.errorLine ?? 'Lesson').trim();
 
   const pathsLiteral = paths.map((p) => JSON.stringify(String(p))).join(', ');
@@ -528,7 +633,7 @@ export function renderLessonMarkdown(candidate, options = {}) {
  * @param {string} text
  * @returns {object}
  */
-export function parseLessonFile(id, text) {
+export function parseLessonFile(id, text, now = new Date()) {
   const { front: rawFront, body: rawBody } = splitFrontmatter(text);
   const front = rawFront ?? '';
   const body = rawBody.trim();
@@ -546,6 +651,7 @@ export function parseLessonFile(id, text) {
     : [];
   const expMatch = /^simt-expires:\s*(\S+)/m.exec(front);
   const expires = expMatch ? expMatch[1].trim() : null;
+  const expired = isExpired(expires, now);
 
   const titleMatch = /^#\s+(.+)$/m.exec(body);
   const title = titleMatch ? titleMatch[1].trim() : id;
@@ -566,16 +672,23 @@ export function parseLessonFile(id, text) {
     keywords,
     evidence,
     expires,
+    expired,
   };
 }
 
 /**
- * List all promoted lessons in `docs/lessons/*.md`.
+ * List the promoted lessons in `docs/lessons/*.md` that are still in force.
+ *
+ * `simt-expires` is read here, once, so every consumer — recall, `why`, the
+ * hook, the bench, `lessons list` — agrees on what has expired. Nothing was
+ * reading the field, so expired lessons kept firing indefinitely (review 0003
+ * Q36). Pass `includeExpired` to see the retired ones with `expired: true`.
  *
  * @param {string} root
+ * @param {{includeExpired?: boolean, now?: Date}} [options]
  * @returns {Promise<Array<object>>}
  */
-export async function listPromotedLessons(root) {
+export async function listPromotedLessons(root, { includeExpired = false, now = new Date() } = {}) {
   const dir = join(root, LESSONS_DIR);
   let names = [];
   try {
@@ -587,7 +700,8 @@ export async function listPromotedLessons(root) {
   for (const name of names) {
     const text = await readFile(join(dir, name), 'utf8');
     const id = name.replace(/\.md$/, '');
-    lessons.push(parseLessonFile(id, text));
+    const lesson = parseLessonFile(id, text, now);
+    if (!lesson.expired || includeExpired) lessons.push(lesson);
   }
   return lessons;
 }
@@ -612,17 +726,20 @@ async function nextLessonNumber(root) {
 }
 
 /**
- * Promote a lesson candidate from `.simt/lessons.jsonl` to `docs/lessons/NNNN-<slug>.md`.
+ * Promote a lesson candidate from the lessons ledger to `docs/lessons/NNNN-<slug>.md`.
+ *
+ * Capture is not promotion's business: `promoteLesson` used to scan the ledger
+ * first, so a preview (`review` without `--yes`) wrote to the store it was
+ * only reading. Capture is an explicit `lessons capture` now (review 0003 Q36).
  *
  * @param {string} root
- * @param {{id?: string, apply?: boolean, paths?: string[], expires?: string, title?: string}} [options]
+ * @param {{id?: string, apply?: boolean, paths?: string[], expires?: string, title?: string, journal?: object[]}} [options]
  * @returns {Promise<{ok: boolean, error?: string, candidate?: object, path?: string, markdown?: string, written?: boolean}>}
  */
 export async function promoteLesson(root, options = {}) {
-  await captureFromLedger(root);
   const { candidates } = await readLessonCandidates(root);
   if (candidates.length === 0) {
-    return { ok: false, error: 'no lesson candidates in .simt/lessons.jsonl' };
+    return { ok: false, error: `no lesson candidates in ${LESSONS_FILE}; capture some with: lessons capture` };
   }
 
   let target = null;
@@ -633,19 +750,48 @@ export async function promoteLesson(root, options = {}) {
     if (!target) {
       return { ok: false, error: `no lesson candidate matching "${options.id}"` };
     }
+    if (target.status === 'promoted') {
+      return { ok: false, error: `lesson candidate ${target.id} is already promoted to ${target.promotedTo}` };
+    }
   } else {
-    target = candidates.find((c) => c.status !== 'promoted') ?? candidates[0];
+    // A promoted candidate is done: falling back to it re-promotes the same
+    // lesson under a new number, which is how one candidate became 0001/0002/0003.
+    target = candidates.find((c) => c.status !== 'promoted') ?? null;
+    if (!target) {
+      return { ok: false, error: 'nothing to promote: every candidate is already promoted' };
+    }
+  }
+
+  // No `**` default: a trigger that watches every path fires on every failure,
+  // which is the same as firing on none. A pathless candidate needs `--paths`.
+  const paths = Array.isArray(options.paths) && options.paths.length > 0
+    ? options.paths
+    : (Array.isArray(target.paths) ? target.paths : []);
+  if (paths.length === 0) {
+    return { ok: false, error: `lesson candidate ${target.id} names no paths; pass --paths to say what it governs` };
   }
 
   const num = await nextLessonNumber(root);
   const slug = slugify(options.title ?? target.errorLine ?? target.summary ?? target.kind);
   const relPath = `${LESSONS_DIR}/${num}-${slug}.md`;
-  const markdown = renderLessonMarkdown(target, options);
+  const markdown = renderLessonMarkdown(target, { ...options, paths, expires: options.expires ?? defaultExpires() });
+
+  // The `--diff` before-side, read before anything is written so the diff is true
+  // in preview and in apply alike (R50). Always a creation in practice — the
+  // number is fresh — but a hand-placed file at the same path would be
+  // overwritten, and a diff that claimed a creation there would lie about it.
+  let before = null;
+  try {
+    before = await readFile(join(root, relPath), 'utf8');
+  } catch (error) {
+    if (error.code !== 'ENOENT') throw error;
+  }
 
   if (options.apply) {
     const fullPath = join(root, relPath);
     await mkdir(dirname(fullPath), { recursive: true });
     await writeFile(fullPath, markdown, 'utf8');
+    if (Array.isArray(options.journal)) recordCreatedFile(root, options.journal, join(root, relPath), markdown);
     target.status = 'promoted';
     target.promotedTo = relPath;
     await writeLessonCandidates(root, candidates);
@@ -656,6 +802,7 @@ export async function promoteLesson(root, options = {}) {
     candidate: target,
     path: relPath,
     markdown,
+    before,
     written: Boolean(options.apply),
   };
 }

package/src/name.mjs

@@ -32,6 +32,15 @@ export const MANIFEST_FILE = 'simt.json';
 /** What the manifest file was called, and still is in every adopted repo. */
 export const MANIFEST_LEGACY = 'simt-dev.json';
 
+/** The projection lock: the input and output digests a frozen check compares, and the
+ *  locked `variants` winners `simt bench variants` records (ADR-086). */
+export const LOCK_FILE = 'simt.lock.json';
+
+/** What the lock was called. Read, not written: an adopted repo's lock under the old
+ *  name may hold variant winners nothing can regenerate, so it is read until the next
+ *  write migrates it (ADR-110). */
+export const LOCK_LEGACY = 'simt-dev.lock.json';
+
 /**
  * The namespace the generated region writes into a repository's files: the begin and end
  * markers, and the provenance header inside them. It follows the command, like the