replume-cli 0.1.0 → 0.1.1

package/README.md

@@ -18,9 +18,42 @@ Create a disposable project in a scratch directory. If Git asks for an identity
 
 ```sh
 mkdir replume-first-run && cd replume-first-run && git init
-printf '{"name":"replume-first-run","version":"1.0.0","type":"module"}\n' > package.json
-mkdir src && printf 'export const add = (a, b) => a - b;\n' > src/add.js
+printf '{"name":"replume-first-run","version":"1.0.0","type":"module","scripts":{"test":"node --test"}}\n' > package.json
+mkdir src test && printf 'export const add = (a, b) => a - b;\n' > src/add.js
+cat > test/add.test.js <<'JS'
+import test from 'node:test';
+import assert from 'node:assert';
+import { add } from '../src/add.js';
+test('add returns the sum', () => assert.equal(add(1, 2), 3));
+JS
 replume init
+git add -A && git commit -m 'Set up first run'
+replume draft --task "Change src/add.js so add returns a+b instead of a-b"
+cat .replume/contract.yaml
+```
+
+The draft is a proposal, not policy. `allow` lists files the agent may change; check that it contains `src/add.js`. `test_command` should be `npm test`; it must run at least one test. `protect` lists the existing test file, so the agent may not weaken it. If `allow` is empty, use a task that names `src/add.js` or add it to the contract; `replume confirm` refuses an empty list unless you explicitly accept broad scope. Confirmation records a local task-start baseline. Commit the confirmed contract and generated `.replume/.gitignore` before asking the agent to work. The test fails at first because the function subtracts.
+
+```sh
+replume confirm
+git add .replume/contract.yaml .replume/.gitignore && git commit -m 'Confirm Replume task'
+```
+
+Now give the agent the task in this folder, for example `claude -p "Change src/add.js so add returns a+b instead of a-b"` with Claude Code, and let it edit with the hooks installed by `replume init`. Review and commit its change, then verify and accept:
+
+```sh
+git add src/add.js && git commit -m 'Make add return the sum'
+replume verify
+replume accept
+```
+
+Expected: the report starts with `Verdict: PASS`, `test_command` shows as DONE, and an `OBSERVED` line lists `src/add.js` as "checked by test_command and observed steps; no scenario". The last line states the actual isolation mode. `replume accept` then records the accepted change. A passing test establishes only what that test checks.
+
+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:
+
+```sh
 cat > .replume/scenarios/add.yaml <<'YAML'
 v: 1
 id: add
@@ -36,30 +69,15 @@ cat > .replume/scenarios/add.mjs <<'JS'
 import { add } from '../../src/add.js';
 console.log(`ADD=${add(1, 2)}`);
 JS
-git add package.json src .replume/scenarios && git commit -m 'Set up first run'
-replume draft --task "Change src/add.js so add returns a+b instead of a-b"
-cat .replume/contract.yaml
-```
-
-The draft is a proposal, not policy. `allow` lists files the agent may change; check that it contains `src/add.js`. `must_check` names required scenarios; check that it contains `add`. A scenario is a command and an expected result. Its `declared_covers` is a declaration, not measured coverage. If `allow` is empty, use a task that names `src/add.js` or add it to the contract; `replume confirm` refuses an empty list unless you explicitly accept broad scope. Confirmation records a local task-start baseline. Commit the confirmed contract and generated `.replume/.gitignore` before asking the agent to work. The initial scenario should fail because the function subtracts.
-
-```sh
-replume confirm
-git add .replume/contract.yaml .replume/.gitignore && git commit -m 'Confirm Replume task'
-printf 'export const add = (a, b) => a + b;\n' > src/add.js
-git add src/add.js && git commit -m 'Make add return the sum'
-replume verify
 ```
 
-Expected: the final report starts with `Verdict: PASS`, the scenario shows `DONE`, and the last line states the actual isolation mode. This sample uses a manual edit, so the report warns that agent actions were not observed. With an agent, give it the same task between `confirm` and `verify`, then review and commit its change. A passing scenario establishes only the stated `ADD=3` behavior.
-
 Cursor project hooks are installed by `replume init` only when `.cursor/` already exists in the project or `--cursor` is supplied. The global install keeps `replume hook claude` and `replume hook cursor` 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.
 
 ## Reading the report
 
-The first lines give `PASS`, `FAIL`, or `INCOMPLETE` and the reason. `DONE` means a scenario ran and met its stated expectations. `FAILED` means a run or required check failed. `EXTRA` names a changed path outside the allowed scope. `TAMPERING` names a suspicious test or configuration change. `NOT CHECKED` means no scenario declares coverage of the changed path. A green scenario does not prove the entire task correct.
+The first lines give `PASS`, `FAIL`, or `INCOMPLETE` and the reason. `DONE` means a scenario ran and met its stated expectations. `FAILED` means a run or required check failed. `EXTRA` names a changed path outside the allowed scope. `TAMPERING` names a suspicious test or configuration change. `OBSERVED` names a changed path that no scenario declares but that a passing `test_command` and observed agent steps checked. `NOT CHECKED` means a changed path is neither declared by a scenario that ran nor checked that way; the reason is shown. A green scenario does not prove the entire task correct.
 
 Evidence labels distinguish what this verify run computed (`Verified in this environment`), what came from editable local files (`Observed`), optional model judgment (`Assumed`), and what was not checked (`Unknown`). The local event ledger records only actions that reached installed hooks. A manual commit can pass its checks while agent steps were not observed; the report calls that out. Use `replume demo` for a built-in recorded replay of rule decisions; it does not show live steering.