replume-cli 0.2.1 → 0.2.3

package/README.md

@@ -15,6 +15,8 @@ npm install -g replume-cli
 Cursor hooks are installed by `replume init --cursor`, or automatically when the project already has a `.cursor/` directory and you run `replume init`; otherwise Cursor agent steps will not be recorded in the ledger.
 Codex hooks are installed by `replume init --codex`, or automatically when the project already has a `.codex/` directory and you run `replume init`; finding `codex` on PATH alone does not install them. Otherwise Codex agent steps will not be recorded in the ledger. After installation, review and trust the hook definition with `/hooks` in Codex.
 
+Log in to your coding agent first; Replume watches the agent you already use and does not log in for you. Claude Code: run `claude` and type `/login`. Codex: run `codex login`.
+
 Create a disposable project in a scratch directory, then:
 
 ```sh
@@ -22,13 +24,13 @@ npm install -g replume-cli
 replume init
 ```
 
-Start your agent in that folder. That is the whole setup. `replume init` installs the hooks and writes `.replume/config` with `mode: auto`. The first thing you ask the agent is the task. You do not write a contract, confirm it, or make a setup commit.
+Start your agent in that folder. That is the whole setup. `replume init` installs the hooks and writes `.replume/config` with `mode: auto`. The first thing you ask the agent is the task. You do not write a contract or confirm it. If the project has no commit yet, make one first (`git add -A && git commit -m "initial"`): Replume compares the agent's work against it, and `replume init` reminds you when there is none.
 
 `replume init --approve` writes `mode: approve` and keeps the older path: `replume draft --task`, review, `replume confirm`, then `replume accept` after verify.
 
 Scenarios are optional. Without one, verify can PASS when all of these hold: the contract's `test_command` runs at least one test and passes; nothing is FAILED, EXTRA or TAMPERING; and the ledger has an agent session for the task with an event naming each changed file. Otherwise the file is `NOT CHECKED` and the verdict is `INCOMPLETE`, with the reason: "agent steps not observed" (no session for this task in the ledger) or "change not seen by hooks" (no event names the file). A manual edit made without hooks therefore gives `INCOMPLETE`. Scenarios listed in `must_check` are required.
 
-Optional: a scenario adds a stated behaviour check. A scenario is a command and an expected result. Its `declared_covers` is a declaration, not measured coverage. Add scenario files before `replume confirm`; a scenario added after confirmation is reported as TAMPERING. For example:
+Optional: a scenario adds a stated behaviour check. A scenario is a command and an expected result. Its `declared_covers` is a declaration, not measured coverage. With `replume init --approve`, add scenario files before `replume confirm`; a scenario added after confirmation is reported as TAMPERING. For example:
 
 ```sh
 cat > .replume/scenarios/add.yaml <<'YAML'
@@ -50,7 +52,16 @@ JS
 
 Cursor project hooks are installed by `replume init` only when `.cursor/` already exists in the project or `--cursor` is supplied. Codex project hooks follow the same opt-in rule with `.codex/` or `--codex`. The global install keeps `replume hook claude`, `replume hook cursor`, and `replume hook codex` available to hooks. A one-shot npx does not leave a persistent hook command. If npm returns 404, the package has not been published yet.
 
-To remove Replume's project hooks, run `replume init --remove-cursor-hooks` for Cursor. For Claude Code, edit the project's `.claude/settings.json` and remove only the `replume hook claude` entries, keeping any other hooks. `replume init` does not currently have a Claude hook removal flag.
+`replume report --json` prints the newest session's summary when there is no commit report to print; `--session <id>` names one. The summary has:
+- the status;
+- one failure class: `test_failed`, `setup`, `timeout`, `zero_tests`, `suite_shrank`, `policy`, `incomplete_events`, `incomplete`, or `stale_result` when the working tree changed after the report;
+- the failing test IDs;
+- the next step and its command;
+- the tree hash of the verified state.
+
+`replume report --agent` prints the same as a few plain `key: value` lines. Each intervention in a report also has a `Why:` line: which rule fired, why, and the next step.
+
+To remove Replume from a repository, run `replume uninstall`. It lists what it will remove and asks first (`--dry-run` only lists, `--yes` skips the question, `--keep-reports` keeps `.replume/reports/`). It takes only Replume's entries out of `.claude/settings.json`, `.codex/hooks.json`, `.cursor/hooks.json` and `.github/hooks/replume.json`, keeps your other hooks, and backs up each file first (`<file>.replume-backup-<time>`). A hook file left with nothing else in it is deleted. It also removes `.replume/` and the task-start snapshots (`refs/replume/auto/*`). It says whether `.replume/contract.yaml` is in git history, which keeps it after the folder is deleted. Hermes hooks live outside the repository (`~/.hermes/config.yaml`), so it names them and you remove them. The `replume` command itself stays installed (`npm uninstall -g replume-cli`).
 
 ## Reading the report
 
@@ -62,11 +73,32 @@ In a second terminal inside the project, run `replume watch` while the agent wor
 
 ## What stays on your machine / what can leave it
 
-The default Replume flow (`init`, `draft`, `confirm`, hooks, `verify`) makes no Replume-managed outbound request. Contract, events, report and scenario results stay local. Commands in your own repository, including test/scenario commands, can use the network themselves; inspect them before running. Docker scenario mode disables container networking; the isolated working copy does not.
+The default Replume flow (`init`, `draft`, `confirm`, hooks, `verify`) makes no Replume-managed outbound request of its own, except the model review at done described below, which is on by default in AUTO mode. Contract, events, report and scenario results stay local. Commands in your own repository, including test/scenario commands, can use the network themselves; inspect them before running. Docker scenario mode disables container networking; the isolated working copy does not.
+
+### What leaves your machine when review is on
+
+When the agent stops and the stop goes through, Replume starts a second agent CLI that is already installed and signed in here: Codex for a Claude Code session, Claude Code for Codex, Cursor, Copilot and Hermes, or the same CLI in a fresh session if only one is installed. `review: cli: claude` or `review: cli: codex` in `.replume/config` makes Replume use only that CLI (the default `auto` keeps this order), and if it is not installed or fails, the review does not run and no other CLI is tried. With `auto`, if the first CLI fails to run (for example it refuses the model set in its own config, or is not logged in), Replume tries the other installed CLI once (`review.model` is not passed to it; its `REPLUME_REVIEW_…_MODEL` variable is), and the report says which one failed and why. `review: model: <name>` passes that model name to the chosen CLI (`--model` for Claude Code, `-m` for Codex); `REPLUME_REVIEW_CLAUDE_MODEL` and `REPLUME_REVIEW_CODEX_MODEL` override it. That CLI sends one prompt to its own vendor (OpenAI for Codex, Anthropic for Claude Code) under your existing login and plan. The prompt holds the task text (up to 4,000 characters), the list of changed file paths (up to 200), the diff of the working tree against the task start (`.replume/`, `.claude/`, `.cursor/`, `.codex/` and `.github/hooks/` excluded, cut at 80,000 characters) and whether the diff was truncated, the test command, the last 4,000 characters of the test output Replume ran and the passed-test lines from it, and the names of protected files (up to 60). Secrets are redacted by pattern first, which is best effort. The CLI runs in an empty temporary directory with no tools, no hooks and no saved session, so it cannot read your project's files. The CLI adds its own context as in any session (for example its working directory and OS); Claude Code is started with `--safe-mode`, so your CLAUDE.md, skills, plugins and MCP servers are not loaded, while Codex loads its user configuration and a global `AGENTS.md` if you have one. Replume sends nothing to its own servers. The review runs at most once per state of the work and gives up after `review.timeout_sec` seconds (90 by default). When it does not run, the Stop notice, `replume watch` and the report say why and what to change (for example "set review.model or REPLUME_REVIEW_CODEX_MODEL"). A review steer counts as a steer in the report. A change the task did not ask for but that a protected test or a comment already in the code requires is not flagged and gets no steer; the report lists it under "Model review" as "Beyond the task, needed by a protected test" (or "required by a comment in the code"), so you can see the work went further than you asked. A test or comment the agent added itself does not count.
+
+### How to turn it off
+
+Put this in `.replume/config`:
+
+```yaml
+review:
+  enabled: false
+```
+
+or set `REPLUME_REVIEW=off` in the environment the agent runs in. With either one, no reviewer CLI is started and the report says the review was turned off. The verdict does not depend on the review, so the only thing lost is the one steer it can send the agent.
 
 | Choice | Destination | Data sent |
 | --- | --- | --- |
 | Default flow | None from Replume | Nothing sent by Replume |
+| Model review at done (AUTO, on by default; `review: enabled: false` turns it off) | The vendor of the second agent CLI on this machine (Codex: OpenAI; Claude Code: Anthropic), through that CLI and your login | Task text, the diff against the task start, the last test output Replume ran and the protected file names, with best-effort secret redaction; the CLI runs in a temporary directory with no tools, no hooks and no saved session |
+| `judge: enabled: true` in `.replume/config` (off by default) | The vendor named in `judge.vendor` (`api.anthropic.com`, `api.openai.com`, `generativelanguage.googleapis.com`) or `judge.base_url`, with your API key from the environment | Once: the task text, to list its acceptance items. After each write: the items, that write's diff and recent steps. At the end: the items, the full diff and ledger facts. Redacted first |
+| `judge-eval --provider P --model M` | That provider | The built-in labeled fixture tasks and patches; no code from your project |
+| `judge-eval --review <dir>` | The vendor of the reviewer CLI, as for the model review | Task text, diff and test output of each recorded run in `<dir>` |
+| `share` | `replume.dev` | One session report, previewed before upload (see below) |
+| `task JIRA-123` | Your `JIRA_BASE_URL` | The issue key and your Jira credentials, to read the issue text |
 | `verify --legacy-judge` | OpenAI, `api.openai.com` | Full Git diff, task text and agent action summary; also a GitHub check-run with commit SHA and verdict to `api.github.com` |
 | `verify --legacy-judge --post-github-comment` | GitHub PR, `api.github.com` | Task text and model reasoning in a PR comment; it can be public if the repository is public |
 | `github comment --repo OWNER/REPO --pr N` | GitHub PR via logged-in `gh` or `api.github.com` with `GITHUB_TOKEN` | Previewed, redacted, allow-listed sections from one saved session report (or a saved verify JSON supplied with `--report`); task text and changed paths may be included |
@@ -85,13 +117,15 @@ Cursor CLI: protected-file Write blocked in 2 CLI runs; out-of-scope Write warne
 
 Docker mode: when a local Docker daemon is running and the image (default `node:20-bookworm-slim`) is present, `replume verify` runs scenarios in a container with no network and a read-only copy of the commit; otherwise it uses the isolated working copy, which is not a security boundary. The container's no-network setting, read-only mount and timeout cleanup were tested in a real container on one Mac, not in CI. The isolated working copy runs commands with your machine access; use only trusted repositories.
 
+The container has no `node_modules`. When `package.json` declares dependencies and this machine has `node_modules`, the isolated working copy gets them linked in, and in `auto` isolation the tests run there instead of in Docker (the report says so). If the test runner still cannot be found (exit 127, `command not found`, `No module named pytest`), the result is INCOMPLETE with "test runner not found in the isolated copy" and what to install, never FAIL. The Stop gate does the same in the project folder: it does not block, it says "test runner not found in the project".
+
 ### Optional RUNTIME check
 
 `replume verify --runtime` tries the committed program as a user would, then runs the same probe at the base commit. It detects a `package.json` binary or `start`/`dev` script, a Python entry point, a static `index.html`, or a Dockerfile `CMD`/`EXPOSE`. CLI projects get `--help` and an explicit literal command from the task when one is present. Servers get localhost requests to `/` and literal GET routes found in source; mutating and parameterized routes are not guessed. Web apps additionally need Playwright Chromium in the local runtime image: the browser opens `/`, records console errors and failed requests, and writes a screenshot under `.replume/evidence/`. Runtime findings appear in a separate `RUNTIME (like a user)` report section. A new failure relative to the base is FAIL. Missing tools or an inconclusive base are NOT CHECKED; a failure already present at the base remains visible and prevents a runtime PASS.
 
 This stage **only** runs in Docker, even if scenario verification used the worktree fallback. For a detected web app, Replume uses the [official Playwright image](https://playwright.dev/docs/docker) pinned to `v1.64.0-noble`. On first use it announces the roughly 3.5 GB local image download and builds a local image with `playwright@1.64.0`, because the official image contains browsers but [not the npm package](https://playwright.dev/docs/docker). Image preparation contacts the image/npm registries; the app and browser run together over localhost in a fresh container with `--network none`, a read-only repo mount, and no host Docker socket. CLI and HTTP probes do not pull Playwright. Use `--runtime-image <local-image>` to supply another image; Replume never pulls a custom image. A Dockerfile `CMD` is run against the selected image and clean commit, without a Dockerfile build. If anything cannot run, the report says NOT CHECKED. An automatic end-of-task integration can call `runRuntimeAtTaskEnd` from `src/sandbox/index.ts`; its `enabled: false` option and CLI `--no-runtime` disable the stage. Existing projects should add `evidence/` to `.replume/.gitignore` before running this option; new `replume init` projects include it. Docker is useful isolation, not a perfect security boundary.
 
-Commands: `replume init`, `replume task`, `replume draft`, `replume confirm`, `replume watch`, `replume verify`, `replume accept`, `replume report`, `replume share`, `replume github`, `replume memory`, `replume usage`, `replume demo`, `replume judge-eval`, `replume install`, `replume hook`.
+Commands: `replume init`, `replume status` (what Replume does in this repo: mode, agent hooks, Docker, model review and what it sends, the last Stop check, last report), `replume uninstall`, `replume task`, `replume draft`, `replume confirm`, `replume confirm-config`, `replume watch`, `replume verify`, `replume accept`, `replume report`, `replume share`, `replume github`, `replume memory`, `replume usage`, `replume demo`, `replume judge-eval`, `replume doctor`, `replume install`, `replume hook`.
 
 ### Local task metrics (first slice)
 
@@ -101,4 +135,6 @@ Commands: `replume init`, `replume task`, `replume draft`, `replume confirm`, `r
 
 Replume reads Claude Code token counters from its local transcript at Stop and SessionEnd. To add counters from a local Codex rollout or Cursor CLI success JSON, run `replume usage import-codex --rollout <path> --task-id <id> --session-id <id>` or `replume usage import-cursor --result <path> --task-id <id> --session-id <id>`. These commands store only counts and task/session IDs in `.replume/usage.jsonl`; they make no API call. Uncaptured usage remains Unknown. Active agent time and human waiting time remain Unknown.
 
+In AUTO mode, test runner configs (`conftest.py`, `pytest.ini`, jest/vitest/playwright config and setup files) are protected, but an edit that only adds something (a fixture, an alias, a matcher, a marker, a setting) goes through and the report lists it for review. An edit that can weaken the run (retries, timeout, test selection, skip or deselection, a result-changing pytest hook, a mock or alias of the code under test) is refused, and the agent passes on a command such as `replume confirm-config jest.config.js --sha <hash>`. Running it confirms that exact file content; any other content is checked again.
+
 After `replume verify` passes, run `replume accept` to explicitly accept the current commit. It runs verification again and records the acceptance locally. Run `replume verify` afterward to refresh the saved report's accepted-change metrics. Any dollar figure is labelled **estimated API-equivalent** for captured tokens using a dated price table; it is not a bill or a savings claim. Before acceptance, it remains Unknown.