@redue/cli 0.0.0-stage → 0.1.0-alpha.11

package/CHANGELOG.md

@@ -0,0 +1,181 @@
+# Changelog
+
+## 0.1.0-alpha.11 — 2026-10-18
+
+Bench numbers below are from one 800-file project on macOS arm64, Node 22.13.0.
+Released alpha.10 and this build ran back to back on the same machine.
+
+- Faster status decisions for the direct TypeScript recipe on macOS and Linux.
+  The observer checks the compiler's recorded filesystem questions in-process
+  instead of starting a probe that rebuilds the whole program. A full probe runs
+  only when that check fails, the plan or toolchain changes, or observation was
+  interrupted. While idle it no longer starts any probe process.
+  - warm `status --sync`: 741 → 194 ms (+683 → +154 ms over cached `status`)
+  - `status --sync` after an unrelated edit: 619 → 219 ms
+  - `status --sync` after a relevant edit: 1472 → 321 ms. It answers STALE without
+    a full probe when the edited inputs already differ from the receipt.
+  - probe processes started in 20 s idle: 4 → 0
+- Cheaper `redue run` on macOS and Linux. The compiler records its own inputs
+  while it runs, so REDUE no longer probes before and after the compile. After
+  a relevant edit, the run builds the new certificate from that recording instead
+  of running a full probe. Output and exit code are those of plain `tsc`.
+  - repeat run: 4143 → 2752 ms, overhead over plain `tsc` 72% → 16%
+  - run right after a relevant edit: 3990 → 2802 ms, overhead 65% → 18%
+- The direct TypeScript recipe accepts inert Node settings. Before, any non-empty
+  `NODE_*` setting other than `NODE_ENV` kept a check from becoming CURRENT.
+  Now accepted: `NODE_EXTRA_CA_CERTS`, `NODE_PATH`, and `NODE_OPTIONS` made only of
+  `--max-old-space-size`, `--max-semi-space-size`, `--use-openssl-ca`,
+  `--use-bundled-ca`, `--use-system-ca` and `--dns-result-order`. A run under one
+  value is not reused under another. See [Node settings](docs/user/direct-typescript.md#node-settings).
+- `redue agent setup claude --apply` adds a Claude Code hook to
+  `.claude/settings.local.json`. When the agent reruns a configured typecheck
+  that is CURRENT and PASS, the hook blocks it and names the passing run. When
+  the check is not CURRENT, it rewrites the command to `redue run CHECK`, so the
+  result is recorded and the next identical command can be skipped. Prefix a
+  command with `REDUE_FORCE=1` to always run it. On the bench: a skip decision
+  takes about 155 ms; a forced command adds 39 ms. Tested live with Claude Code
+  2.1.302 (`claude -p`). See [the hook](docs/user/agents.md#claude-code-typecheck-hook).
+- Unstable-run and observation-gap reasons now name the failed check or operation.
+- macOS counts each input event once, which removes an intermittent UNVERIFIED
+  after an edit.
+
+Known limits:
+
+- Two bench targets are still missed: warm sync adds 154 ms over cached status
+  (target < 100 ms), and `redue run` adds 16–18% over plain `tsc` (target < 10%).
+- An edit that changes imports, configuration or lib files still costs one full
+  probe, at the end of the next run.
+- Windows keeps the earlier probe-based path, except the STALE shortcut. Yarn
+  and pnpm recipes still probe on each decision. The bench was not run on Linux.
+- The Claude hook covers the Bash tool only, from the project root. It allows the
+  rewritten command without a permission prompt. It judges its own environment,
+  not variables the Bash tool adds from your shell profile.
+- To upgrade, stop observers, install into the same prefix, and keep config, state
+  and receipts. Rerun `redue agent setup claude --apply` to add the hook.
+
+## 0.1.0-alpha.10 — 2026-10-10
+
+- Combine guarded caller-discovery reuse and cheaper non-reusable recording on
+  the existing macOS direct-TypeScript path. Healthy runs still validate both
+  boundaries in the caller context, falling back to full probes when necessary.
+- Once a healthy start observation is missing, omit qualification-only work that
+  cannot repair it. Execute the configured compiler and durably record its true
+  outcome; later observer recovery cannot make that invocation reusable.
+- Refuse missing, malformed or mismatched state ownership before execution.
+  Preserve cancellation, immutable history and newest-receipt selection.
+- Three fixed A–H cycles cost 15.16/15.35/15.82 seconds versus matched ordinary
+  compiler totals of 16.69/16.66/16.56 seconds. These modest CLI savings do not
+  establish real-world reuse frequency, CPU/memory or whole-agent benefit.
+- Provide a [fixed-build opt-in pilot guide](docs/user/pilot.md). External usage
+  has not started. No compiler/platform expansion or policy redesign is included;
+  Claude behavior and cross-host handoff remain untested.
+- Stop observers before upgrading in the same prefix, preserve config/state and
+  receipts, preview/apply project-local policy updates, then restart and reassess.
+  Never silently migrate a check. Alpha.9 remains an unshipped candidate.
+
+## 0.1.0-alpha.9 — unshipped candidate (2026-10-09)
+
+- Reduce repeated caller discovery on the guarded macOS direct-TypeScript path.
+  Both execution boundaries still validate in the actual caller environment,
+  with full-probe fallback when a discovery certificate cannot be used.
+- Preserve required content/membership, compiler/context, observation and durable
+  receipt-selection guards. The configured compiler still executes on every run.
+- Recording overhead fell in the measured debugger-project sample, but every
+  complete A–H candidate cycle remained slower than eight ordinary compiler runs.
+  No net workflow saving, broader support or CPU/memory improvement is claimed.
+- Stop observers before upgrading in the existing prefix, retain config/state
+  and receipts, then restart. No automatic migration is performed.
+
+## 0.1.0-alpha.8 — 2026-10-08
+
+- Consume compiler-certificate input asynchronously while preserving the input-size
+  limit, parent deadline, complete-input validation and conservative fallbacks.
+- Support the exact reviewed TypeScript 5.5.2 distribution in the explicitly selected
+  single-package npm direct-compiler recipe. Enforce implementation membership and
+  reject ETW module overrides before compiler API loading.
+- Real independent Codex/macOS sessions reused compiler evidence on the pinned
+  vscode-js-debug project. Cross-platform CLI/package acceptance is separate;
+  Claude behavior and cross-host handoff remain untested.
+- The measured eight-case workflow avoided four compiler executions but cost
+  20.01 seconds versus 16.97 seconds for eight ordinary compiler runs. No net
+  workflow or whole-agent speedup is claimed. This verifies compiler inputs only,
+  not npm lifecycle behavior or application correctness.
+- Stop observers before upgrading, retain the same configuration/state, then
+  restart. Do not delete receipts or automatically convert existing checks.
+
+## 0.1.0-alpha.7 — 2026-10-07
+
+- Guide explicitly configured direct-compiler reuse through one caller-aware
+  synchronized query; skip reuse queries when fresh execution is already required.
+- Update intact project-local agent instructions safely; installation alone does
+  not update them. See the [existing-user procedure](docs/user/agents.md#update-an-existing-connection).
+- In the finite Codex/macOS comparison, revised guidance reached eligible evidence
+  and reused it in 4/4 opportunities versus 1/4; verification tool calls fell
+  from 28 to 14. Evidence semantics are unchanged. No universal compliance,
+  tail-latency or causal agent-task speedup is claimed. Claude behavior and
+  cross-host handoff remain untested.
+
+## 0.1.0-alpha.6 — 2026-10-07
+
+- Reuse guarded compiler discovery for warm direct-TypeScript decisions on macOS
+  with healthy historical observation. Membership, absence, compiler bytes,
+  caller context and receipt selection remain validated independently.
+- Keep full discovery/reconciliation fallbacks and existing platform boundaries.
+- On one measured project, complete warm decision median fell from roughly
+  791 to 474 ms. This is not a universal speedup, agent-task acceleration,
+  memory improvement, or a faster relevant-edit/rebuild claim.
+- Stop observers before upgrading and restart with the same config/state.
+  Preserve receipts; no configuration migration is performed.
+
+## 0.1.0-alpha.5 — 2026-10-07
+
+- Add opt-in project-local agent activation and direct TypeScript evidence, with
+  fresh-session reuse demonstrated in the tested Codex/macOS configuration.
+- Preserve ordinary npm execution as a separate, recording-only obligation.
+  Direct compilation requires explicit selection and a fresh baseline receipt.
+- Initial direct recipe supports reviewed TypeScript 5.6.3/5.9.3 in single-package
+  npm projects, with documented Node/environment restrictions.
+- Claude integration mechanics are tested; Claude behavior and cross-host reuse
+  remain untested. No universal compliance or inexpensive-check speedup is claimed.
+
+## 0.1.0-alpha.4 — 2026-10-07
+
+- Withdraw automatic npm-launcher applicability because update notifications consume
+  unobserved remote/cache/time state. Npm scripts still run and record outcomes.
+- Preserve historical PASS/FAIL and require stop/start when upgrading an observer.
+  Do not delete receipts. See the [maintainer notice](docs/user/npm-launcher-notice.md).
+- Supported Yarn/pnpm and explicit reviewed contracts are unchanged. No agent
+  activation or npm direct-compiler recipe is included in this correction.
+
+## 0.1.0-alpha.3 — 2026-10-06
+
+Install: `npm install --global @redue/cli@alpha`.
+
+- Fix selected execution outcomes remaining hidden behind an older observer/cache
+  after a missed reload notification. A newer failure must not leave an older
+  passing receipt eligible for reuse.
+- Withhold applicability during incomplete receipt persistence, unreadable or
+  changing selection, and client connections to an older observer.
+- Preserve immutable run history. Upgrade requires an observer stop/start;
+  receipts need not be deleted. See the [maintainer notice](docs/user/receipt-selection-notice.md).
+
+## 0.1.0-alpha.2 — 2026-10-06
+
+Install: `npm install --global @redue/cli@alpha`.
+
+- npm distribution moved to the product-owned `@redue/cli` package.
+- The executable remains `redue`; verification semantics and runtime code are unchanged.
+- Alpha.1 (`@msiric/redue`) remains available but is superseded by the canonical package.
+
+## 0.1.0-alpha.1 — 2026-10-06
+
+Install: `npm install --global @msiric/redue@alpha`. The command remains `redue`.
+
+- Persistent execution evidence with independent CURRENT, STALE, and UNVERIFIED applicability.
+- Node/TypeScript onboarding for npm, supported Yarn node-modules workspaces, and pnpm 12 isolated/hoisted layouts.
+- macOS, Linux, and Windows observation with conservative deterministic recovery.
+- Human status/explain output, JSON integration contract, and recording-only checks.
+- Standard npm tarball installation and scoped state cleanup.
+
+Known limitations include incomplete test/lint/build contracts, uncaptured direct
+commands, and synchronized decisions that can cost more than cheap checks. See README.

package/LICENSE

@@ -0,0 +1,180 @@
+Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -1,3 +1,163 @@
-# Temporary Holding Version
+# REDUE
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+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 what still holds. Redo what's due.**
+
+You ran the checks. Then the code changed—or a new coding agent started with no
+conversation history. Which results can you still use?
+
+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.11**. 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`.
+
+```sh
+npm install --global @redue/cli@alpha
+```
+
+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
+```
+
+`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.
+
+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.
+
+Since alpha.4, ordinary npm scripts are recording-only after
+[an npm launcher applicability gap](docs/acceptance/npm-launcher-boundary.md).
+A separate explicit [direct compiler recipe](docs/user/direct-typescript.md) can
+qualify supported npm typechecks. It does not claim that npm/lifecycle scripts ran.
+
+## Connect your agent (experimental)
+
+```sh
+redue agent setup codex --dry-run
+redue agent setup codex --apply  # or claude
+redue agent doctor
+```
+
+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**. Claude setup/removal mechanics are tested; Claude behavior and
+cross-host reuse are not. This is experimental guidance, not guaranteed agent
+compliance, general sandbox compatibility, or a promise of time savings.
+
+## What the states mean
+
+| State | Meaning | Normal 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.
+- Existing 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
+
+```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
+```
+
+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.
+
+[User docs](docs/README.md) · [Contributing](CONTRIBUTING.md) ·
+[Architecture](docs/contributor/architecture.md) · [Acceptance evidence](docs/acceptance/README.md)
+
+## License
+
+REDUE is licensed under [Apache-2.0](LICENSE). Dependencies retain their own licenses.