Audit the Markdown surface: one shape for a one-object card, and a helper that enforces it

[jmrplens]

Status 2026-09-12

What is left, the earlier body kept below for context:

Layers 1 and 2 are on main (PRs 708 to 721): toolutil.Card is the one card writer, docs/development/markdown-card.md defines it, every formatter is migrated, and both gates read zero. Layer 3, what remains: (1) flip the card and bool-time contexts into check-md-escaping and make the runtime registry gate fail rather than log (fill mdGateExceptions, turn mdGateLog into a failure); (2) remove the FmtMd* constants from internal/toolutil/markdown.go and their last caller in cmd/gen_llms; (3) the English docs and the Spanish site page on the card; (4) the four findings that stand between here and the flip: a HintAction id in keys that the catalog does not have (and a test validating every HintAction literal against the catalog), the bool-time context judging five values that are not Markdown, a declaration for the elicitationtools consent lines, and the leftovers in prompts and the default surface's own output.

---

The Markdown a tool returns is what a model reads, and the shape of it is currently decided per file rather than by any rule. Measured on the tree today:

• 27 packages render a single-object card as a | Field | Value | table.
• 76 render one as a bulleted list of - **Label**: value.
• 4 files use both shapes, so the same package answers two questions in two shapes.

internal/toolutil/markdown.go has helpers for a URL, pagination, a list summary, a description and an empty result, and the FmtMd* constants for the commonest bulleted labels. It has no helper for a field row, which is why the choice is made again in every formatter and why the two shapes drifted apart.

What surfaced this

A formatter that appends to a bulleted card was given table rows. A pipe row with no header and no delimiter row is not a table in GFM, so those lines rendered as literal | Runners Token | glrt-… | text in the middle of the card. It was caught and fixed on the 1:1 branch and never reached main, but nothing would have caught it: no gate compares a formatter's output shape against the section it writes into, and the test asserted only that a substring was present.

What the audit should settle

1. One rule for a one-object card, table or list, and a helper in toolutil that implements it so a formatter cannot pick the other by accident.
2. The four files that use both, resolved to whichever the rule says.
3. Whether a gate is worth it: a check that a formatter never emits a pipe row without a preceding delimiter row would have caught the defect above mechanically, in the same spirit as make check-md-escaping.
4. A sweep for values that should go through an existing helper and do not: booleans printed with %v instead of BoolEmoji, labels re-spelled instead of using the FmtMd* constant, timestamps not passed through FormatTime.

Queued deliberately after the 1:1 field work, not before it.

[aucypa]

I have opened three pull requests for this #713, #714 and #715 and would like to be assigned, so that nobody else starts the same work.

I tried solving it first and am asking only now, because I wanted to be sure I could actually finish it rather than claim a task and stall on it. Below is what the audit found and which rule I chose. If it is not the rule you want, say so and I will turn the migration around, the two defects and the gate hold either way, since neither depends on which shape wins.

The measurement reproduces. 76 packages write a one-object card as a bulleted list and 31 as a | Field | Value | table. Five files use both rather than four, depending on whether a | Property | Value | header counts as the same degenerate shape iterationdata, mergetrains, pipelineschedules, projects, runners. projects.FormatHookMarkdown writes a third shape as well: **Label:** value with no list marker at all.

1. The rule I propose: a table row is an object, not a field. A table carries many objects, one row an object, under column headings that name the fields they hold. A card carries one object, one field a line. | Field | Value | is that card in the other notation with the information taken out of its header. The bulleted list wins on three counts: 76 packages already write it, so the migration is 31 rather than 76; it costs nothing per response where a table costs two header lines, which audit_tokens -footprint confirms; and the line it draws leaves real tables alone, the 19-row "Event Triggers" table in FormatHookMarkdown stays a table, because each of its rows is an object.

The helper is a family of toolutil.WriteMdField* functions, each escaping or rendering its own value. None of them formats through fmt, so the escaping audit reads no template inside toolutil; WriteMdFieldRendered is the one that escapes nothing and is declared a sink in audit_md_escaping, so a raw value is still reported against the package that wrote the call and the //gitlab:allow-unescaped directives keep matching.

2. Two of the mixed files are broken on main, not merely inconsistent. iterationdata.FormatOutputMarkdown and mergetrains.FormatOutputMarkdown open a | Property | Value | table and then write FmtMdID into it. A list item ends the table at the delimiter row, so the card renders as a header with no body followed by every later field collapsed into one list item as literal text. Both are reachable, the group and project iteration get actions, and merge train get. Neither test caught it for exactly the reason you name in the issue: they assert that a substring is present, and every field is present.

3. The gate is worth it, and it has to render rather than read. A gate over the source has to model the conditionals, loops and helpers a card is assembled from across three packages. I wrote that version first as a prototype and it produced 25 false positives on this tree, all of the same kind: a table header written by the caller and its rows by a helper is invisible to a per-function walk. Rendering a sample of each registered output type through the registry and judging the finished string has none of that ambiguity. The first run reported 83 blocks, none of them false, in 24 packages.

4. The sweep found a cause that is not about cards at all. WriteListSummary wrote its line with no blank line above it, and nine formatters wrote FormatPagination's result into their builder rather than through WritePagination. A line written straight after a table row is read as another row and split on its own pipes, so Page 2 of 7 | 84 items total | 20 per page reached the model as two cells with the third dropped.

Still open and reported rather than fixed: 70 bold-prefix-field findings in 24 formatters, 32 hand-written labels duplicating a FmtMd* constant, 37 booleans written %t in a card instead of BoolEmoji, nine timestamps not passed through FormatTime, and nine spellings of a delimiter row where MarkdownTableSeparator exists.

Why three pull requests. Together this is ~1700 lines, which the size guideline asks to split, so I have staged it:

1. fix(toolutil): open a block for the summary and pagination lines #713 fix(toolutil) - the block-separation defect above. 89 lines, independent of the other two, and mergeable on its own.
2. feat(toolutil): one shape for a one-object card, and the helpers that write it #714 feat(toolutil) - the rule, the helpers, the two broken cards, the five packages. 500 lines, 314 of them the new file and its test.
3. feat(audit): gate the shape of every rendered Markdown response #715 feat(audit) - the gate, its CI wiring and the documentation. 1113 lines, and larger than I would like; I could not find an honest seam inside it, since mdshape without the command is a package nothing imports and the command without its rules is not a gate.

Two and three are stacked, because the gate only goes green once the fixes land. Each builds, tests and lints on its own.

One finding is outside this issue and I will open it separately unless you would rather it lived here: runners registers FormatAuthTokenMarkdown and FormatRegTokenMarkdown for the same AuthTokenOutput. The registry is keyed by reflect.Type, so the second registration overwrites the first and runner reset auth token answers under the heading "Runner Registration Token".

[jmrplens]

@aucypa, thank you, and I owe you an apology: when you asked to be assigned, a stack for this issue had already been open for six hours and nothing here said so. That is on me, not on you. I have answered each of your three pull requests with where the same work lives in that stack (#708 through #720), and you are credited as co-author on the four commits that carry what you proposed: the block separation, the one-object card writer, and both gates. The runners double registration you found is real on main and is fixed in 717.

[jmrplens]

The stack for this issue is merged into main, ten pull requests from #708 to #721: the one card writer and its contract, the shared renderers, both gates in report mode, the four migration waves, and the review fixes on top. Both gates read zero on main: the static one reports no unescaped value, and the runtime one reports no structural and no hostile-value finding over 589 rendered cases.

What this issue still owes, and why it stays open: the gates report and do not fail yet. Flipping them is the last layer, together with the English docs, the Spanish site and the removal of the old vocabulary, whose constants no package outside toolutil references any more. Four small things stand between here and the flip, and each is a finding of the migration rather than of the audit: a hint in keys that names an action id the catalog does not have, which is a class (HintAction takes any string and nothing validates it against the catalog); the bool-time context judging five values that are not Markdown at all; a declaration for the consent dialog lines in elicitationtools; and a few leftovers in prompts and the default surface's own output.

[jmrplens]

Body rewritten to layer 3, which is what remains, and moved to 3.1.0.