simt-dev 0.6.2 → 0.6.3

package/docs/decisions/ADR-104-the-pre-tool-use-policy-reads-the-command-the-way-a-shell-reads-it.md

@@ -0,0 +1,76 @@
+---
+simt-affects: ["src/agenthooks/shell.mjs", "src/agenthooks/policy.mjs", "src/agenthooks/decide.mjs"]
+simt-supersedes: []
+---
+
+# ADR-104 — the pre-tool-use policy reads the command the way a shell reads it
+
+Status: **accepted** · 2026-10-28
+
+## Context
+
+The two command policies — push (ADR-001) and rewrite (ADR-017) — matched the
+payload's command string with a regular expression. Review 0003 (Q01) verified
+against the shipped binary that an agent routes around both of them: `git -C .
+push`, `git --no-pager push`, `sh -c 'git push'`, `$(git push)`, `(git push)`,
+`git push;echo ok`, the alias `git p`, `git send-pack`, `git commit -n`,
+`--amen`, `--no-verif`, `git reset --har`, `git -C . commit --amend`,
+`git pull --rebase`, and with `SIMT_ALLOW=push`, `git push -fu` and
+`git push origin +main`. Three acts no policy named at all: `git -c
+core.hooksPath=/dev/null commit`, `git config core.hooksPath …` and
+`rm -rf .simt-hooks` — the repository's gates going away without a policy ever
+seeing them. And two false positives: `echo --no-verify` and `grep -r "git
+rebase" docs` were denied because a flag or a phrase sat in a command that was
+not git.
+
+Every bypass is the same act spelled another way, and a policy that reads text
+cannot tell them apart. The decision is made on the act.
+
+## Ruling
+
+1. **The command is normalised before a policy matches it.**
+   `src/agenthooks/shell.mjs` tokenises the command the way POSIX sh tokenises
+   it — quotes, escapes, `; && || | &`, newlines, subshells, `$()` and
+   backticks — descends into the wrappers a shell executes for you (`sh|bash|
+   zsh|dash -c`, `eval`, `env`, `command`, `exec`, `xargs`, `nice`, `time`,
+   `sudo`), and reduces every git invocation to the fact a policy can read:
+   which subcommand, with which options, in which repository. Long options are
+   resolved by git's unique-prefix rule (`--amen` is `--amend`), short clusters
+   are expanded (`-fu` is `-f -u`), and a leading `+` on a refspec is force.
+   The policies match that fact, not the text.
+2. **A command the tokenizer cannot read is judged by the row's regex, never by
+   nothing.** Unbalanced quotes and an unclosed `$()` mark the command as
+   unparseable, and the pre-normaliser regex runs on it, so a parse failure
+   weakens nothing. Facts that were never normalised — a test that hands
+   `decide` a bare command string — take the same path. The push and rewrite
+   ids and messages are unchanged, so an adopted repository reads the same
+   denial it read before.
+3. **A third command policy, `hooks-disable`, names the act the other two
+   cannot:** removing or rerouting the git hooks a repository's gates run in —
+   `git -c core.hooksPath=…`, `git config … core.hooksPath`, and `rm` of the
+   hooks directory. It carries no regex fallback because it did not exist
+   before this ruling: a command that cannot be tokenised is judged exactly as
+   it was judged before the row was written.
+4. **The author's aliases are resolved with one `git config --get-regexp
+   '^alias\.'` per command, and only when a fact's subcommand is not one git
+   ships.** A value that starts with `!` is a shell command and is read the
+   way any other command string is; an alias that resolves to nothing the
+   table can read is left as-is, which is the same position the pre-lookup
+   policy found it in. A git that is missing or cannot answer yields no
+   aliases, and the facts stand where the pre-lookup policy would have left
+   them.
+
+## Consequences
+
+- The false positives go with the text: `echo --no-verify` and `grep -r "git
+  rebase" docs` carry no git fact, so the rewrite policy does not fire on
+  them.
+- Every force spelling — `--force`, `-f` in a cluster, `+refspec` — is both a
+  push and a rewrite, so lifting `push` no longer carries a force-push
+  through, in any of the spellings the regex let past.
+- The decision stays pure and fast: normalisation is a fact-gathering step in
+  `factsFor`, and `decide` reads facts. The latency test, which measures
+  `decide` over prebuilt facts, is unchanged.
+- A command that names only builtin subcommands pays nothing for the lookup;
+  one that names an alias pays a single `git config` spawn with a one-second
+  ceiling.

package/docs/decisions/ADR-105-the-json-ceiling-shrinks-arrays-and-never-cuts-bytes.md

@@ -0,0 +1,44 @@
+---
+simt-affects: ["src/output/index.mjs"]
+simt-supersedes: []
+---
+
+# ADR-105 — the JSON ceiling shrinks arrays and never cuts bytes
+
+Status: **accepted** · 2026-10-29 · filed as review 0003 Q10
+
+## Context
+
+ADR-070 ruling 5 gave `emitJson` the byte ceiling: a document over `--max-bytes`
+was cut at the byte count with a `TRUNCATED` line after it, the same announcement
+the text renderer prints. Compact JSON has no newlines, so the cut landed
+mid-token and the command exited 0: `why --json --max-bytes 120` answered with a
+document no parser accepts and a status that called it a success.
+
+## Ruling
+
+1. **JSON is never byte-truncated.** `emitJson` shrinks the payload to fit: the
+   longest arrays empty first, and the document carries
+   `truncated: { field, omitted, limit }` (or `fields: [{ field, omitted }]`
+   when several lists shrank) naming exactly which list lost how many items.
+2. **A ceiling no trimming can fit is a `MAX_BYTES` error envelope, not a cut.**
+   `{ ok: false, error: { code: 'MAX_BYTES', message, remedy } }` with
+   `truncated: { omitted, limit }`, still one parseable document. The remedy
+   reads `rerun with --max-bytes 0 for the whole document` — the same ceiling
+   the text renderer names, in the same words.
+3. **The text ceiling is unchanged.** `emit` still cuts lines and announces the
+   omitted bytes; prose has line boundaries worth cutting at, JSON does not.
+
+## Consequences
+
+- Every `--json --max-bytes` answer parses, trimmed or enveloped. A reader can
+  trust that a document on stdout is the whole answer when no `truncated` key
+  rides with it.
+- `truncated` is additive: readers that ignore unknown fields see today's shape
+  with shorter lists, so no schema bump.
+
+## Rejected
+
+- **Cutting at a newline for JSON too.** Compact output has none and pretty
+  output's newlines are indentation, not item boundaries; either cut still
+  breaks the parse the caller was promised.

package/docs/decisions/README.md

@@ -68,6 +68,50 @@ record's status line — never by editing the ruling in place.
 | [058](ADR-058-one-tool-three-channels-and-the-order-is-forced.md) | One tool, three channels, and the order is forced | accepted |
 | [059](ADR-059-the-version-a-repository-runs-is-the-one-it-pinned.md) | The version a repository runs is the one it pinned, and the gate refuses otherwise | accepted |
 | [060](ADR-060-a-repository-with-nothing-to-run-is-adopted-and-says-so.md) | A repository with nothing to run is adopted and says so; a gate is verified where it runs | accepted |
+| [061](ADR-061-the-skill-registry-is-workspace-data.md) | The skill registry is workspace data, and the package ships none of it | **accepted** · 2026-10-12 · filed as S61 |
+| [062](ADR-062-a-fresh-adoption-seeds-the-gates-it-can-run.md) | A fresh adoption seeds the canonical gates it can run, and never more | **accepted** · 2026-10-13 · filed as S40 |
+| [063](ADR-063-the-adoption-escape-hatch-is-opt-in.md) | The adoption escape hatch is opt-in, and the default writes in place | **accepted** · 2026-10-13 · filed after a consumer asked why every adoption branched |
+| [064](ADR-064-the-context-meter-counts-what-the-tool-wrote.md) | The context meter counts what the tool wrote, and says what it did not | **accepted** · 2026-10-13 · filed after review 0002 S38 |
+| [065](ADR-065-a-pack-is-one-shared-rule-set-pinned-by-digest.md) | A pack is one shared rule set, vendored into the repository and pinned by digest | **accepted** · 2026-10-13 · filed as S39 |
+| [066](ADR-066-a-monorepo-projects-once-per-package.md) | A monorepo projects once per package | **accepted** · 2026-10-13 · filed as S41 |
+| [067](ADR-067-which-harnesses-read-agents-md-is-a-column.md) | Which harnesses read AGENTS.md is a column, and a row without a document gets none | **accepted** · 2026-10-13 · filed as S42 |
+| [068](ADR-068-the-mcp-revision-list-cites-what-was-read.md) | The revision list is a claim about revisions that were read | **accepted** · 2026-10-13 · filed as S43 |
+| [069](ADR-069-the-conformance-lint-checks-the-published-specification.md) | The conformance lint checks the published specification | **accepted** · 2026-10-13 · filed as S44 |
+| [070](ADR-070-the-json-payload-carries-its-own-version.md) | The JSON payload carries its own version | **accepted** · 2026-10-13 · filed as S51 |
+| [071](ADR-071-a-rule-that-can-be-narrowed-is-written-narrow.md) | A rule that can be narrowed is written narrow | **accepted** · 2026-10-14 · filed as S50 |
+| [072](ADR-072-the-budget-is-a-declaration-beside-the-gates.md) | The budget is a declaration beside the gates, not a number inside the projection | **accepted** · 2026-10-14 · filed as S38 |
+| [073](ADR-073-a-kernel-is-a-smaller-projection-the-repository-asks-for.md) | A kernel is a smaller projection the repository asks for, not one it is given | **accepted** · 2026-10-14 · filed as S38 (R07) · ruling 6 narrowed by ADR-084 |
+| [074](ADR-074-a-rule-and-a-decision-are-readable-by-uri.md) | A rule and a decision are addressable, so they are readable by URI | **accepted** · 2026-10-14 · filed as S43 |
+| [075](ADR-075-nothing-leaves-the-machine.md) | Nothing leaves the machine: no telemetry, local transcripts, loopback models by default | **accepted** · 2026-10-14 · filed as D7 (R06) |
+| [076](ADR-076-a-change-to-what-agents-read-is-measured.md) | A change to what agents read is measured before it ships, or labelled unmeasured in its record | **accepted** · 2026-10-15 · filed as D1 (R01) |
+| [077](ADR-077-the-command-card-leads-the-region-and-reads-committed-evidence.md) | The command card leads the region, and is derived from committed evidence only | **accepted** · 2026-10-16 · filed as R10 (plan 0003) · ruling 1 narrowed by ADR-086 |
+| [078](ADR-078-a-line-the-repository-already-proves-does-not-ship.md) | A line the repository already proves does not ship, and the author says so | **accepted** · 2026-10-16 · filed as R09 (plan 0003) |
+| [079](ADR-079-the-rules-are-enforced-at-the-tool-call-from-one-policy-table.md) | The rules are enforced at the tool call, from one policy table every harness renders | **accepted** · 2026-10-16 · filed as R15 (plan 0003) |
+| [080](ADR-080-the-tools-own-names-are-not-repositories-and-neither-reader-decides-by-shape.md) | The tool's own names are not repositories, and neither reader decides by shape | **accepted** · 2026-10-16 · settles what `rules why` calls a repository |
+| [081](ADR-081-a-tracker-is-read-through-the-repositorys-template.md) | A tracker is read through the repository's template | **accepted** · 2026-10-16 · rulings 1 and 2 superseded by ADR-082 |
+| [082](ADR-082-the-tracker-override-is-a-manifest-key.md) | The tracker override is a manifest key, and init keeps what it did not write | **accepted** · 2026-10-16 · supersedes ADR-081 rulings 1 and 2 |
+| [083](ADR-083-a-budget-is-met-by-cutting-the-kernel-and-hard-is-the-floor.md) | A budget is met by cutting the kernel, and the hard constraints are the floor | **accepted** · 2026-10-17 · filed as R08 (plan 0003) · ruling 7 narrowed by ADR-084 |
+| [084](ADR-084-a-workspace-carries-its-repeated-rules-once.md) | A workspace carries its repeated rules once, and the region does not read the reader's home | **accepted** · 2026-10-17 · filed as R11 (plan 0003) |
+| [085](ADR-085-the-region-ends-with-the-names-it-kept-out.md) | The region ends with the names of what it kept out | **accepted** · 2026-10-18 · filed as R12 (plan 0003) |
+| [086](ADR-086-the-stable-prefix-comes-first-and-the-lock-records-both-digests.md) | The stable prefix comes first, and the lock records both digests | **accepted** · 2026-10-18 · filed as R13 (plan 0003) |
+| [087](ADR-087-a-run-is-evidence-for-one-tree.md) | A run is evidence for one tree | **accepted** · 2026-10-18 · filed as R17 (plan 0003) |
+| [088](ADR-088-a-marked-line-is-enforced-by-a-checker.md) | A marked line is enforced by a checker | **accepted** · 2026-10-18 · filed as R19 (plan 0003) · ruling 3 narrowed by ADR-090 |
+| [089](ADR-089-the-local-index-is-a-cache-of-git-blobs.md) | The local index is a cache of git blobs | **accepted** · 2026-10-18 · filed as R20 (plan 0003) |
+| [090](ADR-090-an-optional-adapter-is-off-until-named.md) | An optional adapter is off until a repository names it | **accepted** · 2026-10-18 · filed as R21 (plan 0003) |
+| [091](ADR-091-the-map-ranks-files-a-task-mentions.md) | The map ranks the files a task mentions, and the files next to them | **accepted** · 2026-10-18 · filed as R22 (plan 0003) |
+| [092](ADR-092-tests-are-imports-conventions-and-coverage.md) | A test is an import, a conventional neighbour, or a coverage record | **accepted** · 2026-10-18 · filed as R24 (plan 0003) |
+| [093](ADR-093-why-names-what-governs-a-file.md) | why names what governs a file | **accepted** · 2026-10-18 · filed as R25 (plan 0003) |
+| [094](ADR-094-a-change-runs-the-tests-that-import-it.md) | a change runs the tests that import it | **accepted** · 2026-10-18 · filed as R16 (plan 0003) |
+| [095](ADR-095-gate-output-keeps-the-failures.md) | gate output keeps the failures | **accepted** · 2026-10-18 · filed as R18 (plan 0003) |
+| [096](ADR-096-impact-names-who-a-change-reaches.md) | impact names who a change reaches | **accepted** · 2026-10-18 · filed as R23 (plan 0003) |
+| [097](ADR-097-the-channels-publish-by-hand-and-the-version-rides-in-as-an-input.md) | the channels publish by hand, and the version rides in as an input | **accepted** · 2026-10-25 · ruling 3's Homebrew precondition is superseded by [ADR-098](ADR-098-the-fourth-channel-is-one-file-and-it-needs-no-toolchain.md), which also restates what each channel now waits on |
+| [098](ADR-098-the-fourth-channel-is-one-file-and-it-needs-no-toolchain.md) | The fourth channel is one file, and it needs no toolchain | **accepted** · 2026-10-26 · supersedes ADR-058 ruling 5 · narrows ADR-058 ruling 7 and ADR-097 ruling 3 · supersedes ADR-059 ruling 3 · ruling 3's cross-host byte-identicality narrowed by [ADR-099](ADR-099-the-release-verifies-served-bytes-and-the-formula-mirrors-them.md) |
+| [099](ADR-099-the-release-verifies-served-bytes-and-the-formula-mirrors-them.md) | the release verifies served bytes, and the formula mirrors them | **accepted** · 2026-10-27 · narrows ADR-098 ruling 3 |
+| [100](ADR-100-a-staged-diff-is-the-last-gate-before-history-and-it-runs-inside-the-tool.md) | a staged diff is the last gate before history, and it runs inside the tool | **accepted** · 2026-10-27 |
+| [101](ADR-101-a-file-lease-belongs-to-one-session-and-the-pre-edit-hook-refuses-another.md) | a file lease belongs to one session, and the pre-edit hook refuses another's edit | **accepted** · 2026-10-28 |
+| [102](ADR-102-the-two-queued-review-rows-are-closed-by-ruling.md) | the two rows review 0002 left queued are closed by ruling, not by authoring | **accepted** · 2026-10-28 |
+| [103](ADR-103-co-projected-duplicates-merge-down.md) | duplicates stand alone, fingerprints generalize, references spell out | **accepted** · 2026-10-28 |
+| [104](ADR-104-the-pre-tool-use-policy-reads-the-command-the-way-a-shell-reads-it.md) | the pre-tool-use policy reads the command the way a shell reads it | **accepted** · 2026-10-28 |
 
 ADR-001 to ADR-010 resolve the contradictions found across the 16 repos in the 2026-10-05
 audit; each record names the repos whose text it replaces. ADR-011 and ADR-012 are the

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "simt-dev",
-  "version": "0.6.2",
+  "version": "0.6.3",
   "description": "An intelligence amplifier for AI coding agents: rules and dual gates adopted by one command, plus local retrieval, task briefs, benches and repo memory — deterministic by default, with local-model adapters that propose and never select.",
   "license": "Apache-2.0",
   "author": "Said Elimam",

package/rules/mdc/preview-postflight.mdc

@@ -27,18 +27,17 @@ simt-substitutions:
   # neither, declares that. A worker that serves derivatives and calls no API has no
   # API base URL to set, so it declares only its own custom-domain binding.
   - key: previewApiBaseUrlNote
-    default: "- Point the preview build at the preview API Worker: set `SOCIAL_API_BASE_URL` in the Cloudflare Workers Builds preview environment to the preview API Worker URL."
+    default: "- Point the preview build at the preview API: set the preview environment's API base URL to the preview API URL."
     describe: build-config instruction, when this repo actually has a preview API base URL to set
   - key: googleOnlyNote
-    default: "- Production and public browser flows remain Google-only."
+    default: "- Production and public browser flows use the production identity only."
     describe: the identity policy this repo enforces in production
 ---
 
 # Preview-Only Authenticated Postflight
 
 Authenticated remote postflight and release checks use only {{previewWorkers}}, deployed
-with `AUTH_PROVIDER_POLICY=preview_postflight_password` and a secret-bound Firebase password
-identity (`POSTFLIGHT_PASSWORD_UID`).
+with a preview-only auth provider policy and a secret-bound password identity.
 
 ## Requirements
 
@@ -52,8 +51,8 @@ identity (`POSTFLIGHT_PASSWORD_UID`).
 ## Forbidden
 
 - Authenticated postflight against production domains ({{productionDomains}}).
-- Using real Social Google accounts for feature slice verification.
-- Demanding, pasting, or storing production Google OAuth tokens in chat or tickets.
+- Using real user accounts for feature slice verification.
+- Demanding, pasting, or storing production OAuth tokens in chat or tickets.
 
 ## Allowed Without Account
 

package/rules/stacks/android.md

@@ -27,17 +27,17 @@ this profile; see `jvm`.
 
 ## Modules and layers
 
-- `:core:domain` depends on no other internal module. Enforce it; do not add an
+- The core domain module depends on no other internal module. Enforce it; do not add an
   import that breaks the direction.
 - Layer suffixes: `*Repository`, `*ViewModel`, `*UiState`, `*Screen`, `*Service`.
-- Feature modules never import `androidx.compose.ui.window.Dialog`, M3 `AlertDialog`
-  or M3 `ModalBottomSheet`. The raw `Dialog` window belongs to allowlisted `core:ui`
-  surfaces, and `checkOverlayModalPolicy` fails `./gradlew check` when a feature
-  bypasses it.
+- Feature modules never present a raw `Dialog` window (`androidx.compose.ui.window.Dialog`,
+  M3 `AlertDialog`, M3 `ModalBottomSheet`) that bypasses the shared modal policy.
+  Modals go through the design system's dialog surfaces, and the repo's check fails
+  the build on a bypass.
 
 ## Accessibility
 
-- Every user-facing string is a resource, with a `cd_` content description where an
+- Every user-facing string is a resource, with a content description where an
   icon or image carries meaning. Decorative images declare `contentDescription = null`
   explicitly.
 - Touch targets meet the platform minimum, and the minimum is asserted rather than
@@ -61,5 +61,4 @@ this profile; see `jvm`.
 
 - Unit tests for view models, repositories and mappers; instrumentation tests for UI.
 - `Dispatchers.setMain` in a `@BeforeTest`, restored in `@AfterTest`.
-- Assert behaviour, not implementation. Never weaken an assertion, an accessibility
-  check or a fixture to match current behaviour.
+- Assert behaviour, not implementation — including accessibility checks and fixtures. Never weaken one to match current behaviour.

package/rules/stacks/cloudflare-workers.md

@@ -41,7 +41,7 @@ Applies to: `cloudflare-workers` — a `wrangler.json`, `wrangler.jsonc` or
 - Validate at the edge with the schema layer. Authorization is server-authoritative; a
   client-side role, claim, cache entry or URL parameter grants nothing.
 - `Request`/`Response` are globals. Do not pass them through as values into domain code.
-- Caching defaults to `private, no-store`. Never cache token, account, block, reveal, admin
+- Caching defaults to `private, no-store`. Never cache tokens, account data, admin
   decisions or authenticated errors.
 - Streaming is the default for large bodies; do not buffer without a stated reason.
 

package/rules/stacks/container.md

@@ -7,6 +7,8 @@ simt-scope: ["Dockerfile", "*.dockerfile"]
 simt-fallback: false
 ---
 
+# Stack profile: Containers
+
 ## Containers
 
 A Dockerfile is the build. If a rule here and the repo's own instructions disagree, the

package/rules/stacks/jvm.md

@@ -26,7 +26,7 @@ rules live in the `android` profile, which selects on `has-android-manifest`.
 
 ## Modules and layers
 
-- `:core:domain` depends on no other internal module. Enforce it; do not add an
+- The core domain module depends on no other internal module. Enforce it; do not add an
   import that breaks the direction.
 - Layer suffixes: `*Repository`, `*Service`, `*Mapper`, `*Controller`. A class named
   `*Repository` that talks to HTTP is not a repository.

package/rules/stacks/react-native.md

@@ -10,11 +10,9 @@ simt-priority: convention
 simt-scope: ["app.json", "metro.config.js", "ios/**", "android/**"]
 ---
 
-# Stack profile: React Native
-
-Applies to: `react-native` — a `react-native` or `expo` dependency. A repository whose
-UI is rendered in a browser gets the `react-web` profile instead; see that profile for
-the rules this one does not repeat.
+# Stack profile: React NativeApplies to: `react-native` — a `react-native` or `expo` dependency. A repository whose
+UI is rendered in a browser follows the browser rules instead; nothing here assumes a
+DOM, a stylesheet cascade, or URL-shared state.
 
 ## What does not apply here
 

package/rules/stacks/react-web.md

@@ -17,8 +17,10 @@ UI is rendered in a browser.
 
 ## Types
 
-- `strict` plus the full strictness set listed in the Workers profile. Generated API DTOs only;
-  never hand-write a duplicate of a type the API already produces.
+- `strict` plus `noUncheckedIndexedAccess`, `exactOptionalPropertyTypes`,
+  `noImplicitOverride`, `noFallthroughCasesInSwitch`, `noImplicitReturns`,
+  `isolatedModules`. Generated API DTOs only; never hand-write a duplicate of a
+  type the API already produces.
 - No `any`, no unsafe casts, no non-null boundary bypasses, no floating promises, no
   `console.*`.
 
@@ -39,10 +41,9 @@ UI is rendered in a browser.
 
 ## RTL and localisation
 
-- Arabic mirrors application chrome only. North, coordinate order, geographic pan and zoom,
-  map symbols, media and universal status meaning do not mirror.
-- Every user-visible string exists in every supported locale in the same change. Adding a
-  locale touches tests, which assert locale parity.
+- RTL locales mirror application chrome only. North, coordinate order, geographic pan and
+  zoom, map symbols, media and universal status meaning do not mirror.
+- Every user-visible string exists in every supported locale in the same change.
 
 ## Accessibility
 
@@ -58,6 +59,5 @@ UI is rendered in a browser.
 - Assert behaviour, not implementation. Never weaken an assertion, an accessibility check or a
   fixture to match current behaviour.
 - No arbitrary sleeps. No `.only`. No committed `.skip`. No flaky reruns.
-- Inject a sentinel token, UID, text, gender, coordinate, URL and private media value, and
-  prove its absence from unauthorised UI, storage, cache, telemetry, URL history and
-  artifacts.
+- Inject sentinel values (a token, an id, a coordinate, a URL) and prove their absence
+  from unauthorised UI, storage, cache, telemetry, URL history and artifacts.

package/src/agenthooks/decide.mjs

@@ -2,9 +2,9 @@
 //
 // 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.
+// consulted in `factsFor` for exactly the facts a payload cannot carry — whether a
+// file holds bytes this tool generates, who has leased it (ADR-101), and what the
+// author's git aliases expand to (ADR-104) — and nothing else decides from disk.
 //
 // Two properties are deliberate and both are about an author standing still:
 //
@@ -19,11 +19,14 @@
 // understand this" into "blocked" makes the hook a false-positive machine, and a hook
 // that blocks real work is uninstalled the same afternoon.
 
+import { spawnSync } from 'node:child_process';
 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';
+import { activeLeases, leasePathFor, readLeases } from '../lease.mjs';
+import { ALLOW_ENV, EVENTS, POLICY_IDS, SESSION_ENV, policiesFor } from './policy.mjs';
+import { applyAliases, commandFacts, GIT_BUILTINS } from './shell.mjs';
 
 /**
  * The policies this session has lifted, and the names in `SIMT_ALLOW` that are not
@@ -42,14 +45,39 @@ export function overrides(env = {}) {
   };
 }
 
-/** Whether one row applies to the facts. A row with no matcher reads the facts itself. */
-function applies(row, facts) {
+/**
+ * Whether one row applies to the facts. A row with no matcher reads the facts itself.
+ *
+ * `env` is only consulted by `lease`, which is the one row asking who is doing this
+ * rather than what is being done — and the one row with a fact the payload never
+ * carries: an unreadable claim file denies a write, but a shell command with no file
+ * fact is not an edit (ADR-101 ruling 4).
+ *
+ * A command row is judged on the normalised facts when they exist: the shell tokenised,
+ * wrappers unwrapped, each git invocation reduced to subcommand and options (ADR-104).
+ * When the command could not be tokenised, or the facts were never normalised at all —
+ * a test that hands `decide` a bare command string — the row's regex runs instead, so
+ * a parse failure and a pre-normalised fact are both judged the way they were before
+ * the normaliser existed.
+ */
+function applies(row, facts, env) {
   if (row.inspects === 'command') {
-    return typeof facts.command === 'string' && row.match !== null && row.match.test(facts.command);
+    if (typeof facts.command !== 'string') return false;
+    if (facts.shell !== null && facts.shell !== undefined && facts.shell.parsed === true) {
+      return row.match(facts);
+    }
+    return row.regex !== null && row.regex.test(facts.command);
   }
   if (row.inspects === 'write') {
     return (facts.writes ?? []).some((w) => w.generated !== null && w.generated !== undefined);
   }
+  if (row.inspects === 'lease') {
+    const writes = facts.writes ?? [];
+    if (writes.length === 0) return false;
+    if (facts.leaseError) return true;
+    const session = typeof env[SESSION_ENV] === 'string' ? env[SESSION_ENV] : '';
+    return writes.some((w) => w.lease && w.lease.session !== session);
+  }
   return false;
 }
 
@@ -62,7 +90,7 @@ function applies(row, facts) {
  */
 export function decide({ event = EVENTS[0], facts = {}, env = {} } = {}) {
   const { ids: lifted, unknown } = overrides(env);
-  const matched = policiesFor(event).filter((p) => applies(p, facts));
+  const matched = policiesFor(event).filter((p) => applies(p, facts, env));
   const blocked = matched.filter((p) => !lifted.has(p.id));
   return {
     event,
@@ -70,7 +98,14 @@ export function decide({ event = EVENTS[0], facts = {}, env = {} } = {}) {
     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})`),
+    // A row may carry a `detail` for the parts of its message that are only knowable
+    // at decision time (the lease holder's name and expiry, ADR-101 ruling 5). Every
+    // row without one renders exactly as before, override hint included.
+    messages: blocked.map((p) => {
+      const detail = typeof p.detail === 'function' ? p.detail(facts, env) : null;
+      const body = detail ? `${p.message} ${detail}` : p.message;
+      return `${body} (override: ${ALLOW_ENV}=${p.id})`;
+    }),
     adrs: blocked.map((p) => p.adr),
   };
 }
@@ -114,10 +149,66 @@ export async function generatedBytes(root, file) {
   return null;
 }
 
+/**
+ * The author's git aliases, name to value, as `git config` spells them.
+ *
+ * One spawn for the whole command, and only when a fact needs it: the lookup reads the
+ * configuration the agent's own `git p` would read, and a git that is missing or cannot
+ * answer yields no aliases, which leaves the facts exactly where the pre-lookup policy
+ * would have found them.
+ */
+function gitAliases(root) {
+  const result = spawnSync('git', ['-C', root, 'config', '--get-regexp', '^alias\\.'], {
+    encoding: 'utf8',
+    timeout: 1000,
+  });
+  const aliases = new Map();
+  if (result.status !== 0) return aliases;
+  for (const line of String(result.stdout ?? '').split('\n')) {
+    const m = /^alias\.(\S+)\s+(.*)$/.exec(line);
+    if (m !== null) aliases.set(m[1], m[2]);
+  }
+  return aliases;
+}
+
+/**
+ * The normalised command facts the table asks about: the shell tokenised, wrappers
+ * unwrapped, each git or rm invocation reduced to what it runs.
+ *
+ * A subcommand git does not ship may be the author's alias, and what it expands to is
+ * read from their git configuration - the one step in this path that leaves the
+ * module. A command that cannot be tokenised is marked, not dropped: the policies fall
+ * back to their regex rather than seeing nothing (ADR-104).
+ */
+async function normalizeCommand(root, command) {
+  const parsed = commandFacts(command); // non-null: `command` is a string here
+  if (parsed === null || !parsed.parsed) return { parsed: false };
+  if (parsed.facts.some((f) => f.kind === 'git' && !GIT_BUILTINS.has(f.sub))) {
+    parsed.facts = applyAliases(parsed.facts, gitAliases(root));
+  }
+  return parsed;
+}
+
 /** 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 };
+  // Shell facts, read only when the payload carried a command: the same "pay for what
+  // you use" rule as the lease facts below, which a payload with no command cannot touch.
+  const shell = typeof command === 'string' ? await normalizeCommand(root, command) : null;
+  // Lease facts, read only when the payload named a file to write: the claim file is
+  // irrelevant to a shell command, and a payload with no file pays nothing for a
+  // feature it cannot touch. Expired claims are dropped here because the hook runs
+  // now, so a TTL needs no sweeper; ownership is left whole because `decide` is the
+  // one that knows which session is asking (ADR-101 ruling 3).
+  if (resolved.length === 0) return { command, writes: resolved, leaseError: null, shell };
+  const read = await readLeases(root);
+  if (read.error !== null) return { command, writes: resolved, leaseError: read.error, shell };
+  const live = new Map(activeLeases(read).map((l) => [l.path, l]));
+  for (const w of resolved) {
+    const rel = leasePathFor(root, w.path);
+    w.lease = rel === null ? null : live.get(rel) ?? null;
+  }
+  return { command, writes: resolved, leaseError: null, shell };
 }

package/src/agenthooks/policy.mjs

@@ -20,6 +20,7 @@
 // they can ask about.
 
 import { CLI } from '../name.mjs';
+import { HOOKS_DIR, HOOKS_PATH_KEY } from '../hooks/shim.mjs';
 
 /**
  * The events an agent-time hook can answer, normalised across harnesses.
@@ -35,12 +36,29 @@ export const EVENTS = ['pre-tool-use', 'prompt-submit', 'post-tool-use'];
 /** The environment variable that lifts named policies for one session. */
 export const ALLOW_ENV = 'SIMT_ALLOW';
 
+/**
+ * The environment variable that names the session a claim was filed under and the
+ * session an edit is asked for (R54).
+ *
+ * One name in both places on purpose: a denial is only explainable if the session the
+ * hook protected is the same name `simt lease` recorded, and two spellings would drift
+ * into a refusal nobody can reconcile with a claim that exists.
+ */
+export const SESSION_ENV = 'SIMT_SESSION';
+
 /**
  * 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.
+ * `inspects` names the fact the matcher is handed, and `match` the condition. A command
+ * row carries two matchers because the facts come in two states: `match` reads the
+ * normalised command - the shell tokenised, wrappers unwrapped, each git invocation
+ * reduced to subcommand and options (ADR-104) - and `regex` is the fallback that runs
+ * when the command cannot be tokenised at all, so a parse failure never weakens a
+ * policy. Facts that were never normalised - a test that hands `decide` a bare command
+ * string - also take the fallback, which is why it stays in the table rather than
+ * beside the tokenizer. 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.
@@ -51,7 +69,8 @@ const POLICIES = [
     adr: 'ADR-001',
     event: 'pre-tool-use',
     inspects: 'command',
-    match: /(?:^|[\s;&|(])git\s+push(?:\s|$)/,
+    match: (facts) => facts.shell.facts.some((f) => f.kind === 'git' && (f.sub === 'push' || f.sub === 'send-pack')),
+    regex: /(?:^|[\s;&|(])git\s+push(?:\s|$)/,
     message: `Push needs explicit approval (ADR-001); ask the user.`,
   },
   {
@@ -59,12 +78,50 @@ const POLICIES = [
     adr: 'ADR-017',
     event: 'pre-tool-use',
     inspects: 'command',
-    match:
+    match: (facts) =>
+      facts.shell.facts.some((f) => {
+        if (f.kind !== 'git') return false;
+        if (f.opts.has('--no-verify')) return true;
+        if (f.sub === 'commit' && (f.opts.has('--amend') || f.opts.has('n'))) return true; // -n is --no-verify
+        if (f.sub === 'reset' && f.opts.has('--hard')) return true;
+        if (f.sub === 'rebase') return true;
+        if (f.sub === 'pull' && f.opts.has('--rebase')) return true; // pull --rebase rebases
+        return (
+          (f.sub === 'push' || f.sub === 'send-pack') &&
+          (f.opts.has('--force') || f.opts.has('f') || f.refspecs.some((r) => r.startsWith('+')))
+        );
+      }),
+    regex:
       /--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: 'hooks-disable',
+    adr: 'ADR-104',
+    event: 'pre-tool-use',
+    inspects: 'command',
+    // No regex fallback: before ADR-104 this policy did not exist, so a command that
+    // cannot be tokenised is judged exactly as it was judged before this row was written.
+    regex: null,
+    match: (facts) => {
+      const dir = (a) => a.replace(/^\.\/+/, '').replace(/\/+$/, '');
+      const key = HOOKS_PATH_KEY.toLowerCase(); // config keys are case-insensitive in git
+      return facts.shell.facts.some((f) => {
+        if (f.kind === 'git') {
+          if (f.globals.c.some((s) => s.toLowerCase().startsWith(`${key}=`))) return true;
+          if (f.sub === 'config' && f.refspecs.some((r) => r.toLowerCase() === key || r.toLowerCase().startsWith(`${key}.`))) return true;
+          return false;
+        }
+        if (f.kind === 'rm') return f.args.some((a) => dir(a) === HOOKS_DIR || dir(a).startsWith(`${HOOKS_DIR}/`));
+        return false;
+      });
+    },
+    message:
+      `That removes or reroutes the git hooks this repository's gates run in, so the gates would stop ` +
+      `running without anyone saying so; if it is deliberate, run \`${CLI} hooks install --yes\` afterwards (ADR-104).`,
+  },
   {
     id: 'generated',
     adr: 'ADR-036',
@@ -75,6 +132,25 @@ const POLICIES = [
       `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).`,
   },
+  {
+    id: 'lease',
+    adr: 'ADR-101',
+    event: 'pre-tool-use',
+    inspects: 'lease',
+    match: null,
+    message: `That path is leased by another session (ADR-101); wait for its TTL or ask the holder to release it.`,
+    // The only row whose message is not a constant: what the blocked session needs to
+    // hear — which path, whose, until when — is read from the claim file at decision
+    // time, and a static row cannot carry a timestamp it has never seen.
+    detail: (facts, env) => {
+      if (facts.leaseError) return `${facts.leaseError}; fix or remove it so the claims are readable`;
+      const mine = env[SESSION_ENV] ?? '';
+      const held = (facts.writes ?? [])
+        .filter((w) => w.lease && w.lease.session !== mine)
+        .map((w) => `${w.path} held by ${w.lease.session} until ${new Date(w.lease.expiresAt).toISOString()}`);
+      return held.length > 0 ? `held: ${held.join('; ')}` : '';
+    },
+  },
 ];
 
 /** The policy ids, in table order: the vocabulary an override is checked against. */