fix: export AGENT_BRAIN_PATH for Claude, document the contract #118

Merged

joshtronic merged 1 commit from docs/agents-memory-path-and-honesty into master

2026-05-23 05:31:32 +00:00

joshtronic commented

2026-05-23 05:31:21 +00:00

Owner

Two failure modes surfaced from a tier-1 ticket:

The bot didn't actually save a memory it told us it would,
because AGENTS.md said "use the Edit/Write tool" without
making the brain path explicit. From a tier-1 worktree, a
relative path like memories/projects/foo.md lands in the
target repo's worktree, not in brain, and gets either shipped
in the PR diff or torn down with the worktree.
Worse, even if the bot HAD known to use $AGENT_BRAIN_PATH, the
variable wasn't exported to any of the four Claude Code
invocations after the cost-ledger refactor -- the inline
AGENT_BRAIN_PATH=X command patterns only scoped to specific
subprocesses (rag_query, discretionary-read.sh). The main
claude --print invocation in tier-1 / PR-review / maintenance
/ site-work saw no brain path at all.
As a separate honesty issue, the bot's PR body checked off
"Save memory about X" with a green checkmark despite never
writing the file. Fabricated completed work breaks reviewer
trust.

Fixes:

Export AGENT_BRAIN_PATH (and AGENT_WEBSITE_PATH) globally in
tick.sh right after BOT_USER is resolved, so every Claude
invocation inherits them.
AGENTS.md "Writing memories" section now spells out the
absolute-path requirement with examples ($AGENT_BRAIN_PATH/
memories/projects/.md etc.), and explains why a
relative path silently fails.
AGENTS.md "Producing work" section adds a new MANDATORY bullet:
every checkbox in PR_BODY.md must correspond to an actual
diff change. Don't ship a PR claiming work that wasn't done.

Co-Authored-By: Claude Opus 4.7 noreply@anthropic.com

Two failure modes surfaced from a tier-1 ticket: 1. The bot didn't actually save a memory it told us it would, because AGENTS.md said "use the Edit/Write tool" without making the brain path explicit. From a tier-1 worktree, a relative path like `memories/projects/foo.md` lands in the target repo's worktree, not in brain, and gets either shipped in the PR diff or torn down with the worktree. 2. Worse, even if the bot HAD known to use $AGENT_BRAIN_PATH, the variable wasn't exported to any of the four Claude Code invocations after the cost-ledger refactor -- the inline `AGENT_BRAIN_PATH=X command` patterns only scoped to specific subprocesses (rag_query, discretionary-read.sh). The main `claude --print` invocation in tier-1 / PR-review / maintenance / site-work saw no brain path at all. 3. As a separate honesty issue, the bot's PR body checked off "Save memory about X" with a green checkmark despite never writing the file. Fabricated completed work breaks reviewer trust. Fixes: - Export AGENT_BRAIN_PATH (and AGENT_WEBSITE_PATH) globally in tick.sh right after BOT_USER is resolved, so every Claude invocation inherits them. - AGENTS.md "Writing memories" section now spells out the absolute-path requirement with examples ($AGENT_BRAIN_PATH/ memories/projects/<repo>.md etc.), and explains why a relative path silently fails. - AGENTS.md "Producing work" section adds a new MANDATORY bullet: every checkbox in PR_BODY.md must correspond to an actual diff change. Don't ship a PR claiming work that wasn't done. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

joshtronic added 1 commit

2026-05-23 05:31:21 +00:00

fix: export AGENT_BRAIN_PATH for Claude, document the contract

Lint / check-sync (push) Successful in 5s

Details

Lint / check-sync (pull_request) Successful in 4s

Details

725211bfa6

Two failure modes surfaced from a tier-1 ticket:

1. The bot didn't actually save a memory it told us it would,
   because AGENTS.md said "use the Edit/Write tool" without
   making the brain path explicit. From a tier-1 worktree, a
   relative path like `memories/projects/foo.md` lands in the
   target repo's worktree, not in brain, and gets either shipped
   in the PR diff or torn down with the worktree.

2. Worse, even if the bot HAD known to use $AGENT_BRAIN_PATH, the
   variable wasn't exported to any of the four Claude Code
   invocations after the cost-ledger refactor -- the inline
   `AGENT_BRAIN_PATH=X command` patterns only scoped to specific
   subprocesses (rag_query, discretionary-read.sh). The main
   `claude --print` invocation in tier-1 / PR-review / maintenance
   / site-work saw no brain path at all.

3. As a separate honesty issue, the bot's PR body checked off
   "Save memory about X" with a green checkmark despite never
   writing the file. Fabricated completed work breaks reviewer
   trust.

Fixes:
- Export AGENT_BRAIN_PATH (and AGENT_WEBSITE_PATH) globally in
  tick.sh right after BOT_USER is resolved, so every Claude
  invocation inherits them.
- AGENTS.md "Writing memories" section now spells out the
  absolute-path requirement with examples ($AGENT_BRAIN_PATH/
  memories/projects/<repo>.md etc.), and explains why a
  relative path silently fails.
- AGENTS.md "Producing work" section adds a new MANDATORY bullet:
  every checkbox in PR_BODY.md must correspond to an actual
  diff change. Don't ship a PR claiming work that wasn't done.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

joshtronic merged commit d602b1e197 into master

2026-05-23 05:31:32 +00:00

joshtronic deleted branch docs/agents-memory-path-and-honesty

2026-05-23 05:31:32 +00:00

joshtronic referenced this pull request from a commit

2026-05-23 05:31:34 +00:00

Merge pull request 'fix: export AGENT_BRAIN_PATH for Claude, document the contract' (#118) from docs/agents-memory-path-and-honesty into master