PROTOCOL.md stays one contract on one page, the one hand-written file past 400 lines, until the schema can say what a field means¶
Decision 1009 · accepted · 2026-11-16 · issue #422
Superseded in part
In part by 1035.
What reading the file found. That split needs the reference to be a copy of the schema, and it is not.
- The schema knows names and types, not meaning.
protocol/schema/v1/is 203 documents and not onedescription:user_shellis ten properties, five required, each a type. Its row in the event table says whatended's four values mean, thatoutputis capped attool_output_limitwith theread_outputmarker, and whatagent: falseis. Of the 68 rows in the durable event table, 16 are only field names; the other 52 are the contract for that event, and a generated page would carry none of it. - Moving the prose by hand would cost what the rule is there to save. The file says
of itself that it is complete on its own, and a client author reads it end to end and
searches it as one thing; the site publishes it as one page (
mkdocs.yml, through the hook that serves root files at their paths). The code and the tests cite it 76 times in 42 files, by section (PROTOCOL.md §621 times,§10ten,§8nine) and by anchor;people_named_test.exsreads the event table from the file; the Python conformance client is written against it. Split along its headings as Decision 940 splits other pages, every§Ncitation would point at a stub, and a reader would follow links across a dozen pages for what one search finds now.
The decision.
PROTOCOL.mdstays one file and one page, and it is the one hand-written Markdown filescripts/doc-size.exsdoes not hold to 400 lines, with the reason written beside the exemption. No other page gets an exemption of this kind; a generated file anddocs/history/stay exempt as Decision 940 has them.- What may come out of it is what a schema can generate. When
Troupe.Protocol.Schemacarries a description for a field (as JSON Schema'sdescription, written intoprotocol/schema/v1/bymix troupe.schema.gen), the table row for that event or command can be generated from it, on a page underdocs/protocol/with a check in CI besidemix troupe.schema.diff, andPROTOCOL.mdlinks to it. That is a move of the meaning into the code, one event at a time, not a move of text between files; until it is done for a whole table, the table stays here. - It does not grow without care. A new event is a row, a new command a heading and its
paragraphs, as
docs/developer/conventions.mdsays; history (when a field arrived, what a log written before a release lacks) stays where a client needs it to read an old log, and nowhere else.
Not chosen. A generated reference of field names and types under docs/protocol/
beside the whole file: it would add a page that says less than the JSON Schema already
committed, and shrink nothing. Splitting the file into a page per section: the cost above,
for a line count. Raising the limit for everyone: the rule holds for every other page.
Governs: PROTOCOL.md, scripts/doc-size.exs, mkdocs.yml