@redue/cli 0.1.0-alpha.32 → 0.1.0-alpha.33

package/CHANGELOG.md

@@ -1,5 +1,38 @@
 # Changelog
 
+## 0.1.0-alpha.33 — 2026-11-06
+
+pytest checks follow the project's quick suite, and the hook starts for
+every check form.
+
+- **The pull-request workflow's narrowed suite.** For pytest, `init` now
+  reads `coverage run -m pytest`, quoted arguments (`-m "not slow"`) and
+  lines continued with a backslash, and leaves out options that only write
+  a report (`--junit-xml`, `--html`, `--durations`). When a workflow that
+  runs on pull requests narrows the suite (`-m`, `-k`, `--ignore`,
+  `--deselect`), its line wins. On project-lighter/lighter the test check is
+  now `pytest tests -m "not slow"` (4.7 s), not the full suite with its
+  CIFAR download: setup took 68 s instead of 10.5 minutes, and all three
+  checks qualify.
+- **Trigger rules that Claude Code matches.** A hook trigger rule with a
+  quote in it never started the hook in a real session, so such a check's
+  runs were neither skipped nor recorded. A rule now ends before the first
+  character outside letters, digits, spaces and `_./:=,+@-`, and the hook
+  matches the whole command itself, spaces inside quotes included.
+- **`redue agent doctor` checks the trigger rules.** `trigger_rules` says
+  whether the installed rules start the hook for every command form of
+  every configured check, as REDUE models Claude Code's matching, and names
+  the forms they miss.
+- **README.** Setup can take longer with a large environment or a slow
+  suite; trial runs stop at 5 minutes and `redue init --check test
+  --no-time-limit` tries a check without the limit.
+
+Measured: stranger sessions on lighter (alpha.32 code with these changes)
+skipped mypy and pytest after a docs edit and ran both through REDUE after
+a source change, 0 critical. Python product census: 0 critical; 17 test,
+15 typecheck and 22 lint checks qualify, as in alpha.32. `init` on the 13
+slowest census repos chose the same checks as alpha.32.
+
 ## 0.1.0-alpha.32 — 2026-11-05
 
 REDUE's status is now the point: what is verified on the code as it is

package/README.md

@@ -1,14 +1,36 @@
 # REDUE
 
-**Know which checks still hold. Redo what's due.**
+**Know what is verified on the code you have now.**
 
-You or your coding agent ran the typecheck, the linter or the tests. Then the
-code changed, or a new agent session started with no memory of it. REDUE
-records each check's result with the exact inputs it ran on, and tells you and
-your agent whether that result still applies to the code you have now, so a
-check that still holds is not run again and one that is stale is.
+Your typecheck, linter and tests passed at some point. Then the code
+changed, or a new agent session started with no memory of what ran. REDUE
+records each check's result with the exact inputs it ran on, and gives you
+and your coding agent one dependable answer: which checks are verified on
+the code as it is now, which are stale, and which are due. When it cannot
+tell, it says so and why; it never guesses a result into place.
 
-## Quickstart (about 5 minutes)
+## What it changes
+
+Coding agents often finish without running every check on their final code.
+In headless Claude Code sessions on realistic tasks whose prompts never
+mention checks (bug fixes, small features and refactors; 21 tasks on 7
+TypeScript and Python projects, two runs each), the share of sessions that
+ended with every check verified on the final code:
+
+| Model | Without REDUE | With REDUE |
+|---|---|---|
+| Sonnet 5.5 | 12% (5 of 42) | 98% (41 of 42) |
+| Opus 5.5 | 48% (20 of 42) | 100% (42 of 42) |
+
+A check counts as verified when the session ran all of it on the final code,
+or REDUE said CURRENT for it at the end; counting only the agents' own check
+commands, it was 90% and 98% with REDUE. REDUE never called a failing check
+verified: in no session did it say CURRENT / PASS for a check that failed
+when run plainly on the final code. Without REDUE, 4 Sonnet sessions ended
+with a failing check they had not run; with it, none did. The harness and
+tasks are in [`eval/`](eval/README.md).
+
+## Quickstart
 
 You need macOS or Linux, Node 22 or 24, Git, Claude Code, and either a
 JavaScript or TypeScript project with its dependencies installed
@@ -32,50 +54,85 @@ stops before writing anything if the dependencies are not installed. It:
   pyright and ty (typecheck), ruff (lint) and pytest (test). It says which
   checks it left out and why, and which it can only record, not reuse;
 - connects Claude Code: a short section in `CLAUDE.md`, a skill, hooks in
-  `.claude/settings.local.json`, and a status line there that shows what is
-  verified on the code as it is now ("REDUE ✓ 3 verified", "REDUE 2 due:
-  typecheck, test"). A status line you already have stays;
+  `.claude/settings.local.json`, and a status line there. A status line you
+  already have stays;
 - starts REDUE's file observer, waits while it indexes the project (a minute
   or more in a large one), then runs each check that can qualify once, so
-  there is a first result to reuse, and prints one line per run (the run's
-  own output only when it fails);
+  there is a first result, and prints one line per run (the run's own output
+  only when it fails);
 - prints every file it writes. Running it again changes nothing.
 
-Then start a new Claude Code session in the project and work as usual. When
-the agent is about to rerun a check whose last pass still applies, the hook
-skips it and tells the agent why. After an edit, the hook runs the check
-through REDUE so the new result is recorded. When the agent is about to finish a
+Setup takes a minute or two in most projects. It can take longer in a large
+environment, such as a `.venv` with PyTorch or a workspace with many
+packages, because the observer indexes every installed file first, and with
+a slow test suite, because `init` runs each check once plainly and once in
+the sandbox before it chooses how to run it. Each of those trial runs stops
+after 5 minutes; a check that runs longer is left out of the sandbox, and
+setup names it and prints the command that tries it without the limit, such
+as `redue init --check test --no-time-limit`. For pytest, `init` takes the
+arguments the project's own workflows run it with, and prefers a
+pull-request workflow that leaves slow tests out (`-m "not slow"`).
+
+Then start a new Claude Code session in the project and work as usual. The
+status line shows where things stand, updated as the agent works:
+
+```text
+REDUE ✓ 3 verified
+REDUE ✓ 2 verified · 1 due: typecheck
+REDUE ✓ 2 verified · 1 not verifiable
+```
+
+When the agent runs a check whose last pass still applies, the hook skips
+the rerun and tells it why; after an edit, the hook runs the check through
+REDUE so the new result is recorded. When the agent is about to finish a
 turn in which files changed while a check is due, the hook asks it once to
 run `redue verify` first (`"endOfTurnCheck": false` in the config turns
 this off).
 
-To look yourself:
+To ask yourself:
 
 ```text
 $ redue status
 ✓ typecheck  CURRENT / PASS
 ✓ lint  CURRENT / PASS
+✓ test  CURRENT / PASS
 
 # after editing src/main.ts
-$ redue explain typecheck
-typecheck: STALE / PASS
-src/main.ts changed
-Due again when verification is needed: redue run "typecheck"
+$ redue status
+⚠ typecheck  STALE / PASS
+  src/main.ts changed
+⚠ lint  STALE / PASS
+  src/main.ts changed
+✓ test  CURRENT / PASS
+
+$ redue verify
+redue verify: running typecheck (STALE: src/main.ts changed)
+typecheck: PASS recorded.
+Check redue status before reusing this evidence.
+redue verify: running lint (STALE: src/main.ts changed)
+lint: PASS recorded.
+Check redue status before reusing this evidence.
+
+✓ typecheck  CURRENT / PASS
+✓ lint  CURRENT / PASS
+✓ test  CURRENT / PASS
+Verified: every check that can be verified (3) passed on the files as they are now.
 ```
 
 `redue status` checks the files and your environment before it answers, as
 the agent's hook does. `redue status --cached` gives the last answer the
 observer published without checking; it can say UNVERIFIED ("cannot confirm
 your execution context") where `redue status` would say CURRENT.
+`redue explain CHECK` says why a check is in its state.
 
 `redue verify` runs every check that is due (STALE, or UNVERIFIED with a
-command it can run), then prints the status. It exits 0 only when every check
-ends CURRENT / PASS, so it answers "is everything verified on the code as it
-is now?" in one command. A check no run can confirm is shown as NOT
-VERIFIABLE with the reason, and left out: a recording-only check, or one
-whose runs change its own inputs (two passing runs in a row changed the same
-files, such as a test script that rebuilds a tracked bundle). Any other
-change, or a failing run, makes it due again.
+command it can run), then prints the status. It exits 0 only when every
+check that can be verified ends CURRENT / PASS, so it answers "is everything
+verified on the code as it is now?" in one command. A check no run can
+confirm is shown as NOT VERIFIABLE with the reason, and left out: a
+recording-only check, or one whose runs change its own inputs (two passing
+runs in a row changed the same files, such as a test script that rebuilds a
+tracked bundle). Any other change, or a failing run, makes it due again.
 
 `redue stats` shows, per check, the reruns the hook skipped, the time saved,
 the recorded runs and the top reasons a check was UNVERIFIED, from a log kept
@@ -83,6 +140,26 @@ on your machine.
 
 To undo everything setup did: `redue remove`.
 
+## Time saved, as a bonus
+
+A check whose last pass still applies does not run again. Headless Claude
+Code sessions (Sonnet 5.5, CI Linux runner) on the same tasks with and
+without REDUE, three sessions per task. Session time, medians per task
+summed over the projects:
+
+- **Typecheck** (twilio-node, semiotic, Ultra-Card, SwitchHosts; four tasks;
+  96 sessions; 0.1.0-alpha.12 code): 464 s without, 330 s with. REDUE skipped
+  33 typechecks. Each was checked afterwards with plain `tsc` on the exact tree
+  it was skipped on, and all 33 agreed.
+- **Unit tests** (cheerio with Vitest 4, SwitchHosts with Vitest 5, twilio-node
+  with Jest 29; four tasks; 72 sessions; 0.1.0-alpha.14 code): 515 s without,
+  295 s with. REDUE skipped 21 test runs. Each was rerun plainly three times on
+  the exact tree, and all passed every time.
+
+API cost was the same in both arms. The savings come only when an earlier
+pass still applies: a task that changes source code saves nothing. A handful
+of projects and three runs per task show direction, not a general rate.
+
 ## Still CURRENT after your build and tests
 
 Running the project's build or tests writes files (`dist/`, `.next/`,
@@ -136,26 +213,6 @@ into and the sandbox can't run (inside Claude Code's macOS sandbox, on
 Windows), the project uses Bun, or a check writes into its own inputs.
 [Supported projects](docs/user/supported-projects.md) has the details.
 
-## Measured with Claude Code
-
-Headless Claude Code sessions (Sonnet 5.5, CI Linux runner) on the same tasks
-with and without REDUE, three sessions per task. Session time, medians per
-task summed over the projects:
-
-- **Typecheck** (twilio-node, semiotic, Ultra-Card, SwitchHosts; four tasks;
-  96 sessions; 0.1.0-alpha.12 code): 464 s without, 330 s with. REDUE skipped
-  33 typechecks. Each was checked afterwards with plain `tsc` on the exact tree
-  it was skipped on, and all 33 agreed.
-- **Unit tests** (cheerio with Vitest 4, SwitchHosts with Vitest 5, twilio-node
-  with Jest 29; four tasks; 72 sessions; 0.1.0-alpha.14 code): 515 s without,
-  295 s with. REDUE skipped 21 test runs. Each was rerun plainly three times on
-  the exact tree, and all passed every time.
-
-API cost was the same in both arms. The savings come only when an earlier
-pass still applies: a task that changes source code saves nothing. A handful
-of projects and three runs per task show direction, not a general rate. The
-harness, tasks and raw results are in [`eval/`](eval/README.md).
-
 ## What REDUE won't do
 
 - **Prove your code is correct.** CURRENT means the inputs of the recorded
@@ -165,9 +222,10 @@ harness, tasks and raw results are in [`eval/`](eval/README.md).
 - **Trust what it cannot see.** A program it cannot account for, a file it
   does not observe, or a gap in observation makes the result UNVERIFIED and
   says why. It never turns that into CURRENT by guessing.
-- **Support yet:** TypeScript 7's native compiler, Bun, per-package checks in
-  large monorepos, results shared across machines, and the general recipe on
-  Windows (Windows has the strict recipes only).
+- **Support yet:** Bun, per-package checks in large monorepos, results shared
+  across machines, and the general recipe on Windows (Windows has the strict
+  recipes only). TypeScript 7's native compiler is covered: a typecheck that
+  runs it gets the [sandboxed recipe](docs/user/sandbox.md).
 
 ## What the states mean
 
@@ -177,6 +235,7 @@ harness, tasks and raw results are in [`eval/`](eval/README.md).
 | STALE | An input changed since the recorded result. | Rerun when you need the answer. |
 | UNVERIFIED | REDUE cannot tell: no result yet, an input it cannot see, or observation not ready. | Read the reason; rerun if it matters. |
 | FAILED | The last run failed: the check ran and reported a failure, or could not run. | Fix and rerun. |
+| NOT VERIFIABLE | No run can confirm a result: a recording-only check, or one whose runs change its own inputs. | Read the reason; `redue verify` leaves it out. |
 
 ## Without Claude Code, or step by step
 

package/docs/user/agents.md

@@ -307,7 +307,18 @@ config resolution, cached observer health, a bounded read-only control-access pr
 managed-file integrity, detected host
 version, and loading guidance. `behavior_verified: false` is deliberate: intact
 files do not prove the agent followed them. For Claude, doctor reports whether the
-typecheck hook is installed. Doctor neither
+typecheck hook is installed, the status line, and `trigger_rules`: whether the
+`if` rules in the settings start the hook for every command form of every
+configured check (`covered`, or the forms they miss, which would run plainly,
+neither skipped nor recorded), including the fan-out commands and the forms
+after a `cd` into a check's directory. It applies the rules as REDUE models
+Claude Code's matching, not by asking Claude Code: `Bash(PREFIX*)` (or the
+legacy `Bash(PREFIX:*)`) matches a simple command that starts with PREFIX in
+the characters known to match (letters, digits, spaces and `_./:=,+@-`), and a
+hook with no `if` matches every command. Setup ends a rule before any other
+character, such as the quote in `-m "not slow"`, and the hook then matches
+the whole command itself, spaces inside quotes included; a rule that would
+end before the program's first argument is not written. Doctor neither
 executes checks nor starts observers, reconciles inputs, or installs a host.
 
 Doctor separates missing/unreadable state, a missing or refused endpoint, an

package/docs/user/direct-typescript.md

@@ -64,8 +64,9 @@ byte for byte, in one of two ways:
 
 CI runs the same contract suite against the last release of each minor from
 5.0 to 5.8 that the reviewed releases do not cover. Later minors (6.1 and up)
-wait until CI covers them. TypeScript 7 (the native compiler) is not
-supported.
+wait until CI covers them. This recipe does not take TypeScript 7 (the
+native compiler); a typecheck that runs it gets the
+[sandboxed recipe](sandbox.md).
 
 ## Script forms
 

package/docs/user/sandbox.md

@@ -41,9 +41,13 @@ built declarations) gets the whole checkout. See
   `.venv` (`uv sync` makes one; Poetry does with `virtualenvs.in-project`).
   `init` uses the arguments your CI workflow, Makefile, tox, nox, justfile or
   shell scripts in `scripts/` run the tool with, through `uv run`, `poetry run`,
-  `python -m` or `.venv/bin`. Without them it uses the tool's default:
-  `ruff check`, `ty check`, `pyright`, and `mypy` (with `.` when mypy's
-  configuration names no `files`).
+  `python -m`, `coverage run -m` or `.venv/bin`, including quoted arguments
+  (`-m "not slow"`) and lines continued with a backslash. It takes the first
+  such line, but a pull-request workflow's when it narrows the test suite
+  (`-m`, `-k`, `--ignore`, `--deselect`), and leaves out options that only
+  write a report (`--junit-xml`, `--html`, `--durations`). Without them it
+  uses the tool's default: `ruff check`, `ty check`, `pyright`, `pytest`, and
+  `mypy` (with `.` when mypy's configuration names no `files`).
 - **Platforms:** macOS (Seatbelt, `sandbox-exec`) and Linux 6.7 or later
   (Landlock; the launcher needs Python 3).
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@redue/cli",
   "private": false,
-  "version": "0.1.0-alpha.32",
+  "version": "0.1.0-alpha.33",
   "publishConfig": {
     "access": "public",
     "tag": "alpha"

package/src/agent-integration.mjs

@@ -12,7 +12,7 @@ import {readCachedStatus} from './cached-state.mjs';
 import {samePath,withinPath} from './path-identity.mjs';
 import {processAlive} from './process-liveness.mjs';
 import os from 'node:os';
-import {fanoutRules,hookCommand,hookForms,redueFor,runsEntry,shellQuote as quote,statusLineCommand} from './claude-hook.mjs';
+import {fanoutRules,hookCommand,hookForms,redueFor,runsEntry,shellQuote as quote,statusLineCommand,triggerRule,uncoveredForms} from './claude-hook.mjs';
 
 const policy=fs.readFileSync(new URL('./agent-policy.md',import.meta.url),'utf8');
 const hosts={codex:{instruction:'AGENTS.md',skill:'.agents/skills/redue-verification/SKILL.md'},
@@ -22,13 +22,14 @@ const marker=host=>`.redue/agents/${host}.json`;
 // The hook needs a local REDUE install, so it lives in per-developer settings.
 const settingsPath='.claude/settings.local.json';
 const sameJson=(a,b)=>JSON.stringify(a)===JSON.stringify(b);
-// One handler per exact command form; `if` keeps other Bash calls from starting Node.
+// One handler per command form (triggerRule: up to its first quote or other
+// character a rule cannot hold); `if` keeps other Bash calls from starting Node.
 // The hook waits for status up to 10 s; 15 s leaves room for starting Node.
 // Fan-out commands (turbo, nx, `pnpm -r`) and root scripts that run one get
 // prefix rules; the hook decides from the full command.
 function hookFor(config,relative,scripts,command=hookCommand){
   const rules=[...new Set([...hookForms(config,relative,scripts).flatMap(row=>[...row.forms,...row.local]),
-    ...fanoutRules(config,scripts)])].map(form=>`Bash(${form}*)`);
+    ...fanoutRules(config,scripts)].map(triggerRule).filter(Boolean))];
   return rules.length?{matcher:'Bash',hooks:rules.map(rule=>({type:'command',if:rule,command,timeout:15}))}:null;
 }
 // The same command on SessionStart starts the observer; it needs no check to match.
@@ -263,7 +264,7 @@ const priorBlocks=(host,relative)=>[false,true].map(legacy=>`\n\n<!-- REDUE:${ho
 // varies, and only in the safe character set. Earlier owned versions are
 // recognized so setup can replace them; other stored text never is.
 function knownBlock(host,relative,block){
-  const list='((?:`[A-Za-z0-9_./:=,+@ -]+`(?: and )?)+)';
+  const list='((?:`[A-Za-z0-9_./:=,+@ "\'()-]+`(?: and )?)+)';
   const forms=pattern=>{const named=new RegExp(pattern).exec(block);return named?[...named[1].matchAll(/`([^`]+)`/g)].map(m=>m[1]):[];};
   const rows=[...forms(`^\\n\\n<!-- REDUE:[a-z]+:begin -->\\nTypecheck with ${list}\\.`).map(form=>({kind:'typecheck',form})),
     ...forms(`Run the unit tests with ${list}\\.\\n`).map(form=>({kind:'test',form})),
@@ -368,7 +369,7 @@ export async function agentCommand(args,{configFile,stateOverride,entry,cwd=proc
       if(value.state_access)console.log(`State access: ${value.state_access.status}${value.state_access.reason?' — '+value.state_access.reason:''}`);
       if(value.compatibility?.reason)console.log(`Observer compatibility: ${value.compatibility.reason}`);
       if(value.applicability?.requires_reassessment)console.log('Applicability: cached evidence needs reassessment; choose synchronization or execution deliberately.');
-      for(const row of value.hosts)console.log(`${row.host}: ${row.version||'host unavailable'}; integration ${row.integrity}; hook ${row.hook}${row.host==='claude'?`; session start ${row.session_start}; status line ${row.status_line}`:''}; behavioral validation NOT VERIFIED by doctor${row.reason?' — '+row.reason:''}`);
+      for(const row of value.hosts)console.log(`${row.host}: ${row.version||'host unavailable'}; integration ${row.integrity}; hook ${row.hook}${row.host==='claude'?`; session start ${row.session_start}; status line ${row.status_line}; trigger rules ${!row.trigger_rules?(row.hook==='absent'?'not installed':'not checked'):row.trigger_rules.covered?'match every check form (as REDUE models Claude Code)':`miss ${row.trigger_rules.count} check form${row.trigger_rules.count>1?'s':''}`}`:''}; behavioral validation NOT VERIFIED by doctor${row.reason?' — '+row.reason:''}`);
       console.log('Doctor does not start observers, execute checks, or prove agent behavior.');
       for(const warning of value.warnings)console.log(`Review: ${warning}`);
     }return value;
@@ -462,16 +463,28 @@ export async function doctor({configFile,stateOverride,entry,cwd,host}){
     if(executable){const launch=windowsLaunch([executable,'--version']);
       const out=spawnSync(launch.file,launch.args,{...launch.options,encoding:'utf8',timeout:2000,maxBuffer:4096,stdio:['ignore','pipe','pipe']});
       if(out.status===0)version=out.stdout.trim();}
-    let integration={installed:false,integrity:'unknown'},hook=name==='claude'?'absent':'none',sessionHook=hook,statusLineState=hook;
+    let integration={installed:false,integrity:'unknown'},hook=name==='claude'?'absent':'none',sessionHook=hook,statusLineState=hook,triggers=null;
     const installed=()=>hookRunnable(p.root);
     if(p)try{const record=saved(p.root,name);integration=inspect(p.root,name,record);
       if(name==='claude'&&hookInstalled(p.root))hook=installed();
       if(name==='claude'&&hookInstalled(p.root,'SessionStart'))sessionHook=installed();
+      // Every check's command forms must start the hook: a form no trigger
+      // rule matches runs plainly, neither skipped nor recorded.
+      if(name==='claude'&&hookInstalled(p.root)){
+        let scripts={};try{scripts=JSON.parse(read(p.root,'package.json')??'{}').scripts||{};}catch{}
+        // REDUE's entries for Bash: a hook without `if` starts for every command.
+        const rules=(parseSettings(read(p.root,settingsPath)).hooks?.PreToolUse||[]).filter(entry=>ownedHook(entry)&&['Bash','*','',undefined].includes(entry.matcher))
+          .flatMap(entry=>entry.hooks.map(h=>typeof h.if==='string'?h.if:'Bash'));
+        const missing=uncoveredForms(rules,p.config,p.relative,scripts);
+        triggers=missing.length?{covered:false,missing:missing.slice(0,10),count:missing.length}:{covered:true};
+        if(missing.length)value.warnings.push(`The hook's trigger rules do not match ${missing.length} command form${missing.length>1?'s':''} of configured checks `+
+          `(such as ${missing[0]}): those runs are neither skipped nor recorded. Run redue agent setup claude --apply again.`);
+      }
       if(name==='claude'){let local=null;try{local=parseSettings(read(p.root,settingsPath)).statusLine;}catch{}
         statusLineState=ownedStatusLine(local)?'installed':otherStatusLine(p.root)?'another status line':'absent';}
       value.warnings.push(...warnings(p.root,name,cwd));
     }catch(e){integration={installed:false,integrity:'conflict',reason:e.message};}
-    value.hosts.push({host:name,executable,version,...integration,hook,session_start:sessionHook,...name==='claude'?{status_line:statusLineState}:{},behavior_verified:false,
+    value.hosts.push({host:name,executable,version,...integration,hook,session_start:sessionHook,...name==='claude'?{status_line:statusLineState,trigger_rules:triggers}:{},behavior_verified:false,
       loading:name==='codex'?'AGENTS.md at session start; .agents/skills; overrides and size limits apply':
         'CLAUDE.md at session start; .claude/skills; managed/user policies and exclusions apply'});
   }

package/src/claude-hook.mjs

@@ -21,6 +21,8 @@ export const hookCommand='redue agent hook claude';
 export const statusLineCommand='redue agent statusline claude';
 // No shell metacharacters; `@` starts scoped package names.
 const safe=/^[A-Za-z0-9_./:=,+@-]+$/;
+// Those characters and a space: what a trigger rule may hold (triggerRule).
+const ruleText=/^[A-Za-z0-9_./:=,+@ -]*$/,ruleStop=/[^A-Za-z0-9_./:=,+@ -]/;
 const typecheck=check=>check?.kind==='typecheck'||check?.name==='typecheck';
 // A direct test check: its command is the runner and the script's arguments.
 const tests=check=>check?.qualification==='npm-tests-direct-v1'&&Array.isArray(check.command)&&
@@ -31,8 +33,9 @@ const general=check=>(check?.qualification==='node-script-v1'&&['typecheck','tes
 // A sandboxed check: a root package script, or a tool from the project's .venv.
 // sandbox.mjs's isSandboxed, written out: the hook does not load the sandbox module.
 const sandboxed=check=>['sandbox-v1','sandbox-v2','sandbox-v3'].includes(check?.qualification)&&['typecheck','lint','test'].includes(check.kind);
+// An argument may hold spaces and parentheses (`-m "not slow"`): the forms quote it.
 const python=check=>sandboxed(check)&&Array.isArray(check.command)&&/^\.venv\/bin\/[A-Za-z0-9_.-]+$/.test(check.command[0]||'')&&
-  check.command.every(word=>typeof word==='string'&&safe.test(word));
+  check.command.every((word,i)=>typeof word==='string'&&(safe.test(word)||i>0&&/^[A-Za-z0-9_./:=,@+% ()-]+$/.test(word)&&/\S/.test(word)));
 const eligibleCheck=check=>typecheck(check)||tests(check)||general(check)||python(check);
 export const checkKind=check=>tests(check)?'test':general(check)||python(check)?check.kind:'typecheck';
 // The ways an agent runs a Python check's tool: through uv or Poetry, with
@@ -40,11 +43,45 @@ export const checkKind=check=>tests(check)?'test':general(check)||python(check)?
 // or the tool's name depends on PATH, so the hook takes it only when PATH
 // finds that program in the project's .venv/bin first (pathForm).
 const wrappers=['uv run ','poetry run '];
+// The `if` rules setup writes start the hook for a check's command forms.
+// As REDUE models Claude Code's matching (doctor's check; a stranger session
+// confirms it for real): `Bash(PREFIX*)` (or the legacy `Bash(PREFIX:*)`)
+// matches a simple command that starts with PREFIX, `Bash(TEXT)` exactly
+// TEXT, and plain `Bash` every command; compound commands are matched part by
+// part. Only the characters in ruleText are known to match in real sessions:
+// a rule with a quote in it never started the hook (alpha.32, `-m "not
+// slow"`). So a rule ends before the first other character; it may start the
+// hook for more commands, and the hook then matches each exactly. A rule
+// that would end before the program's first argument is not written: it
+// would start the hook for every run of the program.
+export function triggerRule(form){
+  const cut=form.search(ruleStop),prefix=cut<0?form:form.slice(0,cut);
+  return cut<0||/^\S+ \S/.test(prefix)?`Bash(${prefix}*)`:null;
+}
+// Whether a rule matches a simple command, as modeled above.
+export function triggerMatches(rule,command){
+  if(typeof rule!=='string'||typeof command!=='string')return false;
+  if(rule==='Bash')return true;
+  const body=/^Bash\((.*)\)$/s.exec(rule)?.[1];
+  if(body===undefined)return false;
+  const prefix=body.endsWith(':*')?body.slice(0,-2):body.endsWith('*')?body.slice(0,-1):null;
+  if(prefix!==null)return ruleText.test(prefix)&&command.startsWith(prefix);
+  return ruleText.test(body)&&command===body;
+}
+// The command forms of configured checks (as typed at the root, after a cd
+// into a check's directory, and the fan-out commands that run them) that no
+// rule in `rules` matches.
+export function uncoveredForms(rules,config,configFile=defaultConfig,packageScripts=null){
+  return [...new Set([...hookForms(config,configFile,packageScripts).flatMap(row=>[...row.forms,...row.local]),
+    ...fanoutRules(config,packageScripts||{})])].filter(form=>!rules.some(rule=>triggerMatches(rule,form)));
+}
+// An argument with a space (`-m "not slow"`) is written quoted, in double and in single quotes.
 function pythonForms(check){
-  const [file,...args]=check.command,tool=file.split('/').at(-1),rest=args.length?' '+args.join(' '):'';
-  return [`.venv/bin/${tool}${rest}`,`./.venv/bin/${tool}${rest}`,`.venv/bin/python -m ${tool}${rest}`,
+  const [file,...args]=check.command,tool=file.split('/').at(-1);
+  const rests=[...new Set(['"',"'"].map(q=>args.length?' '+args.map(arg=>/\s/.test(arg)?`${q}${arg}${q}`:arg).join(' '):''))];
+  return rests.flatMap(rest=>[`.venv/bin/${tool}${rest}`,`./.venv/bin/${tool}${rest}`,`.venv/bin/python -m ${tool}${rest}`,
     ...wrappers.flatMap(wrapper=>[`${wrapper}${tool}${rest}`,`${wrapper}python -m ${tool}${rest}`]),
-    `python -m ${tool}${rest}`,`python3 -m ${tool}${rest}`,`${tool}${rest}`];
+    `python -m ${tool}${rest}`,`python3 -m ${tool}${rest}`,`${tool}${rest}`]);
 }
 // For a form that names a program PATH finds (`mypy .`, `python -m mypy .`),
 // whether PATH finds it first in the project's .venv/bin.
@@ -289,7 +326,16 @@ function split(command){
   if(typeof command!=='string'||/[\r\n]/.test(command))return null;
   const [,base,suffix,rest=null]=command.trim()
     .match(/^(.*?)((?:[ \t]+2>&1)?(?:[ \t]+\|[ \t]+(?:tail|head)[ \t]+(?:-n[ \t]+\d+|-\d+))?)(?:[ \t]*(?:;|&&)[ \t]*([^\s;&|].*))?$/);
-  const one=text=>text.replace(/[ \t]+/g,' ');
+  // Runs of spaces are one, but not inside quotes: `-m "not  slow"` is not `-m "not slow"`.
+  const one=text=>{let out='',quote=null,space=false;
+    for(const c of text){
+      if(quote){out+=c;if(c===quote)quote=null;continue;}
+      if(c===' '||c==='\t'){space=true;continue;}
+      if(space){out+=' ';space=false;}
+      if(c==='"'||c==="'")quote=c;
+      out+=c;
+    }
+    return out+(space?' ':'');};
   return {base:one(base),suffix:one(suffix),rest};
 }
 // {check, rest}, or {fanout, rest} for a turbo/nx/`pnpm -r` command or a root

package/src/python-onboarding.mjs

@@ -20,9 +20,11 @@ export const pythonTools=[{tool:'mypy',kind:'typecheck',sub:[]},{tool:'pyright',
 const section=(text,header)=>{const at=text.split(/\r?\n/).findIndex(line=>line.trim()===header);
   if(at<0)return null;const rest=text.split(/\r?\n/).slice(at+1);const end=rest.findIndex(line=>/^\s*\[/.test(line));
   return (end<0?rest:rest.slice(0,end)).join('\n');};
-// Ways a project starts a tool: through uv, poetry or pdm, `python -m`, or from .venv/bin.
+// Ways a project starts a tool: through uv, poetry or pdm, `python -m`,
+// coverage (`coverage run -m pytest`), or from .venv/bin.
 const wrappers=[/^uv run(?: --(?:frozen|locked|no-sync|offline|quiet|all-extras|all-groups))*(?: --(?:group|extra|with|python|package) [^ ]+)* /,
   /^poetry run /,/^pdm run /,/^python3?(?:\.\d+)? -m /,/^(?:\.\/)?\.venv\/bin\//,
+  /^coverage run(?: --?[A-Za-z][\w-]*(?:=[^ "']+)?)* -m /,
   // A variable that names the environment's bin directory: `${PREFIX}mypy`.
   /^\$\{?[A-Za-z_]+\}?(?=[A-Za-z])/];
 // A tool's arguments in one line of a script or workflow, or null. The line
@@ -30,22 +32,51 @@ const wrappers=[/^uv run(?: --(?:frozen|locked|no-sync|offline|quiet|all-extras|
 // ones that change files or install packages, and pytest's that run a set
 // chosen from its cache (--lf, --ff, --sw, --nf), show the cache, loop
 // (-f), rewrite snapshots or add to earlier coverage data, are not taken.
+// A quoted argument (`-m "not slow"`) is one argument, and may hold spaces
+// and parentheses, nothing a shell would expand. Options that only write a
+// report (JUnit XML, HTML, durations) are left out: they change no result,
+// and a report written into the checkout would be an input the run changes.
+const reportOption=/^--(?:junit-?xml|html|self-contained-html|durations|durations-min|junit-prefix|report-log)(?:=|$)/;
+const reportValue=/^--(?:junit-?xml|html|durations|durations-min|junit-prefix|report-log)$/;
+function words(text){
+  const out=[];let current=null,quote=null;
+  for(const c of text){
+    if(quote){if(c===quote)quote=null;else current+=c;continue;}
+    if(c==='"'||c==="'"){quote=c;current??='';current+=`\u0000`;continue;}
+    if(c===' '){if(current!==null)out.push(current);current=null;continue;}
+    current=(current??'')+c;
+  }
+  if(quote)return null;
+  if(current!==null)out.push(current);
+  // A quoted word is marked with NUL while it is read: its text must be plain.
+  return out.map(word=>word.includes('\u0000')?{quoted:true,text:word.replaceAll('\u0000','')}:{quoted:false,text:word});
+}
 export function toolArgs(line,{tool,sub}){
   let text=line.trim().replace(/^-\s+/,'').replace(/^run:\s*/,'').replace(/^[@-]+/,'');
   text=text.split(/\s(?:&&|\|\||;|\|)\s/)[0].replace(/\s+/g,' ').trim();
   for(let changed=true;changed;){changed=false;for(const wrapper of wrappers)if(wrapper.test(text)){text=text.replace(wrapper,'');changed=true;}}
-  const words=text.split(' ');
-  if(words[0]!==tool||JSON.stringify(words.slice(1,1+sub.length))!==JSON.stringify(sub))return null;
-  const args=words.slice(1+sub.length);
-  if(args.some(arg=>!/^[A-Za-z0-9_./:=,@+%-]+$/.test(arg)||/^--(?:fix|unsafe-fixes|write|install-types|watch|lf|last-failed|ff|failed-first|sw|sw-skip|sw-reset|stepwise|stepwise-skip|stepwise-reset|nf|new-first|cache-show|looponfail|snapshot-update|update-snapshots|inline-snapshot|cov-append)(?:=|$)/.test(arg)||arg==='-f'||arg.startsWith('..')||arg.startsWith('/')))return null;
+  const parsed=words(text);
+  if(!parsed)return null;
+  const names=parsed.map(word=>word.text);
+  if(parsed.slice(0,1+sub.length).some(word=>word.quoted)||names[0]!==tool||JSON.stringify(names.slice(1,1+sub.length))!==JSON.stringify(sub))return null;
+  const given=parsed.slice(1+sub.length);
+  if(given.some(({quoted,text:arg})=>!(quoted?/^[A-Za-z0-9_./:=,@+% ()-]+$/:/^[A-Za-z0-9_./:=,@+%-]+$/).test(arg)||
+    /^--(?:fix|unsafe-fixes|write|install-types|watch|lf|last-failed|ff|failed-first|sw|sw-skip|sw-reset|stepwise|stepwise-skip|stepwise-reset|nf|new-first|cache-show|looponfail|snapshot-update|update-snapshots|inline-snapshot|cov-append)(?:=|$)/.test(arg)||
+    arg==='-f'||arg.startsWith('..')||arg.startsWith('/')))return null;
+  const args=[];
+  for(let i=0;i<given.length;i++){
+    if(reportOption.test(given[i].text)){if(reportValue.test(given[i].text))i++;continue;}
+    args.push(given[i].text);
+  }
   return args;
 }
 // The places a project writes how it runs its tools, in order of preference.
+// A workflow that runs on pull requests is marked `pr`.
 function scriptTexts(root){
   const texts=[];
   const workflows=path.join(root,'.github','workflows');
   let files=[];try{files=fs.readdirSync(workflows).filter(file=>/\.ya?ml$/.test(file)).sort();}catch{}
-  for(const file of files)texts.push(read(path.join(workflows,file)));
+  for(const file of files){const text=read(path.join(workflows,file));texts.push({text,pr:/\bpull_request(?:_target)?\b/.test(text)});}
   for(const file of ['Makefile','makefile','justfile','tox.ini','noxfile.py'])texts.push(read(path.join(root,file)));
   // Shell scripts: *.sh, or a file whose #! line runs a shell (scripts/check).
   for(const dir of ['scripts','script','bin','ci']){let names=[];try{names=fs.readdirSync(path.join(root,dir)).sort();}catch{}
@@ -53,13 +84,24 @@ function scriptTexts(root){
       if(name.endsWith('.sh')||/^#!\S*(?:\/|env\s+)(?:ba|z|da)?sh\b/.test(text))texts.push(text);}}
   return texts;
 }
-// The arguments the project runs `tool` with, or its default.
+// The arguments the project runs `tool` with, or its default: the first line
+// that runs it, but a pull-request workflow's when it narrows the suite (-m,
+// -k, --ignore, --deselect), as a project's quick tests leave out slow ones.
+// A line continued with a backslash is one line.
+const narrows=args=>args.some(arg=>/^(?:-m|-k|--ignore|--ignore-glob|--deselect)(?:=|$)/.test(arg));
 export function projectArgs(root,spec,texts=scriptTexts(root)){
-  for(const text of texts)for(const line of text.split(/\r?\n/)){
-    if(/^\s*#/.test(line))continue;
-    const args=toolArgs(line,spec);
-    if(args)return {args,source:'project'};
+  let first=null;
+  for(const entry of texts){
+    const {text,pr}=typeof entry==='string'?{text:entry,pr:false}:entry;
+    for(const line of text.replace(/\\\r?\n[ \t]*/g,' ').split(/\r?\n/)){
+      if(/^\s*#/.test(line))continue;
+      const args=toolArgs(line,spec);
+      if(!args)continue;
+      if(pr&&narrows(args))return {args,source:'project'};
+      first??={args,source:'project'};
+    }
   }
+  if(first)return first;
   if(spec.tool!=='mypy')return {args:[],source:'default'};
   // mypy without targets needs `files` in its configuration.
   const configured=[section(read(path.join(root,'pyproject.toml')),'[tool.mypy]'),section(read(path.join(root,'mypy.ini')),'[mypy]'),
@@ -83,7 +125,7 @@ export function discoverPythonProject(root){
     const several=found.filter(other=>other.kind===spec.kind).length>1;
     checks.push({config:{name:several?`${spec.kind}:${spec.tool}`:spec.kind,kind:spec.kind,qualification:sandboxQualification,
       command:[`.venv/bin/${spec.tool}`,...spec.sub,...args],...sandboxCheckInputs()},level:'ready',qualification:sandboxQualification,
-      reason:`sandboxed recipe: ${[spec.tool,...spec.sub,...args].join(' ')} from .venv${source==='project'?' as the project runs it':''}; the whole checkout is its input`});
+      reason:`sandboxed recipe: ${[spec.tool,...spec.sub,...args].map(arg=>/\s/.test(arg)?JSON.stringify(arg):arg).join(' ')} from .venv${source==='project'?' as the project runs it':''}; the whole checkout is its input`});
   }
   return {root,checks,skipped};
 }