@ataraxy-labs/sem 0.25.0 → 0.27.0

package/CHANGELOG.md

@@ -4,6 +4,67 @@ All notable changes to sem are documented in this file.
 
 ## [Unreleased]
 
+## [0.27.0] - 2026-10-04
+
+### Changed
+
+- **A smaller command line: eight verbs, variations as flags.** `sem --help` now lists `find`, `grep`, `impact`, `check`, `certify`, `diff`, `graph` and `history`, the `cloud` and `config` groups, and `mcp`, one line each saying which question the verb answers, with a QUICKSTART for the four agent questions (where is it, what does my change touch, is it correct, what should a human review).
+  - `sem find X --callers | --refs | --context` and `sem find --in PATH` replace `callers`, `refs`, `context` and `entities`.
+  - `sem impact --diff <range>` takes a whole change; with `--tests` in a JS/TS workspace it uses the module graph's affected-test selection.
+  - `sem certify <range> --arch` (with `--html`, `--view`, `--md`) replaces `arch-diff`.
+  - `sem graph --modules | --dataflow [--witness] | --system` replaces `topology`, `dataflow` and `system`.
+  - `sem history X` and `sem history --blame FILE` replace `log` and `blame`.
+  - `sem cloud login|logout|whoami|review|xref|repos|enable|disable` and `sem config setup|unsetup|telemetry|completions|update|stats` group the account and setup commands.
+  - Every old command name and flag still works with identical output, JSON included. At a terminal it prints a one-line note on stderr naming the new spelling; in `--json` mode or when stdout is not a terminal it prints nothing extra.
+- **`sem mcp` lists the core verbs only:** `sem_find` (with `mode` callers, refs or context, `in`, `text` and `intent`), `sem_grep`, `sem_impact`, `sem_check`, `sem_certify`, `sem_diff`, `sem_graph` and `sem_history`. The earlier tools (`sem_entities`, `sem_context`, `sem_callers`, `sem_log`, `sem_blame`) still answer when called by name. The review-listener tools are listed for `sem mcp --review`, which the review-listener plugin now passes.
+
+### Added
+
+- **`sem check`, an exact incremental verifier.** Runs the project's TypeScript, lint, test, Go, Cargo and configured checkers and prints one verdict: exit 0 pass, 1 fail, 2 could not decide (nothing to check is 2, never a pass). A checker rechecks only what a change can affect when that is provably the verdict of the full tool, and otherwise runs in full and says why; `--json` adds a verification certificate. `--promises` also proves every promise in `.sem/promises` can fail.
+- **`sem dataflow --witness` and an experimental execution-witness runner (`witness/`).** `--witness` emits one instrumentation task per static source -> sink flow (Python, TS/JS). The runner has a model propose a harness, runs it in a network-less docker sandbox with a runtime that injects a secret canary at the source, and marks a flow CONFIRMED only when the canary reaches the sink along the claimed path in 3 of 3 runs. See `witness/DESIGN.md`.
+- **More Python data-flow sources:** typer/click command parameters, FastAPI route parameters, framework base-class handlers, functions run through `asyncio.to_thread` and executors, typed `*args`/`**kwargs`, and `getattr(self, name)` dispatch.
+- **`sem arch-diff --view`, `--html` and `--from-json`.** A ranked, collapsed view of an arch-diff report (at most 10 items that need a human decision, each with what changed and why it matters), a self-contained HTML page with the module graph around the change, and rendering of a saved `--json` report.
+- **`sem system deps|fetch|build` (experimental).** A layered whole-system graph (repo code, locked dependencies and stdlib, database schema, config and routes, service contracts, a runtime trace) that gives every call and boundary site one outcome per layer and reports how much of the system is knowable. Optional TypeScript front-end and runtime tracers live in `scripts/system/`.
+- **`sem dataflow`, `sem arch-diff <base>..<head>` and `sem certify <base>..<head>`.** `sem dataflow` lowers Python, JS/TS, Go and Rust functions into one IR and reports source -> sink paths with witness paths, matched against declarative models of sources, sinks, sanitizers and callbacks; a call with no known target is an escape, never dropped. `sem arch-diff` reports the architecture delta of a change: new and removed data paths, dependency and cycle changes, signature changes with their unresolved possible callers, broken Python imports and complexity deltas, ranked by severity (text, `--json`, `--md`), in bounded time (`--budget`) and memory (`--max-memory`; above that it analyzes the diff's region and says so). `sem certify` writes a review certificate: touched entities, callers a signature change left unmodified, laws kept or newly broken with their shortest witness paths, affected tests.
+- **An exact-or-unknown call graph for Rust, Go and Python.** Each call site resolves to a target set, external, or unknown; a base or trait method call gets dispatch edges to its overrides. It replaces the scope resolver for those languages (persisted facts are invalidated and rebuild on upgrade).
+- **`sem topology`** for JS/TS workspaces: the module reference graph (value vs type-only imports, workspace imports resolved to source without a build, asset nodes, dynamic-import patterns), graph metrics (cycles, betweenness, propagation cost, blast radius, affected tests) and laws (`forbid`, `only`, `acyclic`, `layers`, `forbidImport`, `forbidPattern` tree-sitter queries in any sem language). `sem promises check|status|verify` evaluates laws that carry a human promise, and `verify` requires each law to break under its declared mutation. `callsFit` reports Python calls that no longer fit their target's signature.
+
+### Changed
+
+- **Caller answers say whether they are complete.** `sem callers`, `sem impact` and `sem certify` attach a completeness verdict: when an alias, a dispatch registration or an untyped receiver may hide callers, the answer says so and lists the possible callers, nearest first, instead of printing "callers: none" or a green "No tests found". `find`/`callers`/`refs` accept qualified names (`Class.method`, `module.func`, `name@line`) and suggest near matches on a miss; `--file` takes a directory.
+- `sem grep` accepts rg-style trailing paths, `-l` and `-n`; `sem context` labels packed entities with `file:start-end`; members of decorated Python classes are extracted; a cold `sem find` builds through the shared graph cache.
+
+- Experimental simple agent sessions now support explicitly acknowledged exact-source reuse and content-only diff reviews since a captured review. Cold file parses run with bounded concurrency, and batch-edit preflight avoids repeated reads of the same file. Validation result reuse is opt-in and requires an operator-owned complete-input fingerprint provider; ordinary checks continue to execute by default.
+- **Signature changes and deletions now report the callers a batch left behind.** Before `weave_transaction` deletes an entity or applies an edit with `allow_signature_change`, it asks sem's graph for that entity's dependents and returns the ones the batch did not edit as `caller_review.unedited_dependents`, so a missed caller shows up before the build. The list comes from the syntax-level graph and is a review aid, not a compile check. Out-of-range integer arguments such as `max_entities: 0` are now clamped instead of failing the call, and the pi package README documents the transaction mode as it runs today.
+
+## [0.26.0] - 2026-10-02
+
+### Removed
+
+- **The strict and adaptive transaction policies are gone from pi, leaving the simple structural session policy as the only one.** `pi/config/transaction.mjs` and `pi/config/adaptive-transaction.mjs` are removed, and `config/simple-transaction.mjs` is now the documented configuration for `PI_SEM_MODE=transaction`.
+
+### Added
+
+- **Opt-in simple structural session policy for agents.** `pi/config/simple-transaction.mjs` packages batched exact reads, acknowledged context reuse, scoped edit composition and snapshot-checked edits without fixed discovery/transaction call quotas. Includes regression tests and setup instructions. This policy remains experimental, not a guarantee of faster sessions or semantic completeness.
+
+### Fixed
+
+- **Portable transaction startup and guarded batches.** The simple server starts without JeV credentials; external ranking requires explicit `SEM_JEV_ENABLED=1` plus credentials and task. Same-file exact-edit batches enforce intermediate snapshot guards and roll back earlier writes on a later edit error.
+
+- Experimental structural-session adapter snapshot adds explicitly scoped reads and edit programs, batched discovery, bounded validation evidence, and timeout recovery. Retained as a research branch: benchmark timings vary with agent-selected validation workloads and do not establish a universal speedup.
+- Text search includes eligible files without a structural parser (such as Objective-C++ `.mm` and custom build files), including alongside a warm structural index. Search responses preserve coverage limits separately from result pagination; binary content remains excluded.
+
+- Simple transaction edits preserve overloaded entity selectors. Timed-out public checks retain partial diagnostics and restart their disposable checker so subsequent validation can proceed.
+
+- Simple transaction read batches preserve valid results when another selector is malformed or a requested path is rejected as a symlink. Partial captures report their errors explicitly; strict capture and edit checks remain unchanged.
+
+- **Copilot CLI can connect to the MCP server again.** Unsupported discovery probes return `Method not found` without closing the connection, allowing clients to fall back to `initialize` in both standalone and shared modes. Fixes #497.
+- **Indexed name lookup sees renames and added definitions in edited files.** `sem find` checks indexed file freshness and reparses changed files on demand, without requiring a whole dependency-graph refresh. Includes TypeScript, Python and Rust regression coverage.
+- **Dart dependency graphs now resolve ordinary calls, constructor-bound receivers and typed parameters.** Callers and refs no longer select a same-named Dart method for a TypeScript receiver (or vice versa); imported class owners take precedence. Persisted graph/query caches are invalidated so upgrades rebuild the affected edges. Fixes #491.
+- **Shared MCP clients keep independent context history and stay bound to their repository.** Concurrent daemon startup is serialized with an OS lock, stale sockets recover after crashes, and handshakes are bounded. Adds `sem mcp --status` for health checks and reproducible lifecycle coverage on macOS and Linux.
+- **Telemetry uploads are no longer rejected by the server.** 0.21.0 removed the install id from the upload payload while the ingest endpoint still required one, so every batch uploaded since then was refused and active-install counts only ever reflected 0.20.0 and older. Uploads now carry `hash(local seed + day number)`, where the seed is generated once, stays on the machine and is never sent, so a batch groups with the rest of that machine's day and with nothing before or after it. Telemetry is still local-by-default and opt-in, so this only changes the contents of an upload that someone enabled with `sem telemetry on`.
+- **`sem setup` no longer reports success when part of it failed.** It writes the global `diff.external` config first, then installs the Claude Code hook and the pre-commit hook, and those two steps used to treat a permissions or JSON failure as a warning before falling through to a closing message that listed all three features as live and returned success. An unparseable `~/.claude/settings.json` therefore left changed git config, no hook, and a final line reading "sem is wired in". The closing summary is now built from the steps that actually ran, and a failed step reports what did and did not apply before exiting 2. The successful path is unchanged. Thanks to kantorcodes1 on Reddit for the report.
+
 ## [0.25.0] - 2026-09-13
 
 ### Added

package/README.md

@@ -17,6 +17,7 @@
 
 <p align="center">
   <a href="https://ataraxy-labs.com/blogs/code-is-not-text">Why sem?</a> ·
+  <a href="#using-sem-with-agents">Using sem with agents</a> ·
   <a href="#install">Install</a> ·
   <a href="#commands">Commands</a> ·
   <a href="#use-with-ai-agents-mcp">Agents (MCP)</a> ·
@@ -42,6 +43,83 @@ Cloud-backed queries are opt-in per repo: logging in does not upload a repo or s
   <img src="assets/terminal.svg" alt="sem diff" width="800" />
 </p>
 
+## Using sem with agents
+
+Four questions, four verbs. Every verb takes `--json`.
+
+| Question | Verb |
+|---|---|
+| Where is it? | `sem find`, `sem grep` |
+| What does my change touch? | `sem impact` |
+| Is it correct? | `sem check` |
+| What should a human review? | `sem certify` |
+
+**Where is it?** Find a function, class or method by name:
+
+```bash
+sem find parse_config
+```
+```
+function parse_config src/config.py:1
+```
+
+Who calls it (`--callers`), what it uses (`--refs`), or its code with its callers and callees (`--context`):
+
+```bash
+sem find parse_config --callers
+```
+```
+function parse_config src/config.py:1
+  function load src/config.py:6
+  function test_parse_config tests/test_config.py:4
+```
+
+Search text, like `rg`:
+
+```bash
+sem grep splitlines
+```
+```
+src/config.py:2:    pairs = [line.split("=", 1) for line in text.splitlines() if line]
+```
+
+**What does my change touch?** Everything that depends on an entity, and the tests to run:
+
+```bash
+sem impact parse_config --tests
+```
+```
+⚡ 1 tests affected:
+    tests/test_config.py
+      function test_parse_config (L4–5)
+```
+
+`sem impact --diff HEAD --tests` answers the same for your whole uncommitted change.
+
+**Is it correct?** Run the project's own compiler, type checker, linter and tests, rechecking only what the change can affect when that gives the same answer. Exit 0 means pass, 1 fail, 2 could not decide:
+
+```bash
+sem check
+```
+```
+cmd    FAIL      full        sh (0 rechecked, 279 ms)
+  `python3 -m pytest -q tests` exited 1:
+  E       AssertionError: assert {'a': '1'} == {'a': '2'}
+```
+
+**What should a human review?** A review certificate for a commit range: what changed, which callers the change leaves behind, which tests reach it:
+
+```bash
+sem certify main..HEAD
+```
+```
+# sem certificate 94f4bd74e26e..d73d4d092b43
+1 files, 2 entities changed (1 added, 1 modified, 0 deleted, 0 renamed, 0 moved).
+- modified `parse_config` (src/config.py:1): 2 static caller(s) in 2 file(s) that this change does not modify
+```
+
+For agents that speak MCP, `sem mcp` serves the same verbs as tools (see [Use with AI agents](#use-with-ai-agents-mcp)).
+
 ## Install
 
 ```bash
@@ -129,8 +207,97 @@ If you installed via npm/bun, the binary lives in `node_modules/.bin/sem` and is
 
 Works in any Git repo. No setup required. Also works outside Git for arbitrary file comparison.
 
+| Verb | The question it answers |
+|---|---|
+| `sem find` | Where is it defined? Who calls it, what does it use, what is around it? |
+| `sem grep` | Where does this text appear? |
+| `sem impact` | What does changing this entity, or this diff, touch? |
+| `sem check` | Is my change correct? |
+| `sem certify` | What should a human review in this commit range? |
+| `sem diff` | Which functions and classes changed? |
+| `sem graph` | How is the code connected? |
+| `sem history` | How did this entity change over time? Who last changed it? |
+| `sem cloud` | Account, cloud reviews, cross-repo queries |
+| `sem config` | git diff integration, telemetry, completions, updates, stats |
+| `sem mcp` | The same verbs as MCP tools for agents |
+
+`sem <verb> --help` shows every flag with an example.
+
 sem stores its SQLite entity cache outside the repository, under the OS cache directory by default. Set `SEM_CACHE_DIR=/path/to/cache` to override the cache root; repo-local overrides are ignored so cache files do not dirty the working tree.
 
+### sem find
+
+Find entity definitions by name, then ask about one: who calls it, what it uses, or its code with the code around it. Answers come from an on-disk query index (`index.sem`, next to the entity cache); the first call in a repo builds it, later calls read it directly, with no daemon.
+
+```bash
+sem find "function diff_command"        # where it is defined ("type name" narrows by kind)
+sem find diff_command load_config       # several names in one call
+sem find diff_command --callers         # who calls it; says when the caller set may be incomplete
+sem find diff_command --refs            # what it calls and references
+sem find diff_command --context         # its code plus callers and callees, within a token budget
+sem find diff_command --context --budget 4000 --hops 1
+sem find --in src/auth.ts               # every entity in a file or directory
+sem find diff_command --in src/         # only definitions under src/
+sem find --text "retry budget"          # entity bodies containing a string, named by entity
+sem find diff_command --json            # JSON on any of the above
+```
+
+With `--context`, when the target signature itself does not fit, JSON output reports `target_omitted: true`.
+
+### sem grep
+
+Text search across source files, rg-compatible `file:line:text` output, served from the index's trigram postings when one exists.
+
+```bash
+sem grep "TODO"
+sem grep -i todo src/                   # case-insensitive, under src/
+sem grep -e foo -e bar --json           # several patterns, hits kept apart
+```
+
+### sem impact
+
+What breaks if an entity changes: its dependencies, its dependents (transitively), and the tests that reach it.
+
+```bash
+sem impact authenticateUser             # full impact
+sem impact authenticateUser --deps      # direct dependencies only
+sem impact authenticateUser --dependents
+sem impact authenticateUser --tests     # the tests to run
+sem impact authenticateUser --file src/auth.ts   # disambiguate by file
+sem impact --diff HEAD --tests          # tests for the uncommitted change
+sem impact --diff main..HEAD --json     # one impact report per changed entity
+```
+
+With `--diff` and `--tests` in a JS/TS workspace, the answer is the module graph's affected-test selection over the changed files (`sem graph --modules affected-tests`); elsewhere it is the entity graph's. `--no-default-excludes` includes generated, fixture, vendor, benchmark and build trees.
+
+### sem check
+
+Runs the project's compiler, type checker, linter and tests on the working tree and prints one verdict: exit 0 pass, 1 fail, 2 could not decide. Each checker gives the verdict the real tool would give on the whole project; it rechecks only what the change can affect when that is provably the same answer, and otherwise runs the tool in full and says why. Nothing to check is 2, never a pass.
+
+```bash
+sem check                               # every checker the project has (TypeScript, lint, tests, Go, Cargo)
+sem check --checkers ts,lint,tests      # only these
+sem check --base origin/main            # against origin/main instead of HEAD
+sem check --promises                    # also prove every promise in .sem/promises can fail
+sem check --json                        # one JSON object with a verification certificate
+```
+
+Commands of your own go in `.sem/check.json`, e.g. `{"commands": ["python3 -m pytest -q"]}`; they always run in full.
+
+### sem certify
+
+A review certificate for a commit range: entities touched, signature changes and the callers they leave behind, callee deltas, promises kept or broken (with witnesses), module reachability deltas (JS/TS), affected tests, and the static reference cone. `--arch` gives the architecture view instead: new or removed data paths, side effects, dependencies, cycles, and what did not change, ranked.
+
+```bash
+sem certify main..HEAD                  # markdown certificate
+sem certify main..HEAD --json           # the full certificate
+sem certify main..HEAD --arch           # architecture delta
+sem certify main..HEAD --arch --view    # at most 10 ranked items
+sem certify main..HEAD --html > view.html   # one self-contained page
+```
+
+`<base>...<head>` uses the merge base; one ref means `<ref>..HEAD`.
+
 ### sem diff
 
 Entity-level diff with rename detection, structural hashing, and word-level inline highlights.
@@ -171,167 +338,125 @@ echo '[{"filePath":"src/main.rs","status":"modified","beforeContent":"...","afte
 sem diff --file-exts .py .rs
 ```
 
-### sem impact
-
-Cross-file dependency graph shows what breaks if an entity changes.
-
-```bash
-# Full impact analysis
-sem impact authenticateUser
-
-# Direct dependencies only
-sem impact authenticateUser --deps
-
-# Direct dependents only
-sem impact authenticateUser --dependents
-
-# Affected tests only
-sem impact authenticateUser --tests
-
-# JSON output
-sem impact authenticateUser --json
-
-# Disambiguate by file
-sem impact authenticateUser --file src/auth.ts
-
-# Include default-excluded paths such as generated, fixture, vendor, benchmark, and build trees
-sem impact authenticateUser --no-default-excludes
-```
-
-### sem blame
-
-Entity-level blame showing who last modified each function, class, or method.
-
-```bash
-sem blame src/auth.ts
-
-# JSON output
-sem blame src/auth.ts --json
-```
-
-### sem log
-
-Track how a single entity evolved through git history.
-
-```bash
-sem log authenticateUser
-
-# Verbose mode (show content diff between versions)
-sem log authenticateUser -v
-
-# Limit commits scanned
-sem log authenticateUser --limit 20
-
-# JSON output
-sem log authenticateUser --json
-```
+### sem graph
 
-With no entity, `sem log` analyzes recent repo history at the entity level:
-**hotspots** (most-changed functions/classes, with author counts) and
-**co-change pairs** (entities that repeatedly change in the same commits:
-"if you touch one, don't forget the other"):
+How the code is connected. With no flag, the entity dependency graph (the graph `sem impact` and `sem find --context` are built on); the flags select other layers.
 
 ```bash
-sem log                 # repo hotspots + co-change pairs (last 50 commits)
-sem log --limit 200     # deeper history
-sem log --file src/auth.ts   # scoped to one file
-sem log --json          # full data
+sem graph --json                        # entities and the calls/references between them
+sem graph --modules metrics             # JS/TS module graph: density, cycles, depth, centrality
+sem graph --modules blast-radius pkg-a  # who breaks if pkg-a changes
+sem graph --modules path src/a.ts src/b.ts
+sem graph --dataflow                    # reads, writes and source -> sink paths
+sem graph --dataflow --witness          # experimental: witness tasks per static flow
+sem graph --system                      # exact dependency versions from every lockfile
+sem graph --system build --out sys/     # the layered whole-system graph
 ```
 
-### sem entities
+### sem history
 
-List all entities under a file or directory path. No path is the same as `.`.
+How an entity changed through git history, logic changes told apart from cosmetic ones.
 
 ```bash
-sem entities
-
-sem entities .
-
-sem entities src/auth.ts
-
-# JSON output
-sem entities --json
-sem entities src/auth.ts --json
-
-# Include default-excluded paths such as generated, fixture, vendor, benchmark, and build trees
-sem entities --no-default-excludes
+sem history authenticateUser
+sem history authenticateUser -v         # with the content diff of each version
+sem history authenticateUser --limit 20
+sem history                             # repo hotspots and co-change pairs
+sem history --blame src/auth.ts         # who last changed each entity in the file
 ```
 
-### sem context
+With no entity, `sem history` analyzes recent repo history at the entity level: **hotspots** (most-changed functions/classes, with author counts) and **co-change pairs** (entities that repeatedly change in the same commits: "if you touch one, don't forget the other").
 
-Token-budgeted context for LLMs: the entity, its dependencies, and its dependents, fitted to a strict content token budget.
-When the target signature itself does not fit, JSON output reports `target_omitted: true`.
+### sem cloud, sem config
 
 ```bash
-sem context authenticateUser
-
-# Custom token budget
-sem context authenticateUser --budget 4000
-
-# JSON output
-sem context authenticateUser --json
+sem cloud login                         # API key, or GitHub when omitted
+sem cloud enable                        # cloud queries for this public repo (shows what is sent, asks first)
+sem cloud disable                       # stop cloud for this repo
+sem cloud review listen <diff-id>       # attach an agent to a cloud code review
+sem cloud xref --json                   # cross-repo dependencies
+sem cloud repos                         # where your code is stored
+
+sem config setup                        # make `git diff` show sem's entity diff
+sem config telemetry off
+sem config completions zsh              # shell completions
+sem config update
+sem config stats                        # local diff counters; nothing leaves your machine
+```
+
+### Old command names
+
+Every earlier command name and flag still works, with the same output. At a terminal, sem prints a one-line note on stderr with the new spelling; in `--json` mode or when output is piped, it prints nothing extra.
+
+| Old | New |
+|---|---|
+| `sem callers X` | `sem find X --callers` |
+| `sem refs X` | `sem find X --refs` |
+| `sem context X` | `sem find X --context` |
+| `sem entities PATH` | `sem find --in PATH` |
+| `sem log X` | `sem history X` |
+| `sem blame FILE` | `sem history --blame FILE` |
+| `sem arch-diff RANGE` | `sem certify RANGE --arch` |
+| `sem topology OP` | `sem graph --modules OP` |
+| `sem dataflow` | `sem graph --dataflow` |
+| `sem system OP` | `sem graph --system OP` |
+| `sem promises verify` | `sem check --promises` |
+| `sem login`, `logout`, `whoami`, `review`, `xref`, `repos` | `sem cloud ...` |
+| `sem cloud never` | `sem cloud disable` |
+| `sem setup`, `unsetup`, `telemetry`, `completions`, `update`, `stats` | `sem config ...` |
+
+### Promises
+
+A promise is something an agent (or a person) claims about the codebase, written down as a check that either passes or fails. "Done" means the check passes. Promises live in `.sem/promises/*.json`; each law may carry a human `"promise"`. Code-shape laws are tree-sitter queries that work in any language sem parses; every capture whose name does not start with `_` counts as a violation, and nested captures are reported once, at the outermost node. For example, `.sem/promises/jsx-no-logic.json`:
 
-# Include default-excluded paths such as generated, fixture, vendor, benchmark, and build trees
-sem context authenticateUser --no-default-excludes
+```json
+{ "laws": [
+  { "id": "jsx-no-logic/conditionals",
+    "promise": "JSX contains no conditional rendering",
+    "forbidPattern": { "from": ["**/*.tsx", "**/*.jsx"], "within": ["jsx_expression"],
+                       "query": "(ternary_expression) @conditional" } },
+  { "id": "jsx-no-logic/inline-handler-bodies",
+    "promise": "JSX event handlers are references, not block bodies",
+    "forbidPattern": { "from": ["**/*.tsx", "**/*.jsx"], "within": ["jsx_attribute"],
+                       "query": "(arrow_function body: (statement_block (_))) @handler_body" } }
+] }
 ```
 
-### sem find / callers / refs / grep
-
-Cold-start lookups backed by an on-disk, mmap-able query index (`index.sem`, stored next to the SQLite entity cache). The first call in a repo builds the index; every call after that reads it directly, no daemon or background process involved:
-
 ```bash
-# Find where an entity is defined
-sem find "function diff_command"
-
-# Who calls it
-sem callers diff_command
-
-# What it calls
-sem refs diff_command
-
-# Text search across source files (rg-compatible file:line:text output,
-# served from the index's trigram postings when one exists)
-sem grep "TODO"
-
-# JSON output on any of the above
-sem find diff_command --json
+sem promises check                        # KEPT / BROKEN n per promise, then file:line:col  capture  snippet; exit 1 if any broken
+sem promises check --changed src/App.tsx  # only violations in these files (what an edit hook runs)
+sem promises check --since main           # only files changed since a ref, uncommitted and untracked included
+sem promises status --json                # id, kept, violation count per promise
+sem check --promises                      # prove every promise can fail (each needs a mutation)
 ```
 
-Measured on this repo (`crates/`) with `time`: the first `sem find` (index not built yet) took 185ms; the second call against the same repo, once the index existed, took 7ms. Run it yourself; the exact numbers will depend on your machine and repo size. The point is the cold-vs-warm gap: no daemon needs to stay alive for the warm number to hold.
+`sem promises` is not listed in `sem --help`; `sem certify` reports promises kept or broken for a range. The same file also works with `sem graph --modules check --laws <file>`, which adds graph and import laws (`forbid`, `only`, `acyclic`, `layers`, `forbidImport`, `allowImports`) for JS/TS workspaces. With `--changed` or `--since`, those laws still run over the whole graph, but only violations that involve a changed file (or the package containing it) are reported.
 
-### sem graph
-
-Prints the full entity dependency graph for the current repo, or `--json` for the underlying edge list (the same graph `sem impact` and `sem context` are built on top of):
+To have an agent see a broken promise right after it makes an edit, run [`scripts/promises-hook.sh`](scripts/promises-hook.sh) after each edit. The script exits 2 and prints the violations to stderr when a promise breaks, and stays silent otherwise. In Claude Code, add it to your settings as a `PostToolUse` hook:
 
-```bash
-sem graph
-sem graph --json
+```json
+{ "hooks": { "PostToolUse": [ { "matcher": "Edit|Write|MultiEdit",
+    "hooks": [ { "type": "command", "command": "sh /path/to/sem/scripts/promises-hook.sh" } ] } ] } }
 ```
 
-### sem stats
-
-Local, cumulative counters: how many diffs `sem` has run in this environment and how much of that was noise filtered out. Nothing here leaves your machine (see [Telemetry](#telemetry)):
-
-```bash
-sem stats
-```
+The script reads `tool_input.file_path` from the hook's stdin. Other harnesses can pass the edited paths as arguments instead. In pi, for example, an extension can do this from its `tool_result` handler for the edit and write tools: run `sh promises-hook.sh <path>` and append the stderr to the tool result when the script exits 2.
 
 ## Use as default Git diff
 
 Replace `git diff` output with entity-level diffs. Agents and humans get sem output automatically without changing any commands.
 
 ```bash
-sem setup
+sem config setup
 ```
 
 Now `git diff` shows entity-level changes instead of line-level. No prompts, no agent configuration needed. Everything that calls `git diff` gets sem output automatically. Also installs a pre-commit hook that shows entity-level blast radius of staged changes.
 
-On macOS and Linux, `sem setup` also registers a Claude Code `UserPromptSubmit` hook (`sem hook prompt-submit`) for prompt-time context injection. It edits `~/.claude/settings.json` idempotently, backs it up first, and leaves any hooks you already have untouched.
+On macOS and Linux, `sem config setup` also registers a Claude Code `UserPromptSubmit` hook (`sem hook prompt-submit`) for prompt-time context injection. It edits `~/.claude/settings.json` idempotently, backs it up first, and leaves any hooks you already have untouched.
 
 To disable and go back to normal git diff (also removes the session hooks):
 
 ```bash
-sem unsetup
+sem config unsetup
 ```
 
 ## Entity-level diffs on every pull request
@@ -361,10 +486,10 @@ No config, no API keys, never fails your build. See [action/](action/) for detai
 
 Local is always free and always fast: the on-disk index answers day-to-day queries in single-digit milliseconds even from a cold process, so there's nothing to keep warm and no login required. You do not pay to make your laptop fast.
 
-Cloud is for what a laptop can't do. On a very large monorepo the first local graph build can take a few seconds; a shared team graph shouldn't be rebuilt per developer; and CI wants the graph without checking anything out. `sem login` connects those cases to sem cloud, which keeps a warm, pre-built graph for your registered repos and serves the heavy queries from it instead of rebuilding locally.
+Cloud is for what a laptop can't do. On a very large monorepo the first local graph build can take a few seconds; a shared team graph shouldn't be rebuilt per developer; and CI wants the graph without checking anything out. `sem cloud login` connects those cases to sem cloud, which keeps a warm, pre-built graph for your registered repos and serves the heavy queries from it instead of rebuilding locally.
 
 ```bash
-sem login                              # GitHub device flow, one time
+sem cloud login                        # GitHub device flow, one time
 sem impact myFunc --file src/foo.rs    # served from the cloud's warm graph
 ```
 
@@ -377,19 +502,20 @@ It is fully optional and transparent:
 Related commands, all cloud-account scoped:
 
 ```bash
-sem logout          # log out
-sem whoami          # show current cloud identity
-sem cloud status    # cloud + telemetry state for this repo (offline; sends nothing)
-sem cloud enable    # turn on cloud queries for a public repo (shows what's sent first)
-sem cloud share     # same, with extra confirmation, for a private repo
-sem cloud forget    # delete this repo's cloud index and unregister it
-sem xref --json     # cross-repo dependencies across your indexed repos
-sem repos           # where your code is stored: cloud-indexed repos + local caches
+sem cloud logout          # log out
+sem cloud whoami          # show current cloud identity
+sem cloud enable          # turn on cloud queries for a public repo (shows what's sent first)
+sem cloud disable         # stop cloud for this repo
+sem cloud xref --json     # cross-repo dependencies across your indexed repos
+sem cloud repos           # where your code is stored: cloud-indexed repos + local caches
+sem cloud status          # cloud + telemetry state for this repo (offline; sends nothing)
+sem cloud share           # cloud queries for a private repo, with extra confirmation
+sem cloud forget          # delete this repo's cloud index and unregister it
 ```
 
-`sem cloud --help` lists every subcommand (`list`, `preview`, `log`, `never` included); each one is read-only or requires explicit confirmation before it sends anything.
+`status`, `share`, `forget`, `list`, `preview` and `log` are not shown in `sem cloud --help` but work as listed; each one is read-only or requires explicit confirmation before it sends anything.
 
-If your team runs code review through sem cloud, `sem review listen <diff-id-or-url>` execs a coding agent pre-configured to join that review as a live listener that answers reviewer questions anchored to specific lines of the diff.
+If your team runs code review through sem cloud, `sem cloud review listen <diff-id-or-url>` execs a coding agent pre-configured to join that review as a live listener that answers reviewer questions anchored to specific lines of the diff.
 
 ## What it parses
 
@@ -472,9 +598,26 @@ This means sem detects renames and moves, not just additions and deletions. Stru
 
 ## Use with AI agents (MCP)
 
-`sem mcp` starts a [Model Context Protocol](https://modelcontextprotocol.io) server over stdin/stdout. It's not a command you run and read yourself: it's a server your coding agent launches in the background so it can ask sem questions while it works. That's the reason `mcp` lives alongside the normal commands. The agent gets 8 entity-level tools mirroring the CLI: `sem_entities`, `sem_diff`, `sem_blame`, `sem_impact`, `sem_log`, `sem_context`, `sem_find`, `sem_grep`. (If you're also using sem cloud for code review, four more tools let an agent attach to a review and answer reviewer questions in a loop: `join_review`, `wait_for_branch`, `reply_to_branch`, `list_open_branches`.)
+On macOS and Linux, clients in the same checkout share a warm repository daemon.
+Run `sem mcp --status` to check it. See the [shared runtime contract and reproducible benchmark](docs/shared-mcp.md)
+for session isolation, fallback behavior, and current platform limits.
+
+`sem mcp` starts a [Model Context Protocol](https://modelcontextprotocol.io) server over stdin/stdout. It's not a command you run and read yourself: it's a server your coding agent launches in the background so it can ask sem questions while it works. That's the reason `mcp` lives alongside the normal commands. The agent gets the core verbs as tools:
+
+| Tool | Answers |
+|---|---|
+| `sem_find` | Where is it defined? `mode`: `callers`, `refs` or `context`; `in` lists a file or directory |
+| `sem_grep` | Where does this text appear? |
+| `sem_impact` | What does changing this entity touch? Dependents, deps, tests |
+| `sem_check` | Is my change correct? A verdict: pass, fail, could not decide |
+| `sem_certify` | What should a human review in this commit range? |
+| `sem_diff` | Which entities changed between two refs? |
+| `sem_graph` | The entity, module, data-flow or system graph |
+| `sem_history` | How did an entity change? `blame` for a file |
+
+Clients that call the earlier tool names (`sem_entities`, `sem_context`, `sem_callers`, `sem_log`, `sem_blame`) still get answers; those names are just not listed. A review-listener session (`sem mcp --review`, which `sem cloud review listen` sets up) also lists `join_review`, `wait_for_branch`, `reply_to_branch` and `list_open_branches`.
 
-Why an agent wants these: instead of reading whole files and burning tokens, it can ask "what breaks if I change `submitOrder`" (`sem_impact`) or "give me just the context to refactor this function" (`sem_context`, which returns the function's source plus its callers and callees) and get a precise, deterministic answer from the dependency graph instead of a grep result that might miss a caller.
+Why an agent wants these: instead of reading whole files and burning tokens, it can ask "what breaks if I change `submitOrder`" (`sem_impact`) or "give me just the context to refactor this function" (`sem_find` with mode `context`, which returns the function's source plus its callers and callees) and get a precise, deterministic answer from the dependency graph instead of a grep result that might miss a caller.
 
 Add it once, then talk to your agent normally. It calls the tools on its own.
 
@@ -579,9 +722,9 @@ Used by [weave](https://github.com/Ataraxy-Labs/weave) (semantic merge driver) a
 Local by default: sem counts command names (e.g. `diff`, `impact`) on your own machine only, and in that mode nothing is ever uploaded. No code, file paths, repo names, or user identity is recorded, and no network call is made.
 
 ```bash
-sem telemetry preview   # see current mode and exactly what would be sent
-sem telemetry on        # opt in: also upload counts to help improve sem
-sem telemetry off       # record nothing at all
+sem config telemetry preview   # see current mode and exactly what would be sent
+sem config telemetry on        # opt in: also upload counts to help improve sem
+sem config telemetry off       # record nothing at all
 ```
 
 `SEM_NO_TELEMETRY=1` or `DO_NOT_TRACK=1` force the record-nothing behavior regardless of mode. Development builds (anything run out of a `cargo build` `target/` directory) never record, so working on sem itself doesn't pollute the numbers.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@ataraxy-labs/sem",
   "mcpName": "io.github.Ataraxy-Labs/sem",
-  "version": "0.25.0",
+  "version": "0.27.0",
   "description": "npm wrapper for the sem CLI. Downloads the matching release binary and exposes the sem command in node_modules/.bin.",
   "license": "MIT OR Apache-2.0",
   "type": "module",