Files
headroom/tests/test_learn/test_writer.py
45dacc1f94 fix(learn): anchor the managed block on its last start marker, append when no end marker (#4342)
## Description

`_merge_into_file` (`headroom/learn/writer.py`) located the managed
block with `block_pattern` (first occurrence of the start marker to the
nearest end marker) whenever `_MARKER_START in existing`. Two
consequences, both reported in #4339:

1. Hand-written prose that quotes the start-marker string became the
start of the match, so `--apply` replaced everything from that mention
through the real block's end marker, deleting the hand-written text in
between.
2. A file holding the start marker but no end marker matched nothing:
`sub()` returned the file unchanged and every recommendation of the run
was silently dropped while the CLI still printed `[WROTE]`.

The block is now identified by the shape `_build_section` writes: a line
that is **exactly** the start marker through the next line that is
**exactly** the end marker. A marker quoted inside prose (sharing its
line with other text, or indented) or inside a fenced code block (a
Markdown example) is not a boundary, and a start marker with no end
marker before the next start marker is skipped. One helper,
`_find_managed_block()`, is used by every reader and writer of the block
in this module, so the block that is parsed is the block that is
replaced.

The first commit (2c6853ea) used "the last start marker that has an end
marker after it"; review showed that only moved the problem to prose
after the block, and left `_parse_prior_recommendations` reading a
different span. The second commit (eba6458b) replaces it with the
line-based rule above, and the third (40880d1e, after review) skips
marker lines inside fenced code blocks.

Closes #4339

## Type of Change

- [x] Bug fix (non-breaking change that fixes an issue)
- [ ] New feature (non-breaking change that adds functionality)
- [ ] Breaking change (fix or feature that would cause existing
functionality to change)
- [ ] Documentation update
- [ ] Performance improvement
- [ ] Code refactoring (no functional changes)

## Changes Made

- `headroom/learn/writer.py`: new `_find_managed_block(text) -> (start,
end) | None` (linear scan of lines; whole-line markers only; marker
lines inside ``` / ~~~ fences ignored, CommonMark-style open/close
rules; first complete block). `extract_marker_block`,
`_parse_prior_recommendations`, `_merge_into_file`,
`_strip_marker_block` and the two legacy-migration presence checks in
`_migrate_legacy_block` use it. With no block (including a dangling
start marker), `_merge_into_file` appends a fresh section as for a file
with no markers. `_MARKER_PATTERN` and the `block_pattern` import are
removed from this module; `managed_block.block_pattern` and
`sanitize_block_text` are unchanged.
- `tests/test_learn/test_writer.py` (`TestClaudeCodeWriter`), four
tests:
- `test_merge_keeps_prose_that_quotes_the_start_marker_above_the_block`
and `test_merge_appends_a_block_when_the_end_marker_is_missing` (the two
cases in #4339; both fail on `main`);
- `test_merge_keeps_prose_quoting_both_markers_after_the_block` and
`test_prior_sections_come_from_the_block_not_from_quoting_prose` (the
two layouts from the first review; both fail on the first commit);
- `test_merge_leaves_a_fenced_example_of_the_block_untouched` (the
fenced-example layout from the second review; fails on
eba6458b/35cf4a98) and
`test_fenced_code_inside_the_block_does_not_hide_its_end_marker` (a
closed code fence in a recommendation body).

Behaviour notes: a file holding two complete blocks used to have both
replaced by `sub()`; the merge now rewrites the first one and leaves the
second as text, and `_strip_marker_block` (legacy migration) still
removes every complete block. An unclosed code fence inside the managed
block would hide its end marker (the merge then appends a fresh block);
recommendation bodies with balanced fences are covered by a test.

## Testing

- [x] Unit tests pass (`pytest`) — `tests/test_learn/`,
`tests/test_managed_block_injection.py`,
`tests/test_memory/test_traffic_learner.py`: 617 passed, 10 skipped (on
40880d1e)
- [x] Linting passes (`ruff check .`) — on the two changed files, plus
`ruff format --check`
- [x] Type checking passes (`mypy headroom`) — run on
`headroom/learn/writer.py`; the single reported error is in
`headroom/providers/model_metadata.py:79` and is identical on `main`
- [x] New tests added for new functionality
- [ ] Manual testing performed

### Test Output

```text
# the four tests against the FIRST commit 2c6853ea (fail-before for the two review layouts)
$ pytest tests/test_learn/test_writer.py -q -k "quotes_the_start_marker or end_marker_is_missing or both_markers_after or quoting_prose" --tb=line
tests/test_learn/test_writer.py:379: AssertionError: assert 2 == 1          # "### Manual policy" copied into the block
FAILED tests/test_learn/test_writer.py::TestClaudeCodeWriter::test_merge_keeps_prose_quoting_both_markers_after_the_block
FAILED tests/test_learn/test_writer.py::TestClaudeCodeWriter::test_prior_sections_come_from_the_block_not_from_quoting_prose
2 failed, 2 passed, 44 deselected in 1.82s

# with eba6458b (pass-after)
4 passed, 44 deselected in 0.99s

# fenced-example case (second review) on 35cf4a98, then on 40880d1e
FAILED tests/test_learn/test_writer.py::TestClaudeCodeWriter::test_merge_leaves_a_fenced_example_of_the_block_untouched
1 failed, 1 passed, 48 deselected
2 passed, 48 deselected in 1.14s

# the #4339 cases against main 4c7acba5 (from the first round)
2 failed (hand-written rule line deleted; file returned unchanged)

$ pytest tests/test_learn tests/test_managed_block_injection.py tests/test_memory/test_traffic_learner.py -q
617 passed, 10 skipped, 1 warning in 10.90s

$ ruff check headroom/learn/writer.py tests/test_learn/test_writer.py && ruff format --check headroom/learn/writer.py tests/test_learn/test_writer.py
All checks passed!
2 files already formatted
```

## Real Behavior Proof

- Environment: WSL2 Ubuntu, Python 3.12.15, pytest 9.1.1, ruff 0.17.1,
mypy 2.4.0; a clone of this fork with the core runtime dependencies only
- Exact command / steps: on the PR branch at the first commit, apply
only the two new tests and run the four `-k` tests above (the two review
layouts fail, the two #4339 cases pass); apply the source change and run
them again (all pass); then the learn, managed-block and traffic-learner
suites, ruff and mypy as pasted
- Observed result: prose that quotes the start marker above the block,
prose that quotes both markers below it, and headings inside such prose
all stay hand-written text: the managed block is the one rebuilt, its
prior sections are read from that same block, and a dangling start
marker gets a fresh section appended instead of losing the run's
recommendations
- Not tested: `headroom learn --apply` end to end through the CLI (only
`_merge_into_file`, the parser and the writer tests); the memory
writers, which share `block_pattern` but are not changed here

## Runtime Rollout Safety

- Rollout-managed feature(s): none (`headroom learn` is not behind a
rollout flag)
- Minimum rollout channel: n/a (not rollout-managed)
- Stable/default behavior changed: only for files with marker strings
quoted in prose, a dangling start marker, or two complete blocks (see
Behaviour notes); a file the writer produced merges exactly as before
- Kill switch / disable path: none added; `headroom learn` without
`--apply` never writes
- Unsafe override required: no
- Qualification impact: none known; no `CHANGELOG.md` edit
(release-please)
- Rollback path: revert the two commits

## Review Readiness

- [x] I have performed a self-review
- [x] This PR is ready for human review

## Checklist

- [x] My code follows the project's style guidelines
- [x] I have performed a self-review of my code
- [x] I have commented my code, particularly in hard-to-understand areas
- [ ] I have made corresponding changes to the documentation (none
needed)
- [x] My changes generate no new warnings
- [x] I have added tests that prove my fix is effective or that my
feature works
- [x] New and existing unit tests pass locally with my changes
- [x] I did **not** edit `CHANGELOG.md` — it is generated by
release-please from my Conventional Commit PR title (a CI guard enforces
this)

## Additional Notes

Produced with AI assistance (Claude Code) operated by me (HetCreep); the
test runs above were executed on my machine on a clone of this fork.
Related: #3850 (introduced `managed_block.py` and the nearest-end-marker
rule).

🤖 Generated with [Claude Code](https://claude.com/claude-code)

---------

Co-authored-by: Claude Fable 5.1 <noreply@anthropic.com>
Co-authored-by: JerrettDavis <mxjerrett@gmail.com>
2026-10-24 08:45:10 -07:00

990 lines
41 KiB
Python

"""Tests for recommendation writer — marker-based file updates."""
import subprocess
from pathlib import Path
import pytest
from headroom.learn.models import ProjectInfo, Recommendation, RecommendationTarget
from headroom.learn.writer import (
_MARKER_END,
_MARKER_START,
ClaudeCodeWriter,
CodexWriter,
GeminiWriter,
GrokWriter,
_merge_into_file,
_parse_prior_recommendations,
_read_text_tolerant,
extract_marker_block,
)
def _project(tmp_path: Path) -> ProjectInfo:
proj_dir = tmp_path / "myproject"
proj_dir.mkdir()
data_dir = tmp_path / "data"
data_dir.mkdir()
memory_dir = data_dir / "memory"
memory_dir.mkdir()
return ProjectInfo(
name="myproject",
project_path=proj_dir,
data_path=data_dir,
)
def _rec(target: RecommendationTarget, section: str, content: str) -> Recommendation:
return Recommendation(
target=target, section=section, content=content, confidence=0.8, evidence_count=5
)
class TestClaudeCodeWriter:
def test_dry_run_does_not_write(self, tmp_path):
proj = _project(tmp_path)
writer = ClaudeCodeWriter()
recs = [_rec(RecommendationTarget.CONTEXT_FILE, "Environment", "- Use uv")]
result = writer.write(recs, proj, dry_run=True)
assert result.dry_run is True
assert len(result.files_written) == 1
# File should NOT exist (dry run)
claude_local = proj.project_path / "CLAUDE.local.md"
assert not claude_local.exists()
# Default target is the personal CLAUDE.local.md, never the shared CLAUDE.md
assert result.files_written[0].name == "CLAUDE.local.md"
def test_apply_writes_claude_local_md(self, tmp_path):
proj = _project(tmp_path)
writer = ClaudeCodeWriter()
recs = [_rec(RecommendationTarget.CONTEXT_FILE, "Environment", "- Use `uv run python`")]
result = writer.write(recs, proj, dry_run=False)
assert result.dry_run is False
# Learnings go to the personal, gitignored CLAUDE.local.md by default...
claude_local = proj.project_path / "CLAUDE.local.md"
assert claude_local.exists()
content = claude_local.read_text()
assert "uv run python" in content
assert _MARKER_START in content
assert _MARKER_END in content
# ...and never touch the team-shared CLAUDE.md.
assert not (proj.project_path / "CLAUDE.md").exists()
def test_apply_writes_memory_md(self, tmp_path):
proj = _project(tmp_path)
writer = ClaudeCodeWriter()
recs = [_rec(RecommendationTarget.MEMORY_FILE, "Retry Prevention", "- Don't retry globs")]
writer.write(recs, proj, dry_run=False)
memory_md = proj.data_path / "memory" / "MEMORY.md"
assert memory_md.exists()
assert "Don't retry globs" in memory_md.read_text()
def test_hand_written_claude_md_left_untouched(self, tmp_path):
proj = _project(tmp_path)
claude_md = proj.project_path / "CLAUDE.md"
original = "# My Project\n\nExisting instructions here.\n"
claude_md.write_text(original)
writer = ClaudeCodeWriter()
recs = [_rec(RecommendationTarget.CONTEXT_FILE, "Environment", "- Use uv")]
writer.write(recs, proj, dry_run=False)
# A hand-written CLAUDE.md with no headroom block is left exactly as-is.
assert claude_md.read_text() == original
# Learnings land in the personal CLAUDE.local.md instead.
local_content = (proj.project_path / "CLAUDE.local.md").read_text()
assert "Use uv" in local_content
def test_carries_forward_prior_sections_not_resurfaced(self, tmp_path):
"""Re-running learn must not drop prior sections that the new run didn't re-surface."""
proj = _project(tmp_path)
claude_md = proj.project_path / "CLAUDE.local.md"
prior_block = (
f"# My Project\n\n{_MARKER_START}\n"
"## Headroom Learned Patterns\n"
"*Auto-generated by `headroom learn` on 2026-01-01 — do not edit manually*\n\n"
"### Large Files\n"
"*~15,000 tokens/session saved*\n"
"- src/App.tsx is huge\n\n"
"### Build Commands\n"
"- cargo check from src-tauri/\n\n"
f"{_MARKER_END}\n"
)
claude_md.write_text(prior_block)
writer = ClaudeCodeWriter()
recs = [_rec(RecommendationTarget.CONTEXT_FILE, "Environment", "- Use uv")]
writer.write(recs, proj, dry_run=False)
content = claude_md.read_text()
assert "My Project" in content
# New section present
assert "Use uv" in content
# Prior sections preserved (neither heading re-surfaced by the new run)
assert "### Large Files" in content
assert "src/App.tsx is huge" in content
assert "### Build Commands" in content
assert "cargo check from src-tauri/" in content
# Tokens annotation round-tripped
assert "*~15,000 tokens/session saved*" in content
# Still exactly one marker pair
assert content.count(_MARKER_START) == 1
assert content.count(_MARKER_END) == 1
def test_new_run_overrides_same_named_prior_section(self, tmp_path):
"""When a section appears in both prior and new, the new run wins."""
proj = _project(tmp_path)
claude_md = proj.project_path / "CLAUDE.local.md"
prior_block = (
f"{_MARKER_START}\n"
"## Headroom Learned Patterns\n"
"*Auto-generated by `headroom learn` on 2026-01-01 — do not edit manually*\n\n"
"### Environment\n"
"- old stale environment note\n\n"
f"{_MARKER_END}\n"
)
claude_md.write_text(prior_block)
writer = ClaudeCodeWriter()
recs = [_rec(RecommendationTarget.CONTEXT_FILE, "Environment", "- fresh environment note")]
writer.write(recs, proj, dry_run=False)
content = claude_md.read_text()
assert "fresh environment note" in content
assert "old stale environment note" not in content
# Only one Environment section in the final block
assert content.count("### Environment") == 1
def test_opt_in_same_section_merge_preserves_prior_pattern_items(self, tmp_path):
context_file = tmp_path / "AGENTS.md"
context_file.write_text(
"<!-- headroom:learn:start -->\n"
"## Headroom Learned Patterns\n\n"
"### Learned: preference\n"
"- Keep the established queue <!-- headroom:pattern-id:queue -->\n"
"- Keep local reviews\n\n"
"<!-- headroom:learn:end -->\n"
)
recommendation = _rec(
RecommendationTarget.CONTEXT_FILE,
"Learned: preference",
"- Use the updated queue <!-- headroom:pattern-id:queue -->\n"
"- Keep local reviews <!-- headroom:pattern-id:reviews -->",
)
recommendation.preserve_prior_items = True
final = _merge_into_file(context_file, [recommendation])
assert "Use the updated queue" in final
assert "Keep the established queue" not in final
assert final.count("Keep local reviews") == 1
def test_active_ids_keep_unbatched_items_and_drop_expired_ones(self, tmp_path):
"""The removal invariant: preservation is bounded by the active id set.
``ripgrep`` is active but was left out of this batch (ranking/top-N),
so it must survive. ``vendored`` is no longer active, so it must be
deleted rather than pinned into the file forever.
"""
context_file = tmp_path / "AGENTS.md"
context_file.write_text(
"<!-- headroom:learn:start -->\n"
"## Headroom Learned Patterns\n\n"
"### Learned: preference\n"
"- Keep local reviews <!-- headroom:pattern-id:reviews -->\n"
"- Prefer ripgrep over grep <!-- headroom:pattern-id:ripgrep -->\n"
"- Build against the vendored SDK <!-- headroom:pattern-id:vendored -->\n\n"
"<!-- headroom:learn:end -->\n"
)
recommendation = _rec(
RecommendationTarget.CONTEXT_FILE,
"Learned: preference",
"- Keep local reviews <!-- headroom:pattern-id:reviews -->",
)
recommendation.preserve_prior_items = True
recommendation.active_item_ids = frozenset({"reviews", "ripgrep"})
final = _merge_into_file(context_file, [recommendation])
assert final.count("Keep local reviews") == 1
assert "Prefer ripgrep over grep" in final
assert "Build against the vendored SDK" not in final
assert "headroom:pattern-id:vendored" not in final
def test_active_ids_drop_untagged_legacy_items(self, tmp_path):
"""Untagged prior items pre-date id tagging and are not a lifecycle signal.
The still-active one comes back with an id from the current run and
collapses into a single bullet; the one the learner dropped goes away.
"""
context_file = tmp_path / "AGENTS.md"
context_file.write_text(
"<!-- headroom:learn:start -->\n"
"## Headroom Learned Patterns\n\n"
"### Learned: preference\n"
"- Keep local reviews\n"
"- Build against the vendored SDK\n\n"
"<!-- headroom:learn:end -->\n"
)
recommendation = _rec(
RecommendationTarget.CONTEXT_FILE,
"Learned: preference",
"- Keep local reviews <!-- headroom:pattern-id:reviews -->",
)
recommendation.preserve_prior_items = True
recommendation.active_item_ids = frozenset({"reviews"})
final = _merge_into_file(context_file, [recommendation])
assert final.count("Keep local reviews") == 1
assert "headroom:pattern-id:reviews" in final
assert "Build against the vendored SDK" not in final
def test_without_active_ids_prior_items_are_unioned(self, tmp_path):
"""No lifecycle signal — every producer that predates it keeps the union."""
context_file = tmp_path / "AGENTS.md"
context_file.write_text(
"<!-- headroom:learn:start -->\n"
"## Headroom Learned Patterns\n\n"
"### Learned: preference\n"
"- Keep local reviews <!-- headroom:pattern-id:reviews -->\n"
"- Build against the vendored SDK <!-- headroom:pattern-id:vendored -->\n"
"- Untagged leftover\n\n"
"<!-- headroom:learn:end -->\n"
)
recommendation = _rec(
RecommendationTarget.CONTEXT_FILE,
"Learned: preference",
"- Keep local reviews <!-- headroom:pattern-id:reviews -->",
)
recommendation.preserve_prior_items = True
assert recommendation.active_item_ids is None
final = _merge_into_file(context_file, [recommendation])
assert final.count("Keep local reviews") == 1
assert "Build against the vendored SDK" in final
assert "Untagged leftover" in final
def test_replacing_existing_block_handles_literal_backslash_escapes(self, tmp_path):
"""LLM text with backslash escapes must not be interpreted as a regex replacement."""
proj = _project(tmp_path)
claude_md = proj.project_path / "CLAUDE.md"
claude_md.write_text(
f"# Existing\n\n{_MARKER_START}\n"
"## Headroom Learned Patterns\n\n"
"### Windows Paths\n"
"- stale\n\n"
f"{_MARKER_END}\n"
)
full_content = _merge_into_file(
claude_md,
[
_rec(
RecommendationTarget.CONTEXT_FILE,
"Windows Paths",
r"- Keep the literal \u sequence and C:\Users\john.doe\repo path",
)
],
)
assert r"\u sequence" in full_content
assert r"C:\Users\john.doe\repo" in full_content
assert "stale" not in full_content
def test_merge_keeps_prose_that_quotes_the_start_marker_above_the_block(self, tmp_path):
"""Prose quoting the start marker above the block must survive the rewrite."""
context_file = tmp_path / "CLAUDE.local.md"
prose = f"The block below starts with {_MARKER_START} and is managed."
context_file.write_text(
f"{prose}\n"
"- Hand-written rule: never force-push\n\n"
f"{_MARKER_START}\n"
"## Headroom Learned Patterns\n\n"
"### Environment\n"
"- old bullet\n\n"
f"{_MARKER_END}\n"
)
recommendation = _rec(RecommendationTarget.CONTEXT_FILE, "Tooling", "- Use uv")
final = _merge_into_file(context_file, [recommendation])
assert "- Hand-written rule: never force-push" in final
assert prose in final
assert "- Use uv" in final
assert final.count(_MARKER_START) == 2
assert final.count(_MARKER_END) == 1
def test_merge_appends_a_block_when_the_end_marker_is_missing(self, tmp_path):
"""A start marker with no end marker is not a block: the recommendations must land."""
context_file = tmp_path / "CLAUDE.local.md"
original = f"{_MARKER_START}\n- Hand-written rule: never force-push\n"
context_file.write_text(original)
recommendation = _rec(RecommendationTarget.CONTEXT_FILE, "Tooling", "- Use uv")
final = _merge_into_file(context_file, [recommendation])
assert final != original
assert "- Use uv" in final
assert "- Hand-written rule: never force-push" in final
def test_merge_keeps_prose_quoting_both_markers_after_the_block(self, tmp_path):
"""Marker quotes in prose below the block are hand-written text, not a second block."""
context_file = tmp_path / "CLAUDE.local.md"
context_file.write_text(
f"{_MARKER_START}\n"
"## Headroom Learned Patterns\n\n"
"### Environment\n"
"- old bullet\n\n"
f"{_MARKER_END}\n\n"
f"Example: {_MARKER_START}\n"
"- Hand-written rule: never force-push\n"
f"{_MARKER_END}\n"
)
recommendation = _rec(RecommendationTarget.CONTEXT_FILE, "Tooling", "- Use uv")
final = _merge_into_file(context_file, [recommendation])
assert "- Hand-written rule: never force-push" in final
assert final.startswith(f"{_MARKER_START}\n## Headroom Learned Patterns")
block = final[: final.index(_MARKER_END)]
assert "- Use uv" in block
assert "- old bullet" in block
assert final.count(f"Example: {_MARKER_START}") == 1
def test_prior_sections_come_from_the_block_not_from_quoting_prose(self, tmp_path):
"""Headings in prose that quotes the start marker must not become generated sections."""
context_file = tmp_path / "CLAUDE.local.md"
context_file.write_text(
f"Example: {_MARKER_START}\n"
"### Manual policy\n"
"- Hand-written rule: never force-push\n\n"
f"{_MARKER_START}\n"
"## Headroom Learned Patterns\n\n"
"### Environment\n"
"- old bullet\n\n"
f"{_MARKER_END}\n"
)
recommendation = _rec(RecommendationTarget.CONTEXT_FILE, "Tooling", "- Use uv")
final = _merge_into_file(context_file, [recommendation])
assert final.count("### Manual policy") == 1
block = final[final.index(f"\n{_MARKER_START}\n") :]
assert "### Manual policy" not in block
assert "### Environment" in block
assert "- Use uv" in block
def test_merge_leaves_a_fenced_example_of_the_block_untouched(self, tmp_path):
"""Markers inside a fenced Markdown example are not the managed block."""
context_file = tmp_path / "CLAUDE.local.md"
example = f"```markdown\n{_MARKER_START}\nEXAMPLE_SENTINEL\n{_MARKER_END}\n```\n"
context_file.write_text(
"How the managed block looks:\n\n" + example + "\n"
f"{_MARKER_START}\n"
"## Headroom Learned Patterns\n\n"
"### Environment\n"
"- old bullet\n\n"
f"{_MARKER_END}\n"
)
recommendation = _rec(RecommendationTarget.CONTEXT_FILE, "Tooling", "- Use uv")
final = _merge_into_file(context_file, [recommendation])
assert example in final
real_block = final[final.index(example) + len(example) :]
assert "- Use uv" in real_block
assert "- old bullet" in real_block
assert "- Use uv" not in final[: final.index(example) + len(example)]
def test_fenced_code_inside_the_block_does_not_hide_its_end_marker(self, tmp_path):
"""A closed code fence in a recommendation body keeps the block recognisable."""
context_file = tmp_path / "CLAUDE.local.md"
context_file.write_text(
f"{_MARKER_START}\n"
"## Headroom Learned Patterns\n\n"
"### Build\n"
"```bash\nmake test\n```\n\n"
f"{_MARKER_END}\n"
)
recommendation = _rec(RecommendationTarget.CONTEXT_FILE, "Tooling", "- Use uv")
final = _merge_into_file(context_file, [recommendation])
assert final.count(_MARKER_START) == 1
assert final.count(_MARKER_END) == 1
assert "- Use uv" in final
def test_memory_md_carry_forward(self, tmp_path):
"""Carry-forward also works for MEMORY.md."""
proj = _project(tmp_path)
memory_md = proj.data_path / "memory" / "MEMORY.md"
memory_md.write_text(
f"{_MARKER_START}\n"
"## Headroom Learned Patterns\n"
"*Auto-generated by `headroom learn` on 2026-01-01 — do not edit manually*\n\n"
"### User Workflow Preferences\n"
"- User rejects sleep-based polling\n\n"
f"{_MARKER_END}\n"
)
writer = ClaudeCodeWriter()
recs = [
_rec(RecommendationTarget.MEMORY_FILE, "Related Codebases", "- web app at ~/Code/web")
]
writer.write(recs, proj, dry_run=False)
content = memory_md.read_text()
assert "User rejects sleep-based polling" in content
assert "web app at ~/Code/web" in content
def test_section_without_tokens_annotation_round_trips(self, tmp_path):
"""Prior sections emitted without a tokens annotation must still carry forward cleanly."""
proj = _project(tmp_path)
claude_md = proj.project_path / "CLAUDE.local.md"
claude_md.write_text(
f"{_MARKER_START}\n"
"## Headroom Learned Patterns\n"
"*Auto-generated by `headroom learn` on 2026-01-01 — do not edit manually*\n\n"
"### Misc\n"
"- one-liner pattern\n\n"
f"{_MARKER_END}\n"
)
writer = ClaudeCodeWriter()
recs = [_rec(RecommendationTarget.CONTEXT_FILE, "Other", "- new one")]
writer.write(recs, proj, dry_run=False)
content = claude_md.read_text()
assert "### Misc" in content
assert "one-liner pattern" in content
# No spurious tokens annotation injected for a prior that didn't have one
misc_idx = content.index("### Misc")
after_misc = content[misc_idx : misc_idx + 200]
assert "tokens/session saved" not in after_misc
def test_appends_to_existing_memory_md(self, tmp_path):
proj = _project(tmp_path)
memory_md = proj.data_path / "memory" / "MEMORY.md"
memory_md.write_text("# Existing Memory\n\nSome facts.\n")
writer = ClaudeCodeWriter()
recs = [_rec(RecommendationTarget.MEMORY_FILE, "Retry Prevention", "- New pattern")]
writer.write(recs, proj, dry_run=False)
content = memory_md.read_text()
assert "Existing Memory" in content
assert "Some facts" in content
assert "New pattern" in content
def _legacy_block(section: str, body: str) -> str:
return (
f"# My Project\n\nExisting instructions.\n\n{_MARKER_START}\n"
"## Headroom Learned Patterns\n"
"*Auto-generated by `headroom learn` on 2026-01-01 — do not edit manually*\n\n"
f"### {section}\n{body}\n\n"
f"{_MARKER_END}\n"
)
class TestContextTargetOverride:
"""--target / set_context_target controls where CONTEXT_FILE recs are written."""
def test_target_override_relative_path(self, tmp_path):
proj = _project(tmp_path)
writer = ClaudeCodeWriter()
writer.set_context_target("CLAUDE.md")
recs = [_rec(RecommendationTarget.CONTEXT_FILE, "Environment", "- Use uv")]
writer.write(recs, proj, dry_run=False)
# Explicit target opts back into the team-shared CLAUDE.md.
assert (proj.project_path / "CLAUDE.md").exists()
assert "Use uv" in (proj.project_path / "CLAUDE.md").read_text()
assert not (proj.project_path / "CLAUDE.local.md").exists()
def test_target_override_via_constructor(self, tmp_path):
proj = _project(tmp_path)
writer = ClaudeCodeWriter(context_target="docs/LEARNINGS.md")
recs = [_rec(RecommendationTarget.CONTEXT_FILE, "Environment", "- Use uv")]
writer.write(recs, proj, dry_run=False)
target = proj.project_path / "docs" / "LEARNINGS.md"
assert target.exists()
assert "Use uv" in target.read_text()
def test_target_absolute_path(self, tmp_path):
proj = _project(tmp_path)
abs_target = tmp_path / "elsewhere" / "NOTES.md"
writer = ClaudeCodeWriter(context_target=str(abs_target))
recs = [_rec(RecommendationTarget.CONTEXT_FILE, "Environment", "- Use uv")]
writer.write(recs, proj, dry_run=False)
assert abs_target.exists()
assert "Use uv" in abs_target.read_text()
class TestLegacyClaudeMdMigration:
"""A stale headroom block in the shared CLAUDE.md migrates to CLAUDE.local.md."""
def test_migrates_block_and_strips_legacy(self, tmp_path):
proj = _project(tmp_path)
claude_md = proj.project_path / "CLAUDE.md"
claude_md.write_text(_legacy_block("Build Commands", "- cargo check from src-tauri/"))
writer = ClaudeCodeWriter()
recs = [_rec(RecommendationTarget.CONTEXT_FILE, "Environment", "- Use uv")]
result = writer.write(recs, proj, dry_run=False)
# Hand-written content stays in CLAUDE.md; the headroom block is gone.
legacy = claude_md.read_text()
assert "Existing instructions." in legacy
assert _MARKER_START not in legacy
assert "Build Commands" not in legacy
# CLAUDE.local.md now owns the migrated section AND the new one.
local = (proj.project_path / "CLAUDE.local.md").read_text()
assert "### Build Commands" in local
assert "cargo check from src-tauri/" in local
assert "### Environment" in local
assert "Use uv" in local
assert local.count(_MARKER_START) == 1
# The migration is surfaced to the user.
assert any("CLAUDE.md" in w for w in result.warnings)
def test_block_only_claude_md_is_removed(self, tmp_path):
proj = _project(tmp_path)
claude_md = proj.project_path / "CLAUDE.md"
# CLAUDE.md holds nothing but the Headroom block (no hand-written content).
claude_md.write_text(
f"{_MARKER_START}\n## Headroom Learned Patterns\n\n"
"### Build Commands\n- cargo check\n\n"
f"{_MARKER_END}\n"
)
writer = ClaudeCodeWriter()
recs = [_rec(RecommendationTarget.CONTEXT_FILE, "Environment", "- Use uv")]
result = writer.write(recs, proj, dry_run=False)
# The empty husk is deleted rather than left behind as an empty file.
assert not claude_md.exists()
local = (proj.project_path / "CLAUDE.local.md").read_text()
assert "### Build Commands" in local
assert "### Environment" in local
assert any("Removed" in w for w in result.warnings)
def test_dry_run_block_only_claude_md_not_removed(self, tmp_path):
proj = _project(tmp_path)
claude_md = proj.project_path / "CLAUDE.md"
original = (
f"{_MARKER_START}\n## Headroom Learned Patterns\n\n"
"### Build Commands\n- cargo check\n\n"
f"{_MARKER_END}\n"
)
claude_md.write_text(original)
writer = ClaudeCodeWriter()
recs = [_rec(RecommendationTarget.CONTEXT_FILE, "Environment", "- Use uv")]
result = writer.write(recs, proj, dry_run=True)
# Dry run leaves the file on disk but still previews the removal.
assert claude_md.read_text() == original
assert any("Removed" in w for w in result.warnings)
def test_dry_run_migration_writes_nothing(self, tmp_path):
proj = _project(tmp_path)
claude_md = proj.project_path / "CLAUDE.md"
original = _legacy_block("Build Commands", "- cargo check")
claude_md.write_text(original)
writer = ClaudeCodeWriter()
recs = [_rec(RecommendationTarget.CONTEXT_FILE, "Environment", "- Use uv")]
result = writer.write(recs, proj, dry_run=True)
# Nothing written on disk, but the warning still fires for the preview.
assert claude_md.read_text() == original
assert not (proj.project_path / "CLAUDE.local.md").exists()
assert any("CLAUDE.md" in w for w in result.warnings)
def test_no_migration_when_local_already_owns_block(self, tmp_path):
proj = _project(tmp_path)
claude_md = proj.project_path / "CLAUDE.md"
legacy = _legacy_block("Build Commands", "- cargo check")
claude_md.write_text(legacy)
local_md = proj.project_path / "CLAUDE.local.md"
local_md.write_text(
f"{_MARKER_START}\n## Headroom Learned Patterns\n\n"
"### Environment\n- prior local note\n\n"
f"{_MARKER_END}\n"
)
writer = ClaudeCodeWriter()
recs = [_rec(RecommendationTarget.CONTEXT_FILE, "Environment", "- fresh note")]
result = writer.write(recs, proj, dry_run=False)
# CLAUDE.md is left untouched (local is already the source of truth).
assert claude_md.read_text() == legacy
assert not result.warnings
local = local_md.read_text()
assert "fresh note" in local
assert "prior local note" not in local
def test_target_override_skips_migration(self, tmp_path):
proj = _project(tmp_path)
claude_md = proj.project_path / "CLAUDE.md"
legacy = _legacy_block("Build Commands", "- cargo check")
claude_md.write_text(legacy)
writer = ClaudeCodeWriter()
writer.set_context_target("CLAUDE.md")
recs = [_rec(RecommendationTarget.CONTEXT_FILE, "Environment", "- Use uv")]
result = writer.write(recs, proj, dry_run=False)
# Explicit CLAUDE.md target merges in place, no migration warning.
assert not result.warnings
content = claude_md.read_text()
assert "### Environment" in content
assert "### Build Commands" in content
class TestHomeDirectoryContext:
"""The home directory keeps writing to ~/.claude/CLAUDE.md (personal global memory)."""
def test_home_dir_writes_global_claude_md(self, tmp_path, monkeypatch):
fake_home = tmp_path / "home"
fake_home.mkdir()
monkeypatch.setattr(Path, "home", classmethod(lambda cls: fake_home))
proj = ProjectInfo(
name="home",
project_path=fake_home,
data_path=tmp_path / "data",
)
writer = ClaudeCodeWriter()
recs = [_rec(RecommendationTarget.CONTEXT_FILE, "Environment", "- Use uv")]
writer.write(recs, proj, dry_run=False)
global_md = fake_home / ".claude" / "CLAUDE.md"
assert global_md.exists()
assert "Use uv" in global_md.read_text()
assert not (fake_home / "CLAUDE.local.md").exists()
class TestParsePriorRecommendations:
"""Direct coverage for _parse_prior_recommendations edge cases."""
def test_no_marker_block_returns_empty(self):
"""A file without any marker block yields no prior recommendations."""
assert _parse_prior_recommendations("# Project\n\nJust a regular README.\n") == []
def test_empty_marker_block_yields_no_recs(self):
"""A marker block with nothing between the markers yields no recs."""
content = f"prefix\n{_MARKER_START}\n{_MARKER_END}\nsuffix\n"
assert _parse_prior_recommendations(content) == []
def test_marker_block_with_empty_heading_is_skipped(self):
"""A stray `### ` (empty heading) inside the block is skipped, not raised."""
# Leading `### ` with no heading text, followed by a real section.
content = (
f"{_MARKER_START}\n"
"## Headroom Learned Patterns\n"
"### \n"
"some orphan content\n"
"\n"
"### Real Section\n"
"- real bullet\n"
"\n"
f"{_MARKER_END}\n"
)
recs = _parse_prior_recommendations(content)
# Only the real section is parsed; the empty-heading entry is dropped.
assert len(recs) == 1
assert recs[0].section == "Real Section"
assert "real bullet" in recs[0].content
class TestExtractMarkerBlock:
"""Direct coverage for extract_marker_block."""
def test_returns_raw_block_when_present(self):
"""Marker block is returned verbatim with delimiters, for LLM prompts."""
content = (
"# Project README\n\n"
"Some text.\n\n"
f"{_MARKER_START}\n"
"## Headroom Learned Patterns\n"
"### Environment\n"
"- Use uv run python\n"
f"{_MARKER_END}\n"
"Trailing text.\n"
)
block = extract_marker_block(content)
assert block is not None
assert block.startswith(_MARKER_START)
assert block.endswith(_MARKER_END)
assert "### Environment" in block
assert "Use uv run python" in block
assert "Trailing text." not in block
def test_returns_none_when_absent(self):
"""File without any marker delimiters yields None."""
assert extract_marker_block("# Project\n\nJust a regular README.\n") is None
def test_returns_none_when_only_start_marker(self):
"""Partial/malformed block (start only) yields None — writer expects both delimiters."""
content = f"prefix\n{_MARKER_START}\n### Something\n- content\n"
assert extract_marker_block(content) is None
def test_returns_empty_block_when_markers_are_adjacent(self):
"""A block with nothing between the markers is still returned (caller's choice what to do)."""
content = f"prefix\n{_MARKER_START}\n{_MARKER_END}\nsuffix\n"
block = extract_marker_block(content)
assert block is not None
assert block == f"{_MARKER_START}\n{_MARKER_END}"
class TestEncodingResilience:
"""Regression tests for #1202 — ``learn --apply`` must not crash merging into
an existing context file that carries a stray non-UTF-8 byte (e.g. a legacy
cp1252 em-dash ``0x97``)."""
def test_read_text_tolerant_preserves_valid_utf8(self, tmp_path):
path = tmp_path / "AGENTS.md"
path.write_text("Use em-dashes — and arrows →.", encoding="utf-8")
assert _read_text_tolerant(path) == "Use em-dashes — and arrows →."
def test_read_text_tolerant_survives_stray_legacy_byte(self, tmp_path):
# Predominantly valid UTF-8 (genuine em-dash E2 80 94) plus one stray
# cp1252 em-dash byte (0x97) that strict UTF-8 cannot decode.
path = tmp_path / "AGENTS.md"
path.write_bytes("real em-dash — here\n".encode() + b"legacy \x97 byte\n")
# The old strict read aborts the whole --apply on that single byte.
with pytest.raises(UnicodeDecodeError):
path.read_text(encoding="utf-8")
text = _read_text_tolerant(path)
# Valid UTF-8 content is preserved (no cp1252 "â€" mojibake) and the
# stray byte is replaced rather than fatal.
assert "real em-dash — here" in text
assert "\x97" not in text
assert "â€" not in text
def test_merge_into_file_applies_over_file_with_stray_byte(self, tmp_path):
path = tmp_path / "AGENTS.md"
path.write_bytes("# Notes — existing\n".encode() + b"stray \x97 byte\n")
recs = [_rec(RecommendationTarget.CONTEXT_FILE, "Environment", "- Use uv")]
merged = _merge_into_file(path, recs)
assert "Use uv" in merged
assert "Notes — existing" in merged
def test_read_text_tolerant_normalizes_crlf_and_cr(self, tmp_path):
path = tmp_path / "AGENTS.md"
path.write_bytes(b"line1\r\nline2\rline3\n")
text = _read_text_tolerant(path)
assert text == "line1\nline2\nline3\n"
def test_apply_does_not_accumulate_carriage_returns_on_crlf_file(self, tmp_path):
proj = _project(tmp_path)
writer = ClaudeCodeWriter()
memory_md = proj.data_path / "memory" / "MEMORY.md"
# Simulate existing Windows CRLF file
memory_md.write_bytes(b"# Memory Index\r\n\r\n- bullet 1\r\n")
recs = [_rec(RecommendationTarget.MEMORY_FILE, "Errors", "- rule 1")]
writer.write(recs, proj, dry_run=False)
writer.write(recs, proj, dry_run=False)
raw = memory_md.read_bytes()
assert b"\r\r" not in raw
assert raw.count(b"\r") == raw.count(b"\r\n")
def _git(proj: ProjectInfo, *args: str, check: bool = True) -> subprocess.CompletedProcess:
"""Run git against the test repo, under the isolated config below."""
return subprocess.run(["git", *args], cwd=proj.project_path, check=check, capture_output=True)
def _git_project(tmp_path: Path) -> ProjectInfo:
"""A project whose directory is a real git repo."""
proj = _project(tmp_path)
_git(proj, "init", "-q")
return proj
def _exclude(proj: ProjectInfo) -> Path:
return proj.project_path / ".git" / "info" / "exclude"
def _exclude_entries(proj: ProjectInfo) -> list[str]:
"""The repo-local exclude rules this PR is responsible for, one per line."""
path = _exclude(proj)
if not path.exists():
return []
return [line.strip() for line in path.read_text().splitlines() if line.strip()]
def _is_ignored(proj: ProjectInfo, name: str) -> bool:
return _git(proj, "check-ignore", "-q", "--", name, check=False).returncode == 0
class TestClaudeLocalMdStaysOutOfGit:
"""CLAUDE.local.md is only personal if git actually ignores it (#1070)."""
@pytest.fixture(autouse=True)
def _isolated_git_config(self, monkeypatch, tmp_path):
"""Decide these tests on the repository alone, on every machine.
``git check-ignore`` consults ``core.excludesFile`` from the developer's
global and system config, and the writer shells out to it too (it skips
adding a rule when one already covers the file). So a contributor whose
global ignore lists CLAUDE.md or CLAUDE.local.md saw this suite fail
while the writer was behaving correctly. Patching the environment rather
than a helper covers the writer's own subprocess as well as ours.
"""
absent = tmp_path / "absent-gitconfig"
monkeypatch.setenv("GIT_CONFIG_GLOBAL", str(absent))
monkeypatch.setenv("GIT_CONFIG_SYSTEM", str(absent))
monkeypatch.setenv("GIT_CONFIG_NOSYSTEM", "1")
def test_apply_adds_exclude_entry(self, tmp_path):
proj = _git_project(tmp_path)
recs = [_rec(RecommendationTarget.CONTEXT_FILE, "Environment", "- Use uv")]
result = ClaudeCodeWriter().write(recs, proj, dry_run=False)
assert "CLAUDE.local.md" in _exclude(proj).read_text()
# The point is the effect, not the file contents.
assert _is_ignored(proj, "CLAUDE.local.md")
assert result.warnings == []
def test_second_run_does_not_duplicate_the_entry(self, tmp_path):
proj = _git_project(tmp_path)
recs = [_rec(RecommendationTarget.CONTEXT_FILE, "Environment", "- Use uv")]
writer = ClaudeCodeWriter()
writer.write(recs, proj, dry_run=False)
writer.write(recs, proj, dry_run=False)
assert _exclude(proj).read_text().count("CLAUDE.local.md") == 1
def test_existing_gitignore_rule_is_left_alone(self, tmp_path):
proj = _git_project(tmp_path)
(proj.project_path / ".gitignore").write_text("CLAUDE.local.md\n")
recs = [_rec(RecommendationTarget.CONTEXT_FILE, "Environment", "- Use uv")]
ClaudeCodeWriter().write(recs, proj, dry_run=False)
assert not _exclude(proj).exists() or "CLAUDE.local.md" not in _exclude(proj).read_text()
def test_tracked_file_warns_instead_of_excluding(self, tmp_path):
proj = _git_project(tmp_path)
local = proj.project_path / "CLAUDE.local.md"
local.write_text("# prior\n")
_git(proj, "add", "CLAUDE.local.md")
recs = [_rec(RecommendationTarget.CONTEXT_FILE, "Environment", "- Use uv")]
result = ClaudeCodeWriter().write(recs, proj, dry_run=False)
# An ignore rule does nothing for a tracked file, so say so rather than
# staging a deletion in the user's repo on their behalf.
assert len(result.warnings) == 1
assert "git rm --cached CLAUDE.local.md" in result.warnings[0]
assert not _exclude(proj).exists() or "CLAUDE.local.md" not in _exclude(proj).read_text()
def test_dry_run_does_not_touch_exclude(self, tmp_path):
proj = _git_project(tmp_path)
recs = [_rec(RecommendationTarget.CONTEXT_FILE, "Environment", "- Use uv")]
ClaudeCodeWriter().write(recs, proj, dry_run=True)
assert not _exclude(proj).exists() or "CLAUDE.local.md" not in _exclude(proj).read_text()
def test_explicit_shared_target_is_never_excluded(self, tmp_path):
proj = _git_project(tmp_path)
recs = [_rec(RecommendationTarget.CONTEXT_FILE, "Environment", "- Use uv")]
ClaudeCodeWriter(context_target="CLAUDE.md").write(recs, proj, dry_run=False)
# --target CLAUDE.md is a deliberate opt-in to the team-shared file, so
# the writer must not add a rule for it. Assert the side effect this PR
# actually owns - the repo's own exclude file - as well as the effect.
assert "CLAUDE.md" not in _exclude_entries(proj)
assert not _is_ignored(proj, "CLAUDE.md")
def test_outside_a_git_repo_is_a_no_op(self, tmp_path):
proj = _project(tmp_path) # no git init
recs = [_rec(RecommendationTarget.CONTEXT_FILE, "Environment", "- Use uv")]
result = ClaudeCodeWriter().write(recs, proj, dry_run=False)
assert (proj.project_path / "CLAUDE.local.md").exists()
assert result.warnings == []
@pytest.mark.windows_newline
class TestNewlineContract:
"""Regression guard for #3594 / #3698 — every learn-writer write pins LF.
This asserts the *call*, not the artifact, on purpose. ``Path.write_text``
with ``newline=None`` translates ``\n`` through ``TextIOWrapper``, whose
translation target is chosen at C-compile time (``#ifdef MS_WINDOWS``), not
read from ``os.linesep`` at runtime. So on POSIX no fixture can make the
unpinned call emit CRLF, and every artifact-level assertion here passes
with the fix reverted. Spying on the kwarg fails the moment a pin is
dropped, on any platform — which is the property #3698 asked for.
"""
def test_every_learn_writer_write_pins_lf(self, tmp_path, monkeypatch):
proj = _project(tmp_path)
context_rec = _rec(RecommendationTarget.CONTEXT_FILE, "Environment", "- Use uv")
memory_rec = _rec(RecommendationTarget.MEMORY_FILE, "Errors", "- rule 1")
# Seed a legacy CLAUDE.md that carries a headroom block *and*
# hand-written prose, so ClaudeCodeWriter's migration branch (which
# rewrites the cleaned CLAUDE.md) is exercised alongside the rest.
(proj.project_path / "CLAUDE.md").write_text(
_legacy_block("Build Commands", "- cargo check"), encoding="utf-8"
)
calls: list[tuple[Path, str | None]] = []
original = Path.write_text
def spy(self, data, encoding=None, errors=None, newline=None):
calls.append((self, newline))
return original(self, data, encoding=encoding, errors=errors, newline=newline)
monkeypatch.setattr(Path, "write_text", spy)
ClaudeCodeWriter().write([context_rec, memory_rec], proj, dry_run=False)
CodexWriter().write([context_rec, memory_rec], proj, dry_run=False)
GeminiWriter().write([context_rec], proj, dry_run=False)
GrokWriter().write([context_rec], proj, dry_run=False)
assert calls, "no writes captured — this test no longer drives the writers"
unpinned = sorted(str(path) for path, newline in calls if newline != "\n")
assert not unpinned, f"learn writers wrote without newline='\\n': {unpinned}"
# All seven write sites in headroom/learn/writer.py are reached above;
# if a writer grows a new target, this set fails loudly rather than
# letting an unguarded write site slip in.
assert {path.name for path, _ in calls} == {
"CLAUDE.local.md", # ClaudeCodeWriter context target
"CLAUDE.md", # legacy-migration rewrite
"MEMORY.md", # ClaudeCodeWriter memory target
"AGENTS.md", # CodexWriter context target
"instructions.md", # CodexWriter memory target
"GEMINI.md", # GeminiWriter
"GROK.md", # GrokWriter
}