Skip to content

No hand-written page passes 400 lines, a page that would is split along its headings with its anchors kept, and a check in CI holds it

Decision 940 · accepted · 2026-10-24 · issue #422

Superseded in part

In part by 1031, 1032, 1033, 1042.

Why. #422's done-when says no hand-written document passes about 400 lines but the protocol, and defects.md lists only open defects; row 7 of the Stage 1 gate checks it. A rule a person checks once a release is a rule that holds once a release.

The decision.

  • 400 lines, checked. scripts/doc-size.exs fails when a Markdown file git knows about passes 400 lines. It runs in ci.yml's versions job and in dev-check.yml, where a chunk's pages grow. Three kinds are not held to it: PROTOCOL.md, one contract a client author reads whole, whose split has a cost #422 asked to be weighed and not made by the line rule; a generated file, one whose first lines say <!-- Generated by (the third-party licences, what Troupe dials); and docs/history/, records kept as they were written that nobody is asked to read. The line is a line, not about 400: a page at 399 that needs another paragraph is split first.
  • A page past the line is split along its own headings. Sections move word for word to pages of their own beside it (docs/user/configuration-layers.md, docs/admin/github-runs.md, docs/developer/architecture-remote.md); the parent keeps each moved ## heading with a sentence or two and a link, and each moved ### heading's anchor as an <a id>, so a link from an issue, a release note or a bookmark still lands on the right page. Links inside the repository are moved to the new page. A dated measurement on an instruction page is a record, not instruction, and is deleted with a line saying it is in the page's git history (prompt-prefix.md's live and offline numbers). Not a redirect plugin: the anchors that matter are inside pages, which a page-level redirect cannot carry, and GitHub, where many readers meet these files, runs no plugin. Not a rewrite: the content is #422's sweep to judge, and a split keeps every claim where a reviewer can see it moved unchanged.
  • Content that something reads stays where it is read. The generated key reference and provider-type table stay in docs/user/configuration.md (mix troupe.config.schema and the core's tests read them there), ARCHITECTURE.md keeps section 2 (code cites its failure matrix and transition table), and a YAML example that moved to a new page is added to the core's test that checks every example is a valid config file.
  • The site's front page is docs/README.md, drawn as a landing page (#189). It is the page both a GitHub reader of docs/ and a site visitor meet, so it stays one file: docs/overrides/hooks.py gives the home page landing.html and hides the nav and the table of contents beside it, rather than front matter GitHub would print as a table. Above the fold: what Troupe is, the install as the quick start has it (held to the quick start word for word by quick-start.yml, as the root README's is), and a figure marked <!-- recording: docs/assets/seam.mp4, ... --> that shows a still until the gate's row 4 recording exists. The search basics are the pages' own: each page's description and canonical URL from the hook, Open Graph on every page with a static image, sitemap.xml from MkDocs, a SoftwareApplication description on the front page, and robots.txt, which a crawler reads at a host's root only and so does its work once the site has a host of its own.

Governs: docs/**, mkdocs.yml, scripts/doc-size.exs, .github/workflows/quick-start.yml