simt-dev 0.6.3 → 0.7.0

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,14 +750,31 @@ 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
@@ -657,6 +791,7 @@ export async function promoteLesson(root, options = {}) {
     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);

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

package/src/plan/index.mjs

@@ -20,10 +20,11 @@
 // the file was read. Status and dependency checks never touch it: a 1 MB
 // section that belongs to a later slice is not copied into the index.
 
-import { readdir, readFile, writeFile } from 'node:fs/promises';
+import { readdir, readFile } from 'node:fs/promises';
 import { join } from 'node:path';
 
 import { CLI } from '../name.mjs';
+import { commitJournal, journaledWriteFile } from '../journal.mjs';
 import { loadFormat } from './template.mjs';
 
 function clean(cell) {
@@ -100,10 +101,16 @@ function sliceKey(path, id) {
  * empty cell is the pipe that closes it. A further empty cell is real: the
  * evidence column is often blank, and stripping every trailing empty would
  * delete it and shift the state into the wrong column.
+ *
+ * A pipe inside a code span is content, not a separator: an evidence cell may
+ * carry a command line with a pipe in it, and splitting there shifts every
+ * later cell left by one (review 0003 Q25). Backticks toggle the span; a
+ * `\|` escape is content in either mode.
  */
 function splitRow(line) {
   const cells = [];
   let current = '';
+  let inCode = false;
   for (let i = 0; i < line.length; i += 1) {
     const char = line[i];
     if (char === '\\' && i + 1 < line.length) {
@@ -111,7 +118,12 @@ function splitRow(line) {
       i += 1;
       continue;
     }
-    if (char === '|') {
+    if (char === '`') {
+      inCode = !inCode;
+      current += char;
+      continue;
+    }
+    if (char === '|' && !inCode) {
       cells.push(current);
       current = '';
       continue;
@@ -596,9 +608,16 @@ export async function planDone(root, id, { sha = null, test = null, state = null
     return { root, id, error: `${id} is no longer on line ${slice.line} of ${slice.docName}`, remedy: `run: ${CLI} plan status` };
   }
 
-  const cells = splitRow(found.lines[found.index]);
-  const width = Math.max(slice.columnCount, slice.stateIdx + 1, slice.evidenceIdx + 1, cells.length);
-  while (cells.length < width) cells.push('');
+  const original = found.lines[found.index];
+  const cells = splitRow(original);
+  if (cells.length !== slice.columnCount) {
+    return {
+      root,
+      id,
+      error: `the row for ${id} has ${cells.length} cells; the table declares ${slice.columnCount}`,
+      remedy: `fix the row in ${slice.docName} — an unescaped pipe splits it — and retry`,
+    };
+  }
   const from = cells[slice.stateIdx] ?? '';
   cells[slice.stateIdx] = replaceState(from, display);
 
@@ -613,14 +632,18 @@ export async function planDone(root, id, { sha = null, test = null, state = null
     evidenceNote = 'no evidence column in this tracker; the sha was not recorded';
   }
 
-  const rebuilt = `| ${cells.join(' | ')} |`;
-  const original = found.lines[found.index];
+  // The rebuilt line keeps the original's ending: a CRLF file must not gain
+  // one LF-terminated line among its CRLF lines (review 0003 Q25).
+  const eol = original.endsWith('\r') ? '\r' : '';
+  const rebuilt = `| ${cells.join(' | ')} |${eol}`;
   const changedCells = splitRow(original).join('\0') !== cells.join('\0');
   const newLine = changedCells ? rebuilt : original;
   const wouldChange = newLine !== original;
   if (wouldChange && !dryRun) {
     found.lines[found.index] = newLine;
-    await writeFile(slice.docPath, found.lines.join('\n'), 'utf8');
+    const journal = [];
+    await journaledWriteFile(root, journal, slice.docPath, found.lines.join('\n'));
+    await commitJournal(root, 'plan', journal);
   }
 
   const apply = `run: ${CLI} plan done ${id}${sha ? ` ${sha}` : ''}${display === format.doneWrite ? '' : ` --state ${JSON.stringify(display)}`}${test ? ` --test ${JSON.stringify(test)}` : ''} --yes`;

package/src/plan/template.mjs

@@ -23,7 +23,7 @@ const KNOWN = new Set(['$comment', 'name', 'directories', 'id', 'columns', 'stat
 const ID_KEYS = new Set(['pattern', 'headers']);
 const COLUMN_KEYS = new Set(['state', 'depends', 'title', 'evidence']);
 const DIRECTORY_KEYS = new Set(['kind', 'word', 'path']);
-const STATE_KEYS = new Set(['id', 'write', 'read', 'satisfies']);
+const STATE_KEYS = new Set(['id', 'write', 'read', 'satisfies', 'role']);
 const DEPENDENCY_KEYS = new Set(['empty', 'separators', 'notes', 'group']);
 const WAVE_KEYS = new Set(['label', 'members']);
 const SECTION_KEYS = new Set(['depth']);
@@ -148,6 +148,7 @@ function compileStates(source, value) {
   const write = new Map();
   const known = new Set();
   const satisfies = new Set();
+  const roles = new Map();
   const order = [];
   const stateNames = [];
   for (let i = 0; i < value.length; i += 1) {
@@ -162,6 +163,13 @@ function compileStates(source, value) {
     }
     if (!Array.isArray(entry.read) || entry.read.length === 0) return bad(source, `${where}.read must list the words that mean this state`);
     if (known.has(entry.id)) return bad(source, `state ${entry.id} is listed twice`);
+    if (entry.role !== undefined && (typeof entry.role !== 'string' || !/^[a-z][a-z0-9-]*$/.test(entry.role))) {
+      return bad(source, `${where}.role must be a lower-case word`);
+    }
+    if (typeof entry.role === 'string') {
+      if (roles.has(entry.role)) return bad(source, `role ${entry.role} is claimed twice`);
+      roles.set(entry.role, entry.write.trim());
+    }
     const display = entry.write.trim();
     const aliases = new Set([entry.id, display.toLowerCase()]);
     for (const alias of entry.read) {
@@ -182,7 +190,7 @@ function compileStates(source, value) {
     else if (entry.satisfies != null && entry.satisfies !== false) return bad(source, `${where}.satisfies must be true or false`);
   }
   if (satisfies.size === 0) return bad(source, 'one state must have satisfies true, or nothing can ever be ready');
-  return { read, write, known, satisfies, order, stateNames };
+  return { read, write, known, satisfies, roles, order, stateNames };
 }
 
 function compile(body, source, root) {
@@ -262,7 +270,7 @@ function compile(body, source, root) {
 
   const byWord = new Map(directories.directories.map((dir) => [dir.word, dir.kind]));
   const doneWrite = body.states.find((entry) => entry.satisfies === true).write.trim();
-  const { read, write } = states;
+  const { read, write, roles } = states;
 
   return {
     format: {
@@ -273,6 +281,12 @@ function compile(body, source, root) {
       order: states.order,
       ready,
       doneWrite,
+      // The display a command moves a row to when work on it starts: the state
+      // carrying the `started` role, or null when no state claims it (review
+      // 0003 Q23). A null here is not an error — the caller falls back to the
+      // in-progress spelling it can read, and `plan done` fails closed on a
+      // word the template never defined.
+      startedWrite: roles.get('started') ?? null,
       stateNames: states.stateNames,
       satisfies: states.satisfies,
       known: states.known,
@@ -292,9 +306,17 @@ function compile(body, source, root) {
       headingRe: new RegExp(`^(#{1,${depth}})\\s+(.*\\S)\\s*$`),
       readState(raw) {
         const plain = String(raw ?? '').replace(/\*\*/g, '').trim().toLowerCase();
+        if (plain === '') return 'unknown';
         if (read.has(plain)) return read.get(plain);
-        const token = plain.split(/[\s(]/)[0];
-        return read.get(token) ?? (token || 'unknown');
+        // A cell may carry a note after the state — "In progress (since Monday)".
+        // The state is the longest alias that prefixes the text: "in progress"
+        // must win over a shorter alias it starts, and a word no state claims
+        // is unknown, not a state (review 0003 Q25).
+        let best = '';
+        for (const alias of read.keys()) {
+          if (alias.length > best.length && plain.startsWith(alias)) best = alias;
+        }
+        return best !== '' ? read.get(best) : 'unknown';
       },
       canonical(input) {
         return write.get(String(input ?? '').trim().toLowerCase()) ?? null;

package/src/plugins.mjs

@@ -32,7 +32,7 @@ import { desiredRegion } from './projection/rules.mjs';
 import { PACKAGE_NAME, BIN_REL } from './name.mjs';
 
 /** The kinds `simt plugin` builds, in the order the help line names them. */
-export const PLUGIN_KINDS = ['claude', 'gemini', 'cursor'];
+export const PLUGIN_KINDS = ['claude', 'gemini', 'cursor', 'opencode'];
 
 /**
  * The package this code ships in: the runtime a generated package copies. Resolved
@@ -71,7 +71,11 @@ function rootFlag(kind) {
 
 /** Where the hooks document lands inside a package, relative to the package root. */
 function hooksPath(kind) {
-  return kind === 'cursor' ? join('.cursor', 'hooks.json') : join('hooks', 'hooks.json');
+  if (kind === 'cursor') return join('.cursor', 'hooks.json');
+  // OpenCode loads a local plugin directory's root `server` file as the plugin, so the
+  // generated document is that file at the root rather than a hooks config to merge.
+  if (kind === 'opencode') return 'server.js';
+  return join('hooks', 'hooks.json');
 }
 
 const json = (value) => `${JSON.stringify(value, null, 2)}\n`;

package/src/prbody.mjs

@@ -21,11 +21,10 @@ import { readLedger, treeId } from './ledger/index.mjs';
 import { readCheckCache } from './status.mjs';
 import { readManifest } from './projection/manifest.mjs';
 import { splitFrontmatter } from './memory/decide.mjs';
+import { decisionsDir } from './decisions/dir.mjs';
 
 const exec = promisify(execFile);
 
-const DECISIONS_DIR = join('docs', 'decisions');
-
 /**
  * The ref the body diffs against: the override when given, else the first
  * candidate that shares history with HEAD. Returns the ref, or null when the
@@ -98,15 +97,18 @@ async function changedPaths(root, base) {
  * reported with what it has rather than dropping the row.
  */
 async function changedDecisions(root, paths) {
-  const names = paths.filter((p) => p.startsWith(`${DECISIONS_DIR}/`) && p.toLowerCase().endsWith('.md'));
+  // Q55: the prefix is the repository's own decisions directory, not a literal.
+  const relDir = await decisionsDir(root);
+  const absDir = join(root, relDir);
+  const names = paths.filter((p) => p.startsWith(`${relDir}/`) && p.toLowerCase().endsWith('.md'));
   try {
-    await readdir(join(root, DECISIONS_DIR));
+    await readdir(absDir);
   } catch {
     return [];
   }
   const out = [];
   for (const name of names.sort()) {
-    const id = /^ADR-\d{3,}/i.exec(name.slice(DECISIONS_DIR.length + 1))?.[0].toUpperCase() ?? name;
+    const id = /^ADR-\d{3,}/i.exec(name.slice(relDir.length + 1))?.[0].toUpperCase() ?? name;
     let title = id;
     let status = 'unknown';
     try {

package/src/projection/baselines.mjs

@@ -76,7 +76,7 @@ trim_trailing_whitespace = false
 indent_style = space
 indent_size = 2
 
-[*.{py,pyi,java,kt,kts}]
+[*.{py,pyi,java,kt,kts,rs}]
 indent_size = 4
 
 [{Makefile,*.mk}]

package/src/projection/disclosure.mjs

@@ -25,7 +25,7 @@ const SKILL_DIRS = ['.agents/skills', '.cursor/skills', '.claude/skills', '.open
  * share a name both stay, because dropping one would hide a trigger.
  *
  * @param {string} root
- * @returns {Promise<{name: string, trigger: string, dir: string}[]>}
+ * @returns {Promise<{name: string, trigger: string, dir: string, file: string}[]>}
  */
 export async function installedSkills(root) {
   const seen = new Set();
@@ -61,7 +61,7 @@ export async function installedSkills(root) {
       const fallback = entry.isDirectory() ? entry.name : entry.name.replace(/\.md$/, '');
       const name = typeof meta.name === 'string' && meta.name !== '' ? meta.name : fallback;
       const trigger = typeof meta.description === 'string' ? meta.description.replace(/\s+/g, ' ').trim() : '';
-      skills.push({ name, trigger, dir });
+      skills.push({ name, trigger, dir, file: key });
     }
   }
   skills.sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : a.dir < b.dir ? -1 : a.dir > b.dir ? 1 : 0));