replume-cli 0.1.0 → 0.1.2

package/README.md

@@ -13,14 +13,48 @@ 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.
 
 Create a disposable project in a scratch directory. If Git asks for an identity when you commit, set `git config user.name "Your Name"` and `git config user.email "you@example.com"` in this disposable repository.
 
 ```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 +70,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.
+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.
 
 ## 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.
 

package/THIRD-PARTY-NOTICES.md

@@ -30,3 +30,31 @@ CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
 TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
 SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
 ```
+
+## Test cases from hoophq/fence — MIT
+
+Some shell-command test cases in this project's tests (`test/core/shell-safety.test.ts` and `test/core/shell-safety-3.test.ts`, for example the recursive-delete commands and the expected block/allow outcomes) are taken from the test suite of hoophq/fence, https://github.com/hoophq/fence (`internal/analyzer/shell/shell_test.go`, commit 31623d48220f8b4abba67f4f9993884e45cd755c). The device-name pattern of `isBlockDevice` in `src/core/rules.ts` (which names count as raw disks) follows `blockDeviceRe` in fence's `internal/analyzer/shell/shell.go`, and the `$TMPDIR` handling follows the behavior its `TestTmpdirResolution` pins. No other fence code is included. The following is its upstream license and copyright notice:
+
+```text
+MIT License
+
+Copyright (c) 2026 hoop.dev
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+```