replume-cli 0.2.4 → 0.2.6

package/README.md

@@ -17,6 +17,14 @@ Codex hooks are installed by `replume init --codex`, or automatically when the p
 
 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`.
 
+**Or let your agent set it up.** Paste this into the agent, in the repository:
+
+```text
+Set up Replume in this repository. Run `npm install -g replume-cli`, then `replume init`, then `replume init --check`. Tell me what the check printed and which files init added; do not commit them until I say so. Then read `replume guide agent`. Replume starts watching in the next session, so tell me to start a new one before I give you a task.
+```
+
+**One task per session, for now.** Replume treats the first message of a session as the task and checks everything in that session against it. For the next task, commit what you have, quit the agent and start a new session; its first message is the new task. A later message in the same session does not change the task.
+
 Create a disposable project in a scratch directory, then:
 
 ```sh
@@ -26,6 +34,8 @@ 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 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.
 
+Optional before the first task: `replume init --check` tries a base test in an isolated copy with a 55-second limit. It says whether a test was already red or the runner could not start. It skips dependency-install steps, warns about `npm ci --offline` and its separate cache, and does not record or change the task baseline. Use `--isolation worktree` or `--isolation docker` to select the check mode.
+
 `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.
@@ -52,12 +62,19 @@ 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.
 
+`.replume/contract.yaml` is written by Replume for each task, and `replume init` lists it in `.replume/.gitignore`. The PR check needs it committed on the base branch: `git add -f .replume/contract.yaml`. `replume init --approve` keeps it committed.
+
+`replume verify` checks a commit and says which; uncommitted changes are not included, and it names them.
+
 `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;
+- one failure class: `test_failed`, `setup`, `timeout`, `zero_tests`, `suite_shrank`, `policy`, `spec_test_conflict`, `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.
+- the tree hash of the verified state;
+- `ignored_changed`, when git-ignored files changed during the task.
+
+`replume guide <topic>` prints how this version works; `replume guide` lists the topics. `replume init` also writes a short `SKILL.md` for agents to `.agents/skills/replume/` and `.claude/skills/replume/`; a file there without Replume's mark is left alone, and `replume uninstall` removes only marked ones.
 
 `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.
 
@@ -73,7 +90,11 @@ 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 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.
+The default Replume flow (`init`, `draft`, `confirm`, hooks, `verify`) makes no Replume-managed outbound request of its own, except the model review at done and the anonymous usage data, both described below and both 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.
+
+### Usage data (on by default)
+
+Replume sends anonymous usage counts: a random install id, versions, OS, agent, test runner, session and verdict counts, which rules fired, and a repo size bucket. Never code, paths, file names, prompts, commit messages or repo names. `replume init` tells you once, before anything is sent. Turn it off with `replume telemetry off`, `REPLUME_TELEMETRY=0` or `DO_NOT_TRACK=1`. `replume telemetry show` prints the exact payloads and sends nothing. Nothing is sent when `CI` is set. Full list: replume.dev/telemetry.
 
 ### What leaves your machine when review is on
 
@@ -125,7 +146,7 @@ The container has no `node_modules`. When `package.json` declares dependencies a
 
 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 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`.
+Commands: `replume init`, `replume guide` (how this version works, by topic), `replume stats` (sessions, verdicts, interventions per agent and an estimate of what catches confirmed by a Replume test run saved in sessions that ended PASS, read-only from the local ledger; `--json`), `replume telemetry` (on, off, status, or show exactly what is sent), `replume bug` (packs the last report, the redacted ledger and local facts into one file and prints where it is; sends nothing), `replume status` (what Replume does in this repo: what it will run, 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)