Skip to content

Rail: keep evidence genres last and apart (rail.evidence) - #2

Merged
pierg merged 2 commits into
mainfrom
rail-evidence-genres
Oct 19, 2026
Merged

pierg merged 2 commits into
mainfrom
rail-evidence-genres

Conversation

@pierg

@pierg pierg commented Oct 19, 2026 •

Copy link
Copy Markdown
Owner

Requested by Pier

Why

In a lab library (for example 98 results, 30 protocols, 13 reports, 7 questions, 3 claims) the rail's "By genre" section lists every genre by name, so protocols and results, which are audit records, sit among the reading genres and dwarf them. The reader cannot tell where to start.

What changes

  • Charter: rail: { evidence: [protocol, result] } names genres the rail lists last and apart. rail: { evidence: [] } lists every genre together in "By genre", by name, as before. An empty evidence: (null) is an error asking for []; rail: or rail: {} leave the packs to decide. Validated in charter.py (list of strings, no duplicates, no unknown keys under rail).
  • Pack default: a PACK.md may name its own genres under evidence, checked as strictly as the charter's: a list of strings, each once, each one of the pack's genres. The lab pack names protocol and result. The charter's value, when set, wins. Library.rail_evidence() resolves it, keeping only active genres.
  • Shell: with evidence genres, "By genre" lists the reading genres in reading order (genreRank), and the evidence genres follow in one closed group headed Evidence, which shows a count line ("30 protocols, 98 results") while closed, in the same order as the groups inside it. It reuses the rail's group(), so it remembers its state, and it opens with the inner genre group when it holds the page being read. Without evidence genres the section is listed by name, as before. Search is not affected.
  • Reading order: READING now places the lab genres (report after entry, claim and question after concept, protocol and result at the end), matching its comment "the way in first, then ideas, then the evidence". A long map without sections uses the same order.
  • Gate: new check rail-genres (error) names a genre in rail.evidence that does not exist or is switched off (its pack is off, or enabled: false).
  • Site data carries rail.evidence. folio config get|set rail.evidence works. Both get and the old value that set prints show the packs' default when the charter sets none, through one shared helper.
  • Specs (model.md §10 and §14, checks.md, pack-format.md, commands.md), the configure skill, the lab PACK.md, the changelog, and the version bump to 0.2.3.

Design notes

  • Reading order applies to "By genre" only when evidence genres are present. So a library without them, or one that writes evidence: [], gets the "By genre" section it had: every genre listed by name. [] does not restore everything, though: the reading order now includes the lab genres, so a long map without its own sections, the closed-section count lines and the rail's key now place lab genres in that order instead of by name.
  • The lab pack sets the default because every lab library has the same shape. A lab library therefore gets the new rail without editing its charter. rail: { evidence: [] } opts out.

Gate

  • python -m pytest -q: 310 passed, 4 skipped (the new tests are in tests/test_rail.py)
  • cd docs && folio check: 39 documents, 0 errors, 0 warnings

Checked by hand as well: the sample fixture and a copy of a 322-page lab library were exported and the rail was rendered with jsdom. On a result page, the reading genres come in reading order and the Evidence group is open with Results open and the page marked. On a concept page, Evidence is closed. With evidence: [], the rail is alphabetical as before.

A library can name genres that are audit records rather than reading, such as
a lab's protocols and results. The rail's By genre section then lists the
reading genres in reading order, and the evidence genres follow in one closed
Evidence group that opens on the page being read.

- Charter: rail.evidence (list of genres); an empty list keeps the old rail.
- Packs: PACK.md may name its own genres under evidence; the lab pack names
  protocol and result, used when the charter sets none.
- Gate: new check rail-genres names an unknown or switched-off genre.
- Site data carries rail.evidence; folio config get/set rail.evidence.
- Reading order places the lab genres.
- Specs, configure skill, lab pack doc, changelog; version 0.2.3.
@pierg pierg self-assigned this Oct 19, 2026
…idence strictly

- An empty rail.evidence (null) is an error asking for []; rail: and rail: {} leave the packs to decide.
- A pack's evidence is checked when present: a list of strings, each once, from its genres.
- config set shows the old value with the packs' default applied, as config get does.
- The closed Evidence group's count line follows the evidence order.
- Say exactly what evidence: [] restores; tests for each case.
@pierg
pierg merged commit 170c2c2 into main Oct 19, 2026
5 checks passed
@pierg
pierg deleted the rail-evidence-genres branch October 19, 2026 23:28
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant