The README intro spec and the HISTORY mirror rule leave no room for a second paragraph, and the audit would report one

[ptr727]

spec/readme-structure.md item 1 and CODESTYLE.md "Markdown and Spelling" item 4 together leave a README no room to say anything about itself beyond one 100-character sentence, and spec/audit.py then reports a repository that takes the room anyway.

$ git show origin/develop:spec/readme-structure.md | sed -n '7p' | cut -c1-274
1. **Title (`# <Name>`)** - the H1 **is the repository name** (a hyphenated name may render its hyphens as spaces: `Financial-Modeling` -> `Financial Modeling`), then a one-line description as the next paragraph. That description is a **single sentence, link-free plain text
$ git show origin/develop:CODESTYLE.md | sed -n '39p' | cut -c1-217
4. **`HISTORY.md` mirrors the README opening**: `HISTORY.md` is the maintainer-curated changelog and opens as the README's twin, carrying the same `# <Title>` (without the README's ToC-omit comment) and the same intro

Neither file states that a second paragraph is forbidden. Both are written as though the intro is the description, so a repository adding a paragraph of context under the tagline has no rule saying it may, and the audit has no way to read one.

The cap belongs to a mirror, not to the reader

The 100-character limit is Docker Hub's short-description cap, the tightest surface the sentence feeds, and spec/readme-structure.md says so outright. It is a constraint on what gets copied out of the README, and it has been applied to what the README itself is allowed to contain. A repository whose purpose needs a sentence of context is the case where that costs something real, and it is exactly the case that comes up while onboarding a repository whose domain is not obvious from its name.

What the audit does with it today

The readme-structure dimension extracts the first non-empty line after the H1 and checks the length, the link-free form, and the mirrors. That behavior is correct for the tagline and has no notion of anything following it, so a legitimate second paragraph either goes unmeasured or is read as part of what the mirrors take, depending on how the extraction is later tightened. The rule and the checker have to move together or the first repository to use the room becomes a finding.

The shape that resolves it

State the tagline as a distinct thing from the intro. The first line after the H1 is the tagline. It alone carries the 100-character link-free constraint. It alone mirrors to the GitHub About panel, the Docker Hub short description, and the HISTORY.md opening. Any paragraph after it is free prose that no mirror reads and no cap applies to.

Three surfaces change with it: spec/readme-structure.md item 1, CODESTYLE.md item 4 (which is carried at intent, so this is a fleet re-vendor), and the extraction in spec/audit.py.

Decide it with the registry-description entry, not before it

TODO.md "Audit and Spec Model" already carries an entry to declare the canonical short description in registry/repos.json rather than deriving it by parsing the README. That change makes every mirror read a declared field instead of a paragraph, which settles this ambiguity by construction and removes the parser that motivates the cap. The two are the same axis and want one decision. Taking this one first means writing an extraction rule that the registry change then deletes.

Filed from the onboarding-feedback pass in #576, where it is recorded as a TODO.md entry.

[ptr727]

Resolved by c2ce145 ("Encode the README Structure, Links, and Tools as Auditable Rules", #632), which is on main. The shape this issue proposed is what shipped: the tagline is a distinct thing from the intro, it alone carries the cap and the mirrors, and any paragraph after it is free prose that no mirror reads. All three surfaces named here changed together.

spec/readme-structure.md item 1 now states the split, and states why the rule is scoped to the one line the mirrors take:

Further paragraphs below the tagline are free prose, carrying whatever a reader needs to understand the project before the fold, under no length or link rule and read by no mirror. The rule is scoped to the one line the mirrors take precisely so that a README is not forbidden from saying anything more about itself above the fold.

CODESTYLE.md "Markdown and Spelling" item 4 narrows the HISTORY.md mirror to match:

The tagline is the first line after the README's H1, and it is the whole of the mirror: a README may carry further paragraphs below it, explaining the project to a reader before the fold, and the changelog does not repeat them.

spec/audit.py extracts the tagline as the first line of the intro region, and the engine self-test asserts the two-paragraph case rather than leaving it to a reading of the code. python3 spec/audit.py --selftest reports ok tagline: the first line of the intro region, further paragraphs excluded and exits SELFTEST PASS.

One correction to this issue's closing argument, recorded so it is not re-derived. It said to hold this until the registry-description entry, because taking it first meant writing an extraction rule the registry change would delete. That sequencing was stated more strongly than the code warranted: spec/audit.py already measured the first line for the About and Docker Hub mirrors, so narrowing the HISTORY.md mirror to match it was one line rather than a new parser. Declaring the description in registry/repos.json remains worth doing and is now an independent simplification rather than a prerequisite, tracked under TODO.md "The Declared Repository Description".

That cluster's second entry, closing the README-to-About hop that nothing writes, had been given this issue number in TODO.md even though this issue's body never covers it. It is not closed by the above and now carries #639 of its own, so a closed number stops standing in for open work.