Context
PR 1 of the CorpusBackend arc (#65) shipped FilesystemCorpusBackend in atomic_agents/corpus/filesystem.py. The logic that derives a page title from frontmatter (title: field) with a fallback to the first H1 heading in the body, and a further fallback to the page-name stem, appears at 4 separate call sites in that file. Any future change to the title-derivation rule must be applied in 4 places, creating drift risk.
Evidence
atomic_agents/corpus/filesystem.py -- title-derivation logic (frontmatter title: lookup, fallback to first # heading, fallback to page-name stem) appears in at least 4 methods (list_pages, read_page, read_version, and the version-restore path). Surfaced as a P3 polish finding during PR 1 review.
Proposed fix
Extract a _derive_title(name: str, frontmatter: dict, body: str) -> str private helper at module level (or as a static method on FilesystemCorpusBackend). Replace all 4 call sites with a call to the helper. No behavior change; the refactor is covered by the existing backend conformance tests.
Acceptance criteria
- Title-derivation logic exists in exactly one place in
filesystem.py.
- All 4 prior call sites delegate to the extracted helper.
uv run pytest tests/test_corpus_filesystem_backend.py tests/test_corpus_protocol_conformance.py -q passes with zero regressions.
Source
PR 1 of #65 (PR #297), polish gap.
Context
PR 1 of the CorpusBackend arc (#65) shipped
FilesystemCorpusBackendinatomic_agents/corpus/filesystem.py. The logic that derives a page title from frontmatter (title:field) with a fallback to the first H1 heading in the body, and a further fallback to the page-name stem, appears at 4 separate call sites in that file. Any future change to the title-derivation rule must be applied in 4 places, creating drift risk.Evidence
atomic_agents/corpus/filesystem.py-- title-derivation logic (frontmattertitle:lookup, fallback to first#heading, fallback to page-name stem) appears in at least 4 methods (list_pages,read_page,read_version, and the version-restore path). Surfaced as a P3 polish finding during PR 1 review.Proposed fix
Extract a
_derive_title(name: str, frontmatter: dict, body: str) -> strprivate helper at module level (or as a static method onFilesystemCorpusBackend). Replace all 4 call sites with a call to the helper. No behavior change; the refactor is covered by the existing backend conformance tests.Acceptance criteria
filesystem.py.uv run pytest tests/test_corpus_filesystem_backend.py tests/test_corpus_protocol_conformance.py -qpasses with zero regressions.Source
PR 1 of #65 (PR #297), polish gap.