The prose gate hand-rolls a CommonMark block parser — seven rounds landed (HTML block state + #226 shipped); RFC: markdown-it-py as the oracle, blocking nothing

[thrillmot]

check_prose_retention.py classifies each line of a SKILL.md as frontmatter, prose or code, and it does so with a hand-rolled block parser. Six review rounds have each taught that parser exactly one more CommonMark construct, and each round's fix exposed the next gap.

The arc, as it actually happened

round	construct taught	how it was found
5	fenced code (already present) + indented code blocks	a critic asked "what Markdown forms does the gate not model?"
7	block quotes as a container	the same question again — a quote defeats both code spellings
9	a paragraph model (headings, thematic breaks, setext underlines)	round 7 disclosed its own residual; a panel weaponised it
10	HTML block state — outstanding	round 9's fix closes a paragraph inside an open HTML block

Every one of those was a real defect. Three were exploitable as false greens on undeclared prose cuts; the current one is the mirror — a pure addition goes red and the only remedy printed is a permanent record asserting words were lost when none were.

Measured, the current regression:

base: a <table> block with indented rows
head: base + ONE inserted line, `<!-- generated from the release notes -->`
      (strict line-superset; 0 words removed)

round 8 (27747ed)   prose: -5  code:  0   -> does not fire
round 9 (e5c5fbc)   prose: 20  code:-25   -> FIRES, demands a row for 20 words

<details> / <summary> already ship in clud-bug-collaboration, logmind and token-frugal-tooling.

The observation this issue exists to record

Every round adjudicated its fix against markdown-it-py. The oracle has been in the loop the whole time — as the test, never as the implementation. Round 9 even refuted two constructs it had been handed by asking the oracle instead of assuming.

So the question is why the gate carries a second, worse CommonMark implementation at all. If markdown-it-py's block tokens (token.map line ranges, already how every round measured agreement) drove the split directly, the entire "form N+1" class would close by construction rather than one round at a time. Divergence from CommonMark would be zero because the classification is CommonMark.

What it would cost, honestly

• A pinned dependency in CI. The workflow already installs pytest==8.3.4 and pyyaml==6.0.2; markdown-it-py is pure Python and pins the same way.
• Re-deriving the FLOOR bands. They are justified by an empty band between each scope's floor and the smallest real removal in that scope, measured against the current split. A new splitter means re-deriving — the same work every round in this sequence already did.
• Re-measuring the shipping-file scope set. Four files currently move under the container reading; that set is pinned by a symmetric-difference assertion and would need re-deriving, not loosening.
• It is a large change at the end of a long sequence, which is a real argument against doing it inside Make rewriting easy and deletion loud: check_prose_retention.py #218 and the reason this is a separate issue.

What this issue is NOT

Not a reason to hold #218. After round 9 the false-green divergence — CommonMark says code, the gate says prose — is 0.28%, down from 12.83%, with 12 minimal forms remaining, all filed (#226) or over-charging rather than under-charging. The gate closes every failure mode found in nine rounds of adversarial review. Shipping it makes the repository better than not shipping it; this issue makes it better still.

The immediate HTML-block regression is being fixed narrowly first, because a pure addition going red is not something to ship even briefly.

[thrillmot]

Re-measured against current dev (origin/dev @ b44a906, 2026-08-18) rather than trusting this issue's round-9 snapshot. Corrections below, control-tested.

Round 10 (HTML block state) is not outstanding — it shipped. docs/decisions-branches/feat__prose-retention-gate.md has a dated entry ## 2026-08-16 - Model the open HTML BLOCK, not just its opener: a pure addition was firing the gate, and that entry's own "Alternatives considered" says verbatim: "Re-plumbing the splitter onto markdown-it-py, which would make the whole class disappear, deliberately NOT done here and filed as #227." So this issue was filed as the deferred RFC the moment round 10 landed, not as a tracker for an unfixed regression. The fix is already present in 5879bb5, the very commit that merged #218 (git log --oneline origin/dev -- .github/scripts/check_prose_retention.py → 3 commits total: 5879bb5/squashed-into-e33ad45 [#218, MERGED 2026-08-17T17:10:21Z], 92bfc65 [#245, unrelated git-diff-scope fix], b44a906 [#226, current HEAD]).

The issue's own worked example (HTML block containing indented content + one inserted <!-- comment --> line, asserting no false fire) is pinned by name, not just vaguely covered:

• tests/test_check_prose_retention.py::test_cli_adding_a_line_inside_an_html_block_asks_for_no_declaration — pure addition inside an open <details>/indented-code HTML block, asserts exit 0, no ledger row demanded.
• Its control, test_cli_control_a_real_cut_beside_the_same_html_block_still_fires — same block, a real cut, asserts it still fires.
• Mutation coverage: test_mutation_turns_the_suite_red[an_html_block_that_stays_open_is_not_modelled] in tests/test_prose_retention_mutations.py.

All three pass on this checkout: PYENV_VERSION=3.11.8 pyenv exec pytest tests/test_check_prose_retention.py -k "test_cli_adding_a_line_inside_an_html_block_asks_for_no_declaration or test_cli_control_a_real_cut_beside_the_same_html_block_still_fires" -v → 2 passed; pyenv exec pytest tests/test_prose_retention_mutations.py -k an_html_block_that_stays_open_is_not_modelled -v → 1 passed.

Residual classes: not "1 outstanding," measured from the module's own Container docstring "WHAT IS STILL WRONG" section (.github/scripts/check_prose_retention.py:513). Control test first — grepped a term known present (Stdlib only, line 99: found) before trusting a grep for residual|known.?gap|outstanding|caveat came back near-empty (1 hit, line 515, which is this section). It names exactly 4 classes:

1. List column survives a container boundary that closed the list — CLOSED, The splitter keeps a list column across a closing block quote, so an indented example there scores as prose #226, fixed in b44a906 (gh issue view 226 → state: CLOSED, closedAt: 2026-08-18T14:28:01Z, PR #247 mergeCommit = b44a906, i.e. this checkout's HEAD exactly).
2. A fence spelled inside a wrapped line — open, false-positive direction, not covered by the alphabets below.
3. A trailing blank line — open but inert: "It cannot move a score in either direction... a blank line carries no words."
4. A lowercase <!doctype html> — open, a deliberate divergence from markdown-it-py 4.2.0 (which still follows the 0.30 spec) rather than from CommonMark 0.31.2 itself, kept because "Following the library instead would put this on the exploitable side of the current spec."

So current count: 3 open, non-exploitable-by-design residuals + 1 closed, not "HTML block state outstanding."

Divergence %: moved, then went stale by the file's own admission — no current up-to-date figure exists. The round-9 figure this issue cites (0.28%, down from 12.83%, 12 forms) is superseded by a broader round-10 remeasurement in the same docstring: over 20,000 generated documents with the catalog's HTML constructs, disagree-at-all fell 15.91% → 0.07%, dangerous direction (CommonMark says code, gate says prose) 0.07% → 0.01%; over a quote-heavy alphabet, 25.03% → 0.27%, dangerous 0.68% → 0.07%; 45 minimal forms total (8 + 37), all attributable to the list-column defect. But the docstring immediately flags that number stale too: "The aggregate counts above (45 minimal forms, the two percentages) describe the corpus BEFORE this fix and were not re-run against it; they overstate what remains until the next round regenerates them." The #226 fix's own verification (docs/decisions-branches/fix__prose-gate-list-column.md) was deliberately narrower — 128 generated documents, 0 disagreements — and explicitly declined to redo the full-alphabet run, calling that "#227-scale re-derivation." So: no current full-alphabet divergence % exists: the last one is admitted-stale, and nothing has regenerated it since.

"Blocking nothing" — confirmed, not asserted. gh issue view 218 → state: MERGED, closedAt: 2026-08-17T17:10:21Z. The gate this RFC proposes to replumb has shipped and is live on dev.

Round count. The docs log 5 distinct CommonMark-construct-class fixes for this splitter: indented code + block-quote-as-container + paragraph model + HTML block state (all dated 2026-08-15/16, docs/decisions-branches/feat__prose-retention-gate.md, squashed into 5879bb5/#218), plus list-column-across-quote (fix__prose-gate-list-column.md, 2026-08-18, #226). #226's own decision entry independently calls it "the fifth distinct defect fixed in Container.reopen's container-boundary handling" and flags it "worth flagging for #227, which argues the hand-rolled parser should be replaced with markdown-it-py as the oracle it already is in every round." That's one more construct-class round landed since this issue's "six" framing (which already counted round 10, then still in flight, as one of the six) — seven, not six, and the newest one (#226) is itself evidence for this issue's own argument, not against it.

---

Corrected one-line statement: This is an RFC to replace check_prose_retention.py's hand-rolled CommonMark block parser with markdown-it-py as the splitting engine — it blocks nothing (#218 merged 2026-08-17), and every construct-class defect found since filing (round 10's HTML block state, #226's list-column-across-quote) has shipped safely through the existing hand-rolled model, which is exactly the "one construct per round" pattern this RFC exists to end rather than a reason to hold it.

Commands run:

git -C /Users/ludlow/code/thrillmade/agent-skills log --oneline origin/dev -- .github/scripts/check_prose_retention.py
git show -s --format='%H%n%s%n%b' <5879bb5|92bfc65|b44a906|e33ad45>
git show 5879bb5:.github/scripts/check_prose_retention.py | grep -n "_html\|HTML_BLOCK"
grep -n "Stdlib only" .github/scripts/check_prose_retention.py                 # control
grep -ni -E "residual|known.?gap|outstanding|caveat" .github/scripts/check_prose_retention.py
grep -n "^## " docs/decisions-branches/feat__prose-retention-gate.md
gh issue view 226 --repo thrillmade/agent-skills --json title,body,state,closedAt
gh issue view 218 --repo thrillmade/agent-skills --json state,closedAt
gh pr view 247 --repo thrillmade/agent-skills --json title,state,mergedAt,mergeCommit
PYENV_VERSION=3.11.8 pyenv exec pytest tests/test_check_prose_retention.py -k "test_cli_adding_a_line_inside_an_html_block_asks_for_no_declaration or test_cli_control_a_real_cut_beside_the_same_html_block_still_fires" -v
PYENV_VERSION=3.11.8 pyenv exec pytest tests/test_prose_retention_mutations.py -k an_html_block_that_stays_open_is_not_modelled -v