[BUG] Claude Code does not enforce branch discipline for documentation files

Preflight Checklist

• [x] I have searched existing issues and this hasn't been reported yet
• [x] This is a single bug report (please file separate reports for different bugs)
• [x] I am using the latest version of Claude Code

What's Wrong?

Claude Code Title: Claude Code does not enforce branch discipline for documentation files — planning docs silently land on feature branches

Environment: Claude Code CLI, manage-my-life-v2 project, macOS

Summary:

When Claude Code is working on a feature branch and is instructed to update planning documents (roadmap, session notes, CURRENT_FOCUS), it writes and commits those updates to the current feature branch rather than to main. The user did not ask it to do this and had no indication it happened. The documents appeared committed and current but were invisible to subsequent sessions that started from main.

Impact:

Multiple work sessions executed against a stale roadmap. Decisions made in earlier sessions were not visible to later sessions. The discrepancy was only caught when the user manually questioned why the roadmap looked wrong. The workaround required a branch audit, cherry-picking doc files back to main, and a manual merge — all of which should not have been necessary.

Expected behavior:

Claude Code should recognize that certain files (roadmaps, session logs, CURRENT_FOCUS docs) are living tracking documents that belong on main regardless of the active working branch. When writing to these files on a feature branch, it should either warn the user or automatically target main.

Workaround applied:

Hard rule added to project CLAUDE.md requiring a branch check (git branch --show-current) before reading or writing any planning document. Rule also added to persistent memory. These are compensating controls — the underlying tool behavior is unchanged. not enforce branch discipline for documentation files

What Should Happen?

Expected Behavior:

When Claude Code is operating on a feature branch and receives an instruction to update a planning document (roadmap, session log, CURRENT_FOCUS, or any file in docs/), it should:

Detect the conflict — recognize that the active branch is not main and that the target file is a tracking document, not a feature file
Warn before writing — surface a clear message: "This file is a project tracking document. Writing it to fix/my-feature will make it invisible to future sessions starting from main. Do you want to commit this to main instead?"
Offer the correct action — give the user the choice to write to main directly, stash the change for later, or proceed to the feature branch with explicit acknowledgment
Never silently write tracking documents to a non-main branch — silent writes to feature branches are the failure mode; the user has no way to detect this without manually auditing branch state
The tool already knows which branch it is on. It already knows which files it is writing. The missing piece is a classification layer that distinguishes feature files from living project documents and applies branch-aware behavior accordingly.

Error Messages/Logs

Steps to Reproduce

Steps to Reproduce:

Initialize a project with a planning document on main (e.g., docs/plans/roadmap.md, docs/CURRENT_FOCUS.md)
Start a Claude Code session — confirm it reads the planning doc from main
Create a feature branch: git checkout -b fix/my-feature
Begin implementation work on the feature branch
During the session, instruct Claude Code to update the roadmap or session notes — e.g., "update the roadmap to reflect what we just completed"
Claude Code writes and commits the document update to fix/my-feature
No warning is shown. No branch conflict is flagged. The commit appears successful.
Merge the feature branch to main (docs files are not included in the merge because they were not part of the PR scope)
Start a new Claude Code session from main
Claude Code reads the planning doc from main — the updates from step 6 are missing
The new session executes against stale information with no indication that anything is wrong
Result: Planning documents silently diverge from main. Subsequent sessions operate on outdated context. The discrepancy is only discoverable by manually comparing branch state — there is no in-tool warning.

Frequency: Reproducible every time a doc update is requested while on a non-main branch.

Claude Model

Opus

Is this a regression?

No, this never worked

Last Working Version

_No response_

Claude Code Version

2.1.179 (Claude Code)

Platform

Anthropic API

Operating System

macOS

Terminal/Shell

Terminal.app (macOS)

Additional Information

_No response_