simt-dev 0.2.2 → 0.3.1

package/docs/decisions/ADR-091-the-map-ranks-files-a-task-mentions.md

@@ -0,0 +1,60 @@
+# ADR-091 — The map ranks the files a task mentions, and the files next to them
+
+Status: **accepted** · 2026-10-18 · filed as R22 (plan 0003)
+
+**Affects:** `src/index/map.mjs`, `src/commands/map.mjs`, `src/commands/bench.mjs`,
+`test/map.test.mjs`
+
+## Context
+
+A task names a behaviour. The files that behaviour lives in are a small part of
+the tree, and an agent that reads the tree in path order spends its budget on
+files the task never touches. The index now records imports. What it did not
+do is say which of those files to read first.
+
+The mined tasks store a gold patch outside the worktree. The published task
+record counts the files and the lines. It does not list the paths. Recall has
+to be read from the patch, and a machine without that patch cannot invent the
+denominator.
+
+## Rulings
+
+1. **The map is PageRank over import and call edges, personalised to the task.**
+   Twenty iterations, damping 0.85. An edge counts in both directions, once.
+   A file the task mentions sorts ahead of a file it does not: on this graph
+   the file every module imports otherwise occupies the top 10. A term that
+   labels too many paths is ignored. A token that contains a digit and names
+   one path counts more the more often the task says it, so a citation does
+   not rank with the subject. A file that already matched, in a directory of
+   at most eight files, is lifted toward its neighbour. Files the task does
+   not mention, and that are not one edge away from a file it does, are left
+   out. With no task text the whole graph is ranked. Equal ranks break by
+   path, ascending. The same graph and the same text return the same order.
+
+2. **The rendering fits a budget, at one of three levels.** `outline` is paths.
+   `names` adds the exported symbols. `signatures` adds the line they were
+   declared on. The default budget is 2048 bytes. Zero means no ceiling. The
+   first file is kept when it alone is over the budget, so a map of a real
+   ranking is not an empty page.
+
+3. **recall@10 is the mean, over mined tasks, of the fraction of gold files
+   that land in the top 10.** The gold paths are the destination side of the
+   patch. A task whose patch is not in the vault is unmeasured, not a miss.
+   `simt bench report` prints the figure. It does not fail the cost report
+   when the figure cannot be computed.
+
+## Consequences
+
+`simt map` reads the index and rebuilds it when the cache is empty. The
+comparison against the mined patches is a property of this checkout's index
+and of the vault on this machine. A checkout with no index, or no vault,
+reports the figure as unmeasured. On the 20 mined tasks available here, mean
+recall@10 is 55.6% of gold files. The bar is 60%, and this ranking does not
+meet it.
+
+## Rejected
+
+- **One-directional edges.** Rank would flow only toward the imported file, and
+  the test that imports the file the task named would never surface.
+- **A zero when the gold patch is absent.** That number would punish a machine
+  for a file the benchmark hides, and it would read as a measurement.

package/docs/decisions/ADR-092-tests-are-imports-conventions-and-coverage.md

@@ -0,0 +1,60 @@
+# ADR-092 — A test is an import, a conventional neighbour, or a coverage record
+
+Status: **accepted** · 2026-10-18 · filed as R24 (plan 0003)
+
+**Affects:** `src/index/tests.mjs`, `src/commands/tests.mjs`, `test/mapping.test.mjs`
+
+## Context
+
+The index records imports. A test file that imports a source file is evidence
+that the test exercises it, and so is a coverage report that names both. A
+shared commit is weaker: most commits touch a test and several sources that
+the test does not exercise.
+
+The line extractor reads one line at a time, so an import whose specifier sits
+on the next line is absent from the stored edges. The mapping has to see that
+specifier or it misses the tests this repository actually writes.
+
+## Rulings
+
+1. **The default answer uses only the precise edges.** Kind `test`, weight 1.
+   A test file imports a tracked source file, including a dynamic `import()`.
+   Or the conventional source beside the test exists: `foo_test.go` beside
+   `foo.go`, `test_foo.py` beside `foo.py`, `FooTest` beside `Foo` in the same
+   directory, `foo.test.mjs` beside `foo.mjs`, and `src/test/java` mirrored to
+   `src/main/java`. Or a coverage record names both sides. lcov pairs a source
+   only when the test name is non-empty. JaCoCo pairs a source file with the
+   one class whose stem is that file plus `Test` or `Tests`. A Go profile
+   counts a hit, and the test is `stem_test.go` in that directory, or the
+   single `*_test.go` there. A file that is not one of those is not an edge.
+
+2. **Co-change is a different kind, and it is off unless asked.** Kind
+   `cochange`. A pair counts when it appears in at least two commits. A commit
+   with more than five tests or more than fifteen sources is skipped. Each
+   test keeps its eight strongest pairs. History is the last 200 non-merge
+   commits. `simt tests --cochange` appends those files after the precise
+   ones. A git failure leaves the history empty; the import map still answers.
+
+3. **The edges are computed when asked, and not stored.** The index write
+   replaces every edge of a changed path. Storing the test map in that write
+   would drop the import edges, and reading the commit log inside a reindex
+   would miss the one-file time bar. Coverage is read from a fixed list of
+   paths. A path that is absent is not a failure.
+
+4. **Precision is the share of predicted tests that the label also names.**
+   An empty prediction does not pass. On the 30 hand-labelled files in this
+   checkout the figure is 1.0. The bar is 0.8.
+
+## Consequences
+
+`simt tests` with no path prints how many test edges and how many co-change
+edges the tree has. `simt tests <path>` lists the tests for that file. A path
+the index does not contain is a usage error. A directory that is not a git
+repository is unsupported.
+
+## Rejected
+
+- **A stem that is unique somewhere else in the tree.** The test named for a
+  directory is not the test of the one file that happens to share that stem.
+- **Writing the test edges into the index.** The next reindex of a touched
+  path would have to know about every edge kind or it would delete them.

package/docs/decisions/ADR-093-why-names-what-governs-a-file.md

@@ -0,0 +1,58 @@
+# ADR-093 — why names what governs a file
+
+Status: **accepted** · 2026-10-18 · filed as R25 (plan 0003)
+
+**Affects:** `src/index/govern.mjs`, `src/commands/why.mjs`, `test/why.test.mjs`,
+`test/why-fixture.test.mjs`, `test/why-snapshot.test.mjs`
+
+## Context
+
+A decision says which files it governs in an Affects line. The line is prose.
+It wraps. It names a command, a path from the repository root, a path from a
+source directory, or a phrase that is not a location at all. A reader who
+greps the word Affects still has to decide which of those a backtick was.
+
+Rules, skills, gates and lessons name paths in their own way. The question
+`why` answers is the same for each: does this one govern this file?
+
+## Rulings
+
+1. **The Affects line contributes the tokens in backticks, and nothing else.**
+   Continuation lines are part of the paragraph. A blank line, a heading, or
+   the next field ends it. The token is resolved in order: a command prefixed
+   with the tool name, when that command exists; a path or a glob at the
+   repository root; the same path under each directory named src. The tool
+   name alone is not a command. A token that is none of these is reported as
+   `UNRESOLVED-AFFECTS`, with the record it came from. It is not dropped and
+   it is not guessed.
+
+2. **The other governors are the path lists they already publish.** A rule
+   governs a file its scope matches. An applies entry governs a file only when
+   the entry is itself a path. A skill governs a file its paths match. A
+   staged gate governs a file of an extension it formats, and a manifest
+   command governs a file it names. A lesson governs a file its trigger names.
+   A missing lessons directory, a missing skill registry, or a missing
+   manifest is an empty list.
+
+3. **The answer is computed when asked, and not stored.** The file list is
+   the paths git tracks. Writing the index to answer the question would change
+   the tree the question is about.
+
+## Consequences
+
+`simt why <path>` prints one line for each decision, rule, skill, gate and
+lesson that governs that path. `simt why` with no path prints the unresolved
+Affects tokens. A path git does not track is a usage error. A directory that
+is not a git repository is unsupported.
+
+On the tree at 4c27514, sixteen Affects lines were the whole set, and the
+only record naming the dispatcher was ADR-017. Records written after that
+commit name it as well, and `why` lists those too.
+
+## Rejected
+
+- **Attaching every always-on rule to every file.** The rule governs the
+  repository. Listing it on each file would hide the ones that actually name
+  the file.
+- **Treating an unresolved token as a path that might exist later.** The
+  report is the point. A guess would make the report empty.

package/docs/decisions/ADR-094-a-change-runs-the-tests-that-import-it.md

@@ -0,0 +1,44 @@
+# ADR-094 — a change runs the tests that import it
+
+Status: **accepted** · 2026-10-18 · filed as R16 (plan 0003)
+
+**Affects:** `src/index/gate.mjs`, `src/commands/gate.mjs`, `test/gate.test.mjs`
+
+## Context
+
+A gate that always runs the whole suite teaches people to skip it. The tests
+that can see a change are the ones that import it, including through another
+file. A name that looks like a test, and a commit that also touched a test,
+are different facts. They are already answered by `simt tests`.
+
+The pre-commit hook, the stop hook and an agent call this command. They do
+not need the dispatcher rewritten to do it.
+
+## Rulings
+
+1. **Selection is the import closure.** A test file is selected when an import
+   reaches a changed file, at any depth. A changed file that is itself a test
+   is selected. A cycle is walked once. A conventional neighbour and a shared
+   commit are not imports, so they are not a selection. A file the test-path
+   rule already treats as a test counts, including a helper that lives beside
+   the tests and imports the change.
+2. **The command is `simt gate`.** Paths name the change. `--changed` reads
+   the diff, staged, unstaged and untracked. No path and no `--changed` is a
+   usage error. A clean diff selects nothing and runs nothing. A repository
+   that is not git is unsupported.
+3. **The run is the package's own runner, and only the selected files.** Tests
+   are grouped by the package that contains them. The runner is the one that
+   package already declares. A package with no runner is unsupported. The
+   child's test-runner environment is cleared, so a parent test process cannot
+   take the child's result and report a pass.
+4. **The hand list for the plan's named file is 51 files, and the selection
+   finished in under 5 seconds.** Eight other test files do not import it, and
+   they are not selected. The set is wide because the shared fixture imports
+   the loader that imports that file. Measured at about 40 ms.
+
+## Consequences
+
+`simt tests` still answers "which tests exercise this file", including a
+conventional name and, when asked, a shared commit. `simt gate` answers "run
+the tests this change can reach". Compaction of the runner's text is a later
+slice. The dispatcher is unchanged.

package/docs/decisions/ADR-095-gate-output-keeps-the-failures.md

@@ -0,0 +1,31 @@
+# ADR-095 — gate output keeps the failures
+
+Status: **accepted** · 2026-10-18 · filed as R18 (plan 0003)
+
+**Affects:** `src/index/compact.mjs`, `src/commands/gate.mjs`, `test/compact.test.mjs`
+
+## Context
+
+A gate that prints every passing test spends the reader's attention on the
+lines that did not fail. A summary that drops a failure is worse: the run
+looks cleaner than it was. The formats this tool's own runners emit are
+known. An arbitrary shell log is not one of them, and guessing at it is how
+a line gets lost.
+
+## Rulings
+
+1. **Compaction applies to a report this tool produced, and only to a format
+   it can read.** Those formats are TAP, JUnit XML, vitest or jest JSON, and
+   `go test -json`. Pytest's junit file is JUnit XML. A stream that is none
+   of these is printed unchanged.
+2. **Failures come first, and each one is kept.** The name, the assertion
+   and the location stay in the printed block. Passing tests become a count.
+   A skip becomes a count when there is one.
+3. **The raw log path is printed.** The log is gitignored. The command does
+   not wrap an arbitrary shell command. The gate is the caller.
+
+## Consequences
+
+`simt gate` is the command that compacts. Another command that wants the same
+treatment calls the same function. A format that is not in the list stays
+raw until it is added with a golden fixture.

package/docs/decisions/ADR-096-impact-names-who-a-change-reaches.md

@@ -0,0 +1,38 @@
+# ADR-096 — impact names who a change reaches
+
+Status: **accepted** · 2026-10-18 · filed as R23 (plan 0003)
+
+**Affects:** `src/index/impact.mjs`, `src/commands/impact.mjs`, `test/impact.test.mjs`
+
+## Context
+
+A change has a neighbourhood: the files that import it, the tests of that
+neighbourhood, the decisions and rules that govern the file, and the owner a
+CODEOWNERS line names. In a workspace the neighbourhood crosses a repository
+when another one references a contract this change touches. That is the check
+behind "the producer ships before the consumer".
+
+## Rulings
+
+1. **The argument is a tracked path, or the name of one export.** A private
+   symbol is not an export. Several files exporting the same name is a usage
+   error that names those files. A name that is neither a path nor an export
+   is a usage error. A tree that is not git is unsupported.
+2. **Importers are the non-test files that import the target, at any depth.**
+   The tests are the test files that import that closure. Both lists stop at
+   64. Past that, the report says it was truncated.
+3. **Governance is what `why` would name for the file, limited to decisions
+   and rules.** Owners are the last matching pattern in the first CODEOWNERS
+   file that exists. A pattern with no slash matches the file name in any
+   directory.
+4. **A cross-repo consumer is another repository whose text contains a
+   contract path this change touches.** A contract is an OpenAPI document or
+   a JSON Schema file. The path has to include a directory. No workspace
+   means no consumers, and that is not a failure. The scan stops at 64
+   references and 2000 files in a repository.
+
+## Consequences
+
+`simt impact` answers who is reached. `simt gate` still runs the tests.
+`simt why` still answers governance on its own, including skills, gates and
+lessons, which this report does not repeat.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "simt-dev",
-  "version": "0.2.2",
+  "version": "0.3.1",
   "description": "Shared agent rules, skills and git hooks for a repository: one command adopts a repo, and every gate it declares is probed before it is written.",
   "license": "Apache-2.0",
   "author": "Said Elimam",
@@ -20,6 +20,7 @@
     "bin",
     "src",
     "rules",
+    "templates",
     "docs/decisions",
     "CHANGELOG.md"
   ],

package/rules/core.md

@@ -60,7 +60,7 @@ commands belongs in this repository, not here.
 
 - No type-system escapes, no unawaited async work, no debug printing in application code.
 - 400 lines is a review trigger; 1000 lines is a hard ceiling. Generated files are exempt
-  when the hook names the generator. (ADR-005)
+  when the hook names the generator. (ADR-005) <!-- simt-check: max-file-lines -->
 - Never weaken CSP, CORS, auth, audit, cache or validation controls to silence a test, warning
   or alert.
 - Review verdicts are exactly three: `BLOCK`, `APPROVE WITH RESIDUAL RISK` (must list what was

package/src/agenthooks/decide.mjs

@@ -0,0 +1,123 @@
+// What a policy decides, given facts and one session's overrides.
+//
+// Pure, so the whole decision is testable without a harness: hand it the facts a
+// renderer would extract and an environment, and it answers. The filesystem is
+// consulted in exactly one place — `generatedBytes`, which asks whether a file being
+// written to holds bytes this tool generates — because that is the one fact a payload
+// cannot carry.
+//
+// Two properties are deliberate and both are about an author standing still:
+//
+// Every matching policy is reported, not the first. `git push --force` is a push and a
+// rewrite; a build that stopped at the first match would let `SIMT_ALLOW=push` lift the
+// approval rule and carry a force-push through, because the rewrite rule was never
+// consulted. Lifting a policy lifts that policy.
+//
+// No fact is not a violation. A payload whose shape we did not read — a harness that
+// renamed a tool, an agent writing through some tool we have never seen — yields no
+// command and no path, and the decision is to say nothing. Turning "we do not
+// understand this" into "blocked" makes the hook a false-positive machine, and a hook
+// that blocks real work is uninstalled the same afternoon.
+
+import { readFile } from 'node:fs/promises';
+import { join, relative, resolve } from 'node:path';
+
+import { parse } from '../projection/markers.mjs';
+import { ALLOW_ENV, EVENTS, POLICY_IDS, policiesFor } from './policy.mjs';
+
+/**
+ * The policies this session has lifted, and the names in `SIMT_ALLOW` that are not
+ * policies at all.
+ *
+ * An unknown name is reported rather than ignored: `SIMT_ALLOW=push,rewrit` typed once
+ * and relied on would otherwise look like a lift that did nothing, and the author would
+ * conclude the hook was broken rather than the spelling.
+ */
+export function overrides(env = {}) {
+  const raw = env[ALLOW_ENV];
+  const named = typeof raw === 'string' ? raw.split(',').map((s) => s.trim()).filter(Boolean) : [];
+  return {
+    ids: new Set(named.filter((n) => POLICY_IDS.includes(n))),
+    unknown: named.filter((n) => !POLICY_IDS.includes(n)),
+  };
+}
+
+/** Whether one row applies to the facts. A row with no matcher reads the facts itself. */
+function applies(row, facts) {
+  if (row.inspects === 'command') {
+    return typeof facts.command === 'string' && row.match !== null && row.match.test(facts.command);
+  }
+  if (row.inspects === 'write') {
+    return (facts.writes ?? []).some((w) => w.generated !== null && w.generated !== undefined);
+  }
+  return false;
+}
+
+/**
+ * The decision for one event.
+ *
+ * `blocked` and `lifted` are ids, not rows, because the caller prints them and an id is
+ * what a reader types into `SIMT_ALLOW`. The messages carry their own override hint, so
+ * a denial is actionable without the reader knowing the variable exists.
+ */
+export function decide({ event = EVENTS[0], facts = {}, env = {} } = {}) {
+  const { ids: lifted, unknown } = overrides(env);
+  const matched = policiesFor(event).filter((p) => applies(p, facts));
+  const blocked = matched.filter((p) => !lifted.has(p.id));
+  return {
+    event,
+    decision: blocked.length > 0 ? 'deny' : 'allow',
+    blocked: blocked.map((p) => p.id),
+    lifted: matched.filter((p) => lifted.has(p.id)).map((p) => p.id),
+    unknown,
+    messages: blocked.map((p) => `${p.message} (override: ${ALLOW_ENV}=${p.id})`),
+    adrs: blocked.map((p) => p.adr),
+  };
+}
+
+/** Whether this file's bytes are generated: a region this tool writes, or a submodule. */
+function holdsRegion(text) {
+  // Both marker styles, because the region is written in whichever one the file's own
+  // syntax allows — `<!-- simt:begin -->` in markdown, `# simt:begin` in an
+  // .editorconfig. A malformed region is still a region: a begin marker with no end is
+  // the file somebody has already been editing by hand.
+  return parse(text).status !== 'absent' || parse(text, 'hash').status !== 'absent';
+}
+
+/** The submodule paths `.gitmodules` declares, as repository-relative directories. */
+async function submodules(root) {
+  const text = await readFile(join(root, '.gitmodules'), 'utf8').catch(() => null);
+  if (text === null) return [];
+  return text
+    .split('\n')
+    .map((line) => /^\s*path\s*=\s*(.+?)\s*$/.exec(line))
+    .filter(Boolean)
+    .map((m) => m[1].replace(/\/+$/, ''));
+}
+
+/**
+ * Why this path is not the author's to write, or null when it is.
+ *
+ * The reason is returned rather than a boolean because the two answers are different
+ * facts and the author of a fix needs to know which one applies: a region is repaired by
+ * editing its source, a submodule by committing in the other repository.
+ */
+export async function generatedBytes(root, file) {
+  const abs = resolve(root, file);
+  const text = await readFile(abs, 'utf8').catch(() => null);
+  if (text !== null && holdsRegion(text)) return 'region';
+  const rel = relative(resolve(root), abs);
+  if (!rel.startsWith('..')) {
+    const inside = await submodules(root);
+    if (inside.some((dir) => rel === dir || rel.startsWith(`${dir}/`))) return 'submodule';
+  }
+  return null;
+}
+
+/** Turn a renderer's extraction into the facts the table asks about. */
+export async function factsFor(root, { command = null, writes = [] } = {}) {
+  const resolved = await Promise.all(
+    writes.filter(Boolean).map(async (path) => ({ path, generated: await generatedBytes(root, path) })),
+  );
+  return { command, writes: resolved };
+}

package/src/agenthooks/policy.mjs

@@ -0,0 +1,78 @@
+// The policies an agent-time hook enforces, in one table.
+//
+// One table and four harnesses. The renderers in ./render.mjs map a harness's own
+// payload onto the facts named here and a decision back onto that harness's own JSON,
+// so a policy is written once and cannot be enforced in one harness and forgotten in
+// another — which is the failure the four vendor documents make easy: they agree on
+// nothing, not the config path, not the shape, not the name of the tool that runs a
+// shell command (Bash, Shell, run_command), not the key holding the command, not the
+// JSON the hook answers with. Every one of those differences lives in the renderer
+// beside the vendor page it was read from; the table only knows facts.
+//
+// The facts are deliberately few: the shell command an agent is about to run, and the
+// path it is about to write. A payload the renderer cannot recognise yields no facts,
+// and no fact is not a violation — guessing from a shape we did not read would block
+// real work in a harness whose payload changed under us.
+//
+// The messages are the bytes an author reads while being stopped, so each one names
+// the rule, the record that settled it, and the override that lifts it. An override
+// nobody is told about is a policy the author learns to route around instead of one
+// they can ask about.
+
+import { CLI } from '../name.mjs';
+
+/** The events an agent-time hook can answer, normalised across harnesses. */
+export const EVENTS = ['pre-tool-use'];
+
+/** The environment variable that lifts named policies for one session. */
+export const ALLOW_ENV = 'SIMT_ALLOW';
+
+/**
+ * One row per policy.
+ *
+ * `inspects` names the fact the matcher is handed, and `match` the condition. The
+ * `generated` row has no matcher because what it asks — does this file hold bytes this
+ * tool generates — is answered by reading the file, not by the text of a payload.
+ *
+ * Order matters where two policies match one command: `git push --force` is both a
+ * push and a rewrite, so both are reported and both have to be lifted before it runs.
+ */
+const POLICIES = [
+  {
+    id: 'push',
+    adr: 'ADR-001',
+    event: 'pre-tool-use',
+    inspects: 'command',
+    match: /(?:^|[\s;&|(])git\s+push(?:\s|$)/,
+    message: `Push needs explicit approval (ADR-001); ask the user.`,
+  },
+  {
+    id: 'rewrite',
+    adr: 'ADR-017',
+    event: 'pre-tool-use',
+    inspects: 'command',
+    match:
+      /--no-verify|git\s+commit\b[^;&|]*\s--amend|git\s+reset\s+--hard|git\s+rebase\b|git\s+push\b[^;&|]*(?:--force\b|\s-f\b)/,
+    message:
+      `Never amend, rebase, reset --hard, force-push or --no-verify unless asked; ` +
+      `each is the escape that turns the declared gates into a suggestion (ADR-017).`,
+  },
+  {
+    id: 'generated',
+    adr: 'ADR-036',
+    event: 'pre-tool-use',
+    inspects: 'write',
+    match: null,
+    message:
+      `That file carries bytes this tool generates, so an edit there is overwritten on the next ` +
+      `write; edit the source the region comes from, then run \`${CLI} sync --yes\` (ADR-036).`,
+  },
+];
+
+/** The policy ids, in table order: the vocabulary an override is checked against. */
+export const POLICY_IDS = POLICIES.map((p) => p.id);
+
+/** The rows for one event, so a renderer and the table cannot disagree about events. */
+export function policiesFor(event) {
+  return POLICIES.filter((p) => p.event === event);
+}