simt-dev 0.7.1 → 0.8.0

package/src/text/tokens.mjs

@@ -0,0 +1,52 @@
+// The token split and the two stopword lists, in one place.
+//
+// The two lists are deliberately NOT merged. The resolver's list is the English
+// filler a task string carries ("fix the thing"), hand-authored because a resolver
+// nobody can review is not a resolver; the index's list is the vocabulary a task
+// about code carries ("file", "test", "line"), sized for a different signal. Merging
+// them would change what each one ranks, and a ranking change is a behaviour change
+// this deduplication was not asked to make.
+
+/**
+ * Split a task string into comparable tokens.
+ *
+ * Length 2 is kept. The floor used to be 3, and it dropped the most specific words in
+ * this domain: `d1`, `r2`, `kv`, `ci` are two-letter vocabulary, not noise, and a task
+ * saying "fix d1 migration" lost the one word that identified the change. The cost is
+ * that six stopwords of two letters (`in on of or an so`) now reach the summary signal,
+ * which is S04's finding and not something this change can resolve on its own - the
+ * remedy there is a stopword list, not a longer minimum.
+ */
+export function tokenize(text) {
+  return String(text ?? '')
+    .toLowerCase()
+    .split(/[^a-z0-9]+/)
+    .filter((t) => t.length > 1);
+}
+
+/**
+ * The English filler a task string carries. Hand-authored rather than derived, for the
+ * same reason the capability aliases are: a resolver nobody can review is not a
+ * resolver.
+ */
+export const STOPWORDS = new Set([
+  'about', 'after', 'all', 'also', 'and', 'an', 'any', 'are', 'as', 'at', 'be', 'because',
+  'been', 'before', 'being', 'both', 'but', 'by', 'can', 'could', 'did', 'do', 'does', 'each',
+  'for', 'from', 'had', 'has', 'have', 'he', 'her', 'here', 'his', 'how', 'if', 'in', 'into',
+  'is', 'it', 'its', 'just', 'like', 'make', 'many', 'may', 'me', 'more', 'most', 'must', 'my',
+  'no', 'not', 'now', 'of', 'off', 'on', 'one', 'only', 'onto', 'or', 'other', 'our', 'out',
+  'over', 'own', 'per', 'same', 'see', 'set', 'she', 'should', 'so', 'some', 'such', 'than',
+  'that', 'the', 'their', 'them', 'then', 'there', 'these', 'they', 'this', 'those', 'to', 'too',
+  'two', 'under', 'up', 'us', 'use', 'used', 'using', 'very', 'was', 'way', 'we', 'were', 'what',
+  'when', 'where', 'which', 'while', 'who', 'why', 'will', 'with', 'within', 'without', 'would',
+  'you', 'your',
+]);
+
+/** The code vocabulary a task about a tree carries, for the index's term signal. */
+export const INDEX_STOP = new Set([
+  'this', 'that', 'with', 'from', 'have', 'been', 'into', 'only', 'when', 'what',
+  'which', 'their', 'about', 'after', 'before', 'where', 'there', 'these', 'those',
+  'would', 'could', 'should', 'every', 'other', 'than', 'then', 'them', 'they',
+  'your', 'will', 'does', 'file', 'files', 'test', 'tests', 'line', 'lines', 'code',
+  'also', 'just', 'more', 'some', 'such', 'each', 'same', 'over', 'used', 'using',
+]);

package/src/toolwords.mjs

@@ -23,7 +23,7 @@ import { LESSON_KEYS } from './memory/lessons.mjs';
 import { DECISION_KEYS } from './memory/decide.mjs';
 import { PROMPT_WORDS } from './mcp/prompts.mjs';
 import { AGENT_STEM, SKILL_STEM } from './agents/render.mjs';
-import { CORPUS_KIND } from './bench/corpus.mjs';
+import { CORPUS_KIND } from './measure/corpus.mjs';
 
 /**
  * `simt-` names that belong to this tool and never to a repository.

package/src/util/fs.mjs

@@ -0,0 +1,20 @@
+// Small file and output helpers with two or more call sites, too small to earn
+// a module apiece.
+
+import { readFile } from 'node:fs/promises';
+
+/** Read a file as UTF-8, answering null when it is not there. */
+export async function readIfExists(path) {
+  try {
+    return await readFile(path, 'utf8');
+  } catch {
+    return null;
+  }
+}
+
+/** `1234567`, never `1,234,567`: two machines must print the same bytes (ADR-013).
+ *  `toLocaleString` output is locale-dependent, and these commands exist so that two
+ *  machines produce two numbers a pull request can compare. */
+export function plainNumber(n) {
+  return String(n);
+}

package/src/util/sort.mjs

@@ -0,0 +1,12 @@
+// The one string comparison for every sort that orders paths, names and ids.
+//
+// Seven copies of the same three-line comparator grew up under src/, spelled two
+// different ways, and a divergence in any one of them would quietly reorder a list
+// a reader has memorized. One definition, one order.
+
+/** Deterministic string order: -1, 0 or 1. */
+export function cmp(a, b) {
+  if (a < b) return -1;
+  if (a > b) return 1;
+  return 0;
+}

package/src/workspace.mjs

@@ -21,6 +21,8 @@
 // confidently wrong.
 
 import { readFile } from 'node:fs/promises';
+
+import { namedRoot } from './repo-root.mjs';
 import { existsSync } from 'node:fs';
 import { homedir, platform as osPlatform } from 'node:os';
 import { dirname, isAbsolute, join, resolve } from 'node:path';
@@ -311,7 +313,7 @@ function absolute(p, base = process.cwd()) {
  * answers it from the filesystem rather than from a guess.
  */
 export async function targetRoot(flags = {}, positional = []) {
-  const explicit = flags.root ?? positional[0];
+  const explicit = namedRoot(flags, positional);
   if (explicit) {
     return { root: absolute(explicit), source: 'flag', detail: explicit, ws: null };
   }

package/src/write/plan.mjs

@@ -0,0 +1,82 @@
+// One change record, and the one function that applies it (review 0003 Q68).
+//
+// Fourteen writers hand-roll the same five steps: read the before bytes, decide create or
+// update, write through the journal, commit the set, print the diff. They do not all do
+// them in the same order, and the differences are defects rather than decisions - a
+// writer that skipped the journal (the tracker, the lock, `skills compile`) could not be
+// undone, and one that read the before bytes after writing produced a diff against
+// itself.
+//
+// A change is data: what the path will hold, what it holds now, who owns it and why it
+// changes. `applyPlan` is the only place that knows about journals, directories and
+// `--yes`, so a writer states the change and nothing else.
+//
+// The record carries no `action` from the caller. Create, update, remove and unchanged
+// are derived from `before` and `after`, because a writer that passes an action it
+// computed by hand is the bug this replaces.
+import { isAbsolute, join } from 'node:path';
+
+import { commitJournal, journaledRemoveFile, journaledWriteFile } from '../journal.mjs';
+
+/**
+ * One change to one path.
+ *
+ * `kind: 'remove'` is a deletion, and `after` is then null. `owner` and `reason` are for
+ * the report a person reads: which writer owns the file and why it is changing. `mode` is
+ * permission bits for a file that must be executable, and rides on the same entry so
+ * `undo` restores the mode it found.
+ */
+export function change({ path, kind = 'file', before, after, owner, reason, mode }) {
+  if (kind !== 'file' && kind !== 'remove') throw new Error(`unknown change kind: ${kind}`);
+  return {
+    path,
+    kind,
+    before,
+    after,
+    owner: owner ?? null,
+    reason: reason ?? null,
+    mode,
+    action: actionOf(kind, before, after),
+  };
+}
+
+function actionOf(kind, before, after) {
+  if (kind === 'remove') return before === null ? 'unchanged' : 'remove';
+  if (before === after) return 'unchanged';
+  if (before === null) return 'create';
+  return 'update';
+}
+
+/** The changes that would do something, in the order the caller listed them. */
+export function pending(changes) {
+  return (changes ?? []).filter((c) => c.action !== 'unchanged');
+}
+
+/**
+ * Apply the plan, or report it.
+ *
+ * Without `mode.apply` nothing touches the disk and the pending paths come back as
+ * `pending`: a rehearsal and a real run answer the same question with the same plan, and
+ * the only difference is whether the bytes moved. With it, every change is journaled into
+ * one set under `label`, so `undo` restores the run rather than one file of it.
+ *
+ * A writer whose run is more than one plan - `init` writes a manifest, an identity and a
+ * set of targets and commits once - passes its own `journal` and `commit: false`. The
+ * entries land in the caller's set, so the run stays one undoable step rather than one
+ * step per plan.
+ */
+export async function applyPlan(root, changes, { mode, label, journal: shared, commit = true } = {}) {
+  const todo = pending(changes);
+  if (todo.length === 0) return { applied: false, written: [], pending: [], journal: [] };
+  if (!mode?.apply) return { applied: false, written: [], pending: todo.map((c) => c.path), journal: [] };
+
+  const journal = shared ?? [];
+  const first = journal.length;
+  for (const c of todo) {
+    const path = isAbsolute(c.path) ? c.path : join(root, c.path);
+    if (c.kind === 'remove') await journaledRemoveFile(root, journal, path);
+    else await journaledWriteFile(root, journal, path, c.after, c.mode === undefined ? {} : { mode: c.mode });
+  }
+  if (commit && journal.length > first) await commitJournal(root, label, journal);
+  return { applied: true, written: todo.map((c) => c.path), pending: [], journal };
+}

package/templates/plan/tracker.json

@@ -3,6 +3,7 @@
   "name": "tracker",
   "directories": [
     { "kind": "plans", "word": "plan", "path": "docs/plans" },
+    { "kind": "research", "word": "research", "path": "docs/research" },
     { "kind": "reviews", "word": "review", "path": "docs/reviews" }
   ],
   "id": {

package/docs/decisions/ADR-033-three-plan-rows-closed-by-decision-not-by-authoring.md

@@ -1,82 +0,0 @@
-# ADR-033 — three plan rows closed by decision, not by authoring
-
-Status: accepted · 2026-10-08
-**Affects:** `docs/plans/0001-centralise-agent-rules.md` §3.1 row 3, §6 phase 6, §6 phase 7.
-Ships no rule text. **Refuses:** the seven agent policies row 3 asks for, the twin collapse
-phase 6 asks for, and untracking the two committed `local.properties` files phase 7 does not
-mention but whose existence made the sweep look unfinished.
-
-## Context
-
-Closing plan 0001 meant auditing each row against the tree rather than against the plan's own
-prose, because the plan was written on 2026-10-05 and three things changed underneath it. This
-record is the audit's residue: three items that read as unfinished work and are not.
-
-Row 3 asked for eight agent policies as separate files. Seven were never authored. A search for
-their source material across every tracked `*.md` and `*.mdc` in the estate returns two files,
-neither of which is a policy: they are a progress ledger and a completed UX plan that happen to
-contain the phrases. The three most specific of the eight — the 70/30 quality-versus-performance
-split, the 12-state coverage list, the matrix-trigger heuristic — have no source anywhere. Writing
-them would mean inventing doctrine this estate never agreed to, into `rules/core.md`, from where
-every adopted repo would inherit it.
-
-Phase 6 asked to "collapse the 7 drifted Social skill twins to canonical + stub". The registry's
-`sources.role` mechanism landed the same evening, two hours after the plan was authored, and
-answers the row directly. All three resolvers select `role === 'canonical'` and nothing else —
-`src/commands/skills.mjs` twice, `src/commands/skillsinstall.mjs:291`, `src/mcp/tools.mjs:192` — so
-a copy declared `duplicate` or `variant` is never installed. The one pair that genuinely had to be
-collapsed, `add-country-galaxy`, is already a stub in `repo-14` pointing at the API repo.
-
-Phase 7 asked for a sweep of hardcoded absolute paths. The sweep found 17 tracked files. Six were
-fixed. The two Android `local.properties` files were not, and were nearly fixed by reflex.
-
-## Rulings
-
-1. **A row is closed by ruling on it when the thing it asks for was never a decision anyone made.**
-   Row 3's eight policies are closed: the four claims `rules/core.md` already carries — the
-   minimum viable team, never weakening a security control, anti-overclaim, and a stated agent
-   budget that never converts a failure into an approval — are the doctrine, and they ship. The
-   other four, including the 70/30 split, the 12-state list and the matrix-trigger heuristic, are
-   recorded here as unmade. If one is wanted it needs someone who held the original
-   conversation, not someone reconstructing it from a table cell.
-
-2. **A mechanism that supersedes a row retires the row, and the deletion is the wrong move.** The
-   `sources.role` vocabulary already distinguishes `canonical`, `duplicate`, `variant`, `stub` and
-   `deprecated`, and `graph lint` passes with all of them in use. Deleting a `duplicate` copy would
-   remove a version-pinned tool from a repo that can still run it, and nothing would detect the loss
-   because resolution never read those bytes. Phase 6's twin collapse is therefore closed as
-   already answered, at `a9983c8`.
-
-3. **`local.properties` stays tracked.** Both `repo-05` and `repo-03` commit it, and both
-   `.gitignore` files have the conventional `# local.properties` line commented out at lines 22 and
-   24 — a deliberate override of Android's own convention, not an oversight. Untracking them would
-   be a house-style change made while closing a plan, and a build machine that checks out without
-   an SDK would stop building. It stays, and plan 0001 says so, so the next sweep does not
-   rediscover it as a defect.
-
-## Consequences
-
-Row 3 reads "done, four of eight" rather than "partial". Phase 6's twin item reads "superseded"
-rather than "outstanding". The estate keeps two `local.properties` files whose `sdk.dir` names a
-developer's home directory, by decision.
-
-The registry's byte counts moved with the two skill bodies corrected in the same pass, because a
-declared source's identity is its size (ADR-015): `cloudflare` 384277 → 384869 and
-`production-quality-review` 5869 → 5904. That changed the provenance digest (ADR-032), so all
-fourteen adopted repos were re-stamped afterwards rather than left pinning a value this tool can no
-longer produce.
-
-## Rejected
-
-**Authoring the seven agent policies.** The plan's one-line summaries are not enough to write seven
-files of rule text, and these rules reach every adopted repo. This is ADR-030's exact shape: an
-unmade decision is not a gap to fill by invention.
-
-**Collapsing `graphify` and `parallel-feature-team`.** Both are declared `duplicate` with matching
-byte counts, so they look like the obvious candidates. `graphify` is `vendored: true` — an
-84 534-byte, ten-file, version-pinned tool present in both one repository on purpose. Deleting
-repo-14's copy would leave nothing to detect the loss, because resolution only ever read the
-canonical copy.
-
-**Untracking `local.properties`.** An Android SDK path is machine state, and two repos chose to
-share it. That is the repo's call to reverse, not a plan's defect sweep.

package/docs/decisions/ADR-102-the-two-queued-review-rows-are-closed-by-ruling.md

@@ -1,49 +0,0 @@
----
-simt-affects: ["docs/reviews/0002-full-review-adoption-and-public-release.md"]
-simt-supersedes: []
----
-
-# ADR-102 — the two rows review 0002 left queued are closed by ruling
-
-Status: **accepted** · 2026-10-28
-
-## Context
-
-Review 0002's §3 tracker is the only tracker of slice state, and two rows in it
-still read Queued while everything around them shipped: S38 (workspace token
-cost) and S39 (estate policy as a pack). Both rows' evidence cells are
-palimpsests — notes from three different landings disagreeing about what is
-still open — so reading them as a work list sends the next reader to build what
-is already built. Closing plan 0001 meant the same audit, and ADR-033 is the
-precedent: rows closed by saying what shipped, what was refused by ruling, and
-where the remainder lives, not by authoring what they asked for.
-
-## Ruling
-
-1. **S38 is Complete.** The instrument shipped (`simt tokens`, ADR-064), the
-   declaration shipped (`budget.bytes` beside `limits` and `gates`, ADR-072),
-   and the gate raises it as a finding through one `budgetFinding` read from
-   one place by both `tokens` and `check` — the "still open" clause the row's
-   first note ends on. Kernel-line packing shipped with it (R07's `mode:
-   kernel`, R08's budget compilation). Blocking enforcement is refused, not
-   outstanding: a gate that fails a repository for exceeding a ceiling it set
-   itself, when nothing was cut, has no repair except lowering the declared
-   number (ADR-072). The one genuine remainder is the kernel-default
-   compliance study, and it is owned by plan 0003 R07's own note, not by this
-   row — the study gates making `kernel` the default, which no row asks to
-   decide here.
-
-2. **S39 is Complete.** The mechanism shipped (packs vendored and digest-pinned,
-   ADR-065; measured ΔR, plan 0003 R45). P4's pack-carries-the-registry line was
-   superseded by ADR-061, which made the registry workspace data, so there is
-   no registry-carrying pack to build. The remaining half — moving estate
-   policy into a pack — is the estate's own commit: no estate content may enter
-   this repository, and a row that waits on another repository's commit is
-   closed by recording whose commit it waits on.
-
-## Consequences
-
-- The §3 tracker reads Complete on both rows, with this record as the evidence,
-  so the next audit starts from rulings rather than from mid-flight notes.
-- A reader asking for a blocking budget gate or a registry-carrying pack gets
-  the refusal and its reason instead of an open row that looks like a promise.

package/src/bench/tasks.mjs

@@ -1,36 +0,0 @@
-// Mined task descriptors, read back from the tool state's `bench/tasks/` directory (plan 0003 R01).
-//
-// Extracted from bench/run.mjs on its second real reader (ADR-002): the R40 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.
-//
-// Deterministic by construction: the directory is read sorted, the filter is exact, and no
-// part of this 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';
-
-/**
- * Load mined benchmark task descriptors.
- *
- * @param {string} root the repository
- * @param {string[]} [filterIds] exact task ids to keep; empty means load them all
- * @returns descriptor objects sorted by id (id, base, sourceCommit, prompt, testCmd,
- *   f2p, p2p, gold {files, linesAdded, linesRemoved}, vault)
- */
-export async function loadTasks(root, filterIds = []) {
-  const tasksDir = join(resolve(root), STATE_DIR, 'bench', 'tasks');
-  const entries = (await readdir(tasksDir).catch(() => []))
-    .filter((f) => f.endsWith('.json'))
-    .sort();
-
-  const filterSet = new Set(filterIds);
-  const tasks = [];
-  for (const entry of entries) {
-    const data = JSON.parse(await readFile(join(tasksDir, entry), 'utf8'));
-    if (filterSet.size > 0 && !filterSet.has(data.id)) continue;
-    tasks.push(data);
-  }
-  return tasks.sort((a, b) => a.id.localeCompare(b.id));
-}