Answer prose round 1: the comments say why, items 95, 96, 91 and 34 read in one pass, the floor's decision drops the rule CLAUDE.md holds, and item 97 files the changelog's order

src/markdown/directive-syntax.ts

@@ -10,7 +10,7 @@ import { serializeCanonicalJson } from '../canonical-json.ts'
 
 export type AttributeReading = { refusal: 'kind' | 'nesting'; value?: undefined } | { refusal?: undefined; value: VocabularyValue }
 
-// An `!adf:` standing at `index`, which only `claimDirectivePrefix` builds.
+// Proof that `!adf:` stands at `index`; only `claimDirectivePrefix` builds one.
 export type ClaimedPrefix = { readonly [claimedPrefix]: true; readonly index: number }
 
 export type DirectiveValue = { decoded: string; spelling: string }

src/markdown/emit/line-escaping.ts

@@ -32,7 +32,6 @@ type EmittedDelimiter = { closes: boolean; offset: number; pair: number; width:
 
 type EmittedRun = { canClose: boolean; canOpen: boolean; character: string; delimiters: EmittedDelimiter[]; length: number; start: number }
 
-// What stays fixed while one line's escapes are decided.
 type EscapeWalk = {
   readonly claims: Claims
   readonly container: LineContainer
@@ -127,7 +126,7 @@ function escapeClaims(scan: string, escapings: readonly InlineEscaping[], contai
   return escaped
 }
 
-// A run joining the emitter's own delimiter escapes its text; a run of text escapes from its start while the reader claims what the escapes leave of it.
+// A text character beside one of the emitter's delimiters would lengthen that delimiter's run, so every text character in such a run escapes.
 function runEscapes(walk: EscapeWalk, start: number, end: number, line: ScanLine): number[] {
   const { escapings, scan } = walk
   const indexes: number[] = []
@@ -137,7 +136,7 @@ function runEscapes(walk: EscapeWalk, start: number, end: number, line: ScanLine
     return indexes
   }
   for (let index = start; index < end; index += 1) {
-    // A backtick run escapes whole: a rest left bare would be a raw run of another length for a closer.
+    // A backtick run escapes whole: a bare rest would be a shorter backtick string, which can close a span an earlier run opens.
     const claimed = (index > start && scan.charAt(index) === '`') || claimsRunRest(walk, index, end, line)
     if (!claimed) break
     indexes.push(index)
@@ -323,7 +322,7 @@ function claimsLineStart(line: ScanLine, index: number, container: LineContainer
   return escapesLineClaim(line.text, index - line.start, line.position)
 }
 
-// Where the closing sequence an ATX heading would read in the text starts, `undefined` where it reads none.
+// The start of the closing sequence an ATX heading would read at the text's end.
 function closingHashes(scan: string): number | undefined {
   let start = scan.length
   while (scan.charAt(start - 1) === '#') start -= 1

src/markdown/inline-tokens.ts

@@ -7,7 +7,7 @@ import { delimiterFlags, runLength } from './commonmark/emphasis-matching.ts'
 import { highlightDelimiter, highlightFlanking } from './portable/conventions.ts'
 import { readEntityReference } from './commonmark/entity-references.ts'
 
-// What the inline reader reads from a token start, `width` characters on; `text` reads literally, a directive reads by its own grammar, and HTML is refused.
+// `directive` and `html` carry no `width`: a directive reads by its own grammar, and the reader refuses HTML.
 export type InlineToken =
   | { email: boolean; kind: 'autolink'; width: number }
   | { image: boolean; kind: 'bracket'; width: number }

src/markdown/parse/inline-content.ts

@@ -147,7 +147,7 @@ function readToken(scan: Scan, index: number, token: InlineToken): Result<number
       scan.pending += scan.source.slice(index, end)
       return success(end)
     case 'hard-break':
-      // CommonMark strips the spaces the two-space break is spelled with, and keeps those before a backslash.
+      // CommonMark keeps the spaces before a backslash hard break.
       flush(scan, false)
       pushNode(scan, { type: 'hardBreak' })
       return success(end)