agentleFS
matt82198matt82198/aesop/tools/CLAUDE.md

aesop / tools

CLAUDE.md2 starsChanged 31 days agoMITView on GitHub

The file

We found no rules to list in this file: it reads as prose or reference rather than instructions.

Files
CLAUDE.md

tools/ — Build utilities

Local-only Python (stdlib only, no external deps), bash (POSIX, CRLF-safe).

Universal rules (every domain)

  • Feature branch only, never main; every push gated by python tools/secret_scan.py --staged exit 0. Tests never pollute cwd or global git config; temp dirs only; dummy secrets are runtime-concatenated, never literal.
  • In worktrees use ABSOLUTE paths under the worktree for every write; redaction and path-handling code must genericize over Windows profile names (use [A-Za-z0-9_]+ regex, not hardcoded) so checkout works across shared boxes.
  • Domain docs stay minimal-but-complete; update this file in the same PR as code it describes.

Core invariants

  • Never print secrets: mask as pattern name + masked value only; NEVER output raw credentials/tokens. AESOP_STATE_ROOT: all heartbeat/ledger/logs use AESOP_STATE_ROOT env var (default ./state) or CLI args; no hardcoded personal paths.
  • halt.py state-dir default: resolve_state_dir()'s precedence is AESOP_STATE_ROOT env > aesop.config.json state_root > $AESOP_ROOT/state (when AESOP_ROOT is set) > common.get_state_dir()'s cwd-relative ./state. The $AESOP_ROOT/state step (fixed 2026-10-05, PR #773) matters because callers that cd elsewhere before invoking halt.py --status (e.g. daemons/run-watchdog.sh's single-source-of-truth delegation) must still find a sentinel written at $AESOP_ROOT/state/.HALT — a bare cwd fallback silently missed it and let a halted daemon keep running.
  • status.js heartbeat path resolution (2026-10-29): resolves heartbeat paths with conductor3 preference (env override, then conductor3 location, then local fallback) to match ui/config.py; tests: tests/status-cli-heartbeat-paths.test.mjs.
  • Fragment-assembled secrets in tests: scanner_selftest.py concatenates dummy secrets at runtime so pattern text never appears contiguously (self-scan invariant).
  • verify_*.py are mandatory CI gates: verify_dash.py, verify_submit_encoding.py, verify_activity_filter.py, verify_agent_inspector.py, verify_prboard.py, verify_failure_drilldown.py, verify_wave_telemetry.py, verify_dispatch_panel.py, verify_scorecards.py, verify_ui_trio.py, verify_cost_panel.py, verify_cost_summary_drawer.py, verify_receipt.py, etc. are required pre-push gates; use --allow-skip only in truly browserless environments (CI must run all).
  • lock.mjs is the ONLY lock implementation: never reimplement locking in proposals.mjs or elsewhere; all proposals/state updates must use fail-closed lock.mjs with exponential backoff + stale-lock breaking. The backoff sleeps via Atomics.wait (synchronous, yields the core; acquireLock must stay sync), never a busy-wait (tracker 4fc897d6b12f; tests: tests/lock.test.mjs "sleeps during backoff").
  • Loop-Proof gate (2026-10-20): loop_proof_check.py --base <rev> [--head <rev>] refuses a range that changes a file listed in LOOP-MANIFEST.json (daemons/run-watchdog.sh, daemons/selfheal.sh, daemons/backup-fleet.sh, and this tool) unless a commit carries Loop-Proof: <declared test> red=a/b green=c/c (red before, fully green after). Fail closed: exit 1 = unproved or refused, exit 2 = manifest unreadable at head. A manifest introduced in the range protects its listed files from that commit on. Wired as a PR-only CI step in ci.yml (shard 0). Trailer counts are shape-checked, not re-executed. Tests: tests/test_loop_proof.py, tests/test_loop_manifest_integrity.py.
  • Conflict marker gate (Guardrail G14, 2026-10-06): conflict_marker_check.py scans tracked text files for literal unresolved markers (<<<<<<</=======/>>>>>>>/diff3 |||||||) via --check (full tree; wired as a CI gate, ci.yml shard-0) or --staged RANGE (added-lines-only diff, pre-push hook); skips binaries + tools/.conflict-marker-allowlist.json paths, honors inline # conflict-marker-ok; exit 0=clean/1=findings/2=error; an unreadable tracked file (AV lock, permission denied) is exit 2 with the path named in BOTH --check and --files modes, never a skip. Closes the PR #834 gap: merge commit b2c4db77 landed a literal <<<<<<< HEAD block in this very file and claudemd_lint/claudemd_sync_gate/all PR CI passed because none of them scan for conflict markers.
  • power_selftest.py scanner check fails closed (2026-10-05): a check that cannot locate/run/parse scanner_selftest.py renders scanner:FAIL, never scanner:None/n/a/OK -- a silently-broken scanner gate must never read healthy. Every check result funnels through render_segment(), which treats a None result or an OK/WARN DETAILED_OK_CHECKS (decisions/scanner/trigger) result whose details is None as FAIL:unevaluated. Tests asserting the overall exit code (e.g. TestPowerSelftestHookDetection) must pin SCRIPTS_ROOT at a real scanner_selftest.py so the scanner check is deterministic regardless of whether the CI runner's $HOME happens to carry ~/scripts -- otherwise an unrelated check flips the exit code these tests assert on.

init_project.py — Worktree support

  • Worktree .git handling: resolve_real_git_dir() detects when .git is a FILE (worktree case) and uses git rev-parse --git-common-dir to locate the actual git directory.
  • Fallback git dir resolution: Manual parsing of .git file's gitdir: pointer if git command fails. Every branch returns Path(...).resolve() (8.3 TEMP alias RUNNER~1 / subst drives differ from raw paths).
  • Hook installation: install_pre_push_hook() uses resolved git dir to place hooks in the common directory (not worktree), preventing ENOTDIR errors in worktree scenarios. Hooks dir is resolved by common.resolve_hooks_dir (git --git-path hooks, honours worktrees + core.hooksPath); health_score FAILs on git error (tests: tests/test_health_score.py::TestHealthScoreHooksDirResolution).
  • Pre-push hook template (PRE_PUSH_HOOK): reads the pre-push stdin lines and runs secret_scan.py --range over each pushed remote_sha..local_sha (new branch: merge-base with the default branch, else the empty tree), in addition to --staged; fail-closed on findings, scanner error, missing scanner or malformed input. Written as LF bytes (install_pre_push_hook). Tests: tests/test_init_project.py::TestPrePushHookScansPushedRange.
  • Security: symlink checks preserved throughout resolution. install_pre_push_hook refuses a symlinked .git/hooks/pre-push even under --force (the check runs before the exists/force decision, so write_bytes never follows the link). Tests: TestInstallPrePushHook in tests/test_init_project.py.
  • Pre-push hook scans pushed refs: the hook init_project.py installs reads git's per-ref stdin, blocks pushes to refs/heads/main|master, and runs secret_scan.py --range <remote-tip>..<local-tip> per ref (whole tree for a new ref); copy_secret_scan_script(force=) refreshes a stale scan script only under --force. Tests: tests/test_init_project.py.
  • state/ git-ignore (F-10, 2026-10-14): ensure_state_gitignore() appends a marker-delimited block (state/* + !state/.gitkeep) to the scaffolded .gitignore, idempotent on re-init. Without it git add -A staged the SQLite event store and tracker json. Tests: tests/test_init_gitignore.py.
  • Push-gate artifacts (0.10.1): generate_push_gate_artifacts() runs the five generators doctor requires (tools/INDEX.md, .pyflakes-baseline.json, .subprocess-guard-baseline.json, .portability-baseline.json, .stateapi-baseline.json) from this tools dir with cwd set to the target repo, in parallel, after the hook install. Existing artifacts are kept unless --force; AESOP_SKIP_PUSH_GATE_ARTIFACTS=1 skips. DEFAULT_CONFIG writes "repos": []. Tests: TestInitWritesPushGateArtifacts in tests/test_init_project.py.
  • Doctor port check (2026-10-17): doctor.js resolveDashboardPort() probes the port aesop dash launches on (PORT env, then aesop.config.json dashboard.port via ci_config.loadAesopConfig, then 8770); the row is labelled Port N available. Tests: tests/doctor-dashboard-port.test.mjs.

dash.js — fresh-init resolution (F-09, 2026-10-14)

  • common.get_state_dir() (F-07, 2026-10-14): precedence is AESOP_STATE_ROOT env > aesop.config.json state_root (relative values resolve against the config's dir, AESOP_ROOT or cwd; same as ui/config.py) > <cwd>/state. Test: tests/test_state_dir_parity.py.
  • dash.js resolves ui/serve.py from the installed package (PACKAGE_DIR = __dirname/..), not process.cwd(), because init does not scaffold ui/. It passes AESOP_STATE_ROOT = env > aesop.config.json state_root > <cwd>/state. Test: tests/dash-fresh-init.test.mjs.
  • dash.js expandHome + signal exits (SEM-1): expandHome expands a leading ~ in state_root before resolution, and a null exit code (signal death) maps to 128+signal or 1. Test: tests/state-root-expanduser.test.mjs.

Key tools

  • tools/event_store/store.py verify requires head (finding A1, 2026-11-14): a schema-2 store with at least one event must carry a 64-hex store.json head; a missing, null or malformed head is a verify problem, so deleting the last line of a non-empty store can no longer verify clean. A zero-event store has no head to check; under store.json schema 1 any line carrying a "v" key is reported (int 2 as a schema downgrade). Tests: tests/test_event_store_verify_requires_head.py.
  • tools/event_store/store.py append lock (2026-11-14): Store.append runs read-tail, line append and head update under <store>/.append.lock (OS advisory lock on a never-deleted sidecar file: msvcrt.locking on Windows, fcntl.flock elsewhere; retries up to 60s then raises StoreError having written nothing; no pid or age rule, a crashed holder frees it at exit; local disks only, network filesystems are not supported). Tests: tests/test_event_store_append_lock.py.
  • event_store append lock sidecar (2026-11-14): cli.py git_commit stages with a :(exclude) pathspec on LOCK_NAME (.append.lock), and init.py writes a .gitignore with .append.lock, so the sidecar is never committed to a store branch. An already-tracked lock stays tracked (an ignore rule does not untrack). Tests: tests/test_event_store_lock_not_tracked.py.
  • tools/event_store/context.py (read-only context builder, 2026-11-14): build_context(store_path, task=None, max_bytes=None) calls Store.verify() first; on any problem it returns CHAIN BROKEN plus the problem strings and no fact lines (load is never called on an unverified store). Otherwise one fact line per event: seq=<n> sha=<12 hex of the event line hash> ts=<ts> actor=<actor> kind=<kind> <text> under a header saying facts are writer assertions, not verified truth. Task filter key: refs["task"]. max_bytes is never exceeded; a dropped tail ends on the TRUNCATION_MARKER line. No CLI yet. Strictly read-only: no writes, no lock, no git, no import of watch.py or claims.py. Tests: tests/test_event_store_context.py.
  • tools/event_store/init.py (G1.1 L2, 2026-10-22): creates a per-project event store: orphan branch + worktree, store.json {"project","schema":2}, *.jsonl -text attributes, empty events/ and runs/, and the append-only guard tools/event_store/guard/events_append_only.sh (ported from conductor3 unchanged). Guard installed per worktree via core.hooksPath under the common dir; exit 1 when the branch or path exists (nothing changed), rollback on failure. Run with python -I. Tests: tests/test_event_store_init.py.
  • tools/event_store/store.py verify (v1 seq): schema 1 (frozen conductor3 logs) restarts seq at 1 in every day file; verify requires each file's seq to run 1..n (a gap, duplicate, or reorder is a problem) and lets a file's first line continue the store-wide count (older fixtures). A broken prev link across files still fails. Each v1 event's ts date must match its file name, ts must be non-decreasing within a file, and a file's first ts must not precede the previous file's last ts; swapped day files and foreign-day timestamps therefore fail. v1 limit: a missing day file is not detectable from v1 data alone (prev and seq restart per file); closing it needs a seal manifest or the v2 cross-file chain. The known-limit test test_known_limit_v1_deleted_middle_day_is_not_detected asserts the current behaviour and must be updated when that lands. Schema 2 verification is unchanged. Tests: tests/test_event_store_core.py (V1PerFileSeqTests).
  • tools/rotate_logs.py (copy-truncate, 2026-10-16): archive is created exclusively (xb) from the bytes read under the sidecar lock, then the kept half is rewritten into the live log in place and truncated (same inode, so >> handles held across a rotation keep writing). os.replace was rejected: a rename orphans long-lived writers and fails with rc=1 on Windows while another process holds the file. Known window: an append between the final size check and the truncate is lost. Callers: monitor/collect-signals.mjs (execFileSync); shell daemons write with per-write >> and long-lived child >> (daemons/run-watchdog.sh pr_sweep and git_integrity_check). Tests: tests/test_rotate_logs.py.
  • tools/gen_tool_index.py: Generated INDEX.md builder. Updated 2026-10-07: --check mode uses git hash-object --path for EOL-agnostic comparison; generated content hash vs working-tree file hash both normalized through git's .gitattributes/core.eol rules. Fixes Windows false positives where CRLF/LF byte differences were misreported as stale. --regenerate writes LF-only (standard git storage format). Post-#925 fix (2026-10-07): when passing expected content to git hash-object via stdin, use binary encoding to avoid Python's platform-specific line-ending conversion on Windows (text=True was converting LF to CRLF). The check_via_git_hash() function now encodes strings as UTF-8 bytes before passing to subprocess, then decodes the hash output.
  • tools/event_store/claims.py + cli.py (one-claim slice): append refuses a kind outside KINDS (exit 2, nothing written) and refuses hand-typed merge. record-merge <owner/repo> <pr> --project P runs gh pr view itself (arg list, 30s timeout, fields incl. number,url) and appends a merge event (actor record-merge, refs source=gh) only when state is MERGED and the returned number and url match the request; any failure or crash prints RECORD-MERGE FAILED: <why>, exit 1, writes nothing, lock released; a repeat prints already-recorded, exit 0; it refuses a store whose chain fails verify or that holds an unrecognised merge event for the PR. A lock path that is a directory is a clean failure.
    • verify-claim <repo> <pr> <sha> --project P verifies the whole chain, requires a well-formed store.json head equal to the last line's sha (a store with no head, such as one with zero events, is unknown), then compares the parsed merge_sha only (full or 7+ hex prefix; head_sha is recorded, never matched): exit 0 verified, 1 refuted, 2 unknown (no event, bad sha, broken chain, head missing or wrong, unrecognised merge event for the PR, two merge events with different shas, or any internal error; a crash is never refuted).
    • baseRefName is recorded and not checked: a PR merged into a non-default branch still counts as merged. Provenance is a partial mitigation: only merge events with actor record-merge and source=gh count, but anything able to write the store files can set those fields; the real anchor is an off-box head push, which does not exist yet.
    • The lock covers record-merge only (stale locks are broken by atomic rename); general append locking is PR #1404. Tests: tests/test_event_store_one_claim.py.
  • tools/event_store/watch.py (trigger projection): one pass over a store's events past a cursor {"seq","head"} at $AESOP_STATE_ROOT/event-watch/<project>.cursor.json (never inside the store); under the append lock it verifies the chain and head, refuses unknown kinds, emits TRIGGER lines for verdict/ruling/handback, then advances the cursor by atomic replace, retried a few times on PermissionError (Windows sharing violations from racing watchers) and failing closed after the last attempt (at-least-once; consumers dedupe on project+seq). First run needs --init. A consumer must discard the TRIGGER lines of any non-zero pass. Emit runs under the append lock, so consumers must not block on stdout. Tests: tests/test_event_store_trigger_watch.py.
  • tools/git_integrity_check.py (fail-closed --repos-json, 2026-10-20, tracker 5999373469c2): an explicit --repos-json is authoritative. A missing, unreadable or malformed file, a non-list payload, or an empty list exits 2 with a specific error; stdin is read only when --repos-json is absent. Previously a parse error fell through to a stdin read with no timeout, which could block the watchdog cycle. Tests: tests/test_git_integrity_check.py (test_malformed_repos_json_fails_closed_without_reading_stdin, test_empty_repos_json_does_not_read_stdin).
  • tools/goal_state.py + tools/boot_state.py (2026-10-15): goal_state.py set|show|history appends/prints the orchestrator GOAL as goal_set events on stream orchestrator_goal (StateAPI append, never patched); boot_state.py prints the ONE canonical boot brief (GOAL, STATE.md ## ACTIVE, BUILDLOG tail, event-store projections, git) capped at --max-bytes (default 12000), exit 2 with no stdout when the store is unreadable or missing.
  • tools/regen_all.py: Regenerator runner. Updated 2026-10-07: paths_with_real_diff() returns all modified paths for restoration in --check mode, preserving fixture byte-identity. EOL normalization delegated to gen_tool_index.py and git's comparison rules. Updated 2026-10-16: --json always emits fixed (an empty list when nothing drifted) alongside exit_code; regen-on-main.yml treats exit_code 0 with fixed == [] as success-nothing-to-do and fails closed on a missing or non-zero exit_code or malformed JSON (tests: tests/test_regen_all.py).

Tool index

  • Receipt gate (emit, verify, spool, flush): tools/receipts/CLAUDE.md
    • Receipt pubkeys keyring (tools/receipt_pubkeys/): Ed25519 public keys for receipt signing, used by verify_receipt.py to verify receipts against a keyring (receipt_pubkey.pub + all receipt_pubkeys/*.pub files). New keys are registered by adding a mattworkpc-<key_id>.pub file to this directory (derived from the private key PEM via key_id_for_pubkey(), first 16 hex chars of SHA256). A key registered in a PR only takes effect once the PR merges — the verifier loads the keyring from the BASE tree (origin/main), never the PR head. Tests: tests/test_receipt_keyring.py.
  • Gate wiring, generated artifacts and adding a gate: tools/gate_wiring/CLAUDE.md
  • Lint and scan gates (secret scan, encoding, pyflakes, lint evasion, dispatch lint): tools/lint_scan/CLAUDE.md
  • Merge actors (merge_train, merge_queue, auto_merge, pr_sweep, halt): tools/merge_actors/CLAUDE.md
  • State tracker, event stores and ingest: tools/state_tracker/CLAUDE.md
  • CI isolation, CI modes and workflow lint: tools/ci_isolation/CLAUDE.md

Recent additions (2026-10)

  • healthcheck.py UTF-8 encoding fix (2026-10-29): The health check command prints emoji (🟢/🟡/🔴) to stdout, which crashed with "charmap can't encode" on Windows cp1252 consoles. Fixed by reconfiguring sys.stdout and sys.stderr to UTF-8 with errors='replace' at the entry point, guarded by hasattr() for compatibility. Test: tests/test_healthcheck_utf8.py::TestHealthcheckUTF8Encoding::test_healthcheck_runs_on_cp1252_console runs with PYTHONIOENCODING=cp1252 and verifies no crash. Fixes finding f-6905850f.
  • linux_shape_check.py — cross-platform test gate: detects commits touching shell/workflow/Node files, runs their suites NATIVELY on a non-Windows host (run_native_leg; WSL never probed) or under WSL on Windows (wsl_status tri-state; NOTICE skip when absent/no-distro, probe error exits 1). Catches Windows-only CI reds (isolated-home USERPROFILE, Ubuntu shell failures). Wired into pre-push-policy.sh after generated_paths check; unit cases in tests/test_linux_shape_check.py. Receipt part linux-shape (requires_wsl) is skipped when WSL is absent/no-distro; a probe error fails closed. Both legs (WSL and native Linux host) build their suite through one shared builder (tripwired_argv), so Node and Shell suites run through test_isolation_tripwire.py as package.json test:node/test:sh do; a tripwire profile-drift finding fails the leg (native-leg tests: tests/test_linux_shape_native_leg.py).

Gates & tests

  • bench_api_runner.py live-spend guard: AESOP_BENCH_OFFLINE=1 is checked before any Anthropic client is constructed in make_api_runner, even with --confirm-spend; main() requires --confirm-spend (exit 2 without it). Guard tests: tests/test_bench_api_runner_guard.py.
  • bench_runner.py offline guard: AESOP_BENCH_OFFLINE=1 makes the claude-CLI runners (--runner haiku|sonnet|opus, which shell claude -p) refuse before any shutil.which or subprocess.run spawn; main() exits 2 with one stderr line before any task runs. Guard tests: tests/test_bench_runner_offline.py.
  • agent-forensics.sh <commit> — behavior forensics; --diff <A> <B> for rules/docs diff
  • Python: npm run test:py; Shell: bash -n tools/*.sh && shellcheck tools/*.sh; Node: node --check tools/*.mjs
  • CLAUDE.md line cap: claudemd_lint.py flags non-fenced lines over 1024 bytes per file, ratcheted against tools/claudemd_line_cap_baseline.json (at or under the file's count is a warning; over it fails; lower a file's entry by hand when it shrinks).
  • Templates: templates/aesop-dispatch-template.yml — ready-to-fork GitHub Actions dispatch workflow (workflow_dispatch + cron); adopter guide docs/ACTIONS-TEMPLATE.md; verified by tests/test_actions_template.py (YAML validity, CLI commands checked against bin/cli.js --help, no invented flags/fabricated output). templates/wave-presets/*.json is the unrelated wave-manifest-preset set consumed by wave_templates.py.
  • wave_templates.py testCmd rules: validate_manifest() rejects a testCmd that pipes into head/tail without pipefail (the pipe's exit status would mask a failing stage), and import X / --cov=X module targets that are not Python identifiers (--cov=src/x paths and unresolved {placeholders} are skipped). Library presets use {module_name} (hyphens to underscores, from module_name_for()) for import, --cov and the src/ package dir. Tests: tests/test_wave_templates.py.
  • wave_manifest_lint.py: Validates wave manifests for file-ownership disjointness, path existence, prompt sanity, git-history churn heuristics, and per-item testCmd binary resolution. Binary resolution now skips leading shell negation (!) and environment assignments (FOO=value) to find the actual executable; tested against both negation and env-var patterns. Shell builtins (cd, export, echo, true, ...; SHELL_BUILTINS) are skipped across &&, ||, ; and | chains, so cd docs && sphinx-build ... checks sphinx-build; a chain of only builtins resolves, and a missing real binary behind a builtin still FAILs. eval "<cmd>" lints <cmd> as a nested testCmd; source/. require the sourced file to exist (manifest-root relative) and lint its first command line; anything unresolvable fails closed as "unresolvable command". tests/test_manifest_lint_presets.py lints every shipped preset in templates/wave-presets/ with absent third-party binaries stubbed on PATH.
  • PR symbol survival (Guardrail G13): pr_symbol_survival_check.py collects top-level symbols (Python def/class/async def at ANY indentation, matched by bare name so a helper nested in a method or block, or re-indented, still counts as surviving; JS/MJS export function|const|class + top-level function name(, shell name() {) ADDED by a PR branch's own non-merge commits and verifies each still exists in the final head tree (same file, or anywhere in the repo if renamed — reported as INFO); catches the "resolved a merge conflict by taking the other side's whole file" class (PR #745: build_bisect_batches / parse_bisect_lineage / bisect_is_exhausted silently dropped by a conflict-resolution merge, CI stayed green). CLI --base REF (default origin/main) --head REF (default HEAD) --original-head SHA --json; exit 0=survived/1=missing/2=error; read-only, stdlib-only. BLOCKING (promoted from advisory): wired into ci.yml as the required pr-symbol-survival job (rc propagated, records G13 rc=<n> in the job summary) and into hooks/pre-push-policy.sh check_symbol_survival() (one base..head range per pushed ref; exit 1 or 2 blocks the push). A symbol absent from head fails when a MERGE commit in range dropped it, checked against ANY parent (conflict-resolution loss, including git checkout main; git merge feature where main is the first parent); only a symbol deleted by a NON-merge commit in range is reported as REMOVED (INFO, printed in the text report) and passes (add-then-delete, regression-tested). pr-symbol-survival is declared in tools/required-checks.json to match live branch protection.
  • verify_test_coverage.py — Guardrail G2: --check fails closed if any tests/**/*.py (except tests/fixtures/) defines a unittest.TestCase or a test_-prefixed function (AST) but is outside the collected tests/test_*.py glob (ci_shard_runner's git ls-files); exit 0=covered/1=orphans/2=error; stdlib-only. Node side: hooks/**/*.test.mjs are discovered by find_hooks_node_test_files() and are covered only by whole-word hooks/...*.test.mjs tokens in package.json test:node (hooks_node_glob_tokens; substrings and tests/hooks/* do not credit).
  • metrics_gate.py — NO-UNVERIFIED-METRICS: scans added lines of *.md in a <range> (default origin/main...HEAD) for unmarked %/Nx/$ claims ($ inside an HTML comment span is skipped, awk field refs; %/Nx still checked there); fail-closed: any git failure on the range (git exit 128 for an unresolvable ref, e.g. a 0000000...<sha> base, or an exception) prints METRICS-GATE: BLOCK unresolvable range <range> (git exit N) and exits 1, while a resolvable range with no .md changes passes; exit 0=pass/1=block; stdlib-only
  • metrics_gate.py retraction (BUILDLOG.md only, append-only logs): a LATER added line <!-- metrics-retracted: <entry timestamp> '<metric>' reason: <text> --> clears an unverified claim whose entry head (- <timestamp> ...) equals <entry timestamp> and whose metric equals '<metric>' (whitespace ignored); earlier or other-timestamp/metric markers and every non-log .md file get no relief
  • pr_footprint_gate.py — Guardrail G2.7: fails PRs with >100 files or >5000 deletions unless labeled big-change, or PRs with fixture-pattern commits (test fixtures committed into lane worktrees); pass on chore(stats)-only commits. CLI: --base <sha> --head <sha> [--labels JSON] (labels from PR event); exit 0=pass/1=fail/2=error; stdlib-only
  • shadow_adjudication.py: build_finding_context_pack(enriched=True) attaches evidence via driver/context_pack.py's add_evidence_to_pack() (pure in-memory, never touches the filesystem or repo_root/conductor_root) — never re-derive the already-built brief through build_context_pack() with a fake brief:<name> source: that resolves the placeholder name as a literal relative path against the process cwd, which only happens to equal repo_root by coincidence (2026-10-06 incident: a prior test's tearDown leaking a polluted process cwd made that placeholder resolve outside the allowlist and raise ContextPackViolation for a perfectly legitimate in-memory brief).
  • multi_dispatch.py (claim TTL covers the dispatch): the atomic path-claim lease TTL is claim_ttl_seconds(--timeout, multibox.lease_ttl_seconds) = max(lease_ttl, timeout + CLAIM_TTL_MARGIN_SECONDS=60), not a hard-coded 300s (audit 2026-10-15: a --timeout 1800 dispatch lost its claim at t=300 and a rival was granted the file). A crashed dispatcher never releases, so its lease expires at claim time + that TTL (bounded by the dispatch timeout; no renewal thread). Tests: tests/test_multi_dispatch_claim.py::TestDispatchLeaseOutlivesDispatch (fake clock, drives main()). multi_dispatch.py (claim read fail-closed): check_conflict reads claims via the strict get_all_claimed_files_strict; an unreadable or corrupt claims store raises ClaimStateUnknown (store path in the message) and main() refuses the dispatch with exit 1, never reading as "no conflict" (tests: tests/test_multi_dispatch_claim_strict.py).
  • box_fence.py (BOX_PROTOCOL fence): compares the checkout BOX_PROTOCOL integer with origin; PASS, fast-forwards a clean strictly-behind tree, FAIL (never resets/stashes) when dirty or diverged, WARN plus a git-dir marker when offline (--push-check then fails closed). Called by daemons/run-watchdog.sh, doctor.js, boot_state.py, pre-push-policy.sh. Tests: tests/test_box_fence.py.
  • watch.js signal exit (SEM-15): watch.js maps a null child exit to 128+signal or 1 (proc.on('exit') in tools/watch.js), so a watched child that dies by signal never makes the wrapper exit 0. Tests: tests/watch-signal-exit.test.mjs.
  • test_isolation_tripwire.py ~/.claude/memory excuse (ledger-gated): a changed file under ~/.claude/memory is excused only when ~/.claude/state/memory-write-ledger.jsonl has a row whose path (relative to ~/.claude) equals that exact file and whose sha256 matches the file's current hash. Rows are {path, sha256, ts, writer}, written by ~/.claude/hooks/auto-commit-brain.mjs (claude-config #462). Directories, prefixes and .bak siblings are never excused; an unreadable or deeply nested ledger line (ValueError, RecursionError) is skipped, never a crash and never an excuse.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.