docs(agents): cross-reference #790's keg-python pin in the root-checkout rule (XS)

[EtanHey]

Follow-up to #789 (merged aaaf09c0). Per canon 9, a change found after merge opens a new PR rather than another commit on the merged branch.

Why now

#789 landed the root-checkout rule with the honest state at the time: the brief told me to cross-reference "the keg-python hook pin" as landed or in flight, and I reported neither — zero open PRs, and the pin existing only in ~/.claude/settings.json as machine config. #790 merged 36 minutes after #789 and changed that. The section says something no longer true, so it gets corrected.

What changed in the text

One bullet becomes three:

1. For hooks, the rule is now defence in depth. fix(hooks): pin every BrainLayer hook to the keg python, never bare python3 (L) #790 gives every hooks/*.py the keg-python shebang via the opt/ symlink, adds src/brainlayer/hook_python.py (resolves the interpreter, refuses a silent PATH fallback) and a settings linter. A git checkout at the root can no longer re-aim a hook.
2. For everything else, the rule is still primary. fix(hooks): pin every BrainLayer hook to the keg python, never bare python3 (L) #790 did not remove the .pth.
3. ⚠️ A live "merged is not deployed" case (new — not in docs(agents): land the "never check out at the repo root" rule in tracked AGENTS.md (XS) #789).

Verification, after #790 merged

$ cat …/site-packages/_brainlayer.pth
/Users/etanheyman/Gits/brainlayer/src                      # still there

$ python3 -c "import brainlayer; print(brainlayer.__file__)"
/Users/etanheyman/Gits/brainlayer/src/brainlayer/__init__.py   # still the working tree

So the mechanism survives #790; only its worst consumer was closed.

And the pin is only half-deployed on this machine. ~/.claude/hooks/*.py are real files, not symlinks into this repo, so #790's shebang edit does not reach them by merging:

deployed copy	shebang on origin/main	shebang at ~/.claude/hooks/
brainlayer-prompt-search.py	#!/opt/homebrew/opt/brainlayer/libexec/venv/bin/python	#!/usr/bin/env python3
brainlayer-session-start.py	same	#!/usr/bin/env python3
session-cleanup.py	same	#!/usr/bin/env python3

They are safe today only because ~/.claude/settings.json names the keg interpreter ahead of the script path, which makes the shebang moot. That is one mechanism, not the two #790 intends. The new bullet tells the reader to run python -m brainlayer.hook_python ~/.claude/settings.json before believing the pin is live on a machine.

This is a note about deployment state, not a defect in #790 — its repo-side change is correct and complete. Flagging it because Etan's letter says merged is not deployed — verify the thing that executes, and because the section is the place a future seat will look.

Docs-only; no code paths touched. Gate scoped: BRAINLAYER_PREPUSH_SCOPE=changed-only BRAINLAYER_CHANGED_FILES=AGENTS.md → passed.

Worktree cut with the absolute form #789 documented, dogfooding round 1's fix:
git worktree add ~/Gits/brainlayer/.worktrees/agents-root-rule-xref -b wt/agents-root-rule-xref origin/main

@coderabbitai review

---

Agent: brainlayerClaude-8a49f7a0 · model claude-opus-5[1m]

---

Note

Low Risk
Documentation-only; no runtime, auth, or data paths changed.

Overview
Updates the “never work at the repo root” section in AGENTS.md so it matches post-#790 reality instead of the pre-pin wording from #789.

The old single bullet (keg pin in machine settings.json only; root .pth still load-bearing for hooks) is replaced by three bullets: for hooks, root-checkout is now defence in depth because repo hooks use the Homebrew keg shebang, hook_python.py, and a settings linter; for everything else, the .pth rule stays primary with a 2026-09-06 verification note; and a ⚠️ merged ≠ deployed warning that copies under ~/.claude/hooks/ may still use #!/usr/bin/env python3 until settings pin them—run python -m brainlayer.hook_python on the live settings file before assuming the pin is active.

^{Reviewed by Cursor Bugbot for commit a9f16f0. Bugbot is set up for automated code reviews on this repo. Configure here.}

Note

Document keg-python pin cross-reference in root-checkout rule in AGENTS.md

Replaces the single keg-pinned Claude Code hooks guidance block with three separate bullets:

• States hook pinning is now defense in depth because hook shebangs use the Homebrew opt/ interpreter, src/brainlayer/hook_python.py rejects silent PATH fallback, and its module invocation lints settings for bare python3
• States the root checkout remains the primary source for non-hook/default-interpreter consumers because the .pth stays active
• Adds deployment guidance that merged repository changes do not update files under ~/.claude/hooks/, and deployed scripts may still use #!/usr/bin/env python3 unless the settings-file pin is verified with the lint command

📊 Macroscope summarized a9f16f0. 1 file reviewed, 1 issue evaluated, 1 issue filtered, 0 comments posted

🗂️ Filtered Issues

AGENTS.md — 0 comments posted, 1 evaluated, 1 filtered

• line 179: The new assertion is dated 2026-09-06, which is still in the future relative to the review date (2026-09-05 UTC). Thus this cannot have been verified when the document is consumed at this commit; it presents the .pth state as completed evidence before the stated measurement date, misleading operators who rely on the root-checkout safety guidance. [ Out of scope (post-validation triage) ]

[cursor]

Bugbot couldn't run - usage limit reached

Bugbot is counted against Cursor usage for this user or team, and this run hit a usage or spend limit.

A user or team admin can review and increase usage limits in the Cursor dashboard.

(requestId: serverGenReqId_10cfba83-8eda-4512-aa0f-b4186467ee4f)

[coderabbitai]

Warning

Review limit reached

Next included review available in 10 seconds.

Check out review usage here.

View limit details

Limit details: You’ve used the included review currently available.

You've used all free OSS reviews for now. Wait for the free limit to reset to keep reviewing this public repository.

Learn how review limits work.

Review configuration:

⚙️ Run configuration

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Team

Run ID: 9c88d9d8-7e57-4888-a317-698987ac2dcb

📥 Commits

Reviewing files that changed from the base of the PR and between a9fc609 and a9f16f0.

📒 Files selected for processing (1)

• AGENTS.md

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[deepsource-io]

DeepSource Code Review

We reviewed changes in a9fc609...a9f16f0 on this pull request. Below is the summary for the review, and you can see the individual issues we found as inline review comments.

See full review on DeepSource ↗

PR Report Card

Overall Grade

Security   Reliability   Complexity   Hygiene

Code Review Summary

Analyzer	Status	Updated (UTC)	Details
Python		Sep 5, 2026 10:33p.m.	Review ↗
Swift		Sep 5, 2026 10:33p.m.	Review ↗
JavaScript		Sep 5, 2026 10:33p.m.	Review ↗
Shell		Sep 5, 2026 10:33p.m.	Review ↗
Secrets		Sep 5, 2026 10:33p.m.	Review ↗

---

Important

AI Review is run only on demand for your team. We're only showing results of static analysis review right now. To trigger AI Review, comment @deepsourcebot review on this thread.

[github-actions]

BrainLayer ratchet

Every Value below was measured by this run. A row this machine cannot measure says n/a — <reason> instead of a number; baselines in Notes name their own machine, method and date and were not measured here.

Row	Status	Value (measured by this run)	Method	Notes
commit provenance	🟢 GREEN	measured a9f16f06c58f == PR head · checkout 5b66b72e7487	commit graph + live PR head · in-process · runner	Which commit this whole table is about. On a pull_request event the checkout is GitHub's synthetic merge ref, whose sha is not on the PR — #759's table printed 13fa724278bf while that PR's head was 4632f979 — so this row names the PR-head parent instead, the sha a reviewer can actually see. The comparison sha is read live from repos/{owner}/{repo}/pulls/{n} when the table is collected, not taken from the event payload, because the payload cannot know the run has been overtaken. Residual window, stated rather than papered over: a push landing between that read and the comment being posted is not caught here — the run for that push refreshes the table.
baseline attestation	🟢 GREEN	baseline f421d1a7c5e6 matches the main attestation (run 33996075101 · main a9fc6098b050 · 2026-09-05T22:30:12Z)	main attestation artifact via Actions API · in-process · runner	What every comparison is measured AGAINST, and who says so. The baseline fields of tests/fixtures/sprint_gate/corpus.json (queries, latency_baseline_ms, thresholds) are compared to the ratchet-attestation artifact of the latest successful push or (no-input) workflow_dispatch run of ratchet-attest.yml on main, fetched through the Actions API — a PR run cannot write to another run's artifacts. A field that differs is RED unless that main run measured the new value; today no runner-side collector measures any baseline field, so today the baseline cannot move by PR at all, and this row says so instead of a hand edit passing. Boundary: the comparator is this PR's checkout of ci_ratchet_table.py, diff-reviewable, not tamper-proof.
provenance	🟢 GREEN	stamped 5b66b72e7487 == HEAD, tree clean	wheel stamp · in-process · runner	Sha half of #749 keg-mode provenance: a keg built from this wheel can answer __build_sha__. The helper-age and served-process predicates need a running BrainBar and are measured only by scripts/sprint_gate.py on an installed Mac. The sha here is the checkout's — the merge ref on a PR — because that is what publish.yml stamps at release time; the PR-head sha this table describes is the one in commit provenance above.
fallback replay debt	⚪ n/a	n/a — no fallback queue on this machine: the pending memories live in ~/Gits/*/docs.local/decisions, and docs.local/ is gitignored, so a runner checkout has no copy of them to count	docs.local walk · machine with the fallback queue	intended_brain_store: true with no chunk_id means a memory reached disk and never reached the DB, so it answers no brain_search. Budget: 0. Any pending or unparseable file is a finding, never a band -- 122 of these sat from 2026-06-28 to 2026-09-05 because nothing counted them where a reader would look. Measured by walking the tree, so it is only ever measured on a machine that HAS the tree.
mapped bytes	⚪ n/a	n/a — no BrainBar daemon at /tmp/brainbar.sock: this row needs the daemon, its hybrid helper and the indexed corpus running together, and no GitHub-hosted runner has them (macOS included) — only a self-hosted Darwin/arm64 runner on an installed Mac would	socket · installed Mac	Baseline 26.2 GB — installed Mac, socket, 2026-09-03, after R2 drained 15,070 → 0. Up from 16.8 GB because the drain left more vectors mapped under the same cap: the change is the drain, not a leak. Not measured by this run.
search p50/p95	⚪ n/a	n/a — no BrainBar daemon at /tmp/brainbar.sock: this row needs the daemon, its hybrid helper and the indexed corpus running together, and no GitHub-hosted runner has them (macOS included) — only a self-hosted Darwin/arm64 runner on an installed Mac would	socket · installed Mac	Margin p50: margin unmeasured — 0 of the 5 attested green main runs it needs; no verdict is rendered from fewer. Margin p95: margin unmeasured — 0 of the 5 attested green main runs it needs; no verdict is rendered from fewer. Calibrated on MacBook-Pro.local at 2026-09-01T08:42:22Z under active_sprint_load (tests/fixtures/sprint_gate/corpus.json). Not measured by this run.
idle CPU	⚪ n/a	n/a — no BrainBar daemon at /tmp/brainbar.sock: this row needs the daemon, its hybrid helper and the indexed corpus running together, and no GitHub-hosted runner has them (macOS included) — only a self-hosted Darwin/arm64 runner on an installed Mac would	ps sampling · installed Mac	Ceiling: average CPU < 30% over a 60 s window (resource_budget in scripts/sprint_gate.py), ratified and kept as a hard budget. Margin daemon: margin unmeasured — 0 of the 5 attested green main runs it needs; no verdict is rendered from fewer. Margin helper: margin unmeasured — 0 of the 5 attested green main runs it needs; no verdict is rendered from fewer. Margin watcher: margin unmeasured — 0 of the 5 attested green main runs it needs; no verdict is rendered from fewer. Needs the BrainBar daemon, helper and watcher actually running. Not measured by this run.
signature_valid	⚪ n/a	n/a — the macOS signature-parity job is trigger-gated and did not run on this PR: it touches no release or signing path (pyproject.toml, scripts/release-*, scripts/brainlayer-version-check.sh, publish.yml, ratchet.yml) and carries no ratchet:signatures label — a GitHub macOS runner bills at ~10× Linux minutes and rebuilds the keg venv from source	codesign · installed keg	scripts/release-verify-signatures.sh <keg> codesign-verifies every *.so/*.dylib under libexec/venv. The macOS parity job installs the published tap formula (etanhey/layers/brainlayer), so this row measures the release path — formula, published sdist and Homebrew's relocation — and not this PR's tree. Release-time baseline for the same keg on a different machine: 442 valid / 0 invalid — installed Mac (M4 Max), brew --prefix brainlayer 1.5.11, 2026-09-03.

🟢 GREEN measured, within budget · 🔴 RED measured, out of budget — a finding to clear before merge · ⚪ n/a not measurable on this machine, never guessed.

No RED rows.

Measured on Linux/x86_64 · measured a9f16f06c58f · PR head a9f16f06c58f · checkout 5b66b72e7487 · run · updated 2026-09-05 22:33:53 UTC