Skip to content

Brain Page format: ## compiled_truth / ## timeline headings conflict with in-content headings #10

Description

@fenbox

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:

  1. Any H1 inside compiled_truth visually outranks the ## compiled_truth marker that's supposed to contain it — the hierarchy is inverted.
  2. 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.

Metadata

Metadata

Assignees

Labels

No labels
No labels

Type

Projects

No projects

Milestone

No milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions