simt-dev 0.2.2 → 0.3.0

package/docs/decisions/ADR-079-the-rules-are-enforced-at-the-tool-call-from-one-policy-table.md

@@ -0,0 +1,162 @@
+# ADR-079 — The rules are enforced at the tool call, from one policy table every harness renders
+
+Status: **accepted** · 2026-10-16 · filed as R15 (plan 0003)
+
+Affects: `src/agenthooks/policy.mjs`, `src/agenthooks/decide.mjs`, `src/agenthooks/render.mjs`,
+`src/commands/agenthook.mjs`, `src/commands/index.mjs`, `src/commands/help.mjs`,
+`bin/simt-dev.mjs`, `test/agenthooks.test.mjs`
+
+## Context
+
+The rules this tool projects reach an agent as text, and text is advice. Three of them are
+broken by habit rather than by disagreement — a `git push`, a `--no-verify`, an edit inside a
+region that is regenerated — and the reader breaking one is an agent that never sees the
+commit that would have caught it. R15 turns those three into a decision at the tool call.
+
+Four harnesses document a pre-tool hook that receives JSON on stdin and answers with a
+decision (each page read 2026-10-16):
+
+| Reader | File | What it does with a decision |
+| --- | --- | --- |
+| Claude Code | `.claude/settings.json` | `hookSpecificOutput.permissionDecision: "deny"`, exit 2 also blocks |
+| Cursor | `.cursor/hooks.json` | `{"permission": "deny"}`; exit 2 blocks; a permission hook blocks on invalid JSON even when `failClosed` is false |
+| Codex | `.codex/hooks.json` | the same `hookSpecificOutput` shape as Claude Code, or the older `{"decision": "block"}` |
+| Antigravity | `.agents/hooks.json` | `{"decision": "deny", "reason"}`; the page documents no exit code |
+
+They agree on the mechanism and on nothing else. The path differs; Antigravity's file is keyed
+by a hook *name* rather than by event; the event is `PreToolUse` or `preToolUse`; the tool name
+for a shell call is `Bash`, `Shell`, `Bash` or `run_command`; the command sits in
+`tool_input.command` for three of them and in `toolCall.args.CommandLine` for the fourth; the
+write tool is `Edit`/`Write`, `apply_patch` (whose paths are inside the patch text),
+`Write`/`Edit`, and `write_to_file`/`replace_file_content`; and the decision document is four
+different shapes.
+
+The plan was written on 2026-10-06 and named `.gemini/settings.json`. The reader table R14
+shipped already carries the correction — the Antigravity page documents
+`<workspace>/.agents/hooks.json` — so this record follows the table and not the plan. The table
+is also the source of the four config paths here: a second list of the same paths is the copy
+ADR-035 exists to prevent.
+
+Measured on this machine (node v26, twenty runs each, every figure from a node parent that
+pays the same fork the harness pays): `node -e 0` costs **85.4 ms** at p50 and **91.9 ms** at
+p95, so the runtime's own start is 92% of the plan's budget before a line of this tool runs.
+Loading the reader table adds 2.8 ms at p50 and the region detector 4.9 ms; the whole hook
+path is **97.4 ms p50 / 101.6 ms p95**, down from 127.6 / 139.0 before `bin/` dispatched
+`agent-hook` without loading the registry.
+
+So the plan's criterion of a p95 under 100 ms is **not met end to end**, and a sample of
+twenty straddling the line is a claim about this machine rather than about the tool. What
+this slice owns is the part above the runtime, and that part is stated exactly: the decision
+is **0.0023 ms** at p95, and the entry point loads no manifest, no fingerprint, no workspace
+and no command registry — the two modules it takes from `src/projection/` (`markers.mjs` to
+ask whether a file already holds a region, `loaders.mjs` for the reader table's paths) are
+leaves that read nothing at import.
+
+## Rulings
+
+**1. One policy table, and one renderer per harness.** `policy.mjs` holds the rows and matches
+them against *facts* — a shell command string, and the files a write touches — so a policy never
+knows which harness asked. Each renderer owns one harness's payload-to-facts mapping, its
+configuration shape and its decision document. The table is data; the dialects are code.
+
+**2. Three policies ship: `push` (ADR-001), `rewrite` (ADR-017) and `generated` (ADR-036).**
+Each names the record it enforces and the override that lifts it, in the message the reader
+sees. `push` quotes the projected rule that cites ADR-001; `rewrite` cites the record whose
+own Context is the `--no-verify` spiral a broken gate teaches; `generated` cites the record
+that made the region note ("Do not edit by hand") ship into every consumer repository, and its
+message names the command that regenerates.
+
+**3. Every matching policy is reported, not the first.** `git push --force` matches two, and
+the denial carries both messages and both records. A first-match rule would let
+`SIMT_ALLOW=push` carry a force-push through on an override that never mentioned rewriting
+history, which is the one thing an override must not do.
+
+**4. `SIMT_ALLOW` lifts exactly the policies it names, and says so.** A lifted policy is
+reported as lifted, so a session that granted something can be read back out of its own output.
+A name that is not a policy is reported as unknown and changes no decision: a typo in an
+override must not silently disable a policy, and it must not block either.
+
+**5. Exit 2 means "block", and only a denial uses it.** A usage error — a missing `--harness`,
+an unknown event — exits 1. Every harness reads 2 as a refusal, so a configuration mistake that
+exited 2 would block every tool call in the session, which is a worse failure than the one the
+hook is there to prevent.
+
+**6. No facts is not a violation.** An unrecognised payload, an empty stdin or unparseable JSON
+produces no decision: exit 0, nothing on stdout. A hook that blocked on a payload it did not
+understand would turn every tool call into a wall, and the harness's own permission model still
+applies. This is the deliberate direction of the failure, and it is why the facts a policy
+needs are read from named fields rather than guessed.
+
+**7. A missing hook is a state; an unreadable config is a defect.** `agent-hooks status` exits 0
+when a harness has no entry and 1 when its config cannot be read, or parses to something that is
+not an object. A harness's settings file is the harness's file, kept for reasons that have
+nothing to do with this tool, so not being in it is a choice; a file this tool cannot parse is
+one it must not write into, in either surface.
+
+**8. `agent-hook` has no envelope of its own.** Its stdout is the dialect of the harness that
+called it — no `ok`, no `schemaVersion`. It is the one command whose contract is four
+documents instead of one, and the reason a JSON contract test does not enumerate it.
+
+**9. The entry point loads neither the registry nor anything that reads the repository.** `bin/simt-dev.mjs`
+dispatches the exact spelling the renderers write, and only that: `--help` still imports the
+registry, so help remains the single list of commands. Nothing above the decision resolves a
+manifest, fingerprints a tree or walks a workspace, because all three would put the cost of
+answering "what is this repository" on every tool call. The two modules the path does take
+from `src/projection/` are leaves that read nothing at import, and the test asserts the
+modules that would read the repository are absent from the import list rather than asserting
+a duration.
+
+**10. Install merges, and identifies its own entry by the command it wrote.** Every other key
+and every foreign handler survives; the entry is found by the command string, because JSON has
+no comment to carry a marker. A config this tool cannot parse is left alone and reported, and
+nothing else is written for that run.
+
+**11. The readers this tool does not write are named.** `agent-hooks status` and `install`
+report Copilot and the DeepSeek harness as "no hooks file is documented" and OpenCode as
+"not ours" (its hooks are plugins), with the table's own note. A command that writes four files
+and stays silent about the fifth reader in the repository reads as "that one is covered too".
+
+## Consequences
+
+**What has not landed.** Three policies the plan lists are not here: formatting and linting a
+file after an edit, refusing reads of secrets (`.env*`, `*.pem`, `*.keystore`), and the Stop
+policy that blocks once when code changed with no ledger entry for the tree — the last waits on
+R17, the evidence ledger. Plan section 16 step 5 scopes this slice to exactly the three that
+shipped. A policy that cannot name its evidence cannot name its remedy, which is why the
+ledger one waits.
+
+**The acceptance criterion's headless run has not been run, and cannot be from here.** R15's
+accept says a headless Claude Code session on probe R05 shows the block. The probes and their
+graders exist and the decision was verified per harness against fixtures; the run itself needs
+a harness, and none is installed on this machine (`claude`, `codex`, `cursor-agent`, `gemini`
+and `aider` are all absent from `PATH`, which is the check that says so rather than a memory of
+one). So this record does not claim it, and the plan's note for the row names it as the one
+piece of R15's accept that is outstanding.
+
+**One field was inferred rather than read.** Cursor's page was read to line 1087 of 1490, which
+does not include its write tool's input key, so its adapter reads `file_path ?? path`. If Cursor
+names it otherwise, a generated-region edit through that harness is not caught — the failure is
+silent, which is why it is written down here rather than left in a comment.
+
+**Codex's trust step is printed, not performed.** Codex records trust against the hook's current
+hash, so a hook nobody has trusted stays inert: `install` names the `/hooks` review and
+`status` repeats it. Nothing this tool can do from a shell substitutes for it.
+
+**The hook name Antigravity keys on is `simt-dev-policies`.** Antigravity's file is a map of
+named hooks, so the entry needs a name; the project name is the one string already exempt from
+the estate-name guard.
+
+## Rejected
+
+- **One shared config written for every harness.** They disagree on the path, the top-level
+  shape, the event name, the matcher, the tool name, the command field, the write tool and the
+  decision document. A shared file would be a fifth dialect none of them reads.
+- **Blocking on a payload the hook did not understand.** Fail-closed is the dispatcher's rule for
+  a gate it was asked to run; it is the wrong rule for a hook that runs on every tool call.
+- **Exit 2 for a usage error.** It means "block" to every harness.
+- **A `stop` policy that blocks without a ledger.** The evidence it would need is R17's.
+- **An `ok`/`schemaVersion` envelope on `agent-hook`.** The harness parses its own dialect.
+- **Reading the manifest for the policy decision.** The rules are the tool's, not the
+  repository's gates; a hook that required adoption would not run in a repository that has not
+  been adopted, which is where the rules matter most.
+- **Guessing a payload shape it cannot recognise.** See ruling 6.

package/docs/decisions/ADR-080-the-tools-own-names-are-not-repositories-and-neither-reader-decides-by-shape.md

@@ -0,0 +1,99 @@
+# ADR-080 — The tool's own names are not repositories, and neither reader decides by shape
+
+Status: **accepted** · 2026-10-16 · settles what `rules why` calls a repository
+
+## Context
+
+`ESTATE_NAME` matched `simt-<anything>` that was not `simt-dev`, on the reasoning that
+every other name sharing the prefix is a repository in the estate these records were
+written in. The reasoning is sound about the estate and false about this tool, which
+prints its own prefixed names in its own records: `simt-priority`, `simt-applies`,
+`simt-inferable-when`, `simt-hooks`.
+
+Measured over the corpus before anything changed, 21 of the 33 records that named
+anything named a name of ours, across 9 records; 7 of those named nothing else:
+
+```
+ADR-018  simt-hooks              ADR-047  simt-applies
+ADR-022  simt-alwaysApply, simt-applies, simt-fallback, simt-gates, simt-id,
+         simt-key, simt-opt-in, simt-owned, simt-substitutions, simt-target, simt-title
+ADR-026  simt-package-ecosystem  ADR-056  simt-hooks
+ADR-040  simt-hooks              ADR-062  simt-applies
+ADR-073  simt-priority           ADR-078  simt-inferable-when, simt-priority
+```
+
+Two harms, and the second is the one that matters. `writtenAgainst` listed them under a
+heading that says the record was written against those repositories, which is a false
+claim about evidence — the one thing a decision record is for. Worse, `redactEstate`
+replaced them in the prose, so a reader opening a record through `rules why` read
+`` `a repository: hard | command | convention | style` `` where the record says
+`simt-priority: hard | command | convention | style`. The command whose whole job is to
+explain a citation printed a sentence with no subject.
+
+The answer was already in this repository and in the wrong half of it: the shipped-text
+guard derived `TOOL_OWN_WORDS` from `mdc.mjs` and `rules.mjs`, exactly to avoid calling
+`simt-priority` a repository. The reader of the same corpus did not, so the guard passed
+while the command that ships the corpus misdescribed it. ADR-079's own record is the third
+instance of the shape: `simt-inferable-when` was reported as a surveyed repository.
+
+## Rulings
+
+**1. The tool's own prefixed names live in `src/toolwords.mjs`, derived from the modules
+that own them.** `KNOWN_KEYS` from `mdc.mjs`, `PROFILE_KEYS` from `rules.mjs`, the
+inferability marker from `kernel/inferability.mjs`, and the three names this tool writes
+on disk (`simt-dev`, `simt-dev-check`, `simt-hooks`). Derived, not listed (ADR-022): a
+second copy of a vocabulary is a copy that drifts and then forgives.
+
+**2. Both readers read that one list.** The decision reader and the shipped-text guard
+answer the same question — is this a repository or a name of ours? — and answering it
+twice is how the two answers came apart. `test/shipped.test.mjs` now imports
+`TOOL_WORDS` instead of deriving its own.
+
+**3. A record whose subject is the prefix names no repository.** `PREFIX_ARGUING` maps
+two files (ADR-022, ADR-026) to the reason each spells the prefix, and both readers use
+it. A vocabulary cannot settle these: a hypothetical key in an argument and a repository
+name are the same shape. The guard's staleness test is unchanged — an exemption that
+stops being needed still fails.
+
+**4. Redaction keeps the tool's names and replaces the estate's.**
+`redactEstate('simt-priority')` is `simt-priority`; `redactEstate` of an estate-shaped
+name is `a repository`. The rule is about what the reader cannot act on, and a key of the
+tool they are running is not that.
+
+**5. Detection stays shape-based and strict.** `test/leaks.mjs` keeps `ESTATE_NAME` and
+does not consult the vocabulary. Detection may be stricter than rendering without harm: a
+word of ours that a surface never should have shipped still fails, and ADR-080 adds no
+false negative. This asymmetry is deliberate and is the reason the list did not become a
+filter inside the pattern.
+
+**6. `writtenAgainst` still names the estate.** 26 of 80 records list `repo-NN` labels and
+keep listing them, every label one of those; the field's purpose is unchanged and the
+reader still learns which parts of a record are not about them.
+
+## Consequences
+
+- 21 misdescribed reads are gone and no record names a name of ours; `simt rules why ADR-073 --json` reports
+  `writtenAgainst: []` and the record is served with `simt-priority` intact.
+- `src/toolwords.mjs` imports `mdc.mjs`, `rules.mjs` and `kernel/inferability.mjs`, so the
+  decision reader loads the projection stack. `rules why` is interactive and pays ~5 ms;
+  no import in that chain has import-time side effects, which is what makes it safe to add
+  to a module the MCP server also loads.
+- The guard gained an import and lost a derivation. Its own comment about where the
+  vocabulary comes from is now in `src/`, next to what it describes.
+- An estate repository whose name does not begin `simt-` is still undetectable, as
+  `ESTATE_NAME` says, and this record does not change that.
+
+## Rejected
+
+- **Keeping the shape and documenting the exception.** The defect was not the pattern's
+  comment; it was that the pattern was the only definition.
+- **Exempting the words instead of the records.** ADR-022's `simt-gates` and a repository
+  sharing that shape are indistinguishable, so a word list would either over-exempt a
+  repository or under-exempt the argument.
+- **A second list inside `src/decisions/index.mjs`.** The guard already had one, and the
+  two drifting apart is the defect this record is about.
+- **Filtering inside `ESTATE_NAME` itself with a lookahead built from the vocabulary.**
+  Detection and rendering want different answers on purpose (ruling 5), and a shared
+  pattern would have silently coupled them.
+- **Renaming `writtenAgainst` to something vaguer.** The field is right; the shape it
+  matched was wrong.

package/docs/decisions/ADR-081-a-tracker-is-read-through-the-repositorys-template.md

@@ -0,0 +1,36 @@
+# ADR-081 — A tracker is read through the repository's template
+
+Status: **accepted** · 2026-10-16 · rulings 1 and 2 superseded by ADR-082
+
+## Context
+
+`plan next` has to open the directory a repository actually keeps its plans in, and it has to
+recognise the columns that repository actually writes. Both were fixed: `docs/plans`,
+`docs/reviews`, a column named State, and the word `review` in a dependency. That is this
+package's own layout. A reader whose plans live somewhere else, or whose tracker says Done
+in a column named Progress, would be told they had no plan.
+
+The selection cannot live in the manifest. `init` rewrites that file from the fields it owns,
+and a repository that has not adopted the tool has no manifest. A plan template has to work
+in both, and it has to survive a re-init.
+
+## Rulings
+
+1. **The format is a template, and the one delivered with the tool is named simt-dev.** It
+   reads `docs/plans` and `docs/reviews`, binds columns by the headers it lists, and treats
+   `done` as complete. A repository that writes nothing gets that template.
+2. **A repository replaces it with `simt-plan.json` at its root.** The file overlays the
+   delivered template: a section it names replaces that section, and a section it omits stays.
+   Directories, column headers, state words, which of those words unblocks a dependency, and
+   the words a dependency uses to name another document are all in that file.
+3. **A template that cannot be read is an error.** Falling back to the delivered template
+   would index the wrong directories and could mark the wrong row done. A directory path has
+   to stay inside the repository.
+4. **`plan done` still previews unless `--yes`.** The template decides which word is written
+   for the completed state. It does not decide that a row may change unseen.
+
+## Consequences
+
+- `simt plan status` names the template and the directories it read.
+- Changing the delivered template changes what every repository without `simt-plan.json` is
+  indexed as. The file is the format; the parser does not keep a second copy of the headers.

package/docs/decisions/ADR-082-the-tracker-override-is-a-manifest-key.md

@@ -0,0 +1,35 @@
+# ADR-082 — The tracker override is a manifest key, and init keeps what it did not write
+
+Status: **accepted** · 2026-10-16 · supersedes ADR-081 rulings 1 and 2
+
+## Context
+
+ADR-081 put the tracker format in a file named for this package, and put a repository's
+override in a second file at the root. The name collided with the package and with the
+manifest's old filename. The second file existed because `init` rebuilt the manifest from
+the keys it knew and dropped the rest, so a `plans` key would not have survived a re-init.
+
+A repository that has adopted already has one config file. A second one, present only when
+the tracker differs from the delivered format, is a file most readers will not know to open.
+
+## Rulings
+
+1. **The delivered template is named `tracker`.** It is `templates/plan/tracker.json`. It
+   reads `docs/plans` and `docs/reviews`. A repository that sets nothing gets that template.
+2. **A repository overrides it with the `plans` key of its manifest.** The key overlays the
+   delivered template. A section it names replaces that section, and a section it omits
+   stays. The manifest's own comment says so, because that comment is the text a reader of
+   the file sees.
+3. **`init` keeps every key it does not write.** Owned keys still refresh, in the order the
+   writer emits them. A key absent from that object is copied after them, in the order the
+   file had those keys. That is what makes ruling 2 survivable: a re-init no longer deletes
+   `plans`, or any other key a repository added.
+
+## Consequences
+
+- `simt plan` reads `plans` from `simt.json`, and from `simt-dev.json` while that name is
+  still the manifest on disk.
+- A manifest written by `init` carries the explanation of `plans` in its comment. The
+  comment is generated, so the next `init` or `sync` refreshes it.
+- ADR-081 rulings 3 and 4 stand: a template that cannot be read is an error, and `plan done`
+  still previews unless `--yes`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "simt-dev",
-  "version": "0.2.2",
+  "version": "0.3.0",
   "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/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);
+}