aesop / tools
CLAUDE.md2 starsChanged 31 days agoMITView on GitHub
In this repository21 other files it gives its agents.
- auth/CLAUDE.mdCLAUDE.md
- bin/CLAUDE.mdCLAUDE.md
- chat/CLAUDE.mdCLAUDE.md
- CLAUDE.mdCLAUDE.md
- daemons/CLAUDE.mdCLAUDE.md
- dash/CLAUDE.mdCLAUDE.md
- driver/CLAUDE.mdCLAUDE.md
- hooks/CLAUDE.mdCLAUDE.md
- mcp/CLAUDE.mdCLAUDE.md
- monitor/CLAUDE.mdCLAUDE.md
- scan/CLAUDE.mdCLAUDE.md
- skills/CLAUDE.mdCLAUDE.md
- state_store/CLAUDE.mdCLAUDE.md
- stdio/CLAUDE.mdCLAUDE.md
- tests/CLAUDE.mdCLAUDE.md
- ui/CLAUDE.mdCLAUDE.md
- buildsystemSkill
- dashboardSkill
- fleetSkill
- healthcheckSkill
- powerSkill
The file
We found no rules to list in this file: it reads as prose or reference rather than instructions.
Files
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 --stagedexit 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_ROOTenv var (default./state) or CLI args; no hardcoded personal paths. - halt.py state-dir default:
resolve_state_dir()'s precedence isAESOP_STATE_ROOTenv >aesop.config.jsonstate_root>$AESOP_ROOT/state(whenAESOP_ROOTis set) >common.get_state_dir()'s cwd-relative./state. The$AESOP_ROOT/statestep (fixed 2026-10-05, PR #773) matters because callers thatcdelsewhere before invokinghalt.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.pyconcatenates 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-skiponly in truly browserless environments (CI must run all). - lock.mjs is the ONLY lock implementation: never reimplement locking in
proposals.mjsor elsewhere; all proposals/state updates must use fail-closedlock.mjswith exponential backoff + stale-lock breaking. The backoff sleeps viaAtomics.wait(synchronous, yields the core;acquireLockmust 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 inLOOP-MANIFEST.json(daemons/run-watchdog.sh, daemons/selfheal.sh, daemons/backup-fleet.sh, and this tool) unless a commit carriesLoop-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.pyscans 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.jsonpaths, 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--checkand--filesmodes, never a skip. Closes the PR #834 gap: merge commit b2c4db77 landed a literal<<<<<<< HEADblock 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.pyrendersscanner:FAIL, neverscanner:None/n/a/OK -- a silently-broken scanner gate must never read healthy. Every check result funnels throughrender_segment(), which treats aNoneresult or an OK/WARNDETAILED_OK_CHECKS(decisions/scanner/trigger) result whosedetailsisNoneasFAIL:unevaluated. Tests asserting the overall exit code (e.g.TestPowerSelftestHookDetection) must pinSCRIPTS_ROOTat a realscanner_selftest.pyso the scanner check is deterministic regardless of whether the CI runner's$HOMEhappens 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.gitis a FILE (worktree case) and usesgit rev-parse --git-common-dirto locate the actual git directory. - Fallback git dir resolution: Manual parsing of
.gitfile'sgitdir:pointer if git command fails. Every branch returnsPath(...).resolve()(8.3 TEMP aliasRUNNER~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 bycommon.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 runssecret_scan.py --rangeover each pushedremote_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_hookrefuses a symlinked.git/hooks/pre-pusheven under--force(the check runs before the exists/force decision, sowrite_bytesnever follows the link). Tests:TestInstallPrePushHookintests/test_init_project.py. - Pre-push hook scans pushed refs: the hook
init_project.pyinstalls reads git's per-ref stdin, blocks pushes torefs/heads/main|master, and runssecret_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 itgit add -Astaged 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 generatorsdoctorrequires (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=1skips.DEFAULT_CONFIGwrites"repos": []. Tests:TestInitWritesPushGateArtifactsintests/test_init_project.py. - Doctor port check (2026-10-17):
doctor.jsresolveDashboardPort()probes the portaesop dashlaunches on (PORTenv, thenaesop.config.jsondashboard.portviaci_config.loadAesopConfig, then 8770); the row is labelledPort 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_ROOTenv >aesop.config.jsonstate_root(relative values resolve against the config's dir,AESOP_ROOTor cwd; same asui/config.py) ><cwd>/state. Test:tests/test_state_dir_parity.py. dash.jsresolvesui/serve.pyfrom the installed package (PACKAGE_DIR = __dirname/..), notprocess.cwd(), because init does not scaffoldui/. It passesAESOP_STATE_ROOT= env >aesop.config.jsonstate_root><cwd>/state. Test:tests/dash-fresh-init.test.mjs.- dash.js expandHome + signal exits (SEM-1):
expandHomeexpands a leading~instate_rootbefore resolution, and a null exit code (signal death) maps to128+signalor 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.jsonhead; 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.appendruns 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.pygit_commitstages with a:(exclude)pathspec onLOCK_NAME(.append.lock), andinit.pywrites a.gitignorewith.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)callsStore.verify()first; on any problem it returnsCHAIN BROKENplus 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_bytesis never exceeded; a dropped tail ends on theTRUNCATION_MARKERline. 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 -textattributes, empty events/ and runs/, and the append-only guardtools/event_store/guard/events_append_only.sh(ported from conductor3 unchanged). Guard installed per worktree viacore.hooksPathunder the common dir; exit 1 when the branch or path exists (nothing changed), rollback on failure. Run withpython -I. Tests:tests/test_event_store_init.py. - tools/event_store/store.py verify (v1 seq): schema 1 (frozen conductor3 logs) restarts
seqat 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 brokenprevlink across files still fails. Each v1 event'stsdate must match its file name,tsmust be non-decreasing within a file, and a file's firsttsmust not precede the previous file's lastts; 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 testtest_known_limit_v1_deleted_middle_day_is_not_detectedasserts 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.shpr_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 --pathfor 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):
appendrefuses a kind outsideKINDS(exit 2, nothing written) and refuses hand-typedmerge.record-merge <owner/repo> <pr> --project Prunsgh pr viewitself (arg list, 30s timeout, fields incl.number,url) and appends amergeevent (actorrecord-merge, refssource=gh) only when state is MERGED and the returned number and url match the request; any failure or crash printsRECORD-MERGE FAILED: <why>, exit 1, writes nothing, lock released; a repeat printsalready-recorded, exit 0; it refuses a store whose chain fails verify or that holds an unrecognisedmergeevent for the PR. A lock path that is a directory is a clean failure.verify-claim <repo> <pr> <sha> --project Pverifies the whole chain, requires a well-formedstore.jsonheadequal to the last line's sha (a store with no head, such as one with zero events, is unknown), then compares the parsedmerge_shaonly (full or 7+ hex prefix;head_shais 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).baseRefNameis 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 actorrecord-mergeandsource=ghcount, 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, emitsTRIGGERlines 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-jsonis 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-jsonis 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|historyappends/prints the orchestrator GOAL asgoal_setevents on streamorchestrator_goal(StateAPI append, never patched);boot_state.pyprints 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:
--jsonalways emitsfixed(an empty list when nothing drifted) alongsideexit_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.pyto verify receipts against a keyring (receipt_pubkey.pub+ allreceipt_pubkeys/*.pubfiles). New keys are registered by adding amattworkpc-<key_id>.pubfile to this directory (derived from the private key PEM viakey_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.
- Receipt pubkeys keyring (tools/receipt_pubkeys/): Ed25519 public keys for receipt signing, used by
- 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.pyUTF-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_consoleruns 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_statustri-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 partlinux-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 throughtest_isolation_tripwire.pyas package.jsontest:node/test:shdo; a tripwire profile-drift finding fails the leg (native-leg tests:tests/test_linux_shape_native_leg.py).
Gates & tests
bench_api_runner.pylive-spend guard:AESOP_BENCH_OFFLINE=1is checked before any Anthropic client is constructed inmake_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.pyoffline guard:AESOP_BENCH_OFFLINE=1makes the claude-CLI runners (--runner haiku|sonnet|opus, which shellclaude -p) refuse before anyshutil.whichorsubprocess.runspawn;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.pyflags non-fenced lines over 1024 bytes per file, ratcheted againsttools/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 guidedocs/ACTIONS-TEMPLATE.md; verified bytests/test_actions_template.py(YAML validity, CLI commands checked againstbin/cli.js --help, no invented flags/fabricated output).templates/wave-presets/*.jsonis the unrelated wave-manifest-preset set consumed bywave_templates.py. - wave_templates.py testCmd rules:
validate_manifest()rejects a testCmd that pipes intohead/tailwithoutpipefail(the pipe's exit status would mask a failing stage), andimport X/--cov=Xmodule targets that are not Python identifiers (--cov=src/xpaths and unresolved{placeholders}are skipped). Library presets use{module_name}(hyphens to underscores, frommodule_name_for()) for import,--covand thesrc/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, socd docs && sphinx-build ...checkssphinx-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.pylints every shipped preset intemplates/wave-presets/with absent third-party binaries stubbed on PATH. - PR symbol survival (Guardrail G13):
pr_symbol_survival_check.pycollects top-level symbols (Pythondef/class/async defat ANY indentation, matched by bare name so a helper nested in a method or block, or re-indented, still counts as surviving; JS/MJSexport function|const|class+ top-levelfunction name(, shellname() {) 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_exhaustedsilently dropped by a conflict-resolution merge, CI stayed green). CLI--base REF(defaultorigin/main)--head REF(defaultHEAD)--original-head SHA--json; exit 0=survived/1=missing/2=error; read-only, stdlib-only. BLOCKING (promoted from advisory): wired intoci.ymlas the requiredpr-symbol-survivaljob (rc propagated, recordsG13 rc=<n>in the job summary) and intohooks/pre-push-policy.shcheck_symbol_survival()(onebase..headrange 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, includinggit checkout main; git merge featurewhere 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-survivalis declared intools/required-checks.jsonto match live branch protection. verify_test_coverage.py— Guardrail G2:--checkfails closed if anytests/**/*.py(excepttests/fixtures/) defines aunittest.TestCaseor a test_-prefixed function (AST) but is outside the collectedtests/test_*.pyglob (ci_shard_runner'sgit ls-files); exit 0=covered/1=orphans/2=error; stdlib-only. Node side:hooks/**/*.test.mjsare discovered byfind_hooks_node_test_files()and are covered only by whole-wordhooks/...*.test.mjstokens inpackage.jsontest:node(hooks_node_glob_tokens; substrings andtests/hooks/*do not credit).metrics_gate.py— NO-UNVERIFIED-METRICS: scans added lines of*.mdin a<range>(defaultorigin/main...HEAD) for unmarked%/Nx/$claims ($inside an HTML comment span is skipped, awk field refs;%/Nxstill checked there); fail-closed: any git failure on the range (git exit 128 for an unresolvable ref, e.g. a0000000...<sha>base, or an exception) printsMETRICS-GATE: BLOCK unresolvable range <range> (git exit N)and exits 1, while a resolvable range with no.mdchanges passes; exit 0=pass/1=block; stdlib-onlymetrics_gate.pyretraction (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.mdfile get no reliefpr_footprint_gate.py— Guardrail G2.7: fails PRs with >100 files or >5000 deletions unless labeledbig-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 viadriver/context_pack.py'sadd_evidence_to_pack()(pure in-memory, never touches the filesystem or repo_root/conductor_root) — never re-derive the already-built brief throughbuild_context_pack()with a fakebrief:<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 1800dispatch 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, drivesmain()). multi_dispatch.py (claim read fail-closed):check_conflictreads claims via the strictget_all_claimed_files_strict; an unreadable or corrupt claims store raisesClaimStateUnknown(store path in the message) andmain()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-checkthen 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')intools/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/memoryis excused only when~/.claude/state/memory-write-ledger.jsonlhas a row whosepath(relative to~/.claude) equals that exact file and whosesha256matches 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.baksiblings are never excused; an unreadable or deeply nested ledger line (ValueError, RecursionError) is skipped, never a crash and never an excuse.
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
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.

