Required sections: a contract can name a body heading a document must carry (gated on a measured case)
- Dominant language
- Python
- Stars
- 21
- Forks
- 2
- Avg merge
- 6h 33m
- Merged PRs (30d)
- 91
Description
Split from #141 (Proposal 2's `sections:` and Proposal 4), which is closed. Kept open as its own narrow issue so the idea and its gate survive the umbrella.
## The idea
A scheme's contract today speaks only about frontmatter: which fields are present, what they hold, when they are required. The body is unchecked. The proposal was to let a contract also name a heading a document must carry — `## Evidence` on an empirical claim, `## Standing in the anthology` on a superseded practice — with `_template.md` as the place the scaffolding for that heading lives, not as the authority for whether it is required.
## Why it was deferred
The review on #141 noted that a required heading repeats the `requires` gap ADR-060 closed: a required heading is satisfied by an empty heading, the same way `requires` was satisfied by any truthy value. So when this lands it has to land as a **shape check** — a heading with something under it — and not a presence check, or it ratifies exactly the document it exists to catch.
## The gate
Nothing here is built until a record produces the failure: a document filed without a section its scheme's readers depend on, discovered too late, on a corpus where that has happened more than once. The consumer records so far have wanted fields, not headings.
## Shape it would take, if it comes
On the field-typing model ADR-076 and ADR-082 point at — one `fields` table with a type per field — a section is closest to a prose field that lives in the body rather than the frontmatter. If that reading holds, `required` and `required_when` apply to it unchanged, `template-drift` (#169) checks that the form scaffolds it, and no new table is needed. That is the direction to test first, before any `sections:` key.
Contributor guide
Research direction
Start by reading ADR-076 and ADR-082, then review the discussion in #141 and the template-drift issue #169. Do not implement until a consumer record demonstrates the missing-section failure on a corpus where it has happened more than once; done means that measured gate exists and the field-typing direction has been evaluated against it.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- python
- Domain
- documentation, tooling
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Active
- Clarity
- Needs clarification
- Newbie friendliness
- 30/100