diff options
Diffstat (limited to 'constrain/README.txt')
| -rw-r--r-- | constrain/README.txt | 57 |
1 files changed, 31 insertions, 26 deletions
diff --git a/constrain/README.txt b/constrain/README.txt index 4da2733..6d4b882 100644 --- a/constrain/README.txt +++ b/constrain/README.txt @@ -1,4 +1,4 @@ -Constrain agents to read files only through vr — enforcement comes from +Constrain agents to read files only through notevi — enforcement comes from harness config; AGENTS.md is navigation guidance only, never the constraint. ── files here ────────────────────────────────────────────────────────────── @@ -6,26 +6,28 @@ claude-settings.json project install: <repo>/.claude/settings.json (hook path uses $CLAUDE_PROJECT_DIR) claude-headless-settings.json no-install variant for `claude -p --settings` (hook path is absolute into this dir) -vr-only-guard.sh PreToolUse hook: blocks cat/rg/sed/... and +notevi-only-guard.sh PreToolUse hook: blocks cat/rg/sed/... and jj/git content reads; its error message points - the agent at `vr -doc`, so agents converge + the agent at `notevi -doc`, so agents converge even with zero instructions -vr-only.rules codex execpolicy rules (allow vr, forbid readers) -AGENTS.md how-to-navigate-with-vr guidance for the repo +notevi-only.rules codex execpolicy rules (allow notevi, forbid + readers) +AGENTS.md how-to-navigate-with-notevi guidance for the repo ── one-time setup ────────────────────────────────────────────────────────── -put both on PATH: go build -o ~/.local/bin/vr . (repo root) - cd vrsite && go build -o ~/.local/bin/vrsite . - (vr is what agents call; vrsite is how you read the trace) +put it on PATH: go build -o ~/.local/bin/notevi . (repo root) + + one binary now: agents call `notevi read/grep/note`, and you + read the trace back with `notevi web` ── running a constrained CLAUDE investigation ────────────────────────────── From the target jj repo dir: - claude -p --settings <vr-repo>/constrain/claude-headless-settings.json \ - --allowedTools 'Bash(vr)' 'Bash(vr:*)' \ + claude -p --settings <notevi-repo>/constrain/claude-headless-settings.json \ + --allowedTools 'Bash(notevi)' 'Bash(notevi:*)' \ < prompt.txt > report.md - (<vr-repo> is wherever this repo lives; the settings file's hook path is + (<notevi-repo> is wherever this repo lives; the settings file's hook path is absolute into this directory, so it must be spelled out in full) - --allowedTools on the CLI is required headless: allow rules inside @@ -36,42 +38,45 @@ From the target jj repo dir: eaten by the flag's list parsing. ── running a constrained CODEX investigation ─────────────────────────────── - cp vr-only.rules ~/.codex/rules/ # activate (GLOBAL: constrains - # every codex session while there) + cp notevi-only.rules ~/.codex/rules/ # activate (GLOBAL: constrains + # every codex session while there) codex exec -s danger-full-access "$(cat prompt.txt)" > report.md - rm ~/.codex/rules/vr-only.rules # deactivate when done + rm ~/.codex/rules/notevi-only.rules # deactivate when done - danger-full-access is required: workspace-write blocks jj metadata writes, - including the sidecar rewrite and `vr read`'s working-copy snapshot. + including the sidecar rewrite and `notevi read`'s working-copy snapshot. - enforcement is pre-exec by codex's execpolicy engine, even through `zsh -lc` wrappers; validate rules with: - codex execpolicy check --rules vr-only.rules -- cat foo.txt + codex execpolicy check --rules notevi-only.rules -- cat foo.txt ── shared trace + rendering ──────────────────────────────────────────────── - - vr creates one anonymous sidecar change directly under jj's root() on the - first append. The repo-local alias vr_log names it; git.private-commits - protects it from accidental pushes. No path or environment setup exists. + - notevi creates one anonymous sidecar change directly under jj's root() on + the first append. The repo-local alias notevi_log names it; + git.private-commits protects it from accidental pushes. No path or + environment setup exists. + - A repository last written by the older `vr` tool is renamed in place the + first time notevi touches it; `notevi migrate <repo>...` does it up front. - Multiple agents in the repo share that sidecar. Rewrites are serialized, note ids are assigned under the same lock, and the project @ is untouched. - The sidecar has no bookmark and is local-only. It does not survive a fresh clone; include the jj repository in backups when the trace matters. - In the prompt, tell the agent to leave pinned notes - (vr note -f FILE:START-END -t kind "...") — that is the payload. - - Read traces afterwards from one process. Bare `vrsite` scans below ~ at + (notevi note -f FILE:START-END -t kind "...") — that is the payload. + - Read traces afterwards from one process. Bare `notevi web` scans below ~ at startup and when Refresh is pressed, then offers every repo with a sidecar: - vrsite + notevi web Its explicit buttons can start an empty private sidecar in a discovered jj repo or initialize colocated jj in a discovered Git repo. The project index is only in memory; those two requested metadata changes are the only writes. - To bypass the dashboard and serve one repository directly: - vrsite -repo <repo> -title "..." + notevi web -repo <repo> -title "..." or take a static copy to hand around (one change, no server features): - vrsite -repo <repo> -out site -title "..." - `vrsite -h` explains both, and what a log needs to be worth reading. + notevi web -repo <repo> -out site -title "..." + `notevi web -h` explains both, and what a log needs to be worth reading. ── known holes (accepted) ────────────────────────────────────────────────── Scripting runtimes (python/node/perl) can still open files — uncomment their -rules in vr-only.rules / extend the hook to close, at the cost of breaking +rules in notevi-only.rules / extend the hook to close, at the cost of breaking legitimate scripts. Neither harness constrains its own non-shell internals beyond what the deny rules cover. Codex's rules file is global-only; there is no per-project rules mechanism (probed, none exists as of codex 0.145). |