personal memory agent
feat(maint): refresh journal AGENTS.md on docs/JOURNAL.md drift
Without drift refresh, existing journals keep stale AGENTS.md content forever whenever docs/JOURNAL.md changes upstream.
Decision log:
- Drift-detection mechanism: direct content compare between the journal's AGENTS.md and docs/JOURNAL.md. No sidecar, no marker file, no hash.
- Hand-edit policy: overwrite on mismatch with a stderr warning noting that prior content is recoverable via git history. AGENTS.md is a derived artifact, not a place for hand edits; per-journal customization belongs in sol/*.md.
- No-op when content already matches, so mtime is preserved.
+14
-10
+11
-8
apps/sol/maint/003_seed_agents_md.py
+11
-8
apps/sol/maint/003_seed_agents_md.py
···
30
30
return 0
31
31
32
32
33
+
# AGENTS.md is derived from docs/JOURNAL.md. Drift-detection: direct content
34
+
# compare. Hand-edit policy: overwrite on mismatch with stderr warning
35
+
# (prior content recoverable from git history).
33
36
def main() -> int:
34
37
parser = argparse.ArgumentParser(description="Seed journal AGENTS.md symlinks.")
35
38
setup_cli(parser)
···
41
44
claude_path = journal / "CLAUDE.md"
42
45
gemini_path = journal / "GEMINI.md"
43
46
44
-
if (
45
-
agents_path.exists()
46
-
and _symlink_points_to_agents(claude_path)
47
-
and _symlink_points_to_agents(gemini_path)
48
-
):
49
-
print("all journal agent files already present")
50
-
return 0
51
-
52
47
try:
53
48
journal_md = (repo_root / "docs" / "JOURNAL.md").read_text(encoding="utf-8")
54
49
55
50
if not agents_path.exists():
56
51
agents_path.write_text(journal_md, encoding="utf-8")
57
52
print("created AGENTS.md")
53
+
elif agents_path.read_text(encoding="utf-8") != journal_md:
54
+
agents_path.write_text(journal_md, encoding="utf-8")
55
+
print(
56
+
"AGENTS.md content differed from docs/JOURNAL.md; refreshing "
57
+
"(previous content preserved in git history)",
58
+
file=sys.stderr,
59
+
)
60
+
print("refreshed AGENTS.md")
58
61
59
62
for path in (claude_path, gemini_path):
60
63
if _symlink_points_to_agents(path):
+3
-2
tests/test_journal_seeding_maint.py
+3
-2
tests/test_journal_seeding_maint.py
···
70
70
assert before == after
71
71
72
72
73
-
def test_seed_agents_md_does_not_refresh_existing_agents_md(journal_path):
73
+
def test_seed_agents_md_refreshes_on_drift(journal_path):
74
74
agents_path = journal_path / "AGENTS.md"
75
75
agents_path.write_text("stale content", encoding="utf-8")
76
76
(journal_path / "CLAUDE.md").symlink_to("AGENTS.md")
77
77
(journal_path / "GEMINI.md").symlink_to("AGENTS.md")
78
+
docs_text = Path("docs/JOURNAL.md").read_text(encoding="utf-8")
78
79
79
80
result = _run_main(journal_path)
80
81
81
82
assert result.returncode == 0
82
-
assert agents_path.read_text(encoding="utf-8") == "stale content"
83
+
assert agents_path.read_text(encoding="utf-8") == docs_text