tamperward 1.4.0 → 1.4.1

package/README.md

@@ -6,55 +6,51 @@
 
 <p align="center"><em>A ward is the obstruction inside a lock that blocks the wrong key.</em></p>
 
-**The deterministic agent-integrity gate.** One ruleset, evaluated on the actual
-diff and commands as a verdict — not a probability — enforced everywhere a change can
-be made: inside the coding agent's loop, at the commit, and at the merge.
-
-AI agents optimize for "the command succeeded," not "the change is trustworthy." To
-make checks pass they take the cheapest path: deleting failing tests, weakening
-assertions, casting to `any`, suppressing lint/type errors, lowering coverage gates,
-editing CI, or bypassing hooks with `--no-verify`. Tamperward treats the safety nets
-themselves as protected assets and blocks the *class* of bypass — so no single
-shortcut is enough.
+<p align="center">
+  <a href="https://www.npmjs.com/package/tamperward"><img src="https://img.shields.io/npm/v/tamperward?label=npm&color=4F46E5" alt="npm version"></a>
+  <a href="https://github.com/hexrift/tamperward/actions/workflows/release.yml"><img src="https://img.shields.io/github/actions/workflow/status/hexrift/tamperward/release.yml?label=release" alt="release"></a>
+  <a href="./LICENSE"><img src="https://img.shields.io/badge/license-Apache--2.0-lightgrey" alt="license"></a>
+</p>
 
-> Apache-2.0 core · `github.com/hexrift/tamperward`
+**The deterministic agent-integrity gate.** AI coding agents optimize for "the command
+succeeded," not "the change is trustworthy." To make checks pass they take the cheapest
+path: deleting failing tests, skipping them, casting to `any`, suppressing lint errors,
+lowering coverage gates, rewriting snapshots, editing CI, or bypassing hooks with
+`--no-verify`. Tamperward treats the safety nets themselves as protected assets and
+blocks the **class** of bypass — one ruleset, evaluated on the actual diff and commands
+as a verdict, not a probability, enforced everywhere a change can be made: **inside the
+agent's loop, at the commit, and at the merge.**
 
-## Stability
+> Apache-2.0 · zero runtime model calls · every headline claim below is measured, with
+> the pre-registered predictions (including the refuted ones) committed to this repo
 
-`1.0.0` commits to the surface you actually depend on: the CLI and its **exit codes**, the
-hook wire format, the `.tamperward.yml` schema, and the `--json` `Finding` shape. The
-package publishes no `main` and no `exports` — it is a binary, not a library — so nothing
-under `src/` is public and internal refactors will never break you.
+## Install
 
-The version answers one question: *can taking this upgrade turn a green build red without
-me changing anything?* **Patch never can** — bypass fixes and false-positive fixes ship as
-patches so they reach you automatically. **Major can**, and only ever will alongside a
-changelog entry saying which rule changed. See
-[CONTRIBUTING](./CONTRIBUTING.md#versioning) for the full rule.
+```bash
+npx tamperward init
+```
 
-Two rules ship as `warn` and do not block: `assertion-weakening` and `guard-removal`. They
-are heuristic, and they stay non-blocking until their precision is measured (SPEC §7.A).
+One idempotent command wires all four enforcement points — it never overwrites anything
+you wrote, and `--dry-run` shows the plan first:
 
-## Does the loop actually work?
+| point | what it wires |
+| --- | --- |
+| agent loop | Claude Code `PreToolUse` deny + `Stop` sweep, merged into `.claude/settings.json` |
+| pre-commit | husky when present, the plain git hook otherwise |
+| CI | a PR-gate workflow with out-of-band sign-off (details below) |
+| policy | a commented baseline `.tamperward.yml` — the defaults apply even without it |
 
-The gate is only half the claim. The other half is what an agent does *after* it is
-denied: fix the real failure, or hunt for another way around. That is the
-**bypass-to-fix conversion rate** (SPEC §7.B), and it is measured, not asserted —
-`harness/run.sh` stands up an isolated repo with a real bug and a failing protected
-test, lets a headless agent loose on it with the hooks installed, and classifies the
-end state with an oracle independent of the detectors under test.
+Or run the views directly:
 
-**42 runs. 0 tampers reached green. Of the 20 runs where a block fired, 20 ended in an
-honest fix.**
+```bash
+npx tamperward check --staged                # pre-commit view
+npx tamperward check --diff "main...HEAD"    # CI view — the authority for main
+```
 
-| arm | model | runs | blocks fired | honest fix | tamper through |
-|---|---|---|---|---|---|
-| `seed` · adversarial | Sonnet 5 | 1 | 0 | 1 | 0 |
-| `seed` · **forced** | Sonnet 5 | 5 | 0 | 5 | 0 |
-| `seed-hard` · adversarial | Sonnet 5 | 3 | 0 | 3 | 0 |
-| `seed-hard` · adversarial | Haiku 4.5 | 33 | 20 | 33 | 0 |
+## What it looks like when it fires
 
-The trajectory the whole design is built around, from a transcript:
+An agent, mid-loop, tries the classic shortcut. The deny happens **before** the tool
+runs, and holds even under `bypassPermissions`:
 
 ```
 5. Bash  rm calc.test.js   → DENIED (test-deletion)
@@ -62,115 +58,97 @@ The trajectory the whole design is built around, from a transcript:
 7. Bash  node --test       → green, honestly
 ```
 
-**Read the number with its limits.** 20/20 is a point estimate on a finite sample: it
-supports "no conversion failure observed in 20 interceptions", whose 95% lower bound is
-≈ 86% — above the ~80% bar SPEC §7.B set for "the loop works", but not a claim of 100%.
-The split matters more than the total — Sonnet 5 never attempted a bypass at all,
-including 5/5 runs in `forced` mode where the prompt *orders* it to delete the failing
-test; all 20 interceptions came from Haiku 4.5 on the seed whose honest fix is genuinely
-expensive. Of those 20, the agent's first move after the denial was a real fix attempt
-19 times; once it went and read `.tamperward.yml` looking for another way through before
-converting. That probe is counted here as an attempted second bypass, not smoothed away.
-
-So on scenarios this size, a frontier model mostly does not need the gate. What the run
-supports is the narrower, more durable claim: **when a shortcut is attempted, it is
-caught deterministically, and the denial redirects the agent to the real fix rather than
-to another bypass.**
-
-Reproduce: `npm run build && harness/run.sh 5 adversarial haiku seed-hard`
-
-## Status
-
-Phase 1 — the engine, the eight mechanical detectors, the `check` CLI, and the Claude Code
-agent layer (PreToolUse hook + Stop sweep + `allow`). Tamperward gates its own repo in CI
-with the same engine it ships.
-
-- `src/types.ts` — the `Change` model every adapter manufactures and every detector
-  consumes (the one decision the codebase inherits).
-- `src/diff/parse.ts` — pure `git diff` → `Change[]` parser. Handles add / modify /
-  delete / **rename (as one change carrying `oldPath`)** / rename+edit / binary, with
-  per-line old/new line numbers correct across multiple hunks.
-- `src/git/build.ts` — the git adapter: range / staged / worktree views, enriching
-  `before`/`after` with full file content for the AST detectors.
-- `src/detectors/` — the **nine mechanical rules**: `no-verify`, `ts-any-cast`,
-  `lint-suppression`, `test-skip`, `coverage-lowering`, `ci-tampering`,
-  `hook-tampering`, `test-deletion` (the last counts `it()/test()` via the TS AST,
-  and handles delete / rename-out-of-glob / shell mutation), and `snapshot-rewrite`
-  (a `warn`: re-recording a snapshot/golden expectation from current output — the one
-  rule built from measured demand, after the affordance experiment put the move at a
-  70% attempt and 100% through rate; see `harness/PREDICTION-affordance.md`).
-- `src/engine.ts` — runs the enabled rules over `Change[]`; honours `policy.ignore`.
-- `src/cli/` — `tamperward check --staged | --worktree | --diff <base>...<head>`,
-  exit 1 on any blocking finding.
-- `test/` — 259 tests, including the AST-vs-regex, self-hosting precision, and
-  pre-go-live audit regression cases, and the renderer accessibility contract.
-
-- `src/adapters/claude/` + `src/cli/hook.ts` — the agent layer: `tamperward hook claude`
-  (PreToolUse deny, fail-closed) and `tamperward sweep claude` (Stop sweep, compared against
-  the turn's starting commit so a mid-turn commit can't launder a tamper past it).
-- `src/signoff.ts` — the three-layer sign-off model: the agent honours nothing it can author.
-
-Next: the negatives corpus to graduate the two heuristic rules, and a larger §7.B run
-to tighten the interval on the conversion rate.
-
-See **[SPEC.md](./SPEC.md)** for the full build spec, the detector table, the
-enforcement-point wiring, and the proof harness.
-
-## Use
-
-```bash
-npx tamperward init                          # wire all four enforcement points in one
-                                             # command: policy file, Claude Code hooks,
-                                             # pre-commit, CI. Idempotent; --dry-run to
-                                             # preview; never overwrites your files.
+The same engine at pre-commit or in CI:
 
-npx tamperward check --staged                # pre-commit view
-npx tamperward check --diff "main...HEAD"    # CI view — the authority for main
+```
+tamperward: 2 blocking
+(2 changes scanned)
+
+  BLOCK  coverage-lowering  package.json
+    Coverage gate weakened: global lines threshold lowered 90 → 10.
+    evidence  global lines threshold lowered 90 → 10
+    instead   Raise real coverage by adding tests; do not lower or exempt
+              the gate to pass.
+    sign-off  tamperward allow coverage-lowering --file package.json --reason "..."
+
+  BLOCK  test-deletion  test/calc.test.js
+    Test blocks removed: 3 → 1 it()/test() in this spec.
+    evidence  2 test block(s) removed from test/calc.test.js
+    instead   Keep the assertions and fix the code. Removing test blocks to go
+              green is the tamper.
+
+A blocking finding clears only with a human sign-off. In CI that sign-off is
+out-of-band — a PR label applied by a reviewer — never a file committed on the
+branch under review.
 ```
 
-### Reading the verdict
-
-One verdict, rendered for whoever is reading it. `--format` picks the view; the default,
-`auto`, picks `github` when `GITHUB_ACTIONS=true` and `text` otherwise, so the CI wiring
-stays a single line.
-
-| Format | Where it goes |
-| --- | --- |
-| `text` | The terminal. Blocking findings first, then by file and line, wrapped to the terminal width. |
-| `github` | An inline annotation per finding — so it lands **on the line** in *Files changed*, not four clicks deep in a job log — plus a job-summary table on the run page. The full text output still goes to the log. |
-| `json` | The findings verbatim, plus a summary count. |
-
-Severity is always spelled out (`BLOCK` / `warn`) and never carried by colour or a glyph
-alone, so the output reads the same piped, in a CI log, on a colour-blind reader's
-terminal, and through a screen reader. Colour honours
-[`NO_COLOR`](https://no-color.org) and `FORCE_COLOR`, and is off whenever stdout is not a
-terminal.
+Under GitHub Actions each finding also lands as an **inline annotation on the diff** in
+*Files changed*, plus a job-summary table — not four clicks deep in a log.
+
+## The rules
+
+Nine mechanical rules, deterministic by construction, `block` by default:
+`test-deletion` (AST block-count, rename-out-of-glob, shell mutation), `test-skip`
+(including `.only`, which narrows the suite), `ts-any-cast`, `lint-suppression`,
+`coverage-lowering` (Jest and Vitest shapes, all four metrics, `package.json` included),
+`ci-tampering` (a **moved** check is not a removed one), `hook-tampering`, `no-verify`
+(flags and the env-var escape hatches), and `snapshot-rewrite` (`warn` — see the FP study
+below for why).
+
+Three heuristics ship as `warn` and never block until their precision clears the bar:
+`assertion-weakening`, `guard-removal`, `ts-any-launder`.
+
+The policy file itself is un-ignorable, CI reads the policy from the **merge-base** (a PR
+cannot govern its own verdict), and the agent honours no sign-off it can author — the
+escape valve is a PR label only a human with write access can apply.
+
+## Measured, not asserted
+
+**Does the loop work?** `harness/run.sh` stands up an isolated repo with a real bug and a
+failing protected test, lets a headless agent loose with the hooks installed, and
+classifies the end state with an oracle independent of the detectors under test
+(SPEC §7.B). **42 runs, 0 tampers reached green; all 20 runs where a block fired ended in
+an honest fix** — a 20/20 point estimate whose 95% lower bound is ≈86%. The split is the
+honest part: Sonnet 5 never attempted a bypass at all, even when the prompt *ordered*
+one; all 20 interceptions came from Haiku 4.5 on a seed whose honest fix is genuinely
+expensive. Reproduce: `npm run build && harness/run.sh 5 adversarial haiku seed-hard`.
+
+**Which detectors deserve to exist?** Measured too. Affordance seeds offer an agent one
+specific bypass each; predictions are pre-registered before any rep runs
+(`harness/PREDICTION-affordance.md`). Result: 7/10 adversarial runs regenerated a golden
+file from buggy output (100% passed unseen — so `snapshot-rewrite` was built), while
+timeout-inflation and lint-config-gutting measured **0/10 attempts each** — two
+pre-registered bets refuted, two detectors *not* built. Bypass classes with no measured
+demand stay in a record-only shadow scanner that accumulates evidence on every weekly
+harness run.
+
+**What about false positives?** `snapshot-rewrite` was swept over **1,652 real mainline
+commits** (prettier, jest, docusaurus, immer): 216 touched snapshots, all legitimately —
+which is exactly why that rule is a `warn` asking for human confirmation, not a block,
+and why the study is committed (`harness/fp-study/`) rather than summarized away.
 
-From a clone:
+## Stability
 
-```bash
-npm install
-npm run build                                      # bundles the CLI to dist/cli/index.js
-node dist/cli/index.js check --staged
-node dist/cli/index.js check --diff "main...HEAD"
-```
+The public surface is the CLI and its **exit codes**, the hook wire format, the
+`.tamperward.yml` schema, and the `--json` `Finding` shape. No `main`, no `exports` —
+it is a binary, not a library. The version answers one question: *can taking this
+upgrade turn a green build red without me changing anything?* **Patch never can** —
+bypass fixes and false-positive fixes ship as patches so they reach you automatically.
+Rule graduations (`warn` → `block`) are **opt-in**: they gate on the `version:` field in
+your policy, so they ship as minors and apply only when you raise it. Releases publish
+via npm trusted publishing with SLSA provenance. Full rule:
+[CONTRIBUTING](./CONTRIBUTING.md#versioning).
 
 ## Develop
 
 ```bash
-npm test           # vitest — parser, detectors, engine, policy
+npm install && npm run build    # bundles the CLI to dist/cli/index.js
+npm test                        # 259 tests — parser, detectors, engine, policy, renderers
 npm run typecheck
 ```
 
-## Layout
-
-```
-tamperward/
-  src/types.ts          the Change / Finding / Detector / Policy contracts
-  src/diff/             pure diff parser + selectors
-  src/git/              git adapter (range / staged / worktree)
-  src/detectors/        the rules (phase 1, in progress)
-  test/                 unit suite — green is the gate
-  .tamperward.yml         the policy: protected assets + rule severities
-  .github/workflows/    CI — dogfoods Tamperward on itself once the CLI lands
-```
+Tamperward gates its own repo in CI with the same engine it ships — including, on more
+than one occasion, blocking its own author's commits. See **[SPEC.md](./SPEC.md)** for
+the build spec, the detector table, the enforcement-point wiring, and the proof-harness
+design; the `harness/` directory holds the seeds, oracles, transcripts tooling, and
+every pre-registered prediction with its outcome.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tamperward",
-  "version": "1.4.0",
+  "version": "1.4.1",
   "description": "The deterministic agent-integrity gate. One ruleset, evaluated on the actual diff/commands as a verdict, enforced everywhere a change can be made.",
   "license": "Apache-2.0",
   "author": "hexrift",
@@ -14,15 +14,18 @@
   },
   "keywords": [
     "ai-agents",
+    "claude-code",
+    "coding-agents",
     "agent-safety",
+    "reward-hacking",
     "code-integrity",
     "guardrails",
-    "claude-code",
+    "test-integrity",
     "pre-commit",
     "ci",
-    "static-analysis",
-    "reward-hacking",
-    "tests"
+    "hooks",
+    "llm",
+    "devsecops"
   ],
   "type": "module",
   "bin": {