From e16f78b255bcf46d8c6f9a4b9e76dd7a3817edeb Mon Sep 17 00:00:00 2001 From: Gabriel Schneider Date: Sun, 2 Aug 2026 12:36:54 -0300 Subject: --- constrain/AGENTS.md | 6 +++++- constrain/README.txt | 34 ++++++++++++++++++--------------- constrain/claude-headless-settings.json | 2 +- constrain/codex-config.toml | 12 ------------ 4 files changed, 25 insertions(+), 29 deletions(-) delete mode 100644 constrain/codex-config.toml (limited to 'constrain') diff --git a/constrain/AGENTS.md b/constrain/AGENTS.md index abec095..871fc6c 100644 --- a/constrain/AGENTS.md +++ b/constrain/AGENTS.md @@ -2,10 +2,14 @@ Files are read with the `vr` tool — run `vr -doc` once for full usage. +`vr` stores the trace in the repo's private local jj sidecar named `vr_log`. +Do not set `VR_LOG`, pass `-log`, or create a working-tree `vr-log.jsonl`. + - `vr read FILE:START-END` — line-numbered read; prefer ranges over whole files - `vr grep PATTERN [PATH]` — regex search; scope with a path - `vr read -r REV FILE`, `vr grep -r REV PATTERN PATH` — at another jj change - `vr note -f FILE:10-42 -t struct TEXT...` — record observations as you read Navigate top-down: grep for the symbol, read the enclosing range, note what -you learn. Reads and notes are keyed to the current jj change automatically. +you learn. Every entry records the full current jj change and commit IDs; the +sidecar append does not modify the project's working-copy change. diff --git a/constrain/README.txt b/constrain/README.txt index 4eee9a1..4da2733 100644 --- a/constrain/README.txt +++ b/constrain/README.txt @@ -11,7 +11,6 @@ vr-only-guard.sh PreToolUse hook: blocks cat/rg/sed/... and the agent at `vr -doc`, so agents converge even with zero instructions vr-only.rules codex execpolicy rules (allow vr, forbid readers) -codex-config.toml optional: centralize VR_LOG for codex AGENTS.md how-to-navigate-with-vr guidance for the repo ── one-time setup ────────────────────────────────────────────────────────── @@ -20,9 +19,8 @@ put both on PATH: go build -o ~/.local/bin/vr . (repo root) (vr is what agents call; vrsite is how you read the trace) ── running a constrained CLAUDE investigation ────────────────────────────── -No repo mutation needed; from the target repo dir: +From the target jj repo dir: - VR_LOG=/abs/path/trace.jsonl \ claude -p --settings /constrain/claude-headless-settings.json \ --allowedTools 'Bash(vr)' 'Bash(vr:*)' \ < prompt.txt > report.md @@ -40,29 +38,35 @@ No repo mutation needed; from the target repo dir: ── running a constrained CODEX investigation ─────────────────────────────── cp vr-only.rules ~/.codex/rules/ # activate (GLOBAL: constrains # every codex session while there) - VR_LOG=/abs/path/trace.jsonl \ codex exec -s danger-full-access "$(cat prompt.txt)" > report.md rm ~/.codex/rules/vr-only.rules # deactivate when done - - danger-full-access is required: workspace-write blocks .git/ writes, - which kills jj's working-copy snapshot and with it `vr read`. + - danger-full-access is required: workspace-write blocks jj metadata writes, + including the sidecar rewrite and `vr 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 ── shared trace + rendering ──────────────────────────────────────────────── - - VR_LOG must point at a FILE path whose parent exists. If the path is a - directory (or becomes one), agents improvise their own log files and you - will be merging jsonl afterwards. Ask me how I know. - - Multiple agents may share one log: note ids are per-session, appends are - line-atomic. Same file = one merged timeline for free. + - 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. + - 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 the trace afterwards — serve it, and write notes of your own back - into the same log: - vrsite -log trace.jsonl -repo -title "..." + - Read traces afterwards from one process. Bare `vrsite` scans below ~ at + startup and when Refresh is pressed, then offers every repo with a sidecar: + vrsite + 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 -title "..." or take a static copy to hand around (one change, no server features): - vrsite -log trace.jsonl -repo -out site -title "..." + vrsite -repo -out site -title "..." `vrsite -h` explains both, and what a log needs to be worth reading. ── known holes (accepted) ────────────────────────────────────────────────── diff --git a/constrain/claude-headless-settings.json b/constrain/claude-headless-settings.json index f125ed2..30aff9b 100644 --- a/constrain/claude-headless-settings.json +++ b/constrain/claude-headless-settings.json @@ -10,7 +10,7 @@ "hooks": [ { "type": "command", - "command": "/Users/goblin/00-projects/0x4200.cafe/vr-agent-logger/constrain/vr-only-guard.sh" + "command": "/home/goblin/00-projects/01-tools/vr-agent-logger/constrain/vr-only-guard.sh" } ] } diff --git a/constrain/codex-config.toml b/constrain/codex-config.toml deleted file mode 100644 index fa5902f..0000000 --- a/constrain/codex-config.toml +++ /dev/null @@ -1,12 +0,0 @@ -# Optional: merge into ~/.codex/config.toml (or pass per-run with -c). -# Enforcement lives in vr-only.rules (~/.codex/rules/); this only centralizes -# the log and, if you want, tightens approvals for everything unmatched. - -# approval_policy = "untrusted" - -[shell_environment_policy] -inherit = "all" - -[shell_environment_policy.set] -# one shared vr log for every repo codex touches -VR_LOG = "/Users/goblin/00-projects/0x4200.cafe/vr-agent-logger/vr-log.jsonl" -- cgit v1.3