@redue/cli 0.1.0-alpha.22 → 0.1.0-alpha.24

package/CHANGELOG.md

@@ -1,5 +1,73 @@
 # Changelog
 
+## 0.1.0-alpha.24 — 2026-10-28
+
+Checks keep working after a normal `npm install`, and agents that chain an
+edit and a check get the same skip-or-record as a check run on its own.
+
+- **Hard-linked installed files.** Without a pnpm store, any installed file
+  with a second hard link made a recorded run UNVERIFIED. esbuild's install
+  makes one (npm, not Yarn or Windows), so after an ordinary `npm install`
+  general-recipe and test checks in projects with esbuild stayed
+  UNVERIFIED. Such a file is now accepted when every one of its links is an
+  installed file the check observes; its link count is checked again before
+  every answer, so a link added later is noticed.
+- **Checks inside a chain.** In a simple chain (`printf ... >> README.md &&
+  npm run lint`), the Claude Code hook rewrites each check to the new
+  `redue run CHECK --if-due`, which skips the check when its last pass still
+  applies at that moment and otherwise runs it through REDUE with the same
+  exit code. The hook changes the command without approving it, so your
+  permission rules still apply. Chains with subshells, substitutions,
+  here-documents, background jobs, shell keywords or builtins before a check
+  run untouched.
+- The CLAUDE.md section asks agents to run each check as a command of its
+  own. Setups from earlier alphas are recognized and updated.
+- The README's coverage numbers now come from a census that installs with
+  dependencies' install scripts on, as users do: of 120 public TypeScript
+  repositories, 86 installed and 30 have a qualifying check (typecheck 21,
+  lint 18, tests 2).
+- Known limit, unchanged: a Vitest run writes under `node_modules/.vite`,
+  which makes a direct TypeScript typecheck STALE until it runs again.
+
+- Contributors: census `--install-scripts`; the stranger test can install
+  from npm (`--npm`) and run a follow-up session that uses the hooks.
+
+## 0.1.0-alpha.23 — 2026-10-26
+
+One command to set up REDUE with Claude Code, and one to undo it.
+
+- **`redue setup claude`** runs `init` (when there is no
+  `redue.config.json`), connects Claude Code, starts the observer, waits for
+  it to index the project, and records each check that can qualify once. It
+  asks once (`--yes` for no prompts), prints every file it writes, and a
+  second run changes nothing. It stops before writing when dependencies are
+  not installed or nothing can be set up.
+- **`redue remove`** undoes exactly what setup created: the integration (or
+  only this machine's hooks), the observer state, the local ignore line, and
+  the config if it is unchanged since setup wrote it. Anything that existed
+  before setup stays. Setup notes what it created in the clone's Git
+  directory, never in a committed file.
+- **Hooks find REDUE.** The Claude Code hooks name plain `redue` only when
+  the `redue` that your shell and a login shell find is this install;
+  otherwise they name this install's Node and entry by absolute path, so a
+  Claude Code started from an IDE or with a shorter PATH still runs it.
+  Checks the hook runs for the agent follow the same rule.
+- `init` keeps a typecheck that runs TypeScript 7's `tsc` (or `tsgo` from
+  `@typescript/native-preview`) recording-only and says why. The pnpm and
+  Yarn TypeScript recipes refuse TypeScript 7 with a clear reason instead
+  of an error from inside the compiler API.
+- The README is rewritten around a 5-minute quickstart, what REDUE covers
+  today (census qualifiers) and what it won't do.
+- Known limits, found by the stranger test: a Vitest run writes under
+  `node_modules/.vite`, which makes a direct TypeScript typecheck STALE until
+  it runs again; an installed file with a second hard link (esbuild's install
+  makes one) keeps the test check UNVERIFIED.
+
+- Contributors: the census can run every recipe (`--all-recipes`) and
+  counts direct TypeScript checks; its unrecorded-program check no longer
+  flags Yarn's temporary `node` wrapper; `eval/stranger.mjs` runs fresh
+  Claude Code sessions that set REDUE up from the README alone.
+
 ## 0.1.0-alpha.22 — 2026-10-25
 
 A correctness fix for recorded runs. Earlier alphas could report CURRENT for

package/README.md

@@ -1,229 +1,145 @@
 # REDUE
 
-Maintainer notice: alpha.4 withdraws automatic npm-launcher applicability.
-Npm commands still execute and record historical outcomes, but remain UNVERIFIED.
-[Why this changed and how to upgrade without deleting receipts](docs/user/npm-launcher-notice.md).
-Alpha.2 users should also review the [receipt correction](docs/user/receipt-selection-notice.md).
+**Know which checks still hold. Redo what's due.**
 
-**Know what still holds. Redo what's due.**
+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.
 
-You ran the checks. Then the code changed—or a new coding agent started with no
-conversation history. Which results can you still use?
+## Quickstart (about 5 minutes)
 
-REDUE keeps persistent verification state for your codebase so developers and
-coding agents can see which previous checks still apply to the code they have now.
-It records evidence, not proofs of correctness.
-
-For a qualified direct-compiler or supported Yarn/pnpm check (ordinary npm scripts are recording-only):
-
-```text
-$ redue status --sync
-✓ typecheck  CURRENT / PASS
-? test  UNVERIFIED / PASS
-  Recording-only: test runtime, transforms and cache inputs need review
-
-# Later, after a relevant edit:
-$ redue explain typecheck
-typecheck: STALE / PASS
-src/main.ts changed
-Relevant inputs changed:
-  src/main.ts
-Due again when verification is needed: redue run "typecheck"
-```
-
-Agent A verifies and exits. Agent B starts fresh. The receipt is still there;
-REDUE checks whether it still applies. Unrelated documentation edits can preserve
-it; relevant source edits make it stale. [Run the reproducible demo](docs/contributor/demo.md).
-
-## Install the alpha
-
-The opt-in pilot uses **0.1.0-alpha.18**. Follow the
-[fixed-version pilot guide](docs/user/pilot.md) for supported projects, setup,
-updates and voluntary feedback. No external usage results are claimed yet.
-
-
-REDUE is published on npm as `@redue/cli`. The installed command is `redue`.
+You need macOS or Linux, Node 22 or 24, Git, Claude Code, and a JavaScript or
+TypeScript project with its dependencies installed (`npm install`,
+`pnpm install` or `yarn`). On Linux, also Python 3.
 
 ```sh
 npm install --global @redue/cli@alpha
+cd your-project
+redue setup claude
 ```
 
-To test a source candidate, run `npm ci` and `npm pack --json`, then install the
-reported tarball filename with `npm install --global ./<filename>`.
-
-Use a Node installation you own; REDUE does not need administrator privileges.
-If a global prefix is not writable, use a user-owned `--prefix` or run the
-installed CLI with Node. [Installation and removal](docs/user/getting-started.md)
-includes PowerShell and isolated-prefix instructions.
-
-Inside an existing, trusted Git project with dependencies already installed:
-
-```sh
-cd my-project
-redue init
-redue start
-redue run typecheck  # use a check name printed by init
-redue status
-```
+`setup` shows what it will do and asks once (`--yes` skips the question). It
+stops before writing anything if the dependencies are not installed. It:
 
-`init` discovers existing scripts, explains which can qualify and which are
-recording-only, and writes a small `redue.config.json`. It never runs your checks
-or changes your package manager, source, scripts, or dependencies. Commit the
-reviewed project config; local evidence stays outside the checkout.
+- finds your typecheck, lint and test scripts and writes `redue.config.json`
+  (it never changes your scripts, source or dependencies). Checks REDUE can
+  only record, not reuse, are listed as recording-only;
+- connects Claude Code: a short section in `CLAUDE.md`, a skill, and two hooks
+  in `.claude/settings.local.json`;
+- 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;
+- prints every file it writes. Running it again changes nothing.
 
-Start with ordinary `status`. When it cannot establish caller context, use
-`redue status --sync` if that is worthwhile—or just rerun an inexpensive check.
-**Synchronization can cost more than rerunning a cheap check, particularly on
-Windows.** REDUE does not choose or execute that tradeoff for you.
+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.
 
-`init` tries the strict recipes first: the [direct compiler recipe](docs/user/direct-typescript.md)
-for npm typechecks, the pnpm and Yarn TypeScript recipes, and the
-[direct test recipe](docs/user/tests-direct.md). A root typecheck or lint
-script none of them takes can use the [general recipe](docs/user/node-script.md),
-which runs the script through the package manager and records every Node
-process; a script that starts another program (git, esbuild, turbo) stays
-UNVERIFIED and the reason names it. Test scripts use the direct test recipe
-(Vitest, Jest); other test scripts stay recording-only.
+To look yourself:
 
-## Connect your agent (experimental)
+```text
+$ redue status --sync
+✓ typecheck  CURRENT / PASS
+✓ lint  CURRENT / PASS
 
-```sh
-redue agent setup codex --dry-run
-redue agent setup codex --apply  # or claude
-redue agent doctor
+# after editing src/main.ts
+$ redue explain typecheck
+typecheck: STALE / PASS
+src/main.ts changed
+Due again when verification is needed: redue run "typecheck"
 ```
 
-Start a fresh agent session and give it an ordinary task. Project-local guidance
-teaches it to inspect evidence before deciding whether verification needs repeating.
-Setup is explicit, reversible, and does not change tool permissions or run checks.
-[Activation, removal, and generic-agent guidance](docs/user/agents.md).
-
-The experimental claim is **opt-in project-local agent activation and direct TypeScript
-evidence, with fresh-session reuse demonstrated in the tested Codex/macOS
-configuration and measured for Claude Code below**. Cross-host reuse is not
-tested. This is experimental guidance, not guaranteed agent compliance, general
-sandbox compatibility, or a promise of time savings.
-
-### Measured with Claude Code
-
-Four public TypeScript projects, four tasks each, three sessions per task with
-and without REDUE: 96 headless Claude Code sessions (Sonnet 5.5, CI Linux
-runner, alpha.12 code, October 2026). Plain `tsc --noEmit` takes 10–19 s on
-these projects. Medians per task, summed over the four projects:
-
-| Task | Session time, without → with REDUE | Input tokens | Typechecks skipped |
-|---|---|---|---|
-| Docs edit, then "make sure it still typechecks" | 97 → 45 s | 169k → 162k | 12 of 12 |
-| "Does it still typecheck?" after a pull | 74 → 22 s | 117k → 89k | 12 of 12 |
-| Source change, typecheck, then a docs edit | 141 → 112 s | 210k → 200k | 9 of 12 |
-| Source change with tests | 152 → 151 s | 269k → 234k | 0 of 12 |
-| **All tasks** | **464 → 330 s** | **765k → 685k** | 33 |
-
-- **Correctness:** every typecheck REDUE skipped was checked afterwards with
-  plain tsc on the exact tree it was skipped on. All 33 agreed, and all 96
-  final trees passed plain tsc and the task checks in both arms.
-- **Cost:** API cost was the same ($0.65 without, $0.66 with). One-time setup
-  per checkout was 3–5 s, plus one recorded typecheck; the CLAUDE.md section
-  REDUE adds is about 60 tokens.
-- **How:** each session gets a fresh clone at a pinned commit; the REDUE arm
-  first runs `redue init`, `agent setup claude`, `start` and one
-  `redue run typecheck`, standing for an earlier session's passing check.
-  The harness, tasks and raw results are in [`eval/`](eval/README.md).
-- **Limits:** four projects and three runs per cell show direction, not a
-  general rate. Savings come only when an earlier pass still applies: tasks
-  that change source code save nothing, and on one project the docs edit came
-  after source edits that made the result STALE, so nothing was skipped. The
-  projects were chosen because they qualify for the direct TypeScript recipe;
-  of 38 screened projects, 19 qualified at alpha.12 and 22 at alpha.13. Times are agent session
-  time only, on one runner type.
-
-### Unit tests, measured with Claude Code
-
-Three public projects (cheerio with Vitest 4, SwitchHosts with Vitest 5, twilio
-with Jest 29), four tasks each, three sessions per task with and without REDUE:
-72 headless Claude Code sessions (Sonnet 5.5, CI Linux runner, alpha.14 code,
-October 2026), using the opt-in [direct test recipe](docs/user/tests-direct.md).
-Medians per task, summed over the three projects:
-
-| Task | Session time, without → with REDUE | Input tokens | Test runs skipped |
-|---|---|---|---|
-| Docs edit, then "make sure the unit tests still pass" | 95 → 41 s | 131k → 121k | 9 of 9 |
-| "Do the unit tests still pass?" after a pull | 80 → 22 s | 62k → 63k | 9 of 9 |
-| Source change, tests, then a docs edit | 171 → 111 s | 224k → 213k | 3 of 9 |
-| Source change with tests | 169 → 120 s | 172k → 164k | 0 of 9 |
-| **All tasks** | **515 → 295 s** | **589k → 559k** | 21 |
-
-- **Correctness:** every skipped test run was rerun plainly three times on the
-  exact tree it was skipped on; all 21 passed every time. All 72 final trees
-  passed the tests and the task checks in both arms.
-- **Limits:** one run of three projects shows direction, not a rate. The
-  source-change task skipped nothing; its time difference is session variance.
-  In two mixed-task sessions the agent left out its final test run on its own
-  after a README-only edit, without asking REDUE, and said so; the eval report
-  lists such sessions. Since alpha.15 the agent instructions ask agents to run
-  the check and leave skipping to REDUE; in a 12-session rerun of that task,
-  no agent left it out. Cost was the same ($0.54 without, $0.56 with).
+`--sync` checks the files and your environment before it answers; this is
+what the agent asks. Plain `redue status` is a fast cached answer and can say
+UNVERIFIED ("cannot confirm your execution context") where `--sync` would say
+CURRENT.
+
+To undo everything setup did: `redue remove`.
+
+## What it covers today
+
+In a census of 120 active public TypeScript repositories (October 2026, REDUE
+at commit 0fcd19b, after 0.1.0-alpha.23), each installed as its users would,
+with dependencies' install scripts on, 86 installed cleanly. A check counts
+when two recorded runs on the same code both came out CURRENT on the same
+inputs. 30 repositories had at least one such check:
+
+| Check | Repositories | How |
+|---|---|---|
+| Typecheck | 21 | 15 by running the project's script with every Node process recorded ([general recipe](docs/user/node-script.md)); 6 by running the local `tsc` directly ([direct recipe](docs/user/direct-typescript.md)) |
+| Lint | 18 | general recipe |
+| Tests | 2 | Vitest run directly ([direct test recipe](docs/user/tests-direct.md)) |
+
+Everything else stays UNVERIFIED, with a reason you can read in
+`redue explain`. The usual ones: a script starts a program REDUE cannot see
+into (esbuild, turbo, nx, oxlint's tsgolint, TypeScript 7's native compiler),
+the project uses Bun, or a test suite writes into its own inputs. One you may
+meet right after setup: a Vitest run writes its results under
+`node_modules/.vite`, which the direct TypeScript recipe counts as an
+installed input, so the typecheck turns STALE until it runs again.
+[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
+  run are unchanged, not that the code works. A failure stays a failure.
+- **Run checks for you.** Nothing runs in the background; checks run when you
+  or the agent run them.
+- **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).
 
 ## What the states mean
 
-| State | Meaning | Normal next step |
+| State | Meaning | Next step |
 | --- | --- | --- |
-| CURRENT | The recorded result applies to the declared inputs. | Reuse a passing result; do not rerun merely for freshness. |
-| STALE | Relevant inputs changed since the recorded result. | Rerun when verification is needed. |
-| UNVERIFIED | Applicability is unknown: no receipt, incomplete coverage, pending observation, or missing context. | Read the reason; synchronize if worthwhile, or run the check. |
-| FAILED | The invocation failed. Its applicability is tracked separately. | Keep the failure visible; it is not green evidence. |
-
-A historical PASS remains PASS when stale or unverified. A historical failure
-never becomes a successful check. CURRENT does not mean every product behavior
-has been verified.
-
-## Supported alpha path
-
-- macOS, Linux, and Windows on supported local filesystems; Node 22+.
-- Linux also requires Python 3 for observation. No WSL or Git Bash needed on Windows.
-- npm, pinned Yarn `node-modules`, and pinned pnpm 12 isolated/hoisted layouts.
-- Automatic qualification for supported Yarn/pnpm TypeScript invocations; ordinary npm
-  launcher checks remain recording-only. Explicitly select the
-  [direct local compiler recipe](docs/user/direct-typescript.md) for the reviewed
-  npm/TypeScript boundary. Workspace
-  boundaries follow the files actually consumed, including built declarations.
-- Opt-in [direct test recipe](docs/user/tests-direct.md) for Vitest 4/5 and
-  Jest 29 in single-package npm projects on macOS and Linux.
-- Other test/lint/build and arbitrary commands can record results while
-  their applicability remains unqualified.
-
-The [supported-project boundary](docs/user/supported-projects.md) is deliberately
-narrow. A script named `test` is not automatically a complete test contract.
-
-## Alpha limitations
-
-- REDUE records evidence; it does not prove correctness.
-- Direct commands outside `redue run` do not create receipts.
-- Some tests, lints, and builds remain UNVERIFIED/PASS because their input contract is incomplete.
-- Synchronized applicability has nontrivial cost and can lose to an inexpensive rerun.
-- Unsupported/exotic install layouts and filesystems remain conservative; they do not become green through guesses.
-- No cloud/team synchronization, IDE extension, or automatic background check execution.
-- Alpha configuration and APIs may evolve. Neither cached nor synchronized status is an atomic snapshot against concurrent edits.
-
-## Humans, shells, and agents
+| CURRENT | The recorded result applies to the code as it is now. | Reuse a pass; no need to rerun. |
+| 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. |
+
+## Without Claude Code, or step by step
 
 ```sh
-redue explain typecheck          # synchronized explanation; may run read-only probes
-redue status --json              # conservative cached data
-redue status --sync --json       # caller-aware decision
-redue status --short             # small cached indicator; never synchronizes
-redue stop                      # retains historical receipts
-redue remove-state              # removes only this config's owned local state
+redue init          # write redue.config.json from your scripts
+redue start         # start the file observer
+redue run typecheck # run a check through REDUE and record the result
+redue status --sync # what still holds
 ```
 
-Agents should use [the documented JSON interface](docs/user/json.md), not parse
-terminal prose. [The canonical agent loop](docs/user/agents.md) keeps the
-sync-versus-rerun choice explicit. [Shell usage](docs/user/shell.md) does not put
-synchronized work in a prompt.
+Codex is supported too (`redue agent setup codex --apply`); see
+[agents](docs/user/agents.md). Agents should read
+[the JSON interface](docs/user/json.md), not the terminal text.
 
-[User docs](docs/README.md) · [Contributing](CONTRIBUTING.md) ·
-[Architecture](docs/contributor/architecture.md) · [Acceptance evidence](docs/acceptance/README.md)
+[Getting started](docs/user/getting-started.md) · [User docs](docs/README.md) ·
+[Contributing](CONTRIBUTING.md) · [Architecture](docs/contributor/architecture.md)
 
 ## License
 
-REDUE is licensed under [Apache-2.0](LICENSE). Dependencies retain their own licenses.
+REDUE is licensed under [Apache-2.0](LICENSE). Dependencies keep their own licenses.

package/bin/redue.mjs

@@ -28,6 +28,9 @@ const help=`REDUE ${version}
 Usage: redue [--config FILE] [--state-dir DIR] COMMAND [OPTIONS]
 
 Commands:
+  setup claude [--yes] Set up REDUE and Claude Code in this project in one step:
+                       init, agent setup claude, start, one recorded run per check
+  remove [--yes]       Undo setup: integration, observer state, and the config setup created
   init [--dry-run] [--workspace NAME] [--check KIND] [--recipe typescript-direct|tests-direct|node-script]
                        Discover existing scripts; optionally select one workspace/check
   agent setup codex|claude [--dry-run|--apply] [--json]
@@ -40,7 +43,8 @@ Commands:
   status --sync        Reconcile inputs and caller context before answering
   explain [CHECK] [--json] Explain applicability (synchronized; may cost more than a rerun)
   detail [CHECK] [--json]  Alias for explain
-  run CHECK            Execute one configured check and record its outcome
+  run CHECK [--if-due] Execute one configured check and record its outcome; with --if-due,
+                       only when its last pass does not apply to the files as they are now
   remove-state         Stop and remove only this configuration's owned local state
 
 No checks run in the background. Direct commands outside redue create no receipts.`;
@@ -58,7 +62,18 @@ if(args.length===3&&args[0]==='agent'&&args[1]==='hook'&&args[2]==='claude'){
   await runClaudeHook(fileURLToPath(import.meta.url));process.exit(0);
 }
 if(args.length===1&&args[0]==='--version'){console.log(version);process.exit(0);}
+// Internal: the entry this command runs, so setup and the hook can tell
+// whether the `redue` on PATH (a link, a package manager's shim, a wrapper)
+// is this install.
+if(args.length===1&&args[0]==='--entry'){console.log(fs.realpathSync(fileURLToPath(import.meta.url)));process.exit(0);}
 if(args.includes('--help')||args.includes('-h')||!args.length){console.log(help);await exit(0);}
+if(args[0]==='setup'||args[0]==='remove'){
+  // Loaded on demand; setup works before a config exists.
+  const {setupCommand}=await import('../src/setup.mjs');
+  try{await setupCommand(args,{entry:fileURLToPath(import.meta.url)});}
+  catch(e){error(e.message);}
+  await exit(0);
+}
 let configFile=null,stateOverride=null;
 for(let i=0;i<args.length;){
   if(args[i]==='--config'||args[i]==='--state-dir'){
@@ -82,6 +97,9 @@ if(command==='agent'){
 if(!['init','start','stop','status','detail','explain','run','remove-state'].includes(command))
   error(`unknown command ${command||'<none>'}; use --help`);
 const json=args.includes('--json');
+// run --if-due: run the check only when its last pass does not apply now.
+const ifDue=command==='run'&&args.includes('--if-due');
+if(ifDue)args.splice(args.indexOf('--if-due'),1);
 const sync=args.includes('--sync');
 const dryRun=args.includes('--dry-run');
 const short=args.includes('--short');
@@ -124,7 +142,7 @@ if(command==='init'){
     checks:discovery.checks.map(({config:check,level,reason})=>({name:check.name,
       script:check.script||null,command:check.command||null,
       workspace:check.workspace||null,level,reason})),config:configFile,
-    written:willWrite,existing:configured};
+    written:willWrite,existing:configured,writable:!configured&&!unsupported&&discovery.checks.length>0};
   if(!json) {
     console.log(`Node ${summary.node}; ${summary.package_manager||'unknown package manager'}`+
       `${summary.version?' '+summary.version:''}; ${summary.installation_layout} installation.`);
@@ -374,6 +392,20 @@ const internal=command==='remove-state'?'uninstall':
 // On macOS and Linux the engine runs in this process, which saves a Node startup
 // on every run; its own handlers receive SIGINT and SIGTERM. Windows keeps a
 // child engine because cancellation reaches it over IPC.
+// Asked when this part of a command runs, after earlier parts may have
+// changed files. REDUE_FORCE=1 runs it anyway.
+if(ifDue&&process.env.REDUE_FORCE!=='1'){
+  const {verdict}=await import('../src/claude-hook.mjs');
+  const asked=spawnSync(process.execPath,[fileURLToPath(import.meta.url),'--config',configFile,...(stateOverride?['--state-dir',stateOverride]:[]),
+    'status','--sync','--json'],{encoding:'utf8',stdio:['ignore','pipe','ignore'],env:process.env,timeout:600_000});
+  let status=null;try{status=JSON.parse(asked.stdout);}catch{}
+  if(verdict(status,check)){
+    const row=status.checks.find(item=>item.name===check);
+    if(json)console.log(JSON.stringify({check,skipped:true,result:'PASS',run_id:row.invocation.runId}));
+    else console.error(`REDUE: ${check} passed on these exact inputs (run ${row.invocation.runId}); not run again. REDUE_FORCE=1 runs it anyway.`);
+    await exit(0);
+  }
+}
 if(command==='run'&&process.platform!=='win32'){
   process.argv=[process.argv[0],engine,runtimeFile,internal,check,...(!json?['--human']:[])];
   await import(pathToFileURL(engine).href);

package/docs/user/agents.md

@@ -74,10 +74,37 @@ observer when a session starts (below); otherwise use `redue start`.
 
 ## Claude Code typecheck hook
 
-`redue agent setup claude --apply` also adds a PreToolUse hook and a
-SessionStart hook to `.claude/settings.local.json`. Both run
-`redue agent hook claude`, which needs a local REDUE install, so they are
-per-developer; keep that file out of commits. Other settings in the file are kept,
+`redue agent setup claude --apply` (and `redue setup claude`) also adds a
+PreToolUse hook and a SessionStart hook to `.claude/settings.local.json`.
+Both run `redue agent hook claude`, which needs a local REDUE install, so
+they are per-developer; keep that file out of commits. Setup names REDUE
+plainly only when the `redue` that both your shell and a login shell find on
+PATH is the install running setup. Otherwise the hooks name this install's
+Node and entry by absolute path, so a Claude Code started from an IDE, a
+desktop app or another shell still runs the right REDUE; run setup again
+after moving or upgrading Node. `redue agent doctor` reports a hook whose
+paths no longer exist. When the hook runs a check through REDUE for the
+agent, it likewise writes plain `redue run` only if its own PATH finds this
+install, else the absolute form.
+
+Agents often chain an edit and a check (`printf … >> README.md && npm run
+lint`). In a simple chain (commands joined by `&&`, `||` or `;`, with no
+subshell, here-document, command substitution, background job or shell
+keyword) where every part before a check is a program on PATH (not a
+builtin such as `cd` or `export`, a shell function such as `nvm`, or a bare
+assignment), the hook rewrites each check to `redue run CHECK --if-due`. That
+command decides when its turn comes, after the earlier parts may have
+changed files: it skips the check (exit 0, and says so) when its last pass
+still applies, and otherwise runs it through REDUE with the exit code a plain
+run gives. A script that runs several checks becomes `{ redue run a --if-due
+&& redue run b --if-due; }`. The rest of the chain is unchanged. The hook
+rewrites only while the observer is healthy and knows each check. It changes
+such a command without approving it, so your permission rules apply to the
+rewritten command; a rule that allows only `npm run lint` will ask about
+`redue run lint --if-due`. Anything more complex runs untouched. Known
+limit: if REDUE cannot start the check when its turn comes (another
+`redue run` holds the project's run lock), that part exits with REDUE's
+error instead of running the check. Other settings in the file are kept,
 but the file is rewritten as 2-space JSON. `.claude/settings.json` is not touched.
 `redue agent remove claude --apply` removes only the entries REDUE added.
 

package/docs/user/direct-typescript.md

@@ -7,7 +7,9 @@ not mean npm or npm lifecycle scripts completed.
 For a supported single-package npm project with a typecheck script of `tsc`
 runs (see [script forms](#script-forms)) or no typecheck script and a root
 `tsconfig.json`, installed dependencies, Node 22/24 and TypeScript 5.x or 6.0
-(see [compiler identity](#compiler-identity)):
+(see [compiler identity](#compiler-identity)). TypeScript 7 is a native
+compiler this recipe cannot run: `init` refuses it
+(`direct-typescript-version-unsupported`):
 
 ```sh
 redue init --recipe typescript-direct --check typecheck --dry-run

package/docs/user/getting-started.md

@@ -67,7 +67,26 @@ the package alone does not update project instructions.
 
 ## First project
 
-From the project root:
+With Claude Code, one command does the steps below and connects the agent:
+
+```sh
+redue setup claude          # asks once; --yes for no prompts
+```
+
+It runs `init` when the project has no `redue.config.json`, `agent setup
+claude`, and `start`, then records each check that can qualify once, unless
+it is already CURRENT. It prints every file it writes, and running it again
+changes nothing that is already set up. When `.claude/settings.local.json`
+is not ignored by Git, it adds it to `.git/info/exclude`; it refuses when
+that file is committed. What setup created is noted in the clone's Git
+directory (`.git/redue-setup-<id>.json`, never committed). `redue remove`
+undoes exactly that: the integration (or only this machine's hooks, when the
+integration was already in the project), the observer and its state
+(receipts included), the local ignore line, and the config if setup wrote it
+and it has not been edited since. A config or observer state that existed
+before setup stays. `remove` asks before it deletes; Enter means no.
+
+Step by step, from the project root:
 
 ```sh
 redue init --dry-run

package/docs/user/node-script.md

@@ -113,7 +113,10 @@ one REDUE can account for:
 
 A process that replaces itself with another program through
 `process.execve` (TypeScript 7's `tsc` does this to start its native
-compiler) is judged the same way as a program it starts.
+compiler) is judged the same way as a program it starts. `init` reads
+TypeScript 7's launchers (`tsc` from `typescript@7`, `tsgo` from
+`@typescript/native-preview`) as that native compiler and keeps such a script
+recording-only.
 
 Anything else makes the result UNVERIFIED and names the program: `git`,
 `sleep`, `find`, and native programs from installed packages such as esbuild,

package/docs/user/supported-projects.md

@@ -83,7 +83,11 @@ entries stay inputs: an import can still reach an excluded file); a file the
 program reads outside them keeps the check recording-only. This avoids pnpm's task-run bookkeeping
 writes during `pnpm run`; it does not alter the project's script. Test, lint,
 build, and ambiguous TypeScript scripts still execute through `pnpm run`; root
-typecheck and lint ones can use the [general recipe](node-script.md). The generated `@typescript-bin:WORKSPACE` token resolves
+typecheck and lint ones can use the [general recipe](node-script.md). The pnpm
+and Yarn TypeScript recipes read TypeScript's compiler API, which TypeScript 7
+does not ship: with TypeScript 7 installed they refuse and say so. The
+general recipe runs such a script, but TypeScript 7's native compiler is a
+program REDUE does not record, so the result is UNVERIFIED. The generated `@typescript-bin:WORKSPACE` token resolves
 the local compiler when the check runs; it is not an absolute machine path.
 
 The pnpm contract indexes consumed installed package contents inside the