dmarx / dmarx/luria

Required sections: a contract can name a body heading a document must carry (gated on a measured case)

Open
#186 0 comments 0 reactions 0 assignees View on GitHub
enhancement
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

Open the contributing 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.