Problem
The canonical Page format uses visible ## compiled_truth / ## timeline headings as structural markers (skills/brain-setup/assets/BRAIN.md:94,98, written by skills/brain-page/bin/brain.mjs:146,150). This conflicts with heading levels inside the content itself:
## compiled_truth <- H2 structural marker
# Some Decision <- H1 content heading, renders larger than its own container
## Background <- H2, same level as the sibling "## timeline" marker below
## timeline <- H2 structural marker
Two concrete issues:
- Any H1 inside
compiled_truth visually outranks the ## compiled_truth marker that's supposed to contain it — the hierarchy is inverted.
- Any
## sub-heading inside compiled_truth sits at the same nesting level as the sibling ## timeline marker, so the structure is ambiguous both to a human reader and to any parser walking headings by level rather than by exact string match.
Proposed fix
Replace compiled_truth's visible heading with an HTML comment marker, <!-- compiled_truth -->. Content between it and the next marker is then free to use any heading level (#, ##, ###) with no collision, since the marker itself renders invisibly.
timeline must keep a visible heading rather than becoming a comment. An HTML-comment marker there would make the section unidentifiable when the page is opened in a plain Markdown editor/previewer with no knowledge of the brain format — there'd be nothing rendered to tell a reader "this is the timeline," and the entries would appear to run together with the preceding prose with no visual break. So timeline is normalized to ## Timeline (capitalized) instead of the current lowercase ## timeline, but stays a real heading — preceded by an <!-- timeline --> comment marker so the parser locates the section by the exact, stable comment rather than by matching heading text/level (which content authors could otherwise duplicate or rename).
Canonical shape:
---
id: page-id
...
---
<!-- compiled_truth -->
# Page Title
## Some sub-section
...
<!-- timeline -->
## Timeline
- time: ...
kind: ...
summary: ...
Any format change needs backward-compatible parsing for existing brain data written under the current ## compiled_truth / ## timeline shape.
Scope of work
skills/brain-page/bin/brain.mjs — update serialization + parsing (lib/brain.mjs:169) to write the new marker shape while still accepting the old one on read.
skills/brain-setup/assets/BRAIN.md — update the documented canonical Page structure.
skills/brain-page/SKILL.md — update prose describing ## compiled_truth / ## timeline (currently lines 74 and 83).
skills/brain-page/test/brain.test.mjs — update fixtures/assertions pinned to the old headings; add coverage for parsing both old and new forms.
- Consider a migration helper in the
brain CLI that rewrites existing pages' markers in place (format-only, no content or timeline changes) so old data isn't silently stuck on the legacy shape.
Problem
The canonical Page format uses visible
## compiled_truth/## timelineheadings as structural markers (skills/brain-setup/assets/BRAIN.md:94,98, written byskills/brain-page/bin/brain.mjs:146,150). This conflicts with heading levels inside the content itself:Two concrete issues:
compiled_truthvisually outranks the## compiled_truthmarker that's supposed to contain it — the hierarchy is inverted.##sub-heading insidecompiled_truthsits at the same nesting level as the sibling## timelinemarker, so the structure is ambiguous both to a human reader and to any parser walking headings by level rather than by exact string match.Proposed fix
Replace
compiled_truth's visible heading with an HTML comment marker,<!-- compiled_truth -->. Content between it and the next marker is then free to use any heading level (#,##,###) with no collision, since the marker itself renders invisibly.timelinemust keep a visible heading rather than becoming a comment. An HTML-comment marker there would make the section unidentifiable when the page is opened in a plain Markdown editor/previewer with no knowledge of the brain format — there'd be nothing rendered to tell a reader "this is the timeline," and the entries would appear to run together with the preceding prose with no visual break. Sotimelineis normalized to## Timeline(capitalized) instead of the current lowercase## timeline, but stays a real heading — preceded by an<!-- timeline -->comment marker so the parser locates the section by the exact, stable comment rather than by matching heading text/level (which content authors could otherwise duplicate or rename).Canonical shape:
Any format change needs backward-compatible parsing for existing brain data written under the current
## compiled_truth/## timelineshape.Scope of work
skills/brain-page/bin/brain.mjs— update serialization + parsing (lib/brain.mjs:169) to write the new marker shape while still accepting the old one on read.skills/brain-setup/assets/BRAIN.md— update the documented canonical Page structure.skills/brain-page/SKILL.md— update prose describing## compiled_truth/## timeline(currently lines 74 and 83).skills/brain-page/test/brain.test.mjs— update fixtures/assertions pinned to the old headings; add coverage for parsing both old and new forms.brainCLI that rewrites existing pages' markers in place (format-only, no content or timeline changes) so old data isn't silently stuck on the legacy shape.