simt-dev 0.7.0 → 0.8.0

package/src/measure/tasks.mjs

@@ -0,0 +1,69 @@
+// Mined task descriptors, read back from the tool state's `bench/tasks/` directory.
+//
+// Extracted from bench/run.mjs on its second real reader (ADR-002): the advice engine
+// needs the two facts a run record does not carry — the prompt, which classifies the
+// task, and the gold stat, which says how many files the change touched. A second private
+// loader beside the first would drift the first time one learned a filter the other
+// lacked.
+//
+// Every descriptor passes through `task-schema.mjs`, so a reader never has to guess
+// whether a field is present: an unreadable task is refused with its file named, and a v1
+// descriptor is normalised rather than skipped. Deterministic by construction: the
+// directory is read sorted, the filter is exact, and nothing here touches a model, a
+// network or a clock.
+import { readdir, readFile } from 'node:fs/promises';
+import { join, resolve } from 'node:path';
+
+import { STATE_DIR } from '../name.mjs';
+import { normaliseTask } from './task-schema.mjs';
+
+/** The directory a repository's mined tasks live in. */
+export function tasksDir(root) {
+  return join(resolve(root), STATE_DIR, 'bench', 'tasks');
+}
+
+/** The file one task descriptor lives in. */
+export function taskPath(root, id) {
+  return join(tasksDir(root), `${id}.json`);
+}
+
+/**
+ * Read one task descriptor by id.
+ *
+ * @param {string} root
+ * @param {string} id
+ * @returns {Promise<object|null>} the v2 descriptor, or null when the file is absent
+ */
+export async function readTask(root, id) {
+  const text = await readFile(taskPath(root, id), 'utf8').catch(() => null);
+  if (text === null) return null;
+  return normaliseTask(JSON.parse(text), { source: taskPath(root, id) });
+}
+
+/**
+ * Load mined benchmark task descriptors.
+ *
+ * @param {string} root the repository
+ * @param {string[]} [filterIds] exact task ids to keep; empty means load them all
+ * @returns {Promise<object[]>} v2 descriptors sorted by id (id, base, prompt, stratum,
+ *   oracle, f2p, p2p, gold {files, linesAdded, linesRemoved}, vault)
+ */
+export async function loadTasks(root, filterIds = []) {
+  const dir = tasksDir(root);
+  const entries = (await readdir(dir).catch(() => [])).filter((file) => file.endsWith('.json')).sort();
+
+  const filterSet = new Set(filterIds);
+  const tasks = [];
+  for (const entry of entries) {
+    const file = join(dir, entry);
+    let raw;
+    try {
+      raw = JSON.parse(await readFile(file, 'utf8'));
+    } catch (error) {
+      throw new Error(`${file}: ${error.message ?? error}`);
+    }
+    if (filterSet.size > 0 && !filterSet.has(String(raw?.id ?? ''))) continue;
+    tasks.push(normaliseTask(raw, { source: file }));
+  }
+  return tasks.sort((a, b) => a.id.localeCompare(b.id));
+}

package/src/memory/decide.mjs

@@ -3,14 +3,12 @@
 // frontmatter first for `rules why` and `why`, and fail lint on partial
 // supersessions stated only in prose.
 
-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);
+import { parseFrontmatter } from '../text/frontmatter.mjs';
+import { gitText } from '../sys/git.mjs';
 
 export const DECISION_KEYS = ['simt-affects', 'simt-supersedes'];
 
@@ -39,13 +37,6 @@ function unquote(value) {
     : t;
 }
 
-/** Strip leading YAML frontmatter (`---\n...\n---`) from a markdown document. */
-export function splitFrontmatter(text) {
-  const raw = String(text ?? '');
-  const match = /^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/.exec(raw);
-  return match ? { front: match[1], body: raw.slice(match[0].length) } : { front: null, body: raw };
-}
-
 function parseInlineStringList(inner) {
   return inner.trim() ? inner.split(',').map(unquote).filter(Boolean) : [];
 }
@@ -93,7 +84,7 @@ function normaliseSupersedesEntry(obj, errors) {
 
 /** Parse `simt-affects` and `simt-supersedes` from an ADR's YAML frontmatter. */
 export function parseDecisionFrontmatter(text) {
-  const { front } = splitFrontmatter(text);
+  const { front } = parseFrontmatter(text);
   if (front === null) {
     return { hasFrontmatter: false, hasAffects: false, hasSupersedes: false, affects: [], supersedes: [], errors: [] };
   }
@@ -255,7 +246,7 @@ export async function diffAffectedPaths(root) {
     ['diff', '--name-only'],
   ]) {
     try {
-      const { stdout } = await exec('git', args, { cwd: root });
+      const stdout = await gitText(root, args);
       addLines(stdout);
     } catch {
       // Ignore if not a git repo or HEAD absent.
@@ -263,7 +254,7 @@ export async function diffAffectedPaths(root) {
   }
   if (paths.size === 0) {
     try {
-      const { stdout } = await exec('git', ['diff-tree', '--no-commit-id', '--name-only', '-r', 'HEAD'], { cwd: root });
+      const stdout = await gitText(root, ['diff-tree', '--no-commit-id', '--name-only', '-r', 'HEAD']);
       addLines(stdout);
     } catch {
       // Ignore.
@@ -455,7 +446,7 @@ export function lintDecision(text, { file = 'ADR-000.md', historicalCutoff = 0 }
   const num = id ? Number(id.replace(/^ADR-/, '')) : null;
 
   const fm = parseDecisionFrontmatter(text);
-  const { body } = splitFrontmatter(text);
+  const { body } = parseFrontmatter(text);
   const findings = fm.errors.map((err) => ({
     file,
     id,

package/src/memory/lesson-text.mjs

@@ -0,0 +1,61 @@
+// Pure helpers for a lesson record: its slug, its capped fix diff, and evidence equality.
+//
+// They touch no file and no clock, which is why they are separable from the store
+// (review 0003 Q80).
+
+
+export function slugify(text) {
+  const slug = String(text ?? '')
+    .toLowerCase()
+    .replace(/^not ok\s+\d+\s*-?\s*/i, '')
+    .replace(/^(?:error|assertionerror|fail|revert|blocked)[:\s-]*/i, '')
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '')
+    .slice(0, 48)
+    .replace(/-+$/g, '');
+  return slug || 'lesson';
+}
+
+/**
+ * Read all candidate records from `.simt/lessons.jsonl`.
+ *
+ * @param {string} root
+ * @returns {Promise<{candidates: Array<object>, errors: string[]}>}
+ */
+
+
+/**
+ * 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}
+ */
+export 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)`;
+}
+
+
+export function sameEvidence(a = [], b = []) {
+  if (a.length !== b.length) return false;
+  return a.every((v, i) => v === b[i]);
+}
+
+/**
+ * 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>}
+ */
+
+/** The cap on a stored fix diff, so one large commit cannot bloat a lesson. */
+export const FIX_DIFF_BUDGET = 20000;

package/src/memory/lessons.mjs

@@ -11,25 +11,23 @@
 // `simt lessons review` promotes a candidate to `docs/lessons/NNNN-<slug>.md` with the
 // Appendix A frontmatter (`simt-trigger`, `simt-evidence`, `simt-expires`).
 
+import { FIX_DIFF_BUDGET, capFixDiff, sameEvidence, slugify } from './lesson-text.mjs';
+import { noteEvent } from '../state/events.mjs';
 import { createHash } from 'node:crypto';
-import { execFile } from 'node:child_process';
 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);
+import { parseFrontmatter } from '../text/frontmatter.mjs';
+import { LEDGER_FILE_LEGACY, LEDGER_FILE_REL } from '../name.mjs';
+import { git } from '../sys/git.mjs';
 
 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']);
 
@@ -38,7 +36,6 @@ export const LESSON_KEYS = new Set(['simt-trigger', 'simt-evidence', 'simt-expir
  * 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:
@@ -167,25 +164,6 @@ function extractKeywords(text, paths = []) {
   }
   return [...words];
 }
-
-function slugify(text) {
-  const slug = String(text ?? '')
-    .toLowerCase()
-    .replace(/^not ok\s+\d+\s*-?\s*/i, '')
-    .replace(/^(?:error|assertionerror|fail|revert|blocked)[:\s-]*/i, '')
-    .replace(/[^a-z0-9]+/g, '-')
-    .replace(/^-+|-+$/g, '')
-    .slice(0, 48)
-    .replace(/-+$/g, '');
-  return slug || 'lesson';
-}
-
-/**
- * Read all candidate records from `.simt/lessons.jsonl`.
- *
- * @param {string} root
- * @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;
@@ -255,38 +233,6 @@ export function lessonIdFor({ kind, signature, evidence = [], cmd = null }) {
     .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 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>}
- */
 export async function appendLessonCandidate(root, candidate) {
   const { candidates } = await readLessonCandidates(root);
   const kind = String(candidate.kind ?? 'fail-then-fix');
@@ -343,21 +289,15 @@ async function diffBetweenTrees(root, fromRef, toRef) {
   }
   try {
     const [namesOut, diffOut] = await Promise.all([
-      exec('git', ['diff', '--name-only', fromRef, toRef, '--', '.', ':(exclude).simt'], {
-        cwd: root,
-        maxBuffer: 8 << 20,
-      }),
-      exec('git', ['diff', '--unified=3', fromRef, toRef, '--', '.', ':(exclude).simt'], {
-        cwd: root,
-        maxBuffer: 8 << 20,
-      }),
+      git(root, ['diff', '--name-only', fromRef, toRef, '--', '.', ':(exclude).simt'], { maxBuffer: 8 << 20 }),
+      git(root, ['diff', '--unified=3', fromRef, toRef, '--', '.', ':(exclude).simt'], { maxBuffer: 8 << 20 }),
     ]);
-    const paths = namesOut.stdout
+    const paths = namesOut
       .split('\n')
       .map((s) => s.trim())
       .filter(Boolean)
       .sort();
-    return { paths, diff: diffOut.stdout.trim() };
+    return { paths, diff: diffOut.trim() };
   } catch {
     return { paths: [], diff: '' };
   }
@@ -371,7 +311,8 @@ async function diffBetweenTrees(root, fromRef, toRef) {
  * @param {{failEntry: object, passEntry: object, failOutput?: string, fixDiff?: string, paths?: string[]}} params
  * @returns {Promise<object>}
  */
-export async function recordFailThenFix(root, { failEntry, passEntry, failOutput, fixDiff, paths }) {
+export async function recordFailThenFix(root, { failEntry, passEntry, failOutput, fixDiff, paths 
+}) {
   const rawError = failOutput ?? failEntry?.errorLine ?? failEntry?.summary ?? failEntry?.cmd ?? '';
   const errorLine = normaliseErrorLine(failEntry?.errorLine ?? firstErrorLine(rawError));
   const signature = failEntry?.signature ?? errorSignature(errorLine);
@@ -386,7 +327,7 @@ export async function recordFailThenFix(root, { failEntry, passEntry, failOutput
     resolvedDiff ??= treeDiff.diff;
   }
 
-  return appendLessonCandidate(root, {
+  const record = await appendLessonCandidate(root, {
     kind: 'fail-then-fix',
     cmd: passEntry?.cmd ?? failEntry?.cmd ?? null,
     signature,
@@ -396,6 +337,13 @@ export async function recordFailThenFix(root, { failEntry, passEntry, failOutput
     paths: resolvedPaths,
     fixDiff: resolvedDiff,
   });
+  // The lessons file is the reader's view; the log is what a UI can tail (Q73).
+  await noteEvent(root, {
+    kind: 'lesson.captured',
+    subject: passEntry?.cmd ?? failEntry?.cmd ?? null,
+    data: { id: record?.id ?? null, signature, tree: fixTree },
+  });
+  return record;
 }
 
 /**
@@ -410,7 +358,7 @@ export async function captureFromLedger(root, entries = null) {
   let list = entries;
   if (!Array.isArray(list)) {
     try {
-      const { text } = await readStateFile(root, LEDGER_REL, [LEDGER_REL_LEGACY]);
+      const { text } = await readStateFile(root, localRel(LEDGER_FILE_REL), [LEDGER_FILE_LEGACY]);
       list = (text ?? '')
         .split('\n')
         .map((s) => s.trim())
@@ -453,12 +401,11 @@ export async function captureRevertedCommits(root, options = {}) {
   const limit = options.limit ?? 50;
   let stdout = '';
   try {
-    const res = await exec(
-      'git',
+    stdout = await git(
+      root,
       ['log', '--no-merges', `-n`, String(limit), '--format=%H%x00%s%x00%b%x1e'],
-      { cwd: root, maxBuffer: 8 << 20 },
+      { maxBuffer: 8 << 20 },
     );
-    stdout = res.stdout;
   } catch {
     return [];
   }
@@ -482,16 +429,16 @@ export async function captureRevertedCommits(root, options = {}) {
     let paths = [];
     let fixDiff = '';
     try {
-      const [namesRes, diffRes] = await Promise.all([
-        exec('git', ['diff-tree', '--no-commit-id', '--name-only', '-r', sha], { cwd: root, maxBuffer: 8 << 20 }),
-        exec('git', ['show', '--format=', '--unified=3', sha], { cwd: root, maxBuffer: 8 << 20 }),
+      const [namesOut, diffOut] = await Promise.all([
+        git(root, ['diff-tree', '--no-commit-id', '--name-only', '-r', sha], { maxBuffer: 8 << 20 }),
+        git(root, ['show', '--format=', '--unified=3', sha], { maxBuffer: 8 << 20 }),
       ]);
-      paths = namesRes.stdout
+      paths = namesOut
         .split('\n')
         .map((s) => s.trim())
         .filter(Boolean)
         .sort();
-      fixDiff = diffRes.stdout.trim();
+      fixDiff = diffOut.trim();
     } catch {
       // ignore diff failure
     }
@@ -634,7 +581,7 @@ export function renderLessonMarkdown(candidate, options = {}) {
  * @returns {object}
  */
 export function parseLessonFile(id, text, now = new Date()) {
-  const { front: rawFront, body: rawBody } = splitFrontmatter(text);
+  const { front: rawFront, body: rawBody } = parseFrontmatter(text);
   const front = rawFront ?? '';
   const body = rawBody.trim();
 

package/src/name.mjs

@@ -46,6 +46,13 @@ export const LOCK_LEGACY = 'simt-dev.lock.json';
  * markers, and the provenance header inside them. It follows the command, like the
  * manifest: the region is the command's footprint in a file the repo owns.
  */
+/** The ledger's pre-STATE_DIR home. Read, never written: state written under the old
+ *  name is still read by the ledger and the lesson sources. */
+export const LEDGER_FILE_LEGACY = '.simt/ledger.jsonl';
+
+/** The ledger the evidence is appended to, under the config directory. */
+export const LEDGER_FILE_REL = 'ledger.jsonl';
+
 export const MARKER_PREFIX = 'simt';
 
 /** What the region was namespaced under, and still is in every adopted repo. */

package/src/node-version.mjs

@@ -0,0 +1,37 @@
+// The runtime floor, in one place both entry points read (review 0003 Q54).
+//
+// `package.json` declares `engines.node` and `pyproject.toml` declares a python
+// version; both are advisory to the installer, so an older runtime reached the CLI
+// and failed somewhere inside it — a syntax error, a missing API — instead of the one
+// sentence that says what to install. This module is deliberately tiny and has no
+// imports: the bootstrap that calls it must not load the tool that cannot run.
+
+/** The oldest Node this package runs on. Mirrors `package.json` `engines.node`. */
+export const MIN_NODE = '22.20.0';
+
+/**
+ * Whether `current` is at least `minimum`, compared component by component.
+ *
+ * A string compare is wrong ("9.0.0" > "22.20.0"), and `process.versions.node` may
+ * carry a pre-release suffix that `Number()` would turn into NaN, so the numeric
+ * prefix of each component is what counts.
+ *
+ * @param {string} current a version such as `22.20.0` or `23.1.0-rc.1`
+ * @param {string} [minimum]
+ * @returns {boolean}
+ */
+export function satisfiesMinimum(current, minimum = MIN_NODE) {
+  const parse = (value) =>
+    String(value)
+      .split('.')
+      .map((part) => Number.parseInt(part, 10))
+      .map((part) => (Number.isFinite(part) ? part : 0));
+  const have = parse(current);
+  const want = parse(minimum);
+  for (let i = 0; i < Math.max(have.length, want.length); i += 1) {
+    const a = have[i] ?? 0;
+    const b = want[i] ?? 0;
+    if (a !== b) return a > b;
+  }
+  return true;
+}